Интеграция 1С-Битрикс со службой доставки DostavkaBy (Беларусь)
DostavkaBy — белорусский сервис курьерской доставки, ориентированный на интернет-торговлю в РБ. Доставка по Минску и регионам, поддержка наложенного платежа, возвраты. Для магазинов, работающих на белорусском рынке, DostavkaBy — одна из локальных альтернатив крупным операторам.
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— адрес склада или точки забора
Особенности белорусской логистики
Работа с белорусскими службами доставки имеет специфику, одинаковую для большинства операторов РБ:
Формат телефонов. Все номера — +375XXXXXXXXX. Нормализуем входящий номер перед отправкой: убираем пробелы, скобки, дефисы, добавляем 375 если введён в локальном формате 80XXXXXXXX.
Валюта BYN. Все суммы в белорусских рублях. При мультивалютном магазине — конвертация через CCurrencyRates Битрикс.
Адресация. Беларусь не использует систему ФИАС/КЛАДР. Адреса — свободной строкой или через собственные классификаторы службы доставки. В некоторых случаях достаточно передать city + address строкой.
Наложенный платёж. Операция стандартная для рынка РБ. При наложенном платеже DostavkaBy собирает деньги с покупателя и переводит магазину за вычетом комиссии по расписанию (обычно раз в неделю).
Расчёт стоимости
В calculateConcrete() запрашиваем стоимость доставки для адреса получателя. Минимальные параметры расчёта: город доставки, вес посылки, тип доставки (курьер). Дополнительно — объявленная ценность, размеры (влияют на стоимость при негабаритных посылках).
Если получен HTTP 200 с ценой — возвращаем в объект CalculationResult. Если адрес вне зоны покрытия или API недоступен — возвращаем ошибку без блокировки оформления заказа (покупатель видит «доставка недоступна для вашего адреса»).
Создание и управление заявками
Заявки создаются автоматически при подтверждении заказа (хук на событие OnSaleStatusOrder) или вручную менеджером. В карточке заказа в административной части добавляем блок «Доставка DostavkaBy» с кнопками:
- «Создать заявку» (если ещё не создана)
- «Показать статус»
- «Распечатать этикетку»
- «Отменить заявку»
Идентификатор заявки DostavkaBy сохраняется в b_sale_order_props как пользовательское свойство DOSTAVKA_BY_ID.
Синхронизация статусов
При небольшом объёме заказов (до 50–100 в день) достаточно polling: агент Битрикс раз в 30 минут проверяет статусы активных заявок. При большем объёме — настраиваем вебхуки: DostavkaBy отправляет уведомления при смене статуса.
Типичный маппинг статусов:
| Статус DostavkaBy | Статус заказа Битрикс |
|---|---|
| Новая | Передан в доставку |
| Принята курьером | В пути |
| Доставлена | Доставлен |
| Отменена | Отменён |
| Возврат | Возврат |
Интеграция с оплатой
Для магазинов с наложенным платежом важна сверка: сколько собрал DostavkaBy и когда перевёл. Реализуем отчёт в административной части: выгрузка заказов с наложенным платежом за период с суммами и датами перевода. Данные берём через API DostavkaBy (если есть метод выгрузки реестра выплат) или ведём вручную.
Сроки
| Масштаб | Состав | Срок |
|---|---|---|
| Базовая интеграция | Расчёт + создание заявок + статусы | 3–4 дня |
| + Интерфейс в админке | Блок управления заявкой в заказе | +1–2 дня |
| + Сверка наложенного платежа | Отчёт + сверка с выплатами | +2 дня |