Інтеграція 1С-Бітрікс з агрегатором доставок Shiptor

Інтеграція 1С-Bitrix з агрегатором доставок Shiptor

Shiptor — агрегатор служб доставки та фулфілмент-оператор. Два продукти: логістичний агрегатор (єдиний API для доступу до перевозників — СДЕК, Boxberry, DPD, Пошта Росії та інші) та фулфілмент (зберігання товарів на складах Shiptor з відгрузкою під замовлення). Для інтернет-магазину на Bitrix інтеграція з Shiptor закриває одразу обидва завдання через один API.

Функціональність API Shiptor

Базова URL: https://api.shiptor.ru. Авторизація — Bearer-токен. Документація доступна на shiptor.ru.

Основні можливості:

• Розрахунок вартості у кількох перевозників одним запитом
• Створення, оновлення, скасування відправлень
• Управління складськими запасами (фулфілмент)
• Список ПВЗ та постаматів
• Трекінг відправлень
• Автоматичний друк етикеток

Архітектура інтеграції у Bitrix

Shiptor у проекті може вирішувати два різні завдання, і їх архітектура різниться:

Варіант 1: тільки логістика. Магазин сам зберігає і збирає товар, Shiptor — тільки перевозник. Інтеграція обмежена модулем доставки: розрахунок → створення заявки → трекінг → етикетка.

Варіант 2: фулфілмент. Товари зберігаються на складі Shiptor. При створенні замовлення в Bitrix — надсилаємо заявку на збірку та відгрузку в Shiptor. Остатки товарів синхронізуємо з Shiptor в Bitrix через агент. Це складніше й вимагає настройки двостороннього обміну.

Модуль доставки (варіант 1)

Клас — спадкоємець \Bitrix\Sale\Delivery\Services\Base. Параметри:

• SHIPTOR_TOKEN — Bearer-токен
• WAREHOUSE_ID — ID складу-відправника у системі Shiptor
• PROVIDER — код перевозника (cdek, boxberry, dpd і т.д.) або auto для автовибору

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

$calcRequest = [
    'warehouse_id' => $warehouseId,
    'destination'  => [
        'city'    => $city,
        'address' => $address,
        'type'    => 'door', // або 'point'
        'point_id' => $pvzId,
    ],
    'packages' => [[
        'weight' => $weightGram,
        'length' => $lengthCm,
        'width'  => $widthCm,
        'height' => $heightCm,
    ]],
    'declared_value' => $declaredValue,
    'payment_method' => $isPrepaid ? 'prepaid' : 'cod',
];

Відповідь — масив пропозицій від перевозників. При provider = auto вибираємо мінімальну ціну або переважаний перевозник за настройками.

Створення відправлення

$shipmentPayload = [
    'warehouse_id'   => $warehouseId,
    'provider'       => $selectedProvider,
    'order_number'   => 'SHOP-' . $bitrixOrderId,
    'recipient'      => ['name' => $name, 'phone' => $phone],
    'destination'    => $destination,
    'packages'       => $packages,
    'items'          => $items,
    'declared_value' => $declaredValue,
    'cash_on_delivery' => $codAmount,
];

Відповідь містить shipment_id (ID у Shiptor) та tracking_number (у перевозника). Етикетку запитуємо через GET /shipments/{id}/label — PDF.

Фулфілмент: синхронізація остатків

При фулфілмент-моделі остатки товарів фізично на складі Shiptor. Синхронізуємо їх у Bitrix:

1. Агент раз на годину викликає GET /inventory — список позицій з остатками.
2. Маппінг за sku або зовнішнім кодом: знаходимо товар у b_iblock_element за артикулем.
3. Оновлюємо остаток через CCatalogProduct::Update() або напряму в b_catalog_product.

Якщо товар у Bitrix не знайдений за SKU — додаємо в лог для ручної перевірки.

Створення заявки на збірку (фулфілмент)

Замість фізичної відправки посилки зі свого складу надсилаємо у Shiptor завдання на збірку:

$fulfillmentOrder = [
    'order_number'  => 'SHOP-' . $bitrixOrderId,
    'recipient'     => $recipient,
    'destination'   => $destination,
    'provider'      => $selectedProvider,
    'items'         => array_map(fn($item) => [
        'sku'      => $item['sku'],
        'quantity' => $item['qty'],
    ], $basketItems),
];

$response = $httpClient->post('/fulfillment/orders', $fulfillmentOrder);

Shiptor сам збирає замовлення, упаковує та передає перевознику. Трекінг-номер повертається, як тільки замовлення передане перевознику.

ПВЗ та карта

Список ПВЗ: GET /pickup-points?city={city}&provider={provider}. Кешуємо в HL-блоці, оновлюємо раз на добу. На карті Яндекс/Google показуємо агреговано по всім перевозникам.

Строки