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

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

Ми часто зустрічаємо магазини, яким потрібно доставляти товари в населені пункти, де немає відділень Нової Пошти. UkrPoshta — єдиний державний оператор, що покриває всю Україну, включаючи села та маленькі міста. Після реструктуризації API став сучасним: REST з авторизацією за JWT. Однак розробники часто спотикаються на обов'язковому послідовному створенні об'єктів (адреса → клієнт → відправлення) та на парсингу адресного рядка. Розберемо реалізацію на Бітрікс. Кожен етап потребує акуратного підходу, інакше інтеграція може затягнутися на тижні. Ми накопичили досвід більш ніж з 10 проектами, де UkrPoshta була основним перевізником, і готові поділитися деталями.

Як авторизуватися в API UkrPoshta?

Авторизація виконується через Bearer-токен в заголовку Authorization: Bearer <token>. Щоб отримати токен, відправте POST-запит на /api/2.0/client-token, передавши ключ з особистого кабінету. Базовий URL API: https://www.ukrposhta.ua/ecom/0.0.1. Токен має обмежений термін дії — його потрібно періодично оновлювати. В Бітрікс зручно зберігати його в налаштуваннях модуля та оновлювати через агент. Таймаут токена — 30 хвилин, тому агент має запускатися не рідше ніж раз на 25 хвилин. Перевірте, щоб у налаштуваннях хостингу не було обмеження на виконання агентів.

Створення відправлення

UkrPoshta вимагає послідовного створення об'єктів: адреса → клієнт → відправлення. Нижче приклад обробника на PHP для компонента bitrix:sale.order.ajax:

class UkrPoshtaHandler
{
    public function createShipment(\Bitrix\Sale\Shipment $shipment): string
    {
        $order = $shipment->getOrder();
        $props = $order->getPropertyCollection();

        // Шаг 1: создать адрес получателя
        $addr = $this->apiPost('/addresses', [
            'postcode'    => $props->getItemByOrderPropertyCode('ZIP')?->getValue(),
            'city'        => $props->getItemByOrderPropertyCode('CITY')?->getValue(),
            'street'      => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'houseNumber' => '1',
        ]);
        $addressUuid = $addr['uuid'];

        // Шаг 2: создать получателя
        $client = $this->apiPost('/clients', [
            'firstName'   => $this->parseFirstName($props),
            'lastName'    => $this->parseLastName($props),
            'phoneNumber' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'type'        => 'INDIVIDUAL',
            'addressId'   => $addressUuid,
        ]);
        $clientUuid = $client['uuid'];

        // Шаг 3: создать отправление
        $response = $this->apiPost('/shipments', [
            'sender'          => ['uuid' => $this->getOption('SENDER_UUID')],
            'recipient'       => ['uuid' => $clientUuid],
            'deliveryType'    => 'W2D',
            'weight'          => max((int)$shipment->getWeight(), 20),
            'length'          => (int)$this->getOption('DEFAULT_LENGTH', 20),
            'width'           => (int)$this->getOption('DEFAULT_WIDTH', 20),
            'height'          => (int)$this->getOption('DEFAULT_HEIGHT', 5),
            'declaredPrice'   => (int)round($order->getPrice()),
            'description'     => 'Товар',
            'paidByRecipient' => false,
        ]);

        return $response['uuid'] ?? '';
    }
}

paidByRecipient: false — магазин оплачує доставку. При true — отримувач при врученні. Зверніть увагу: UkrPoshta API повертає помилку, якщо поля houseNumber немає. В реальному проекті його потрібно брати з властивості замовлення, інакше парсинг може не спрацювати.

Типи доставки

Вибір типу впливає на вартість та терміни доставки. За досвідом, найчастіше використовують W2D для інтернет-магазинів — клієнтам зручніше отримувати вдома.

Як реалізувати трекінг відправлень?

Після створення відправлення збережіть його UUID. Потім налаштуйте агент в Бітрікс, який раз на 3–4 години викликає GET /shipments/{uuid}/statuses. Отримані статуси можна записувати в лог або відображати в адміністративній панелі замовлення. Ось проста реалізація:

