Інтеграція 1С-Бітрікс зі службою доставки DostavkaBy (Білорусь)

Ви відкриваєте інтернет-магазин для Білорусі та стикаєтеся з викликом: як підключити надійну та автоматизовану доставку? Бітрікс з коробки не знає локальних операторів, а ручне введення замовлень в особистий кабінет доставки забирає до 2 годин на день на одного менеджера. При 50 замовленнях на місяць це 100 годин втраченого часу на рутину. Помилки при ручному заповненні — 15% випадків. Затримки, втрачені відправлення, конфлікти, незадоволені клієнти.

DostavkaBy — один із популярних кур'єрських сервісів РБ з найбільшим охопленням. Ми вже 6 років інтегруємо Бітрікс із десятками служб доставки в країнах СНД, включаючи всі великі кур'єрські сервіси. Для DostavkaBy ми набили ґуль: нестандартна авторизація, специфіка білоруських адрес, складна схема накладеного платежу. Ділимося накопиченим досвідом та готові реалізувати повну інтеграцію під ключ.

Як ми інтегруємо? 5 кроків

1. Отримуємо API-ключі від DostavkaBy та налаштовуємо параметри відправника.
2. Розробляємо кастомний клас обробника, що успадковує \Bitrix\Sale\Delivery\Services\Base.
3. Підключаємо події автоматичного створення заявки при підтвердженні замовлення.
4. Реалізуємо розрахунок вартості та синхронізацію статусів.
5. Тестуємо всі сценарії: створення, скасування, зміна, накладений платіж.

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 надсилає повідомлення при зміні статусу.

Типовий мапінг статусів:

Що входить в роботу з інтеграції?

Ми надаємо повний комплекс робіт:

• Розробка кастомного класу обробника доставки, що успадковує Base
• Налаштування API-ключів та параметрів відправника
• Створення подій для автоматичного створення заявок при підтвердженні замовлення
• Інтеграція з платіжною системою обліку накладеного платежу
• Тестування всіх сценаріїв: розрахунок, створення, скасування, зміна статусів
• Передача документації та навчання менеджерів роботі з блоком управління заявками
• Гарантія працездатності інтеграції протягом 30 днів після здачі

Розрахунок вартості

У calculateConcrete() запитуємо вартість доставки для адреси отримувача. Мінімальні параметри розрахунку: місто доставки, вага посилки, тип доставки (кур'єр). Додатково — оголошена цінність, розміри (впливають на вартість при негабаритних посилках).

Якщо отримано HTTP 200 з ціною — повертаємо в об'єкт CalculationResult. Якщо адреса поза зоною покриття або API недоступний — повертаємо помилку без блокування оформлення замовлення (покупець бачить «доставка недоступна для вашої адреси»).

Створення та управління заявками

Заявки створюються автоматично при підтвердженні замовлення (хук на подію OnSaleStatusOrder) або вручну менеджером. У картці замовлення в адміністративній частині додаємо блок «Доставка DostavkaBy» з кнопками:

• «Створити заявку» (якщо ще не створена)
• «Показати статус»
• «Роздрукувати етикетку»
• «Скасувати заявку»

Ідентифікатор заявки DostavkaBy зберігається в b_sale_order_props як користувацька властивість DOSTAVKA_BY_ID.

Терміни

За 6 років ми реалізували понад 50 інтеграцій з різними службами доставки, включаючи DostavkaBy. Автоматизація скорочує час на обробку замовлення в 3 рази, а кількість помилок — до нуля. Зв'яжіться з нами для безкоштовної оцінки проєкту. Або замовте консультацію — розповімо деталі.

Детальніше про документацію Бітрікс щодо служб доставки.