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

Інтеграція 1С-Bitrix зі службою доставки IML

IML — російська служба доставки з власною мережею пунктів видачі та кур'єрською доставкою. Покриття — понад 5000 населених пунктів, фокус на e-commerce. Для інтернет-магазинів на Bitrix актуальні три сценарії: кур'єрська доставка до дверей, доставка в ПВЗ та самовивіз із ПВЗ з приміркою.

API IML: структура та авторизація

IML надає REST API. Базова URL: https://api.iml.ru. Авторизація через Basic Auth (логін та пароль з особистого кабінету IML). Усі запити — POST з тілом у JSON, відповіді також у JSON.

Ключові endpoints:

• POST /api/v2/auto-zones — розрахунок зони та вартості доставки за адресою/індексом
• POST /api/v2/orders — створення заявки на доставку
• GET /api/v2/orders/{orderNumber} — статус заявки
• GET /api/v1/delivery-points — список ПВЗ (може бути великим — кешувати)
• GET /api/v2/tracking/{barcode} — детальний трекінг

Модуль доставки в Bitrix

Клас доставки успадковує \Bitrix\Sale\Delivery\Services\Base. Для відображення ПВЗ на карті додатково реалізуємо окремий компонент або інтегруємось з існуючим віджетом вибору ПВЗ, якщо такий є на проекті.

Параметри в b_sale_delivery_service_params:

• IML_LOGIN, IML_PASSWORD
• SENDER_CODE — код відправника (видається IML під час підключення)
• DELIVERY_TYPE — тип доставки за замовчуванням (courier / pickup)

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

IML розраховує вартість за зоною: спочатку визначається зона доставки за населеним пунктом, потім за тарифною сіткою розраховується вартість залежно від ваги та габаритів.

$response = $httpClient->post(
    'https://api.iml.ru/api/v2/auto-zones',
    [
        'RegionCodeFrom' => $senderRegionCode,
        'RegionCodeTo'   => $deliveryRegionCode,
        'Weight'         => $weightGram,
        'Volume'         => $volumeCm3,
        'AssessedValue'  => $assessedValue,
        'DeliveryType'   => 'CurierDelivery', // або 'PickupPoint'
    ]
);
$deliveryPrice = $response['Price'];
$deliveryDays  = $response['DeliveryTime'];

Коди регіонів IML — власна класифікація. При першому запуску завантажуємо довідник регіонів GET /api/v2/regions і зберігаємо в b_option (або окремій таблиці) для швидкого пошуку.

Створення заявки

При підтвердженні замовлення та виборі способу доставки IML формуємо заявку:

$orderData = [
    'SenderCode'    => $senderCode,
    'OrderNumber'   => 'SHOP-' . $bitrixOrderId,
    'ReceiverName'  => $receiverName,
    'Phone'         => $phone,
    'RegionCode'    => $regionCode,
    'AddressString' => $address,
    'Weight'        => $weightGram,
    'GoodsDescription' => 'Товари інтернет-магазину',
    'AssessedValue' => $assessedValue,
    'CashOnDelivery'=> $codAmount, // накладений платіж, 0 якщо передплата
    'DeliveryType'  => 'CurierDelivery',
];

Відповідь містить BarCode — штрихкод відправлення IML. Зберігаємо його в b_sale_order_props як IML_BARCODE.

ПВЗ і карта вибору

Список ПВЗ повертає GET /api/v1/delivery-points — великий масив (тисячі об'єктів). Завантажуємо раз на добу через агент Bitrix і кешуємо в HL-блоці або таблиці b_iblock_element (інфоблок «ПВЗ IML»).

На сторінці оформлення замовлення відображаємо карту з ПВЗ: Яндекс.Карти або Google Maps з позначками. При виборі ПВЗ записуємо його код у властивість замовлення IML_PICKUP_POINT. При створенні заявки передаємо PickupPointCode замість адреси.

Статуси та трекінг

Синхронізація статусів через агент Bitrix: кожні 30–60 хвилин опитуємо GET /api/v2/orders/{orderNumber} для активних замовлень. IML також підтримує вебхуки (надсилання сповіщень на URL магазину) — краще при великому обсязі замовлень.

Накладений платіж

IML підтримує накладений платіж (COD). Сума CashOnDelivery = вартість замовлення, якщо покупець платить під час отримання. При налаштуванні двох способів оплати (передплата / при отриманні) в Bitrix логіка вибору COD реалізується в calculateConcrete().

Графік