Интеграция 1С-Битрикс с агрегатором доставок Shiptor

Интеграция 1С-Битрикс с агрегатором доставок Shiptor

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

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

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

Основные возможности:

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

Архитектура интеграции в Битрикс

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

Вариант 1: только логистика. Магазин сам хранит и собирает товар, Shiptor — только перевозчик. Интеграция ограничена модулем доставки: расчёт → создание заявки → трекинг → этикетка.

Вариант 2: фулфилмент. Товары хранятся на складе Shiptor. При создании заказа в Битрикс — отправляем заявку на сборку и отгрузку в Shiptor. Остатки товаров синхронизируем из Shiptor в Битрикс через агент. Это сложнее и требует настройки двустороннего обмена.

Модуль доставки (вариант 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. Синхронизируем их в Битрикс:

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

Если товар в Битрикс не найден по 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 показываем агрегированно по всем перевозчикам.

Сроки