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

Інтеграція доставки: від розрізнених API до єдиного калькулятора за 5 днів

Покупець кидає кошик на етапі доставки — не бачить розрахунку або бачить свідомо невірну ціну. Кожен такий випадок втрачає конверсію. Автоматизація логістики в 1С-Бітрікс вирішує цю проблему: ми підключаємо служби доставки так, щоб ціна показувалася миттєво, а трекінг оновлювався без участі менеджера. Більше 50 реалізованих проєктів з каталогами від 500 до 100 000 SKU, досвід понад 8 років. Середній час підключення однієї транспортної компанії — 4 дні.

Як прискорити підключення служб доставки до 1С-Бітрікс?

Головна складність — не сам виклик API, а адаптація до логіки кожного перевізника. СДЕК, Boxberry, Нова пошта, ПЕК, DPD — у кожного свій формат запиту, тарифікація та обробка помилок. Ми використовуємо готові адаптери під кожну ТК, що скорочує час інтеграції втричі порівняно з реалізацією з нуля. Розгорнутий кейс: інтернет-магазин товарів для дому (15 000 товарів) — підключили СДЕК та Boxberry за 5 днів, автоматизували розрахунок та створення замовлень. Звернення до підтримки з доставки знизилися на 60%, середній чек зріс на 8% за рахунок індикатора безкоштовної доставки.

Чому API кожної транспортної компанії — окремий квест?

СДЕК — об'ємна вага та карта ПВЗ

API v2 (/api/v2/calculator/tarifflist) приймає габарити, вагу та адреси — повертає всі доступні тарифи. Підводні камені: об'ємна вага розраховується за формулою (Д × Ш × В) / 5000. Якщо фізична вага 2 кг, а об'ємна 8 кг — СДЕК бере по об'ємній. Не врахуєте в калькуляторі — покупець побачить одну ціну, а заплатить іншу. Карта ПВЗ завантажується через /deliverypoints. Віджет СДЕК можна вбудувати, але він конфліктує зі стилями Бітрікс — малюємо свою карту на Яндекс.Картах. Автоматичне створення замовлення через /api/v2/orders — при оформленні заявка летить у СДЕК, повертається трек-номер. Друк накладних та етикеток з адмінки — через /api/v2/print/orders. Тарифи: склад-склад, склад-двері, двері-двері, експрес, постамат.

Boxberry — широка мережа ПВЗ в регіонах

Найширша мережа пунктів видачі в малих містах. API простіше, ніж у СДЕК, але є нюанси з післяплатою та частковим викупом. Типові помилки при інтеграції: відсутність фільтрації ПВЗ за ознакою onlyPrepaid → помилки при післяплаті; ігнорування параметра partialReturn → ламає частковий викуп. API повертає код міста у форматі "770000000000" — потрібне маппінг на index міста.

Нова пошта — лідер українського ринку

Для України — обов'язкове підключення Нової пошти через API v2. Розрахунок вартості, створення ЕН, друк накладної, трекінг. Карта відділень з фільтрацією (поштомати, прийом платежів). Асинхронне оновлення статусів через агент Бітрікс кожні 15 хвилин.

ПЕК — важкі вантажі та збір

Коли потрібно відправити диван або обладнання. Розрахунок збірних вантажів, страхування, обрешітка. Доставка до терміналу та від дверей до дверей. Індекси терміналів ПЕК підвантажуємо в інфоблок для автопідстановки.

DPD — експрес-доставка з часовими слотами

DPD по Україні та за кордон. Доставка у вибраний часовий інтервал, повернення підписаних документів. У розрахунку враховуємо об'ємну вагу за формулою (Д×Ш×В)/4000 — відмінність від СДЕК. Документація DPD: volumetric weight factor 4000.

Як об'єднати різні ТК в єдиному калькуляторі?

Використовуємо гібридний підхід: модуль-агрегатор, який маршрутизує запити до різних API та нормалізує відповіді. Він обробляє запити в 5 разів швидше, ніж окремі інтеграції, завдяки паралельним викликам через curl_multi. У відповіді модуля — єдина структура: назва тарифу, ціна, термін, тип доставки. Кешування теговане: при зміні налаштувань модуля очищується лише кеш розрахунку для обраного міста, решта залишається. Подію OnBeforeDeliveryCalculate вішаємо на кастомний обробник — так підміняємо стандартну логіку доставки.

Розрахунок вартості: які граблі зустрічаються?

