Проблема: ігнорування CityCode призводить до порожнього списку ПВЗ
Користувач вводить місто, а додаток показує «Нічого не знайдено». Типова ситуація: в запиті ListPoints не вказано параметр CityCode, або він переданий у вигляді рядка замість int. Boxberry API суворо вимагає числовий CityCode, отриманий з методу ListCities. Ми в своїй практиці стикалися з цим десятки разів; рішення — завжди кешувати CityCode після першої відповіді. Помилка не очевидна, оскільки API повертає порожній масив без коду помилки.
Як працює Boxberry API і чим він відрізняється від СДЭК?
Boxberry API — це не стандартний REST, а єдиний ендпоінт https://api.boxberry.ru/json.php, де метод передається параметром method у query string. На відміну від СДЭК v2, де кожен ресурс має свій URL, тут всі запити йдуть на одну адресу. Це означає, що Retrofit-інтерфейс буде з одним базовим URL і багатьма @Query параметрами. Аутентифікація — токен у параметрі token, без заголовків. Токен не має терміну дії за замовчуванням, тому його потрібно зберігати в захищеному сховищі пристрою (Keychain на iOS, EncryptedSharedPreferences на Android). Boxberry API Documentation
Тестового оточення немає — розробка ведеться на бойовому токені. Це накладає вимоги до агресивного кешування та мінімізації запитів. Список ПВЗ ми кешуємо в локальну базу (Room на Android, CoreData на iOS, Hive на Flutter) на 24 години.
Основні методи Boxberry API
| Метод | Endpoint | Основні параметри | Відповідь |
|---|---|---|---|
| ListPoints | GET json.php?method=ListPoints |
token, CityCode, prepaid | Масив ПВЗ з полями Code, Name, Address, GPS, WorkShedule, Phone |
| DeliveryCosts | GET json.php?method=DeliveryCosts |
token, zip, weight, ordersum | price (руб), delivery_period (дні) |
| ParselCreate | POST json.php?method=ParselCreate |
token, JSON body з даними замовлення | track (трек-номер) |
| ListStatuses | GET json.php?method=ListStatuses |
token, ImId (трек) | Масив статусів з Date, Name, Comment |
Типові параметри запитів
Для DeliveryCosts обов'язкові: zip, weight (в грамах), ordersum (в копійках). Опціонально: height, width, depth. Якщо weight > 30000 г, потрібне попереднє узгодження.Особлива увага — полю GPS. Воно приходить рядком "55.7558,37.6173", а не окремими координатами. Парсинг на Swift:
let coords = point.gps.split(separator: ",") let lat = Double(coords[0]) ?? 0 let lon = Double(coords[1]) ?? 0 Чому Boxberry краще СДЭК для деяких сценаріїв?
Мережа Boxberry налічує понад 18 000 пунктів видачі — це в 1.3 рази більше, ніж у СДЭК у регіонах з населенням менше 50 000 осіб. Однак API Boxberry менш RESTful і вимагає більше ручної роботи при інтеграції. Тим не менш, для додатків, де ключовий фактор — кількість ПВЗ і швидкість доставки (в середньому 2–3 дні по РФ), Boxberry часто виявляється вигіднішим. При цьому ми гарантуємо стабільне з'єднання за рахунок перехоплювача OkHttp і ретрай-логіки з експоненційною затримкою.
Як ми інтегруємо Boxberry у мобільний додаток
iOS (Swift)
На iOS ми використовуємо SwiftUI + Combine/async/await. Список ПВЗ завантажуємо за допомогою URLSession, парсимо через Codable. Для карти — Google Maps SDK з кластеризацією при zoom < 12 (GMUMarkerClusterer). При тапі на кластер — анімований zoom до меж групи. Фільтрація ПВЗ (з приміркою, робота у вихідні, оплата карткою) реалізована через SearchResultController з UISearchController і фільтрами у вигляді SegmentedControl.
Android (Kotlin)
На Android — Retrofit з OkHttp Interceptor для автоматичної підстановки токена. Приклад інтерфейсу:
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 } Flutter
На Flutter використовуємо Dio для HTTP, Hive для кешу. Карта — google_maps_flutter або flutter_map. Список ПВЗ відображається ListView.builder з пошуком за назвою/адресою та фільтрами (FilterChip).
Процес роботи над інтеграцією
- Аналіз — вивчаємо поточну архітектуру вашого додатку, визначаємо необхідні методи API та обсяг запитів.
- Проектування — створюємо схему запитів, кешування, офлайн-режиму з урахуванням особливостей Boxberry (відсутність тестового оточення).
- Реалізація — пишемо клієнт на обраній платформі, інтегруємо карту з кластеризацією та фільтрами.
- Тестування — перевіряємо на реальних токенах, симулюємо сценарії (немає мережі, невірні координати, порожня відповідь).
- Деплой — публікуємо оновлення в App Store/Google Play, налаштовуємо Firebase Distribution для бета-тестів.
Що входить в роботу
- Розробка та інтеграція Boxberry API (розрахунок вартості доставки, створення та трекінг замовлень, список ПВЗ).
- Відображення ПВЗ на карті з кластеризацією та фільтрацією.
- Документація по використанню API у вашому проекті.
- Навчання вашої команди (супровід протягом місяця).
- Допомога з публікацією в магазинах додатків (App Store, Google Play).
Терміни інтеграції
Від 3 до 5 робочих днів на одну платформу (iOS, Android або Flutter). Комплексне рішення під ключ для двох платформ — до 8 днів. Вартість від 30 000 руб. на одну платформу, від 50 000 руб. на дві.
Висновок
Наш досвід показує, що Boxberry — надійний партнер для доставки, якщо правильно підійти до його API. Ми гарантуємо, що інтеграція Boxberry API пройде без сюрпризів, допомагаючи вашому мобільному додатку швидко розраховувати доставку та відстежувати замовлення. Оцініть свій проект — зв'яжіться з нами, і ми підготуємо пропозицію за один день. Вартість інтеграції на одній платформі — від 30 000 руб. Економія на логістиці до 25%. Ми маємо понад 10 років досвіду та більше 45 успішних проектів у сфері мобільної розробки та інтеграції логістичних сервісів. Замовте інтеграцію Boxberry API для вашого мобільного додатку вже сьогодні!