Інтеграція Яндекс.Доставки: від розрахунку до трекінгу
Після оформлення замовлення клієнт не отримує 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–10 днів | 2–3 тижні |
| Підтримка статусів | 15 статусів + вебхуки | тільки базові |
| Обробка помилок | вбудоване кешування | потрібна реалізація |
| Масштабування | хмарна інфраструктура | оренда серверів |
Час впровадження через API в 3–5 разів нижчий, а кількість помилок — на 40% менше (за нашими вимірами). Клієнти економлять до 30% на логістичних витратах за рахунок оптимізації тарифів. Зв'яжіться з нами, щоб оцінити вашу інтеграцію.
Процес роботи: від аналітики до деплою
- Аналітика — розбираємо бізнес-логіку: які статуси відображати, коли списувати гроші, як повертати замовлення.
- Проєктування — проєктуємо архітектуру: черговість запитів, кешування, схему вебхуків.
- Реалізація — пишемо код: контролери, сервіси, тести. Використовуємо Repository pattern для абстракції API.
- Тестування — проганяємо на staging: створюємо заявки, скасовуємо, перевіряємо вебхуки через ngrok.
- Деплой — викочуємо на бій, налаштовуємо моніторинг (логи, алерти в Telegram).
Типові помилки при інтеграції
- Неправильна обробка CORS — браузер блокує запити до API Яндекс.Доставки, якщо не налаштований проксі-сервер.
- Відсутність повторних спроб при таймаутах — втрата замовлень у годину пік.
- Ігнорування лімітів API (100 запитів на хвилину) — блокування ключа.
Що входить у роботу?
- Документація — опис ендпоінтів, схема даних, інструкція з додавання нових тарифів.
- Доступи — налаштування API-ключів, вебхуків, політик безпеки.
- Код — репозиторій з інтеграцією (Laravel, Node.js або інший стек за домовленістю).
- Підтримка — безкоштовна підтримка 1 місяць після запуску (консультації, фікси).
Терміни орієнтовно
| Етап | Тривалість |
|---|---|
| Базова інтеграція (розрахунок + заявка + трекінг) | 3–4 робочих дні |
| Повна інтеграція (вебхуки + карта + автоскасування) | 1–1,5 тижня |
| Розширення (кілька складів, повернення) | від 2 тижнів |
Вартість інтеграції розраховується індивідуально.
Як ми гарантуємо якість?
У нас 5 років досвіду в інтеграціях логістичних API та 30+ успішних проєктів з Яндекс.Доставкою, СДЕК, Boxberry. Ми тестуємо кожен сценарій: від розрахунку вартості до скасування замовлення водієм. Гарантуємо збереження даних і роботу 24/7.
Ми готові обговорити ваш проєкт. Зв'яжіться з нами — оцінимо складність і запропонуємо оптимальне рішення. Замовте консультацію для оцінки вашого проєкту.