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

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

Куранти — білоруська кур'єрська служба з фокусом на доставці в Мінську та приміській зоні. Працює з e-commerce, пропонує термінову доставку, доставку до певного часу та можливість примірки перед оплатою (актуально для fashion-магазинів). API надається за договором.

API Курантів

REST API з авторизацією через токен. Документація російською мовою. Базовий URL уточнюється при підключенні (як правило, https://api.kuranty.by/ або адреса, видана менеджером).

private function httpRequest(string $method, string $endpoint, array $body = []): array
{
    $url = rtrim($this->getOption('API_URL'), '/') . '/' . ltrim($endpoint, '/');
    $ch = curl_init($method === 'GET' ? $url . '?' . http_build_query($body) : $url);

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

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

    if ($code >= 400) {
        $err = json_decode($response, true);
        throw new \RuntimeException('Kuranty API: ' . ($err['detail'] ?? $response));
    }

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

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

Куранти розраховують вартість за зонами всередині Мінська та по містах. Зонова модель є типовою для кур'єрських служб великих міст.

public function calcCost(string $address, int $weightGram, string $timeSlot = 'standard'): float
{
    $response = $this->httpRequest('POST', '/tariffs/calculate', [
        'address'   => $address,
        'weight'    => $weightGram / 1000, // г → кг
        'timeSlot'  => $timeSlot, // standard, express, timed
    ]);

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

Типи слотів: standard (стандарт, кілька днів), express (сьогодні), timed (до певного часу). Кожен слот має свою ціну.

Примірка перед оплатою

Характерна особливість Курантів — підтримка примірки. Кур'єр приїжджає з кількома позиціями (наприклад, три розміри однієї моделі), покупець примірює, залишає потрібне, повертає решту. Це вимагає спеціальної логіки в заявці:

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

    $isFitting = $props->getItemByOrderPropertyCode('FITTING')?->getValue() === 'Y';

    $payload = [
        'externalId'  => (string)$order->getId(),
        'type'        => $isFitting ? 'fitting' : 'standard',
        'timeSlot'    => $props->getItemByOrderPropertyCode('DELIVERY_SLOT')?->getValue() ?? 'standard',
        'recipient' => [
            'name'    => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone'   => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
        ],
        'items'       => $this->buildItems($order),
        'payment' => [
            'type'   => $isFitting ? 'after_fitting' : 'prepaid',
            'amount' => $order->getPrice(),
        ],
    ];

    $response = $this->httpRequest('POST', '/orders', $payload);
    $orderNum = (string)($response['number'] ?? '');

    $props->getItemByOrderPropertyCode('KURANTY_ORDER')?->setValue($orderNum);
    $order->save();

    return $orderNum;
}

При типі fitting оплата відбувається після примірки — payment.type: after_fitting. Магазин отримує від кур'єра лише оплату за прийняті товари.

Вибір часового слота

На сторінці оформлення замовлення покупцю відображається вибір слота:

// AJAX-запит для отримання доступних слотів
fetch('/bitrix/services/main/ajax.php?action=kuranty_slots', {
    method: 'POST',
    body: JSON.stringify({ date: selectedDate }),
})
.then(r => r.json())
.then(data => {
    data.slots.forEach(slot => {
        // Додаємо кнопки вибору слота
    });
});

На стороні сервера 1С-Бітрікс: AJAX-компонент запитує доступні слоти у API Курантів та повертає їх фронтенду. Вибраний слот зберігається у властивості замовлення DELIVERY_SLOT.

Трекінг

public function getOrderStatus(string $orderNum): array
{
    $response = $this->httpRequest('GET', '/orders/' . $orderNum);
    return [
        'status'      => $response['status'] ?? '',
        'courierName' => $response['courier']['name'] ?? '',
        'eta'         => $response['eta'] ?? '',
    ];
}

Обмеження

Куранти працюють у Мінську та найближчому передмісті. Для інших міст потрібна інша служба доставки. У 1С-Бітрікс обмеження за зоною доставки реалізується через стандартний механізм «Місцезнаходження».

Терміни