// Агент вызывается каждые 3 часа
public function trackShipments(): string
{
    $shipments = \Bitrix\Sale\Shipment::getList([
        'filter' => ['!UKRPOSHTA_UUID' => null, '!=STATUS' => 'DELIVERED']
    ]);
    foreach ($shipments as $shipment) {
        $statuses = $this->apiGet("/shipments/{$shipment['UKRPOSHTA_UUID']}/statuses");
        // Обновляем статус в заказе
        if (!empty($statuses)) {
            \Bitrix\Sale\Order::update($shipment['ORDER_ID'], [
                'UKRPOSHTA_STATUS' => end($statuses)['code']
            ]);
        }
    }
    return 'trackShipments();';
}

Такий підхід дозволяє бачити актуальне положення посилки без ручного оновлення.

Отримання марки

// Печать марки — кнопка в административной части заказа Битрикс
public function getLabel(string $shipmentUuid): string
{
    $response = $this->apiGet("/shipments/{$shipmentUuid}/label");
    return base64_decode($response['pdf_base64'] ?? '');
}

Метод повертає PDF-файл, який можна зберегти або відобразити користувачеві. В адміністративній частині зручно додати кнопку «Друк марки» прямо в картку відвантаження.

Що потрібно знати про міжнародні відправлення?

Для напрямків UA→BY, UA→PL та інших: митна декларація CN22/CN23, обмеження ваги до 30 кг, обов'язковий HS-код товару. Рекомендується додати користувацьку властивість UF_HS_CODE до товарів в інфоблоці та передавати його в декларацію автоматично. Без цього UkrPoshta відхилить запит. Також зверніть увагу: для міжнародних відправлень потрібно вказати код country в адресі отримувача та країни відправлення.

Особливості адресного поля

УкрПошта очікує роздільні поля: вулиця, номер будинку, квартира. В Бітрікс адреса зазвичай зберігається одним рядком. Потрібно або додати окремі поля в форму замовлення, або реалізувати парсинг рядка адреси. Другий підхід дає ~85% точності, перший — надійніший. У наших проектах ми використовуємо кастомну властивість замовлення «Вулиця», «Будинок», «Квартира» — це виключає помилки розпізнавання. Наприклад, при парсингу часто плутається номер будинку з квартирою, особливо в адресах типу «вул. Гагаріна, буд. 10, кв. 5».

Що входить в інтеграцію під ключ

• Налаштування модуля доставки та отримання токенів
• Створення користувацьких властивостей замовлення для роздільної адреси
• Реалізація обробника відправлення з викликом API UkrPoshta
• Формування та друк накладної у форматі PDF
• Налаштування фонового трекінгу (агент з періодичністю 3-4 години)
• Інтеграція митної декларації для міжнародних посилок
• Підготовка документації та передача доступів

Цей список покриває всі типові складності. Ми гарантуємо стабільну роботу обміну та повну підтримку після впровадження. Якщо вам потрібна інтеграція з UkrPoshta — зв'яжіться з нами для оцінки вашого проекту. Отримайте консультацію щодо етапів та термінів, щоб почати без зайвих затримок.

Терміни

Терміни вказані за умови готовності всіх доступів з боку клієнта. В середньому проект займає один тиждень. Ми працюємо на Бітрікс понад 6 років і реалізували більш ніж 10 інтеграцій з українськими поштовими службами. Звертайтеся — допоможемо налаштувати доставку через UkrPoshta у вашому магазині.

Інтеграція доставки: від розрізнених API до єдиного калькулятора за 5 днів

Покупець кидає кошик на етапі доставки — не бачить розрахунку або бачить свідомо невірну ціну. Кожен такий випадок втрачає конверсію. Автоматизація логістики в 1С-Бітрікс вирішує цю проблему: ми підключаємо служби доставки так, щоб ціна показувалася миттєво, а трекінг оновлювався без участі менеджера. Більше 50 реалізованих проєктів з каталогами від 500 до 100 000 SKU, досвід понад 8 років. Середній час підключення однієї транспортної компанії — 4 дні.

Як прискорити підключення служб доставки до 1С-Бітрікс?

