Інтеграція 1С-Бітрікс зі службою доставки ТехноЛогіст (Білорусь)

Інтеграція 1С-Bitrix зі службою доставки ТехноЛогіст (Беларусь)

ТехноЛогіст — білоруський логістичний оператор, що спеціалізується на доставці для інтернет-магазинів по Беларуси. Власна кур'єрська служба, пункти видачі та фулфілмент. Основна валюта — білоруський рубль (BYN). Для магазинів, що працюють на ринку РБ, — один з основних варіантів доставки нарівні з Європочтою та СДЕК.

API ТехноЛогіст

ТехноЛогіст надає REST API для інтеграції з інтернет-магазинами. Документація надається партнерам при підключенні. Авторизація — за токеном у заголовку. Endpoints:

• POST /orders — створення заявки
• GET /orders/{id} — статус заявки
• GET /orders/{id}/label — етикетка для друку
• POST /orders/calculate — розрахунок вартості
• GET /pvz — список пунктів видачі

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

Клас успадковує \Bitrix\Sale\Delivery\Services\Base. Параметри модуля:

• TECHNOLOGIST_TOKEN — токен доступу до API
• SENDER_ID — ідентифікатор відправника
• DEFAULT_CITY — місто за замовчуванням для розрахунку (Мінськ)
• CURRENCY — BYN (білоруський рубль)

У calculateConcrete() виконуємо запит розрахунку вартості з урахуванням ваги, габаритів, типу доставки (кур'єр/ПВЗ) та міста одержувача.

Особливості білоруського ринку

При інтеграції з білоруськими службами доставки важливо враховувати:

Валюта. Сума замовлення та вартість доставки передаються в BYN. Якщо магазин працює в кількох валютах, у calculateConcrete() конвертуємо через механізм курсів Bitrix (CCurrencyRates::ConvertCurrency()).

Телефон покупця. Білоруські номери: +375 (XX) XXX-XX-XX. У запиті до API передаємо в форматі 375XXXXXXXXX — без плюса, без дужок. Нормалізація через регулярне вираження в обробнику.

Адреси. Класифікатор міст РБ — КЛАДР не використовується (російський стандарт). ТехноЛогіст використовує власний довідник населених пунктів. При оформленні замовлення пошук міста — через GET /cities?q={query} з кешуванням результатів.

Накладений платіж. Широко поширений у Беларуси. При CashOnDelivery > 0 кур'єр приймає готівку або карту (залежно від оснащення кур'єра терміналом — уточнювати у ТехноЛогіста).

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

$payload = [
    'externalOrderId' => 'SHOP-' . $bitrixOrderId,
    'senderId'        => $senderId,
    'recipient' => [
        'name'    => $recipientName,
        'phone'   => $normalizedPhone,
        'address' => [
            'cityId'  => $cityId,
            'street'  => $street,
            'house'   => $house,
            'flat'    => $flat,
        ],
    ],
    'deliveryType'  => 'courier', // або 'pvz'
    'pvzId'         => $pvzId,
    'weight'        => $weightKg,
    'dimensions'    => $dimensions,
    'declaredValue' => $declaredValueBYN,
    'cod'           => $codAmountBYN,
    'comment'       => $deliveryComment,
];

У відповідь отримуємо orderId у системі ТехноЛогіст та trackingNumber. Зберігаємо в b_sale_order_props.

Статуси

ТехноЛогіст сповіщає про зміну статусу через вебхук (POST на URL магазину) або через polling. Маппінг:

Інтеграція ПВЗ

Список ПВЗ завантажується раз на добу агентом Bitrix і зберігається в HL-блоці. Для Мінська — кілька десятків точок, по всій Беларуси — менше, ніж у крупних російських операторів. Відображення на карті з координатами з відповіді API.

Графік