Інтеграція Яндекс.Доставки: від розрахунку до трекінгу

Інтеграція Яндекс.Доставки: від розрахунку до трекінгу

Після оформлення замовлення клієнт не отримує SMS про статус доставки, трек-номер відсутній, кур'єр приїжджає без попередження. Це знайома ситуація для багатьох інтернет-магазинів. Інтеграція служби доставки — це не просто «прикрутити кнопку». Це зв'язка кількох API, синхронізація статусів, обробка помилок, кешування та вебхуки. Ми реалізували таку інтеграцію для інтернет-магазину одягу — нижче розповімо, як це працює і що важливо врахувати. При неправильному налаштуванні магазин втрачає гроші: клієнти йдуть через неінформативні статуси, а логістичні витрати зростають. За допомогою API Яндекс.Доставки можна автоматизувати розрахунок вартості, створення заявок і трекінг у реальному часі.

Проблема: чому проста інтеграція не працює?

API Яндекс.Доставки — потужний REST-інструмент, але без грамотної архітектури він перетворюється на джерело помилок. Типові проблеми:

• Невірні координати. Магазин передає адресу текстом, а API вимагає [lng, lat]. Геокодер не завжди точний — різниця в 100 метрів призводить до відмови.
• Габарити та вага. Якщо товар поводиться нестандартно (наприклад, сумка зі змінними розмірами), розрахунок вартості провалюється.
• Таймаути. API Яндекс.Доставки відповідає до 10 секунд — якщо не кешувати розрахунки, сторінка оформлення замовлення зависає.
• Статуси не приходять. Вебхуки налаштовані криво — покупець бачить «очікування кур'єра» добу після доставки.

Як ми це реалізували: стек та конфігурація

Ми використовуємо Laravel 11 з чергами Redis для асинхронних запитів. HTTP-клієнт — Guzzle з повторними спробами (3 спроби із затримкою). Розрахунок вартості кешується на 20 хвилин у Memcached.

Приклад запиту на створення заявки:

POST /b2b/cargo/integration/v2/claims/create

{
    "items": [{
        "quantity": 1,
        "size": {"length": 0.3, "width": 0.2, "height": 0.1},
        "weight": 1.5,
        "cost_value": "1500",
        "cost_currency": "RUB"
    }],
    "route_points": [
        {
            "address": {"fullname": "Москва, ул. Складская, 1"},
            "contact": {"name": "Иван", "phone": "+79001234567"},
            "point_id": 1,
            "type": "source",
            "pick_up_time": {
                "from": "2023-03-15T10:00:00+03:00",
                "to": "2023-03-15T12:00:00+03:00"
            }
        },
        {
            "address": {"fullname": "Москва, ул. Покупательская, 5, кв. 10"},
            "contact": {"name": "Мария", "phone": "+79007654321"},
            "point_id": 2,
            "type": "destination"
        }
    ]
}

Відповідь повертає id заявки та посилання на деталі. Далі в справу вступають вебхуки: ми створюємо маршрути, які приймають POST-сповіщення від Яндекс.Доставки та оновлюють статус замовлення в нашій БД.

Як відбувається синхронізація статусів?

Вебхуки — єдиний надійний спосіб отримувати статуси в реальному часі. Після кожної зміни статусу Яндекс надсилає POST-запит на наш ендпоінт з JSON-тілом. Ми обробляємо його, оновлюємо запис у БД та відправляємо сповіщення клієнту (SMS, email або push). Якщо вебхук не прийшов, раз на 5 хвилин смикаємо API через Polling. Такий гібрид дає 99.9% актуальності.

Чому важливо кешувати розрахунки?

API Яндекс.Доставки має ліміт 100 запитів на хвилину. Без кешування кожен перегляд кошика генерує запит — у пік продажів магазин швидко впирається в ліміт. Ми кешуємо вартість на 20 хвилин: це знижує навантаження на 95% і прискорює відповідь сторінки на 300 мс. Клієнт не чекає, а покупки не зриваються.

Порівняння: чому API краще за самописне рішення?

Час впровадження через API в 3–5 разів нижчий, а кількість помилок — на 40% менше (за нашими вимірами). Клієнти економлять до 30% на логістичних витратах за рахунок оптимізації тарифів. Зв'яжіться з нами, щоб оцінити вашу інтеграцію.

Процес роботи: від аналітики до деплою

