Интеграция логистических сервисов Boxberry в мобильное приложение

Интеграция логистических сервисов Boxberry в мобильное приложение

Boxberry — логистический оператор с сетью более 18 000 пунктов выдачи в России. Их API старше и менее RESTful, чем у СДЭК v2, но для ключевых задач — расчёт тарифов, список ПВЗ, создание и отслеживание заказов — всё необходимое есть.

Особенности API Boxberry

Boxberry API работает на одном эндпоинте с параметром method в query string: https://api.boxberry.ru/json.php?token={TOKEN}&method={METHOD}&.... Это не типичный REST-подход, поэтому Retrofit-интерфейс выглядит иначе — один базовый URL, параметры в @Query.

Аутентификация — токен в параметре запроса, не в заголовке. Токен выдаётся в личном кабинете и не имеет срока действия по умолчанию. Хранить в Keychain / Android Keystore, не в константах кода.

Тестового окружения в публичной документации нет — разработка на боевом токене с минимальными реальными запросами. Учитывать это при разработке: не делать лишних запросов, кэшировать агрессивно.

Основные методы

Список ПВЗ:

GET /json.php?token=...&method=ListPoints&CityCode=10&prepaid=1

CityCode — внутренний код города Boxberry (не КЛАДР, не ФИАС). Таблицу кодов получаем через method=ListCities. Ответ — JSON-массив точек с полями Code, Name, Address, GPS (формат "55.7558,37.6173"), WorkShedule, Phone.

Обратить внимание: поле GPS — строка с запятой внутри, не отдельные lat/lon. Парсим:

let coords = point.gps.split(separator: ",")
let lat = Double(coords[0]) ?? 0
let lon = Double(coords[1]) ?? 0

Расчёт тарифа:

GET /json.php?token=...&method=DeliveryCosts&zip=...&weight=500&ordersum=2000

zip — почтовый индекс получателя. Возвращает price и delivery_period (дни).

Создание заказа:

POST /json.php?token=...&method=ParselCreate

Body — JSON с полями отправителя, получателя, списком товаров. Ответ содержит track — трек-номер для отслеживания.

Отслеживание:

GET /json.php?token=...&method=ListStatuses&ImId={track}

Возвращает массив статусов с Date, Name, Comment.

Реализация на Android

interface BoxberryApi {
    @GET("json.php")
    suspend fun listPoints(
        @Query("token") token: String,
        @Query("method") method: String = "ListPoints",
        @Query("CityCode") cityCode: Int,
        @Query("prepaid") prepaid: Int = 1
    ): List<BoxberryPoint>

    @GET("json.php")
    suspend fun getDeliveryCosts(
        @Query("token") token: String,
        @Query("method") method: String = "DeliveryCosts",
        @Query("zip") zip: String,
        @Query("weight") weight: Int
    ): BoxberryDeliveryCosts
}

Токен не передавать в каждом вызове — OkHttp Interceptor добавляет его автоматически. Список ПВЗ кэшировать в Room на 24 часа.

Карта ПВЗ с фильтрацией

После загрузки точек отображаем на Google Maps. Фильтры: тип ПВЗ (с примеркой / без), работа в выходные, наличие карточной оплаты — всё есть в полях ответа. Реализуем BottomSheet с фильтрами и MutableStateFlow<FilterState> для реактивной перефильтрации списка без повторного API-запроса.

Кластеризация при зуме < 12 — ClusterManager на Android, GMUMarkerClusterer на iOS. При тапе на кластер — анимированный zoom к его границам.

Flutter

Общий HTTP-клиент с Dio, BoxberryRepository с кэшем на Hive. Карта — google_maps_flutter или flutter_map. Список ПВЗ для выбора — ListView.builder с поиском по названию/адресу и фильтрами в FilterChip.

Срок интеграции: три-четыре дня — клиент, список ПВЗ с картой, расчёт стоимости, создание и отслеживание заказа.