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

Інтеграція 1С-Bitrix зі службою доставки 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

Клас доставки успадковує \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. Раз на добу (агент Bitrix) запитуємо актуальний список через 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 оновлюємо статус через той же механізм вебхуків.

Графік