1C-Bitrix Integration with Kuranty Delivery Service (Belarus)

Integration of 1C-Bitrix with Kuranty Delivery Service (Belarus)

Integrating the Kuranty delivery service with 1C-Bitrix is a task faced by Belarusian online stores when standard modules don't fit. Kuranty's API requires JWT authorization and proper status handling. Our team has implemented several such integrations—from a simple calculator to a full cycle with pickup points and tracking. Here's how to do it right and what's important to consider.

Why Choose Kuranty for Delivery in Belarus?

Kuranty is a Belarusian logistics company specializing in courier delivery and a network of pickup points across the country. Compared to large federal operators, Kuranty offers more flexible tariffs for small and medium e-commerce. For example, delivery within Minsk is often 15–20% cheaper, and times are 1 day faster than traditional postal services. The API is provided to partners through a personal account after signing a contract.

How Does the Kuranty API Work?

The API is REST with JWT authorization. Base URL: https://api.kuranty.by/v2. A token is obtained via POST /auth/token with login and password, and lives for 24 hours. We cache the token for 23 hours to avoid hitting the API on every calculation.

Main methods:

• POST /delivery/cost — cost calculation
• POST /delivery/create — create delivery
• GET /delivery/{uuid}/status — delivery status
• GET /pickup-points — list of pickup points

Cost Calculation

We implement a handler class extending \Bitrix\Sale\Delivery\Services\Base. In the calculateConcrete method, we get the recipient's city from order properties, send a request with weight and order total. The response includes cost and delivery time.

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('Delivery city not defined')); 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 or courier ], $this->getAuthToken()); if (!empty($response['cost'])) { $result->setDeliveryPrice((float)$response['cost']); $days = $response['days_min'] . '–' . $response['days_max']; $result->setPeriodDescription("{$days} days"); } return $result; } } 

An important nuance: if the delivery city is not defined (e.g., the user didn't select a locality), an error is returned. In practice, this rarely happens, but we always add validation on the checkout form side.

Creating a Delivery

After order placement, a delivery must be created in the Kuranty system. The createDelivery method builds a payload: weight, total, cash on delivery, address, and contact data. The response contains the UUID of the order in Kuranty, which we save in an order property.

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 #' . $order->getId(), ]; $response = $this->apiPost('/delivery/create', $payload, $this->getAuthToken()); return (string)($response['uuid'] ?? ''); } 

Pickup Points on the Site

To display pickup points on a map, we use the /pickup-points API. We cache the data for 6 hours—Kuranty updates the list infrequently. The response includes coordinates (lat, lon), allowing us to plot points on Yandex Maps with custom markers.

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 ?? []; } 

Tracking

Kuranty does not provide webhooks—delivery status must be polled manually. We implement a Bitrix agent that queries status for each active order every 2–3 hours and updates it in order properties. The getStatus method accepts a UUID and returns the current status array.

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

What's Included in the Integration

Comparison of Kuranty with Other Belarusian Delivery Services

Kuranty wins on speed in cities and number of pickup points but loses to Belpochta on cost. For high-volume online stores, combining services is more advantageous.

Timeline Estimates

Why Commission Our Integration?

Our team brings over 5 years of experience with 1C-Bitrix and more than 50 successful projects integrating delivery services. We provide a warranty on the code and post-launch support. All our specialists are vendor-certified. You'll receive a detailed quote and roadmap within 1 day after contacting us.

Order a turnkey integration—contact us to evaluate your project.