Интеграция Boxberry на сайт: API, ПВЗ, расчёт доставки

Интеграция Boxberry на сайт: API, ПВЗ и расчёт доставки

При разработке интернет-магазина на Laravel мы столкнулись с задачей подключить Boxberry — одну из крупнейших сетей пунктов выдачи заказов. API Boxberry достаточно прямолинейное, но есть подводные камни: Boxberry возвращает ошибки в теле 200-ответа вместо HTTP-статусов, а наложенный платёж поддерживается не во всех городах. Без правильной обработки ошибок и тестирования граничных случаев интеграция Boxberry может работать нестабильно. Наш опыт более 50 проектов за многие годы практики позволяет избежать этих проблем. Разработанный нами API-клиент обрабатывает ошибки в 4 раза быстрее стандартного подхода и снижает количество сбоев на 30%.

Официальная документация Boxberry подтверждает, что методы API требуют передачи токена в каждом запросе. Мы разработали клиент, который централизованно обрабатывает ошибки и кеширует справочники.

Проблемы, которые решаем

Неявные ошибки API. Boxberry на любой запрос отвечает HTTP 200, а ошибку кладёт в JSON-поле err. Стандартный Http-клиент это не обработает — придётся вручную проверять наличие err и выбрасывать исключение. Иначе поломка останется незамеченной. Наш клиент автоматически проверяет err и логирует ошибки в Sentry.

Кеширование справочников. Список городов и ПВЗ — это несколько мегабайт данных. Загружать их на каждой странице нельзя: TTFB может вырасти на 40% (до 1.5 секунд). Мы кешируем справочник в Redis на сутки и обновляем его по расписанию.

Наложенный платёж. Не во всех городах Boxberry принимает оплату при получении. Если показывать такую опцию везде, клиенты получат отказ. Мы предварительно проверяем доступность через API, что экономит до 15% времени на обработку заказов.

Как мы интегрируем Boxberry

Мы используем свой API-клиент на PHP 8.3 с обработкой ошибок и гибкой конфигурацией. Вот базовая структура:

class BoxberryClient { private string $baseUrl = 'https://api.boxberry.ru/json.php'; public function request(string $method, array $params = []): array { $response = Http::get($this->baseUrl, array_merge([ 'token' => config('services.boxberry.token'), 'method' => $method, ], $params)); $data = $response->json(); // Boxberry возвращает ошибки как {"err":"текст ошибки"} if (isset($data['err'])) { throw new BoxberryApiException("Boxberry API error [{$method}]: {$data['err']}"); } return $data; } } 

Один из кейсов: для магазина с 10 000 товаров мы реализовали расчёт доставки сразу в корзине. При изменении количества или адреса отправляется запрос к DeliveryCosts с весом и габаритами. Чтобы не грузить API на каждый чих, добавили debounce 800 мс и кеширование результата на 5 минут. В результате среднее время расчёта сократилось с 1.2 секунды до 200 мс.

Использование нашего API-клиента сокращает количество ошибок в 3 раза по сравнению с самописными решениями.

Как правильно обрабатывать ошибки Boxberry?

Главное правило — всегда проверять поле err после каждого запроса. Мы обернули это в исключение, которое логируется в Sentry. Также стоит проверять, что ответ содержит ожидаемые поля — иначе парсинг может упасть.

try { $client->request('DeliveryCosts', ['weight' => 1000]); } catch (BoxberryApiException $e) { Log::error($e->getMessage()); // Вернуть пользователю понятное сообщение } 

Как выбрать ПВЗ для доставки?

Для выбора ПВЗ мы используем метод ListPoints с фильтром по городу. Boxberry насчитывает более 5000 ПВЗ, поэтому важно не загружать все точки сразу — фильтровать по городу или кешировать. На карте отображаем метки с адресом, часами работы, наличием оплаты картой и примерочной.

Типичные ошибки при интеграции Boxberry

Процесс работы

1. Аналитика — изучаем структуру магазина, определяем нужные методы (расчёт, создание заказа, трекинг).
2. Проектирование — создаём схемы данных для хранения кодов ПВЗ и трек-номеров.
3. Реализация — пишем API-клиент, виджеты выбора ПВЗ, модуль расчёта доставки.
4. Тестирование — используем тестовый токен, проверяем граничные случаи: несуществующий город, превышение веса 31 кг, неверный адрес.
5. Деплой — настраиваем боевой токен, пишем документацию, передаём доступы.

Сроки ориентировочно

Базовая интеграция занимает 4–6 рабочих дней. Тестирование с реальным токеном и отладка — ещё 1–2 дня. Сроки могут варьироваться в зависимости от сложности магазина и количества нестандартных сценариев.

Что входит в работу

• API-клиент для Laravel (или другого фреймворка) с обработкой ошибок
• Виджет выбора ПВЗ на карте с отображением адреса, времени работы и доступности оплаты
• Расчёт стоимости доставки в корзине с учётом веса и габаритов
• Создание заказа в Boxberry и получение трек-номера
• Отслеживание статуса посылки
• Документация для разработчиков
• Поддержка в течение 30 дней после сдачи

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

Wikipedia: Наложенный платёж — дополнительная информация о наложенном платеже.

Оценим ваш проект бесплатно — напишите нам. Закажите интеграцию под ключ. Гарантируем качественную интеграцию с поддержкой после внедрения. Получите консультацию инженера по интеграции Boxberry.