Интеграция 1С-Битрикс со службой доставки Куранты (Беларусь)
Интеграция службы доставки Куранты с 1С-Битрикс — задача, с которой сталкиваются белорусские интернет-магазины, когда стандартные модули не подходят. API Куранты требует JWT-авторизации и корректной обработки статусов. Наша команда реализовала несколько таких интеграций — от простого калькулятора до полного цикла с ПВЗ и трекингом. Рассказываем, как это сделать правильно и что важно учесть.
Почему Куранты выбирают для доставки в Беларуси?
Куранты — белорусская логистическая компания, специализирующаяся на курьерской доставке и сети пунктов выдачи заказов по всей стране. По сравнению с крупными федеральными операторами, Куранты предлагает более гибкие тарифы для среднего и малого e-commerce. Например, доставка по Минску часто обходится на 15–20% дешевле, а сроки — на 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 дней |
| Стоимость (посылка 1 кг, Минск) | от 3 BYN | от 4 BYN | от 2,5 BYN |
| ПВЗ | 200+ точек | 100+ точек | нет (только почта) |
| API | REST с JWT | REST с ключом | устаревший XML |
Куранты выигрывает по скорости в городах и количеству ПВЗ, но проигрывает Белпочте в стоимости. Для интернет-магазина с большими оборотами выгоднее комбинировать службы.
Сроки реализации
| Состав | Срок |
|---|---|
| Расчёт + создание доставки | 3–4 дня |
| + ПВЗ на карте | +2 дня |
| + Трекинг + уведомления | +2 дня |
| + Наложенный платёж | +1 день |
Почему стоит заказать интеграцию у нас?
Наша команда имеет 5+ лет опыта работы с 1С-Битрикс и более 50 успешных проектов по интеграции служб доставки. Мы предоставляем гарантию на код и поддержку после запуска. Все наши специалисты сертифицированы вендором. Вы получите подробную смету и дорожную карту в течение 1 дня после обращения.
Закажите интеграцию под ключ — свяжитесь с нами для оценки вашего проекта.