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

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

Білпошта — державний поштовий оператор Білорусі з покриттям всієї країни. Для e-commerce незамінна там, де кур'єрські служби не працюють: малі міста, агромістечка, районні центри. Білпошта надає API для роботи з відправленнями, але його функціональність більш обмежена порівняно з комерційними перевізниками.

API Білпошти: особливості

Білпошта надає SOAP та REST API через систему «Автоматизований обмін даними» (АОД). Доступ — за договором. REST API (більш новий): https://api.belpost.by/. Авторизація: токен у заголовку Authorization.

private function apiRequest(string $method, string $path, array $payload = []): array
{
    $url = 'https://api.belpost.by' . $path;
    $ch = curl_init($method === 'GET' ? $url . '?' . http_build_query($payload) : $url);

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: ' . $this->getOption('API_TOKEN'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => $method === 'POST' ? json_encode($payload) : null,
    ]);

    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code >= 400) {
        throw new \RuntimeException("Belpost API {$code}: {$body}");
    }

    return json_decode($body, true) ?? [];
}

Індексація адрес та поштові індекси

Ключовий параметр для Білпошти — поштовий індекс отримувача. Білоруська система індексації 6-значна (наприклад, 220036 — Мінськ). API надає пошук об'єктів за адресою:

public function findPostcode(string $city, string $street, string $house): ?string
{
    $cacheKey = 'belpost_idx_' . md5("{$city}_{$street}_{$house}");
    $cached = \Bitrix\Main\Data\Cache::createInstance();

    if ($cached->startDataCache(86400 * 30, $cacheKey, '/belpost')) {
        $result = $this->apiRequest('GET', '/addresses/index', [
            'city'   => $city,
            'street' => $street,
            'house'  => $house,
        ]);
        $index = $result['index'] ?? null;
        $cached->endDataCache(['index' => $index]);
    }

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

Кеш на 30 днів — поштові індекси змінюються вкрай рідко.

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

public function calcCost(
    string $fromIndex,
    string $toIndex,
    int $weightGram,
    string $type = 'PARCEL'
): float {
    $response = $this->apiRequest('POST', '/tariffs/calculate', [
        'type'       => $type, // PARCEL, REGISTERED_LETTER, EMS
        'fromIndex'  => $fromIndex,
        'toIndex'    => $toIndex,
        'weight'     => $weightGram,
        'declared'   => true,
    ]);

    // Білпошта повертає тариф у білоруських копійках
    return ($response['price'] ?? 0) / 100;
}

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

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

    $payload = [
        'type'           => 'PARCEL',
        'category'       => 'ORDINARY',
        'senderName'     => $this->getOption('SENDER_NAME'),
        'senderIndex'    => $this->getOption('SENDER_INDEX'),
        'senderAddress'  => $this->getOption('SENDER_ADDRESS'),
        'senderPhone'    => $this->getOption('SENDER_PHONE'),
        'recipientName'  => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
        'recipientIndex' => $props->getItemByOrderPropertyCode('BELPOST_INDEX')?->getValue(),
        'recipientAddress' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
        'recipientPhone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'weight'         => $this->getWeight($shipment),
        'declaredValue'  => (int)($order->getPrice() * 100), // у копійках
        'cashOnDelivery' => 0,
        'description'    => 'Товар з інтернет-магазину',
    ];

    $response = $this->apiRequest('POST', '/items', $payload);
    $barcode = $response['barcode'] ?? '';

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

    return $barcode;
}

Грошові значення у Білпошті — у білоруських копійках. Аналогічно Казпошті: при розрахунку та створенні відправлення множимо на 100, при відображенні ділимо на 100.

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

Білпошта підтримує накладений платіж. Поле cashOnDelivery — сума у копійках, яку пошта збирає з отримувача. Мінімальна сума НП і комісія уточнюються в договорі.

Трекінг

public function track(string $barcode): array
{
    $response = $this->apiRequest('GET', '/tracking', ['barcode' => $barcode]);
    $events = $response['events'] ?? [];
    $last = end($events);

    return [
        'status'   => $last['name'] ?? '',
        'date'     => $last['date'] ?? '',
        'place'    => $last['place'] ?? '',
    ];
}

Публічний трекінг Білпошти також доступний на track.belpost.by. Агент 1С-Бітрікс запитує статус активних відправлень 1–2 рази на день.

Терміни