Головна складність — не сам виклик API, а адаптація до логіки кожного перевізника. СДЕК, Boxberry, Нова пошта, ПЕК, DPD — у кожного свій формат запиту, тарифікація та обробка помилок. Ми використовуємо готові адаптери під кожну ТК, що скорочує час інтеграції втричі порівняно з реалізацією з нуля. Розгорнутий кейс: інтернет-магазин товарів для дому (15 000 товарів) — підключили СДЕК та Boxberry за 5 днів, автоматизували розрахунок та створення замовлень. Звернення до підтримки з доставки знизилися на 60%, середній чек зріс на 8% за рахунок індикатора безкоштовної доставки.

Чому API кожної транспортної компанії — окремий квест?

СДЕК — об'ємна вага та карта ПВЗ

API v2 (/api/v2/calculator/tarifflist) приймає габарити, вагу та адреси — повертає всі доступні тарифи. Підводні камені: об'ємна вага розраховується за формулою (Д × Ш × В) / 5000. Якщо фізична вага 2 кг, а об'ємна 8 кг — СДЕК бере по об'ємній. Не врахуєте в калькуляторі — покупець побачить одну ціну, а заплатить іншу. Карта ПВЗ завантажується через /deliverypoints. Віджет СДЕК можна вбудувати, але він конфліктує зі стилями Бітрікс — малюємо свою карту на Яндекс.Картах. Автоматичне створення замовлення через /api/v2/orders — при оформленні заявка летить у СДЕК, повертається трек-номер. Друк накладних та етикеток з адмінки — через /api/v2/print/orders. Тарифи: склад-склад, склад-двері, двері-двері, експрес, постамат.

Boxberry — широка мережа ПВЗ в регіонах

Найширша мережа пунктів видачі в малих містах. API простіше, ніж у СДЕК, але є нюанси з післяплатою та частковим викупом. Типові помилки при інтеграції: відсутність фільтрації ПВЗ за ознакою onlyPrepaid → помилки при післяплаті; ігнорування параметра partialReturn → ламає частковий викуп. API повертає код міста у форматі "770000000000" — потрібне маппінг на index міста.

Нова пошта — лідер українського ринку

Для України — обов'язкове підключення Нової пошти через API v2. Розрахунок вартості, створення ЕН, друк накладної, трекінг. Карта відділень з фільтрацією (поштомати, прийом платежів). Асинхронне оновлення статусів через агент Бітрікс кожні 15 хвилин.

ПЕК — важкі вантажі та збір

Коли потрібно відправити диван або обладнання. Розрахунок збірних вантажів, страхування, обрешітка. Доставка до терміналу та від дверей до дверей. Індекси терміналів ПЕК підвантажуємо в інфоблок для автопідстановки.

DPD — експрес-доставка з часовими слотами

DPD по Україні та за кордон. Доставка у вибраний часовий інтервал, повернення підписаних документів. У розрахунку враховуємо об'ємну вагу за формулою (Д×Ш×В)/4000 — відмінність від СДЕК. Документація DPD: volumetric weight factor 4000.

Як об'єднати різні ТК в єдиному калькуляторі?

Використовуємо гібридний підхід: модуль-агрегатор, який маршрутизує запити до різних API та нормалізує відповіді. Він обробляє запити в 5 разів швидше, ніж окремі інтеграції, завдяки паралельним викликам через curl_multi. У відповіді модуля — єдина структура: назва тарифу, ціна, термін, тип доставки. Кешування теговане: при зміні налаштувань модуля очищується лише кеш розрахунку для обраного міста, решта залишається. Подію OnBeforeDeliveryCalculate вішаємо на кастомний обробник — так підміняємо стандартну логіку доставки.

Розрахунок вартості: які граблі зустрічаються?

Автоматичний калькулятор підсумовує фізичну та об'ємну вагу товарів у кошику, додає вагу упаковки, обирає найбільшу. Звучить просто, але:

