Проблема: игнорирование 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 пунктов выдачи — это покрытие превосходит СДЭК в ряде регионов, особенно в отдалённых городах с населением менее 50 000 человек. Однако API Boxberry менее RESTful и требует больше ручной работы при интеграции. Тем не менее, для приложений, где ключевой фактор — количество ПВЗ и скорость доставки (в среднем 2–3 дня по РФ), Boxberry часто оказывается выгоднее. При этом мы гарантируем стабильное соединение за счёт перехватчика OkHttp и ретрай-логики с экспоненциальной задержкой.
Как мы интегрируем Boxberry в мобильное приложение?
iOS (Swift)
На iOS мы используем SwiftUI + Combine/async/await. Список ПВЗ загружаем с помощью URLSession, парсим через Codable. Для карты — Google Maps SDK с кластеризацией при зуме < 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).
Сроки интеграции
От трёх до пяти рабочих дней на одну платформу (iOS, Android или Flutter). Комплексное решение под ключ для двух платформ — до восьми дней. Стоимость рассчитывается индивидуально исходя из объёма работ и количества платформ.
Заключение
Наш опыт показывает, что Boxberry — надёжный партнёр для доставки, если правильно подойти к его API. Мы гарантируем, что интеграция пройдёт без сюрпризов. Оцените свой проект — свяжитесь с нами, и мы подготовим предложение за один день. Закажите консультацию прямо сейчас!