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

Інтеграція 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 під ваш бізнес.