Інтеграція логістичних сервісів 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.
Тривалість інтеграції: три-чотири дні — клієнт, список ПВЗ з картою, розрахунок вартості, створення та отстеження замовлення.