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

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

Европочта — белорусский частный почтовый оператор, работающий с 2002 года. Занимает значительную долю рынка доставки для белорусского e-commerce: широкая сеть пунктов выдачи по всей стране, приемлемые тарифы, доставка до двери. API предоставляется партнёрам — требуется регистрация в системе Европочты.

API Европочты

Европочта использует REST API с авторизацией через логин/пароль (Basic Auth или токен). Базовый URL: https://api.europochta.by/api. Документация предоставляется после регистрации партнёра.

Основные эндпоинты:

• POST /rate/calculate — расчёт стоимости доставки
• POST /order/create — создание заказа
• GET /order/{id}/status — статус заказа
• GET /pvz/list — список ПВЗ

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

class EuropachtaHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $order  = $shipment->getOrder();

        $response = $this->apiPost('/rate/calculate', [
            'from_city'    => $this->getOption('SENDER_CITY'),
            'to_city'      => $this->getOrderCity($shipment),
            'weight'       => max($shipment->getWeight() / 1000, 0.05),
            'declared'     => round($order->getPrice()),
            'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'), // pvz или door
        ]);

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

        return $result;
    }
}

Создание заказа

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

    $payload = [
        'external_id'   => 'bitrix_' . $order->getId(),
        'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'),
        'weight'        => max($shipment->getWeight() / 1000, 0.05),
        'declared'      => round($order->getPrice()),
        'cod'           => $this->getCodAmount($order), // наложенный платёж, 0 если предоплата
        'sender'        => [
            'name'    => $this->getOption('SENDER_NAME'),
            'phone'   => $this->getOption('SENDER_PHONE'),
            'address' => $this->getOption('SENDER_ADDRESS'),
        ],
        'recipient'     => [
            'name'    => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone'   => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'city'    => $this->getOrderCity($shipment),
            'pvz_id'  => $props->getItemByOrderPropertyCode('EUROPOCHTA_PVZ')?->getValue(),
        ],
        'items'         => $this->buildItems($shipment),
    ];

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

Поле cod — сумма наложенного платежа. Если заказ предоплачен, передаём 0. Если наложенный платёж — передаём полную сумму заказа (Европочта взыскивает с получателя и перечисляет магазину).

ПВЗ на сайте

public function getPvzList(string $city): array
{
    $cache = \Bitrix\Main\Data\Cache::createInstance();
    $key   = 'europochta_pvz_' . md5($city);

    if ($cache->initCache(3600 * 12, $key, '/europochta/')) {
        return $cache->getVars();
    }

    $response = $this->apiGet('/pvz/list?city=' . urlencode($city));
    $pvz = $response['pvz'] ?? [];

    $cache->startDataCache();
    $cache->endDataCache($pvz);

    return $pvz;
}

Список ПВЗ показываем в выпадающем списке или на карте. При выборе ПВЗ сохраняем pvz_id в свойстве заказа.

Трекинг

Вебхуков нет. Агент Битрикс проверяет статус раз в 3–4 часа:

public function getStatus(string $orderId): string
{
    $response = $this->apiGet("/order/{$orderId}/status");
    return $response['status'] ?? '';
}

Сроки