Інтеграція 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 у вашому магазині.