Интеграция 1С-Битрикс со службой доставки DostavkaBy (Беларусь)
Вы открываете интернет-магазин для Беларуси и сталкиваетесь с вызовом: как подключить надёжную и автоматизированную доставку? Битрикс из коробки не знает локальных операторов, а ручной ввод заказов в личный кабинет доставки отнимает до 2 часов в день на одного менеджера. При 50 заказах в месяц это 100 часов потерянного времени на рутину. Ошибки при ручном заполнении — 15% случаев. Задержки, потерянные отправления, конфликты, недовольные клиенты.
DostavkaBy — один из популярных курьерских сервисов РБ с наибольшим охватом. Мы уже 6 лет интегрируем Битрикс с десятками служб доставки в странах СНГ, включая все крупные курьерские сервисы. Для DostavkaBy мы набили шишки: нестандартная авторизация, специфика белорусских адресов, сложная схема наложенного платежа. Делимся накопленным опытом и готовы реализовать полную интеграцию под ключ.
Как мы интегрируем? 5 шагов
- Получаем API-ключи от DostavkaBy и настраиваем параметры отправителя.
- Разрабатываем кастомный класс обработчика, наследующий
\Bitrix\Sale\Delivery\Services\Base. - Подключаем события автоматического создания заявки при подтверждении заказа.
- Реализуем расчёт стоимости и синхронизацию статусов.
- Тестируем все сценарии: создание, отмена, изменение, наложенный платёж.
API DostavkaBy
DostavkaBy предоставляет REST API для партнёров. Документация и credentials предоставляются при заключении договора. Авторизация — Basic Auth или токен в зависимости от версии API. Формат — JSON.
Базовые операции:
- Создание заявки на доставку
- Получение статуса заявки
- Расчёт стоимости
- Получение трекинга
- Отмена/изменение заявки
Как работает модуль доставки в Битрикс?
Класс наследует \Bitrix\Sale\Delivery\Services\Base. Параметры в b_sale_delivery_service_params:
-
DOSTAVKA_API_KEY— ключ API -
SENDER_NAME— название отправителя -
SENDER_PHONE— телефон отправителя -
SENDER_ADDRESS— адрес склада или точки забора
По документации Битрикс, разработка собственного обработчика — стандартная практика.
Типичные ошибки при настройке
- Неверный формат API-ключа (проверьте регистр).
- Отсутствие нормализации телефона: в Беларуси номера должны быть в формате +375XXXXXXXXX.
- Неправильная валюта: все суммы в BYN, при мультивалютности нужна конвертация.
Особенности белорусской логистики
Формат телефонов. Все номера — +375XXXXXXXXX. Нормализуем входящий номер перед отправкой: убираем пробелы, скобки, дефисы, добавляем 375 если введён в локальном формате 80XXXXXXXX.
Валюта BYN. Все суммы в белорусских долларах. При мультивалютном магазине — конвертация через CCurrencyRates Битрикс.
Адресация. Беларусь не использует ФИАС/КЛАДР. Адреса — свободной строкой или через собственные классификаторы службы доставки. В некоторых случаях достаточно передать city + address строкой.
Наложенный платёж. Операция стандартная для рынка РБ. При наложенном платеже DostavkaBy собирает деньги с покупателя и переводит магазину за вычетом комиссии по расписанию (обычно раз в неделю).
Почему наложенный платёж требует отдельной интеграции?
Для магазинов с наложенным платежом критична сверка: сколько собрал DostavkaBy и когда перевёл. Без автоматизации менеджеры вынуждены вручную сопоставлять данные из личного кабинета доставки и заказов Битрикс. Мы реализуем отчёт в административной части: выгрузка заказов с наложенным платежом за период с суммами и датами перевода. Данные берём через API DostavkaBy (если есть метод выгрузки реестра выплат) или ведём полуавтоматически.
Как синхронизировать статусы заказов?
При небольшом объёме заказов (до 100 в день) достаточно polling: агент Битрикс раз в 30 минут проверяет статусы активных заявок. При большем объёме — настраиваем вебхуки: DostavkaBy отправляет уведомления при смене статуса.
Типичный маппинг статусов:
| Статус DostavkaBy | Статус заказа Битрикс |
|---|---|
| Новая | Передан в доставку |
| Принята курьером | В пути |
| Доставлена | Доставлен |
| Отменена | Отменён |
| Возврат | Возврат |
Что входит в работу по интеграции?
Мы предоставляем полный комплекс работ:
- Разработка кастомного класса обработчика доставки, наследующего
Base - Настройка API-ключей и параметров отправителя
- Создание событий для автоматического создания заявок при подтверждении заказа
- Интеграция с платежной системой учёта наложенного платежа
- Тестирование всех сценариев: расчёт, создание, отмена, смена статусов
- Передача документации и обучение менеджеров работе с блоком управления заявками
- Гарантия работоспособности интеграции в течение 30 дней после сдачи
Расчёт стоимости
В calculateConcrete() запрашиваем стоимость доставки для адреса получателя. Минимальные параметры расчёта: город доставки, вес посылки, тип доставки (курьер). Дополнительно — объявленная ценность, размеры (влияют на стоимость при негабаритных посылках).
Если получен HTTP 200 с ценой — возвращаем в объект CalculationResult. Если адрес вне зоны покрытия или API недоступен — возвращаем ошибку без блокировки оформления заказа (покупатель видит «доставка недоступна для вашего адреса»).
Создание и управление заявками
Заявки создаются автоматически при подтверждении заказа (хук на событие OnSaleStatusOrder) или вручную менеджером. В карточке заказа в административной части добавляем блок «Доставка DostavkaBy» с кнопками:
- «Создать заявку» (если ещё не создана)
- «Показать статус»
- «Распечатать этикетку»
- «Отменить заявку»
Идентификатор заявки DostavkaBy сохраняется в b_sale_order_props как пользовательское свойство DOSTAVKA_BY_ID.
Сроки
| Масштаб | Состав | Срок |
|---|---|---|
| Базовая интеграция | Расчёт + создание заявок + статусы | 3–4 дня |
| + Интерфейс в админке | Блок управления заявкой в заказе | +1–2 дня |
| + Сверка наложенного платежа | Отчёт + сверка с выплатами | +2 дня |
За 6 лет мы реализовали более 50 интеграций с различными службами доставки, включая DostavkaBy. Автоматизация сокращает время на обработку заказа в 3 раза, а количество ошибок — до нуля. Свяжитесь с нами для бесплатной оценки проекта. Или закажите консультацию — расскажем детали.
Подробнее о документации Битрикс по службам доставки.