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

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

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

Преимущества агрегатора перед прямыми интеграциями

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

• Единая авторизация, единый формат запросов
• Расчёт стоимости сразу по всем подключённым перевозчикам в одном запросе
• Создание отправлений через один эндпоинт
• Единый трекинг всех заказов
• Агрегированный список ПВЗ

Обратная сторона: агрегатор добавляет прослойку, иногда есть задержки при обновлении API перевозчика. Для магазинов с нестандартными требованиями к конкретному перевозчику прямая интеграция может быть точнее.

API ApiShip

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

Ключевые эндпоинты:

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

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

Один модуль покрывает все службы. Архитектурный выбор: либо один класс \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 в личном кабинете. Статусы унифицированы для всех перевозчиков — один маппинг работает для всех.

Сроки