Интеграция Яндекс.Доставки: от расчёта до трекинга
После оформления заказа клиент не получает 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.
Мы готовы обсудить ваш проект. Свяжитесь с нами — оценим сложность и предложим оптимальное решение. Закажите консультацию для оценки вашего проекта.