Подключение 5Post к 1С-Битрикс: интеграция под ключ

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

Пункты выдачи заказов — основной канал получения товаров для покупателей в регионах. 5Post, дочерняя служба X5 Retail, управляет сетью из более чем 15 000 ПВЗ в магазинах «Пятёрочка» и «Перекрёсток». Но интеграция с 1С-Битрикс часто вызывает сложности: неправильная обработка токенов, неучтённые габаритные ограничения, потеря вебхуков. Мы предлагаем готовое решение — подключаем 5Post по REST API с нуля или дорабатываем существующую интеграцию. Опыт нашей команды — 5+ лет разработки на Битрикс, 100+ проектов по интеграции служб доставки, поэтому вы получаете стабильный результат и гарантию работоспособности.

Почему стоит интегрировать 5Post в 1С-Битрикс?

5Post лучше многих альтернатив: сеть ПВЗ крупнейшая среди российских служб доставки, а стоимость доставки ниже среднерыночной. Для интернет-магазина это означает больше лояльных покупателей и меньшие логистические затраты. Интеграция через REST API даёт полный контроль — от расчёта стоимости до отслеживания статуса в реальном времени.

Как настроить OAuth 2.0 для 5Post?

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

Токен действителен 60 минут, поэтому кешируем его в опциях модуля и обновляем за 5 минут до истечения. При ошибке 401 автоматически запрашиваем новый токен и повторяем запрос. Документация 5Post API подробно описывает параметры запросов.

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

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

Что делать при сбое вебхуков?

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

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

$signature = $_SERVER['HTTP_X_SIGNATURE'];
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $secretKey);
if (hash_equals($expectedSignature, $signature)) {
    // обрабатываем вебхук
} else {
    // игнорируем и логируем
}

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

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

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

$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 не возвращает деньги за невыкупленные заказы автоматически — нужна настройка условий возврата в договоре. Срок хранения на ПВЗ — 7 дней, потом посылка возвращается. При возврате в b_sale_order обновляем статус через тот же механизм вебхуков.

Что входит в интеграцию

• Настройка OAuth 2.0 и кеширование токенов
• Разработка класса доставки с расчётом стоимости
• Загрузка и хранение ПВЗ в HL-блоке
• Фильтрация ПВЗ по городу и габаритам
• Обработка вебхуков с проверкой HMAC-подписи
• Создание заявок и печать этикеток
• Тестирование в песочнице 5Post
• Документация и обучение вашего менеджера

Сроки

Свяжитесь с нами — оценим ваш проект и предложим точные сроки. Мы гарантируем стабильную работу интеграции: мониторинг, обработку ошибок и поддержку после запуска. Получите консультацию по интеграции — мы поможем настроить 5Post под ваш бизнес.