Интеграция 1С-Битрикс со службой доставки 5Post

Интеграция 1С-Битрикс со службой доставки 5Post

5Post — служба доставки группы X5 Retail (Пятёрочка, Перекрёсток, Карусель). Основной канал доставки — пункты выдачи заказов в торговых точках сети. Охват: более 15 000 ПВЗ по России. Для интернет-магазинов это доступ к широкой сети в шаговой доступности для покупателей.

API 5Post

5Post предоставляет REST API. Авторизация — через OAuth 2.0 (client_credentials). Базовый URL продакшн: https://api.5post.ru. Тестовая среда предоставляется при подключении через личный кабинет 5Post.

Основные методы:

• POST /api/v1/orders — создание заявки на доставку
• GET /api/v1/orders/{orderUUID} — статус заявки
• DELETE /api/v1/orders/{orderUUID} — отмена
• GET /api/v1/pvz — список ПВЗ с фильтрацией по региону/городу
• POST /api/v1/orders/calc — расчёт стоимости доставки

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

Класс доставки наследует \Bitrix\Sale\Delivery\Services\Base. Параметры хранятся в b_sale_delivery_service_params: CLIENT_ID, CLIENT_SECRET, PARTNER_CODE (код партнёра 5Post).

Получение токена:

$tokenResponse = $httpClient->post('https://api.5post.ru/api/v1/auth/token', [
    'grant_type'    => 'client_credentials',
    'client_id'     => $clientId,
    'client_secret' => $clientSecret,
]);
$accessToken = $tokenResponse['access_token'];
// токен действует 1 час — кешируем в b_option

Расчёт стоимости

$calcResult = $httpClient->post('/api/v1/orders/calc', [
    'partnerOrder' => [
        'partnerOrderId' => 'SHOP-' . $orderId,
        'pvzCode'        => $selectedPvzCode,
        'dimensions'     => [
            'length' => $lengthCm,
            'width'  => $widthCm,
            'height' => $heightCm,
            'weight' => $weightGram,
        ],
        'assessedValue' => $assessedValue,
    ],
]);
$deliveryCost = $calcResult['deliveryCost'];

Для предварительного расчёта (до выбора конкретного ПВЗ) можно передавать код населённого пункта вместо кода ПВЗ — API вернёт базовую стоимость по зоне.

Загрузка и отображение ПВЗ

Список ПВЗ — большой: более 15 000 объектов. Стратегия загрузки:

1. Раз в сутки (агент Битрикс) запрашиваем актуальный список GET /api/v1/pvz.
2. Сохраняем в HL-блок «ПВЗ 5Post» с полями: код, название, адрес, координаты, время работы, допустимые габариты.
3. На странице оформления заказа фильтруем ПВЗ по выбранному городу и отображаем на карте.

Важный нюанс: ПВЗ 5Post имеют ограничения по габаритам. maxDimensionCm и maxWeightGram — обязательно учитывать при фильтрации, чтобы не показывать покупателю ПВЗ, куда его посылка физически не поместится.

Создание заявки

После выбора ПВЗ и оформления заказа создаём заявку:

$orderPayload = [
    'partnerOrder' => [
        'partnerOrderId'  => 'SHOP-' . $bitrixOrderId,
        'pvzCode'         => $pvzCode,
        'recipientName'   => $fullName,
        'recipientPhone'  => $phone,
        'recipientEmail'  => $email,
        'assessedValue'   => $assessedValue,
        'cashOnDelivery'  => $codAmount,
        'dimensions'      => $dimensions,
        'places'          => [
            ['barcode' => 'SHOP-' . $bitrixOrderId . '-1', 'description' => 'Место 1']
        ],
    ],
];

Ответ содержит orderUUID — сохраняем в b_sale_order_props. Также возвращается этикетка для печати (labelUrl): PDF с штрихкодом для наклейки на посылку.

Статусы доставки

5Post отправляет вебхуки при смене статуса. Регистрируем URL в личном кабинете. Маппинг статусов:

При получении вебхука проверяем X-Signature заголовок (HMAC-подпись) — 5Post подписывает запросы секретным ключом партнёра.

Особенности работы

5Post не возвращает деньги за невыкупленные заказы автоматически — нужна настройка условий возврата в договоре. Срок хранения на ПВЗ — 7 дней, потом посылка возвращается. При возврате в b_sale_order обновляем статус через тот же механизм вебхуков.

Сроки