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

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

Белпочта — государственный почтовый оператор Республики Беларусь. Несмотря на репутацию медленной государственной структуры, Белпочта остаётся безальтернативным вариантом для доставки в небольшие населённые пункты и сельскую местность Беларуси. API предоставляется юридическим лицам по договору.

API Белпочты

Белпочта предоставляет SOAP и REST API. Рекомендуем работать с REST версией: https://api.belpost.by/api/v1. Авторизация через API-токен в заголовке Authorization: Token <token>.

Основные методы:

• POST /parcel/calculate — расчёт стоимости
• POST /parcel/create — создание посылки
• GET /parcel/{id} — статус посылки
• GET /parcel/{id}/label — получение марки

Расчёт стоимости

class BelposhtaHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();

        $response = $this->apiPost('/parcel/calculate', [
            'from_region' => $this->getOption('SENDER_REGION_CODE'),
            'to_index'    => $this->getRecipientIndex($shipment),
            'weight'      => max((int)($shipment->getWeight()), 50), // граммы, минимум 50г
            'cost'        => round($shipment->getOrder()->getPrice()),
            'payment'     => 'prepaid', // или cod
        ]);

        if (!empty($response['amount'])) {
            $result->setDeliveryPrice((float)$response['amount']);
            $days = $response['delivery_days'] ?? '3–7';
            $result->setPeriodDescription("{$days} дней");
        }

        return $result;
    }

    private function getRecipientIndex(\Bitrix\Sale\Shipment $shipment): string
    {
        $props = $shipment->getOrder()->getPropertyCollection();
        return (string)($props->getItemByOrderPropertyCode('ZIP')?->getValue() ?? '');
    }
}

Почтовый индекс в Беларуси — 6 цифр. Добавляем обязательное поле в форму заказа при выборе Белпочты.

Создание посылки

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

    $payload = [
        'sender'    => [
            'name'    => $this->getOption('SENDER_NAME'),
            'address' => $this->getOption('SENDER_ADDRESS'),
            'phone'   => $this->getOption('SENDER_PHONE'),
        ],
        'recipient' => [
            'name'    => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone'   => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'index'   => $props->getItemByOrderPropertyCode('ZIP')?->getValue(),
            'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
        ],
        'parcel'    => [
            'weight'   => max((int)$shipment->getWeight(), 50),
            'cost'     => round($order->getPrice()),
            'contents' => 'Товар',
        ],
        'payment'   => $this->getPaymentType($order), // prepaid или cod
        'cod_sum'   => $this->getCodSum($order),
    ];

    $response = $this->apiPost('/parcel/create', $payload);
    return (string)($response['parcel_id'] ?? '');
}

Печать марки и трекинг

// Марка в PDF — добавляем в административную часть заказа
public function getLabel(string $parcelId): string
{
    $response = $this->apiGet("/parcel/{$parcelId}/label");
    return base64_decode($response['pdf'] ?? '');
}

// Трекинг — агент раз в 6 часов (Белпочта работает медленно)
public function getStatus(string $parcelId): array
{
    return $this->apiGet("/parcel/{$parcelId}") ?? [];
}

Особенности

• Минимальный вес: 50 г. Товары весом менее 50 г оформляются как «мелкий пакет», другой тариф
• Международная доставка: Белпочта — участник UPU, отправка в страны СНГ и дальнее зарубежье. Таможенные декларации CN22/CN23 формируются через отдельный метод API
• Сроки: доставка в пределах Беларуси 3–7 рабочих дней, в отдалённые районы до 10 дней
• Наложенный платёж: поддерживается, перечисление раз в неделю

Сроки работ