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

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

Укрпошта — державний поштовий оператор України. Як і Пошта Росії, незамінна для доставки в малі міста та села. API сучасне (REST, OAuth 2.0), але має ряд специфічних вимог: обов'язкова нормалізація адрес, суворі формати даних. Для магазинів з охопленням всієї України інтеграція з Укрпоштою часто йде паралельно з Новою Поштою.

API Укрпошти: OAuth 2.0

Базовий URL: https://www.ukrposhta.ua/ecom/0.0.1/. Авторизація: Bearer-токен. Токен отримується через OAuth 2.0 з типом grant client_credentials.

private function getToken(): string
{
    $cacheKey = 'ukrposhta_token';
    $cached = \Bitrix\Main\Data\Cache::createInstance();

    if ($cached->startDataCache(3000, $cacheKey, '/ukrposhta')) {
        $ch = curl_init('https://www.ukrposhta.ua/oauth/token');
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => http_build_query([
                'grant_type'    => 'client_credentials',
                'client_id'     => $this->clientId,
                'client_secret' => $this->clientSecret,
            ]),
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $response = json_decode(curl_exec($ch), true);
        $token = $response['access_token'] ?? '';
        $cached->endDataCache(['token' => $token]);
    }

    return $cached->getVars()['token'];
}

Токен кешується на 3000 секунд (TTL токена — 3600 секунд, залишаємо запас).

Розрахунок вартості

public function calcPostcardPrice(
    string $fromPostcode,
    string $toPostcode,
    int $weightGram,
    string $type = 'PARCEL'
): float {
    $response = $this->apiGet('/delivery360/calculate', [
        'from_postcode' => $fromPostcode,
        'to_postcode'   => $toPostcode,
        'weight'        => $weightGram,
        'length'        => 300,
        'width'         => 200,
        'height'        => 100,
        'type'          => $type, // PARCEL, DOCUMENT, LETTER
    ]);

    return (float)($response['deliveryPrice'] ?? 0);
}

Розрахунок вимагає індексів відправки та доставки. Для отримання індексу за адресою використовується метод пошуку адреси: GET /addresses/search?street=...&city=....

Нормалізація та пошук адреси

public function searchAddress(string $city, string $street, string $house = ''): array
{
    $response = $this->apiGet('/addresses/search', [
        'street'       => $street,
        'city'         => $city,
        'houseNumber'  => $house,
        'language'     => 'UA',
    ]);

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

У відповіді приходить масив адрес з postcode — індексом, який потрібен для розрахунку та створення відправлення. Якщо адресу не знайдено або вона неоднозначна — показуємо покупцю список варіантів для уточнення.

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

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

    $addressRef = $props->getItemByOrderPropertyCode('UKRPOSHTA_ADDRESS_ID')?->getValue();

    $payload = [
        'type'           => 'PARCEL',
        'sender'         => [
            'name'    => $this->getOption('SENDER_NAME'),
            'phone'   => $this->getOption('SENDER_PHONE'),
            'postcode' => $this->getOption('SENDER_POSTCODE'),
        ],
        'recipient'      => [
            'name'        => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone'       => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'postcode'    => $props->getItemByOrderPropertyCode('UKRPOSHTA_POSTCODE')?->getValue(),
            'addressId'   => $addressRef,
        ],
        'weight'         => $this->getWeight($shipment),
        'length'         => 300,
        'width'          => 200,
        'height'         => 100,
        'declaredPrice'  => $order->getPrice(),
        'postPay'        => 0, // накладений платіж (0 = без НП)
    ];

    $response = $this->apiPost('/shipments', $payload);
    $barcode = $response['barcode'] ?? '';

    $props->getItemByOrderPropertyCode('UKRPOSHTA_BARCODE')?->setValue($barcode);
    $order->save();

    return $barcode;
}

Трекінг

public function trackShipment(string $barcode): array
{
    $response = $this->apiGet('/statuses/shipments', [
        'barcode' => $barcode,
    ]);

    $event = end($response['eventHistory'] ?? []);
    return [
        'status'    => $event['eventName'] ?? '',
        'date'      => $event['date'] ?? '',
        'postcode'  => $event['postcode'] ?? '',
    ];
}

Push-сповіщень немає. Polling агентом раз на 4–6 годин (терміни доставки Укрпошти — 2–7 днів, частий polling є надлишковим).

Накладений платіж

Укрпошта підтримує накладений платіж (postPay). Сума передається в гривнях. При доставці покупець сплачує суму, Укрпошта утримує комісію і переводить залишок магазину за реквізитами з договору.

Терміни