Інтеграція 1С-Бітрікс зі службою доставки Куранти (Білорусь)
Інтеграція служби доставки Куранти з 1С-Бітрікс — завдання, з яким стикаються білоруські інтернет-магазини, коли стандартні модулі не підходять. API Куранти вимагає JWT-авторизації та коректної обробки статусів. Наша команда реалізувала кілька таких інтеграцій — від простого калькулятора до повного циклу з ПВЗ та трекінгом. Розповідаємо, як це зробити правильно і що важливо врахувати.
Чому Куранти обирають для доставки в Білорусі?
Куранти — білоруська логістична компанія, що спеціалізується на кур'єрській доставці та мережі пунктів видачі замовлень по всій країні. Порівняно з великими федеральними операторами, Куранти пропонує гнучкіші тарифи для середнього та малого e-commerce. Наприклад, доставка по Мінську часто обходиться значно дешевше, а терміни — на 1 день швидше, ніж у традиційних поштових служб. API надається партнерам через особистий кабінет після укладення договору.
Як працює API Куранти?
API — REST з JWT-авторизацією. Базовий URL: https://api.kuranty.by/v2. Токен отримується через POST /auth/token з логіном та паролем, живе 24 години. Ми кешуємо токен на 23 години, щоб не смикати API при кожному розрахунку.
Основні методи:
-
POST /delivery/cost— розрахунок вартості -
POST /delivery/create— створення доставки -
GET /delivery/{uuid}/status— статус доставки -
GET /pickup-points— список ПВЗ
Розрахунок вартості
Реалізуємо клас-обробник, що успадковує \Bitrix\Sale\Delivery\Services\Base. У методі calculateConcrete отримуємо місто отримувача з властивостей замовлення, відправляємо запит з вагою та сумою замовлення. Відповідь містить вартість та терміни доставки.
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;
}
}
Важливий нюанс: якщо місто доставки не визначено (наприклад, користувач не вибрав населений пункт), повертається помилка. На практиці це трапляється рідко, але ми завжди додаємо валідацію на стороні форми оформлення замовлення.
Створення доставки
Після оформлення замовлення необхідно створити доставку в системі Куранти. Метод createDelivery збирає payload: вагу, суму, накладений платіж, адресу та контактні дані. У відповіді отримуємо UUID замовлення в Курантах, який зберігаємо у властивості замовлення.
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'] ?? '');
}
ПВЗ на сайті
Для відображення пунктів видачі на карті використовуємо API /pickup-points. Дані кешуємо на 6 годин — частота оновлення списку ПВЗ у Курантах невисока. Координати (lat, lon) повертаються у відповіді, що дозволяє нанести точки на Яндекс Карти з кастомними маркерами.
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 ?? [];
}
Трекінг
У Куранти немає вебхуків — статус доставки необхідно опитувати вручну. Ми реалізуємо агент Бітрікс, який раз на 2–3 години запитує статус по кожному активному замовленню та оновлює його у властивостях замовлення. Метод getStatus приймає UUID, повертає масив з поточним статусом.
public function getStatus(string $uuid): array
{
return $this->apiGet("/delivery/{$uuid}/status", [], $this->getAuthToken()) ?? [];
}
Що входить у роботу з інтеграції
| Що робимо | Опис |
|---|---|
| Аудит поточної системи | Аналізуємо структуру інфоблоків, властивості замовлення, налаштування доставки |
| Розробка калькулятора | Реалізуємо клас-обробник розрахунку вартості з кешуванням токена |
| Створення замовлень | Пишемо код для відправки замовлення в Куранти після оформлення |
| Відображення ПВЗ | Інтегруємо список пунктів видачі з картою на сайті |
| Трекінг та сповіщення | Налаштовуємо агент для перевірки статусів та відправки листів покупцю |
| Тестування та документація | Перевіряємо всі сценарії, створюємо інструкцію для адміністратора |
Порівняння Куранти з іншими службами доставки Білорусі
| Параметр | Куранти | Європошта | Білпошта |
|---|---|---|---|
| Час доставки по Мінську | 1 день | 1–2 дні | 2–3 дні |
| Час доставки в регіони | 1–3 дні | 2–4 дні | 3–7 днів |
| ПВЗ | 200+ точок | 100+ точок | немає (тільки пошта) |
| API | REST з JWT | REST з ключем | застарілий XML |
Куранти виграє за швидкістю в містах та кількістю ПВЗ. Для інтернет-магазину з великими оборотами вигідніше комбінувати служби.
Терміни реалізації
| Склад | Термін |
|---|---|
| Розрахунок + створення доставки | 3–4 дні |
| + ПВЗ на карті | +2 дні |
| + Трекінг + сповіщення | +2 дні |
| + Накладений платіж | +1 день |
Чому варто замовити інтеграцію у нас?
Наша команда має 5+ років досвіду роботи з 1С-Бітрікс та більше 50 успішних проектів з інтеграції служб доставки. Ми надаємо гарантію на код та підтримку після запуску. Всі наші спеціалісти сертифіковані вендором. Ви отримаєте детальний кошторис та дорожню карту протягом 1 дня після звернення.
Замовте інтеграцію під ключ — зв'яжіться з нами для оцінки вашого проекту.