Інтеграція 1С-Bitrix зі службою доставки DostavkaBy (Беларусь)
DostavkaBy — білоруський сервіс кур'єрської доставки, орієнтований на інтернет-торговлю в РБ. Доставка по Мінську та регіонах, підтримка накладеного платежу, повернення. Для магазинів, що працюють на білоруському ринку, DostavkaBy — одна з локальних альтернатив крупним операторам.
API DostavkaBy
DostavkaBy надає REST API для партнерів. Документація та реквізити надаються при укладанні договору. Авторизація — Basic Auth або токен залежно від версії API. Формат — JSON.
Базові операції:
- Створення заявки на доставку
- Отримання статусу заявки
- Розрахунок вартості
- Отримання трекінгу
- Скасування/зміна заявки
Модуль доставки у Bitrix
Клас успадковує \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 Bitrix.
Адресація. Беларусь не використовує систему ФІАС/КЛАДР. Адреси — вільної строкою або через власні класифікатори служби доставки. У деяких випадках достатньо передати city + address строкою.
Накладений платіж. Операція стандартна для ринку РБ. При накладеному платежі DostavkaBy збирає гроші з покупця і переводить магазину за вирахуванням комісії за розписанням (зазвичай раз на тиждень).
Розрахунок вартості
У calculateConcrete() запитуємо вартість доставки для адреси одержувача. Мінімальні параметри розрахунку: місто доставки, вага посилки, тип доставки (кур'єр). Додатково — оголошена вартість, розміри (впливають на вартість при негабаритних посилках).
Якщо отримано HTTP 200 з ціною — повертаємо в об'єкт CalculationResult. Якщо адреса поза зоною покриття або API недоступна — повертаємо помилку без блокування оформлення замовлення (покупець видить «доставка недоступна для вашої адреси»).
Створення та управління заявками
Заявки створюються автоматично при підтвердженні замовлення (хук на подію OnSaleStatusOrder) або вручну менеджером. У карточці замовлення в адміністративній частині додаємо блок «Доставка DostavkaBy» з кнопками:
- «Створити заявку» (якщо ще не створена)
- «Показати статус»
- «Розпечатати етикетку»
- «Скасувати заявку»
Ідентифікатор заявки DostavkaBy зберігається в b_sale_order_props як користувацька властивість DOSTAVKA_BY_ID.
Синхронізація статусів
При невеликому обсязі замовлень (до 50–100 на день) достатньо polling: агент Bitrix кожні 30 хвилин перевіряє статуси активних заявок. При більшому обсязі — настроюємо вебхуки: DostavkaBy надсилає сповіщення при зміні статусу.
Типовий маппінг статусів:
| Статус DostavkaBy | Статус замовлення Bitrix |
|---|---|
| Нова | Передано в доставку |
| Прийнята кур'єром | У пути |
| Доставлена | Доставлено |
| Скасована | Скасовано |
| Повернення | Повернення |
Інтеграція з оплатою
Для магазинів з накладеним платежем важлива сверка: скільки зібрав DostavkaBy і коли перевів. Реалізуємо звіт в адміністративній частині: виконання замовлень з накладеним платежем за період з сумами та датами переводу. Дані беремо через API DostavkaBy (якщо є метод виконання реєстру виплат) або ведемо вручну.
Графік
| Масштаб | Компоненти | Тривалість |
|---|---|---|
| Базова інтеграція | Розрахунок + створення заявок + статуси | 3–4 дні |
| + Інтерфейс в адміні | Блок управління заявкою в замовленні | +1–2 дні |
| + Сверка накладеного платежу | Звіт + сверка з виплатами | +2 дні |