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

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

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

API Курантов

REST API с JWT-авторизацией. Базовый URL: https://api.kuranty.by/v2. Токен получается через POST /auth/token с логином и паролем, живёт 24 часа.

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

• POST /delivery/cost — расчёт стоимости
• POST /delivery/create — создание доставки
• GET /delivery/{uuid}/status — статус доставки
• GET /pickup-points — список ПВЗ

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

class KurantyHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    private function getAuthToken(): string
    {
        $cache = \Bitrix\Main\Data\Cache::createInstance();

        if ($cache->initCache(3600 * 23, 'kuranty_token', '/kuranty/')) {
            return $cache->getVars();
        }

        $response = $this->apiPost('/auth/token', [
            'login'    => $this->getOption('LOGIN'),
            'password' => $this->getOption('PASSWORD'),
        ]);

        $token = $response['token'] ?? '';
        $cache->startDataCache();
        $cache->endDataCache($token);

        return $token;
    }

    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $order  = $shipment->getOrder();
        $props  = $order->getPropertyCollection();

        $city = $this->getOrderCity($props);
        if (!$city) {
            $result->addError(new \Bitrix\Main\Error('Город доставки не определён'));
            return $result;
        }

        $response = $this->apiPost('/delivery/cost', [
            'from_city' => $this->getOption('SENDER_CITY'),
            'to_city'   => $city,
            'weight'    => max($shipment->getWeight() / 1000, 0.1),
            'sum'       => round($order->getPrice()),
            'type'      => $this->getOption('DELIVERY_TYPE', 'pickup'), // pickup или courier
        ], $this->getAuthToken());

        if (!empty($response['cost'])) {
            $result->setDeliveryPrice((float)$response['cost']);
            $days = $response['days_min'] . '–' . $response['days_max'];
            $result->setPeriodDescription("{$days} дней");
        }

        return $result;
    }
}

Создание доставки

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

    $payload = [
        'external_id'   => 'bx_' . $order->getId(),
        'type'          => $this->getOption('DELIVERY_TYPE', 'pickup'),
        'from_city'     => $this->getOption('SENDER_CITY'),
        'to_city'       => $this->getOrderCity($props),
        'pickup_point'  => $props->getItemByOrderPropertyCode('KURANTY_POINT')?->getValue(),
        'recipient'     => [
            'name'  => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        ],
        'address'       => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
        'weight'        => max($shipment->getWeight() / 1000, 0.1),
        'sum'           => round($order->getPrice()),
        'cod'           => $order->isPaid() ? 0.0 : round($order->getPrice()),
        'comment'       => 'Заказ #' . $order->getId(),
    ];

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

ПВЗ на сайте

public function getPickupPoints(?string $city = null): array
{
    $cacheKey = 'kuranty_pvz_' . md5((string)$city);
    $cache    = \Bitrix\Main\Data\Cache::createInstance();

    if ($cache->initCache(3600 * 6, $cacheKey, '/kuranty/')) {
        return $cache->getVars();
    }

    $params = $city ? ['city' => $city] : [];
    $points = $this->apiGet('/pickup-points', $params, $this->getAuthToken());

    $cache->startDataCache();
    $cache->endDataCache($points ?? []);

    return $points ?? [];
}

Список ПВЗ обновляется раз в 6 часов. Для отображения на сайте используем Яндекс Карты с кастомными маркерами — координаты (lat, lon) возвращаются в ответе API.

Трекинг

public function getStatus(string $uuid): array
{
    return $this->apiGet("/delivery/{$uuid}/status", [], $this->getAuthToken()) ?? [];
}

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

Сроки