1C-Bitrix Integration with Yandex Routing

Integration of 1C-Bitrix with Yandex Routing

Yandex Routing (Yandex.Courier API) — Russian logistics optimization service with real traffic, time windows and vehicle constraints. API allows creating routes, assigning orders to drivers and getting real-time tracking. Integration with Bitrix gives complete cycle: from site order to customer delivery notification.

Registration in Yandex.Courier

To work with API you need:

1. Register company in cabinet courier.yandex.ru
2. Get COMPANY_ID — numeric company identifier
3. Get OAuth token via Yandex OAuth for API access
4. Configure warehouse (depot) — departure point with coordinates

Base API URL: https://courier.yandex.ru/api/v1/companies/{company_id}/

Creating route via API

Route in Yandex.Routing — set of orders assigned to one vehicle. Creating route:

class YandexCourierClient
{
    private string $baseUrl;
    private string $oauthToken;
    private int    $companyId;

    public function __construct()
    {
        $this->baseUrl    = 'https://courier.yandex.ru/api/v1';
        $this->oauthToken = \Bitrix\Main\Config\Option::get('main', 'YANDEX_COURIER_TOKEN');
        $this->companyId  = (int)\Bitrix\Main\Config\Option::get('main', 'YANDEX_COURIER_COMPANY_ID');
    }

    public function createRoute(array $depot, array $vehicle, array $orders): array
    {
        $payload = [
            'number'    => 'BX-' . date('Ymd') . '-' . uniqid(),
            'depot'     => [
                'id'    => $depot['id'],
                'point' => ['lat' => $depot['lat'], 'lon' => $depot['lon']],
                'time_window' => [$depot['open'], $depot['close']],
            ],
            'vehicle'   => [
                'id'          => $vehicle['id'],
                'max_weight'  => $vehicle['max_weight'],
                'max_volume'  => $vehicle['max_volume'],
            ],
            'orders'    => $this->formatOrders($orders),
        ];

        $http = new \Bitrix\Main\Web\HttpClient();
        $http->setHeader('Authorization', 'OAuth ' . $this->oauthToken);
        $http->setHeader('Content-Type', 'application/json');

        $result = $http->post(
            "{$this->baseUrl}/companies/{$this->companyId}/routes",
            json_encode($payload, JSON_UNESCAPED_UNICODE)
        );

        if ($http->getStatus() !== 200) {
            throw new \RuntimeException('Yandex Courier API error: ' . $result);
        }

        return json_decode($result, true);
    }

    private function formatOrders(array $orders): array
    {
        return array_map(fn($o) => [
            'number'          => (string)$o['bitrix_order_id'],
            'point'           => ['lat' => $o['lat'], 'lon' => $o['lon']],
            'address'         => $o['address'],
            'time_window'     => [$o['time_from'], $o['time_to']],
            'weight_kg'       => $o['weight'],
            'customer_name'   => $o['customer_name'],
            'customer_phone'  => $o['customer_phone'],
            'service_duration' => 300,
        ], $orders);
    }
}

Driver and order tracking

Yandex.Courier provides webhooks for event tracking. Register webhook in company settings:

$http->post("{$this->baseUrl}/companies/{$this->companyId}/webhooks", json_encode([
    'url'    => 'https://your-site.ru/bitrix/yandex_courier_webhook.php',
    'events' => ['order_status_changed', 'route_started', 'route_finished'],
]));

Webhook handler:

// /bitrix/yandex_courier_webhook.php
\Bitrix\Main\Loader::includeModule('sale');

$data = json_decode(file_get_contents('php://input'), true);

if ($data['event'] === 'order_status_changed') {
    $orderId = (int)$data['order']['number'];  // we passed bitrix_order_id as number
    $status  = $data['order']['status'];

    $statusMap = [
        'confirmed'    => 'TD',
        'in_progress'  => 'OD',
        'finished'     => 'F',
        'cancelled'    => 'CF',
    ];

    $bitrixStatus = $statusMap[$status] ?? null;

    if ($orderId && $bitrixStatus) {
        $order = \Bitrix\Sale\Order::load($orderId);
        $order?->setField('STATUS_ID', $bitrixStatus);
        $order?->save();

        if ($status === 'finished') {
            \Bitrix\Main\Mail\Event::send([
                'EVENT_NAME' => 'SALE_ORDER_DELIVERED',
                'LID'        => SITE_ID,
                'C_FIELDS'   => ['ORDER_ID' => $orderId],
            ]);
        }
    }
}

http_response_code(200);

Calculating coordinates from addresses

Yandex.Routing requires coordinates (lat/lon), not text addresses. Use Yandex Geocoder API for geocoding during checkout:

function geocodeAddress(string $address): ?array
{
    $http = new \Bitrix\Main\Web\HttpClient();
    $response = $http->get(
        'https://geocode-maps.yandex.ru/1.x/?' . http_build_query([
            'apikey'   => YANDEX_GEOCODER_API_KEY,
            'geocode'  => $address,
            'format'   => 'json',
            'results'  => 1,
        ])
    );

    $data = json_decode($response, true);
    $pos  = $data['response']['GeoObjectCollection']['featureMember'][0]
            ['GeoObject']['Point']['pos'] ?? null;

    if ($pos) {
        [$lon, $lat] = explode(' ', $pos);
        return ['lat' => (float)$lat, 'lon' => (float)$lon];
    }

    return null;
}

Coordinates are saved to custom order properties UF_DELIVERY_LAT and UF_DELIVERY_LON.

Customer tracking link

Yandex.Courier generates public tracking link. Get it via API and send to customer:

$trackingUrl = $routeResponse['tracking_url'] ?? null;
if ($trackingUrl) {
    $order->setField('UF_TRACKING_URL', $trackingUrl);
    // Send in customer email
}

Implementation timeline

What we configure

• YandexCourierClient class with route creation and order management methods
• Agent for collecting daily orders and automatic route creation
• Address geocoding during checkout with saving to UF_DELIVERY_LAT/LON properties
• Webhook handler for updating Bitrix order statuses
• Sending customer tracking link when route starts