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