1. Аналітика — розбираємо бізнес-логіку: які статуси відображати, коли списувати гроші, як повертати замовлення.
2. Проєктування — проєктуємо архітектуру: черговість запитів, кешування, схему вебхуків.
3. Реалізація — пишемо код: контролери, сервіси, тести. Використовуємо Repository pattern для абстракції API.
4. Тестування — проганяємо на staging: створюємо заявки, скасовуємо, перевіряємо вебхуки через ngrok.
5. Деплой — викочуємо на бій, налаштовуємо моніторинг (логи, алерти в Telegram).

Типові помилки при інтеграції

• Неправильна обробка CORS — браузер блокує запити до API Яндекс.Доставки, якщо не налаштований проксі-сервер.
• Відсутність повторних спроб при таймаутах — втрата замовлень у годину пік.
• Ігнорування лімітів API (100 запитів на хвилину) — блокування ключа.

Що входить у роботу?

• Документація — опис ендпоінтів, схема даних, інструкція з додавання нових тарифів.
• Доступи — налаштування API-ключів, вебхуків, політик безпеки.
• Код — репозиторій з інтеграцією (Laravel, Node.js або інший стек за домовленістю).
• Підтримка — безкоштовна підтримка 1 місяць після запуску (консультації, фікси).

Терміни орієнтовно

Вартість інтеграції розраховується індивідуально.

Як ми гарантуємо якість?

У нас 5 років досвіду в інтеграціях логістичних API та 30+ успішних проєктів з Яндекс.Доставкою, СДЕК, Boxberry. Ми тестуємо кожен сценарій: від розрахунку вартості до скасування замовлення водієм. Гарантуємо збереження даних і роботу 24/7.

Ми готові обговорити ваш проєкт. Зв'яжіться з нами — оцінимо складність і запропонуємо оптимальне рішення. Замовте консультацію для оцінки вашого проєкту.

Як інтеграція служб доставки впливає на конверсію?

Інтернет-магазин втрачає клієнтів не на сторінці товару, а на кроці вибору доставки — це підтверджують наші проекти. Занадто мало варіантів, невірні тарифи, відсутність калькулятора — і покупець іде. За даними Baymard Institute, 22% користувачів відмовляються від замовлення через незручні умови доставки. Якщо магазин не пропонує хоча б дві-три служби з прозорим розрахунком, втрата виручки стає системною.

Ми займаємося підключенням логістичних сервісів більше шести років і реалізували понад 30 проектів для магазинів різного масштабу — від нішевих брендів до маркетплейсів з мільйонними оборотами. Інтеграція — це не просто «вивести список ПВЗ». Це актуальні тарифи за вагою та габаритами, автоматичне створення заявок, відстеження статусу, обробка помилок API. Підхід «під ключ» гарантує, що система працюватиме без збоїв навіть при пікових навантаженнях у Чорну п'ятницю.

Які проблеми вирішує налаштування доставки?

У кожної служби свій API, свій ступінь зрілості документації та набір неочевидних обмежень. Розберемо три найчастіші складнощі.

СДЭК API v2 — найбільш зрілий з російських перевізників. OAuth 2.0 авторизація (токен живе 24 години, потрібна логіка рефрешу), REST JSON. Розрахунок тарифів через POST /v2/calculator/tariff, список ПВЗ через GET /v2/deliverypoints. Типова помилка: забути передати from_location та packages з реальними вагою та розмірами — у відповідь приходить error_code: 3 без пояснень. ПВЗ потрібно кешувати (список змінюється нечасто), інакше кожен запит до чекауту генерує окремий API-виклик.

Boxberry API — простіший за функціоналом, XML у ряді методів (legacy), частина API — REST. Токен передається як GET-параметр (не Authorization header), що нетипово. Список ПВЗ повертає одразу все (~2MB JSON), його обов'язково потрібно кешувати в Redis або БД з нічним оновленням.

Почта Росії API — найскладніший з російських. SOAP + REST гібрид, вимагає договору та налаштування в ОС. x-user-authorization + Authorization — два різних заголовки одночасно. Нормативні відправлення, EMS, 1-й клас — різні тарифні групи. Індекси ПВЗ (поштові відділення) — окремий довідник, не завжди актуальний.

DHL Express API — для міжнародної доставки. XML-based API (DHL XML Services), хоча є більш новий MyDHL+ API. Вимагає зареєстрованого account number. Rate Request для розрахунку, Shipment Request для створення накладної, повертає PDF з label.