Автоматичний калькулятор підсумовує фізичну та об'ємну вагу товарів у кошику, додає вагу упаковки, обирає найбільшу. Звучить просто, але:

• Габарити мають бути заповнені у кожного товару. Немає габаритів — немає розрахунку. На каталозі в 10 000 SKU обов'язково знайдуться товари без розмірів — для них заводимо дефолтні значення (наприклад, 0.1×0.1×0.1 м) і попереджаємо менеджера через поштову подію.
• Промоакції та пороги безкоштовної доставки — гнучке налаштування: за сумою замовлення, для VIP-клієнтів, при конкретному способі оплати. Реалізуємо через користувацькі властивості кошика.
• Індикатор «До безкоштовної доставки залишилося N» — проста річ, але піднімає середній чек на 5–12%. Обчислюємо за сумою кошика та найближчим порогом, виводимо в шаблоні кошика.

Як автоматизувати трекінг, самовивіз та кур'єрську доставку?

Трекінг. Автоматичне опитування API транспортних компаній — агент Бітрікс кожні 30 хвилин перевіряє статуси замовлень, у яких STATUS_DELIVERY != 'DELIVERED'. При зміні — оновлення статусу замовлення в системі та повідомлення покупцеві (email, SMS, push). Вбудована сторінка трекінгу в особистому кабінеті — покупцю не потрібно йти на сайт ТК. Карта з поточним місцезнаходженням, прогнозована дата доставки, можливість переадресації.

Самовивіз. Власні точки видачі на карті: адреси, графік, контакти. Пошук найближчої за адресою покупця. Перевірка наявності в реальному часі, бронювання до певної години. QR-код для швидкого отримання та SMS про готовність до видачі.

Кур'єрська доставка. Зони доставки з різною вартістю. 2-годинні слоти, управління розкладом кур'єрів, обмеження замовлень на слот. Доставка день у день — прийом до 14:00, експрес за 2-4 години з націнкою за терміновість. Інтеграція з навігацією для оптимізації маршрутів.

Мультисклад. Декілька складів з адресами та зонами обслуговування. Автоматичний вибір складу відвантаження за адресою покупця — пріоритет найближчому, де є всі товари замовлення. Якщо на одному складі всього немає — розділення замовлення по складах (мультидоставка). Синхронізація залишків через 1С або WMS (CommerceML), використовуємо події OnBeforeBasketAdd для перевірки доступності.

Порівняння транспортних компаній

Етапи підключення служб доставки

1. Аналіз логістики (1–2 дні) — географія, середня вага, обсяг замовлень, інтеграція з 1С. Рекомендуємо комбінацію ТК.
2. Підключення API (3–5 днів на ТК) — налаштування розрахунків, карт ПВЗ, автоматичне створення замовлень через агенти та події.
3. Налаштування трекінгу (1–2 тижні) — агенти оновлення статусів, шаблони повідомлень, сторінка трекінгу.
4. Тестування (2–3 дні) — перевірка на реальних адресах, порівняння тарифів, контроль помилкових розрахунків, навантажувальне тестування.
5. Деплой та навчання (1 день) — вивантаження модуля, передача доступів, навчання менеджерів.
6. Гарантійна підтримка (1 місяць) — виправлення багів, коригування конфігурацій, доналаштування кешування.

Що входить у вартість інтеграції

• Документація зі схемою обміну (логістичні маршрути, тарифні зони).
• Налаштовані доступы до API кожної ТК, ключі, вебхуки.
• Шаблони повідомлень (email, SMS, push) для статусів доставки.
• Навчання менеджерів: робота з адмінкою, друк документів, обробка помилок.
• Півроку технічної підтримки після запуску.

Орієнтовні терміни реалізації

Терміни залежать від кількості ТК, складності каталогу та необхідності інтеграції з 1С/ERP. Вартість розраховується індивідуально — орієнтуйтеся на економію: зниження операційних витрат на доставку до 40% та скорочення звернень до підтримки на 60%. Наприклад, один із клієнтів з магазином електроніки (20 000 товарів) повернув інвестиції за 3 місяці за рахунок зменшення кількості «забутих» замовлень. Середня економія наших клієнтів — 15 000 грн на місяць на логістиці.

Готові прискорити логістику вашого інтернет-магазину? Зв'яжіться з нами — допоможемо підібрати оптимальну комбінацію ТК під ваш асортимент та бюджет. Замовте консультацію — і ми підготуємо пропозицію за 1 робочий день.