Интеграция 1С-Битрикс со службой доставки UkrPoshta (Украина)

Интеграция 1С-Битрикс со службой доставки UkrPoshta (Украина)

УкрПошта — государственный почтовый оператор Украины. Актуальна для небольших городов и сельской местности, где у Новой Почты нет отделений, а также для международных отправлений. После реструктуризации API стал современным: REST + JWT.

API UkrPoshta

Авторизация: Bearer-токен в заголовке Authorization: Bearer <token>. Токен получается через POST /api/2.0/client-token с ключом из личного кабинета. Базовый URL: https://www.ukrposhta.ua/ecom/0.0.1.

Основные операции:

• POST /addresses — создать адрес
• POST /clients — создать клиента
• POST /shipments — создать отправление
• GET /shipments/{uuid}/statuses — трекинг

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

UkrPoshta требует последовательного создания объектов: адрес → клиент → отправление:

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 — получатель при вручении.

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

Получение марки и трекинг

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

// Трекинг — агент Битрикс раз в 3–4 часа
public function getStatuses(string $shipmentUuid): array
{
    return $this->apiGet("/shipments/{$shipmentUuid}/statuses") ?? [];
}

Особенности международных отправлений

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

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

УкрПошта ожидает раздельные поля: улица, номер дома, квартира. В Битрикс адрес обычно хранится одной строкой. Нужно либо добавить отдельные поля в форму заказа, либо реализовать парсинг строки адреса. Второй подход даёт ~85% точности, первый — надёжнее.

Сроки