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