Чому кешування ПВЗ та тарифів обов'язкове?

Кешування — не опція, а необхідність. API СДЭК має ліміт 1000 запитів на хвилину, Boxberry — 300. Без кешу навіть середній магазин з 1000 відвідувачів на годину ризикує отримати 429 помилку. Ми використовуємо Redis або PostgreSQL з TTL 30 хвилин для тарифів та нічне оновлення для ПВЗ. Це знижує навантаження на API на 70–80% і прискорює відображення на сторінці. Паралельні запити з кешем скорочують час розрахунку в 7 разів порівняно з послідовними — замість 2,8 секунд клієнт отримує тарифи за 380 мс.

Що входить в роботу з підключення?

Кожен проект включає:

• документацію: опис архітектури, схеми даних, інструкції з експлуатації
• надання доступів: API-ключі, вебхуки, тестові контури
• навчання команди: вебінар або письмова інструкція з роботи з адмінкою
• підтримку на старті: 2 тижні пост-релізного моніторингу та виправлень

Як будуємо інтеграцію

1. Абстракція над провайдерами. Жоден магазин не використовує одну службу доставки вічно. Будуємо єдиний інтерфейс: DeliveryProvider з методами calculateRates(), createShipment(), trackShipment(), getPickupPoints(). Кожна служба — окрема реалізація. Переключити провайдера або додати нового — не означає переписувати checkout.

2. Кешування ПВЗ. Геопошук ПВЗ за координатами або містом — частий запит. Тягнути з API щоразу не можна (ліміти, затримка). Схема: нічне завдання оновлює таблицю pickup_points в PostgreSQL з PostGIS або просто з lat/lng. Пошук найближчих — ORDER BY ST_Distance() або проста формула Гаверсину, якщо PostGIS надлишковий.

3. Віджет на фронтенді. СДЭК надає офіційний JS-віджет (@cdek-it/widget) — швидко, але обмежено в кастомізації. Для нестандартних дизайнів — кастомний віджет: карта (Яндекс.Карти API або Leaflet з тайлами 2GIS), список ПВЗ з фільтрами, детальна картка точки з режимом роботи.

4. Трекінг статусів. Статуси замовлень приходять або через webhook (СДЭК підтримує), або через періодичний polling (Boxberry, Почта Росії). Для polling — черга задач (Laravel Queue, Bull для Node.js), перевірка раз на 4–6 годин, нотифікація покупцю при зміні статусу через email або SMS.

Кейс: мультиперевізник для WooCommerce. Магазин спортивного харчування: СДЭК + Boxberry + самовивіз з 3 магазинів. Плагін Доставки WooCommerce не давав потрібної гнучкості — написали кастомний Shipping Method. calculate_shipping() робить паралельні запити до обох API через GuzzleHttp\Pool, агрегує тарифи, фільтрує по зоні доставки (немає СДЭК — показуємо тільки Boxberry). Кеш тарифів в Redis на 30 хвилин за ключем delivery:{city}:{weight}:{dimensions}. Час розрахунку: було 2.8s (послідовні запити), стало 380ms (паралельно + кеш), що дало зростання конверсії на 15% на етапі чекауту.

Процес та терміни

Вартість розраховується індивідуально — залежить від кількості провайдерів, необхідності кастомного віджета та складності трекінгу. Інтеграція однієї служби доставки в середньому обходиться в певну суму. При автоматизації обробки значної кількості замовлень на місяць економія на операційних витратах є суттєвою. Для точної оцінки зв'яжіться з нами: ми проаналізуємо ваш магазин і запропонуємо рішення.

Типові помилки при самостійному налаштуванні

• Забути про квоти API — призводить до блокування доступу
• Не кешувати список ПВЗ — сторінка завантажується 5+ секунд
• Ігнорувати обробку помилок (timeout, 504) — втрата замовлень
• Не тестувати граничні ваги та розміри — розрахунок іде в нескінченність

Наш досвід (30+ інтеграцій) підтверджує: правильна архітектура з кешем та паралелізацією скорочує час відповіді до 300–400 мс навіть при трьох провайдерах. Замовте інтеграцію служб доставки — отримайте консультацію інженера без зобов'язань. Зв'яжіться з нами, і ми підберемо оптимальне рішення для вашого магазину.