• Габарити мають бути заповнені у кожного товару. Немає габаритів — немає розрахунку. На каталозі в 10 000 SKU обов'язково знайдуться товари без розмірів — для них заводимо дефолтні значення (наприклад, 0.1×0.1×0.1 м) і попереджаємо менеджера через поштову подію.
• Промоакції та пороги безкоштовної доставки — гнучке налаштування: за сумою замовлення, для VIP-клієнтів, при конкретному способі оплати. Реалізуємо через користувацькі властивості кошика.
• Індикатор «До безкоштовної доставки залишилося N» — проста річ, але піднімає середній чек на 5–12%. Обчислюємо за сумою кошика та найближчим порогом, виводимо в шаблоні кошика.

Як автоматизувати трекінг, самовивіз та кур'єрську доставку?

Трекінг. Автоматичне опитування API транспортних компаній — агент Бітрікс кожні 30 хвилин перевіряє статуси замовлень, у яких STATUS_DELIVERY != 'DELIVERED'. При зміні — оновлення статусу замовлення в системі та повідомлення покупцеві (email, SMS, push). Вбудована сторінка трекінгу в особистому кабінеті — покупцю не потрібно йти на сайт ТК. Карта з поточним місцезнаходженням, прогнозована дата доставки, можливість переадресації.

Самовивіз. Власні точки видачі на карті: адреси, графік, контакти. Пошук найближчої за адресою покупця. Перевірка наявності в реальному часі, бронювання до певної години. QR-код для швидкого отримання та SMS про готовність до видачі.

Кур'єрська доставка. Зони доставки з різною вартістю. 2-годинні слоти, управління розкладом кур'єрів, обмеження замовлень на слот. Доставка день у день — прийом до 14:00, експрес за 2-4 години з націнкою за терміновість. Інтеграція з навігацією для оптимізації маршрутів.

Мультисклад. Декілька складів з адресами та зонами обслуговування. Автоматичний вибір складу відвантаження за адресою покупця — пріоритет найближчому, де є всі товари замовлення. Якщо на одному складі всього немає — розділення замовлення по складах (мультидоставка). Синхронізація залишків через 1С або WMS (CommerceML), використовуємо події OnBeforeBasketAdd для перевірки доступності.

Порівняння транспортних компаній

Етапи підключення служб доставки

1. Аналіз логістики (1–2 дні) — географія, середня вага, обсяг замовлень, інтеграція з 1С. Рекомендуємо комбінацію ТК.
2. Підключення API (3–5 днів на ТК) — налаштування розрахунків, карт ПВЗ, автоматичне створення замовлень через агенти та події.
3. Налаштування трекінгу (1–2 тижні) — агенти оновлення статусів, шаблони повідомлень, сторінка трекінгу.
4. Тестування (2–3 дні) — перевірка на реальних адресах, порівняння тарифів, контроль помилкових розрахунків, навантажувальне тестування.
5. Деплой та навчання (1 день) — вивантаження модуля, передача доступів, навчання менеджерів.
6. Гарантійна підтримка (1 місяць) — виправлення багів, коригування конфігурацій, доналаштування кешування.

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

• Документація зі схемою обміну (логістичні маршрути, тарифні зони).
• Налаштовані доступы до API кожної ТК, ключі, вебхуки.
• Шаблони повідомлень (email, SMS, push) для статусів доставки.
• Навчання менеджерів: робота з адмінкою, друк документів, обробка помилок.
• Півроку технічної підтримки після запуску.

Орієнтовні терміни реалізації

Терміни залежать від кількості ТК, складності каталогу та необхідності інтеграції з 1С/ERP. Вартість розраховується індивідуально — орієнтуйтеся на економію: зниження операційних витрат на доставку до 40% та скорочення звернень до підтримки на 60%. Наприклад, один із клієнтів з магазином електроніки (20 000 товарів) повернув інвестиції за 3 місяці за рахунок зменшення кількості «забутих» замовлень. Середня економія наших клієнтів — 15 000 грн на місяць на логістиці.

Готові прискорити логістику вашого інтернет-магазину? Зв'яжіться з нами — допоможемо підібрати оптимальну комбінацію ТК під ваш асортимент та бюджет. Замовте консультацію — і ми підготуємо пропозицію за 1 робочий день.