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

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

ApiShip — агрегатор служб доставки, що надає єдиний API для роботи з десятками перевозників: СДЕК, Boxberry, ПЕК, Ділові Лінії, Яндекс.Доставка, Пошта Росії та інші. Замість окремих інтеграцій із кожною службою підключається один модуль, через який стають доступні всі перевозники зі списку ApiShip.

Переваги агрегатора перед прямими інтеграціями

Пряма інтеграція з кожною службою доставки — окремий модуль, окремі реквізити, різна схема даних. При зміні API перевозника потрібно оновлювати кожну інтеграцію окремо. ApiShip уніфікує це:

• Єдина авторизація, єдиний формат запитів
• Розрахунок вартості відразу по всім підключеним перевозникам в одному запиті
• Створення відправлень через один endpoint
• Єдиний трекінг усіх замовлень
• Агрегований список ПВЗ

Зворотна сторона: агрегатор додає прошарок, іноді є затримки при оновленні API перевозника. Для магазинів з нестандартними вимогами до конкретного перевозника пряма інтеграція може бути точніше.

API ApiShip

Базова URL: https://api.apiship.ru/v2. Авторизація: Bearer-токен. Тест-середовище: https://api.test.apiship.ru/v2.

Ключові endpoints:

• POST /calculator — розрахунок вартості по всім активним перевозникам
• POST /orders — створення заявки
• GET /orders/{id} — статус заявки
• GET /points — список ПВЗ
• GET /deliveries — список підключених перевозників
• DELETE /orders/{id} — скасування

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

Один модуль охоплює всі служби. Архітектурний вибір: або один клас \Bitrix\Sale\Delivery\Services\Base з параметром «перевозник», або кілька екземплярів одного класу для різних перевозників (кур'єр, ПВЗ, і т.д.). Другий підхід зручніше для покупця: він видить окремі способи доставки.

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

• APISHIP_API_KEY — ключ з особистого кабінету ApiShip
• PROVIDER_KEY — код перевозника (cdek, boxberry, russian_post і т.д.)
• FROM_POINT_ID — ID точки відправки (склад у системі ApiShip)
• DELIVERY_TYPE — door (кур'єр) або point (ПВЗ)

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

$calcRequest = [
    'fromPoint' => ['id' => $fromPointId],
    'toPoint'   => [
        'address' => $deliveryAddress,
        'cityId'  => $apishipCityId,
    ],
    'parameters' => [
        'weight' => $weightGram,
        'length' => $lengthCm,
        'width'  => $widthCm,
        'height' => $heightCm,
        'declaredValue' => $declaredValue,
    ],
    'deliveryType' => $deliveryType,
    'providers'    => [$providerKey], // порожній масив = всі перевозники
];

$results = $httpClient->post('/v2/calculator', $calcRequest);
// $results — масив варіантів з ціною та терміном для кожного перевозника

Якщо providers — порожній масив, ApiShip повернеме розрахунок по всім активним перевозникам. Це дозволяє реалізувати на сайті блок порівняння способів доставки з цінами.

Отримання та зберігання ПВЗ

ПВЗ в ApiShip запитуються за фільтрами:

GET /points?cityId={id}&providerKey={key}&type=pickup_point

Завантажуємо раз на добу агентом для активних перевозників. Зберігаємо в HL-блок «ПВЗ» з полями: providerKey, pointId, name, address, lat, lng, workingHours, maxWeight. На карті відображаємо всё агреговано — покупець вибирає будь-який ПВЗ будь-якого перевозника.

При виборі ПВЗ зберігаємо в b_sale_order_props: APISHIP_PROVIDER_KEY та APISHIP_POINT_ID.

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

$orderPayload = [
    'providerKey'     => $providerKey,
    'senderPointId'   => $fromPointId,
    'deliveryType'    => $deliveryType,
    'toPoint'         => [
        'id'      => $pvzId,   // якщо ПВЗ
        'address' => $address, // якщо кур'єр
    ],
    'recipient'       => ['name' => $name, 'phone' => $phone],
    'parameters'      => $parameters,
    'orderNumber'     => 'SHOP-' . $bitrixOrderId,
    'declaredValue'   => $declaredValue,
    'cashOnDelivery'  => $codAmount,
    'places'          => $places,
];

Відповідь: orderId у системі ApiShip та trackingNumber перевозника. Обидва зберігаємо в b_sale_order_props.

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

Вебхуки: ApiShip надсилає POST при зміні статусу. Реєструємо URL у особистому кабінеті. Статуси уніфіковані для всіх перевозників — один маппінг працює для всіх.

Строки