Интеграция доставки: сквозной процесс

TL;DR: доставка — это цепочка из десяти шагов, на каждом из которых у магазина и оператора своя зона ответственности. Интеграция сводится к тому, чтобы магазину вовремя отдать отправление и данные, а оператору — вовремя вернуть статусы, ярлыки и факты вручения.

Назначение

Страница описывает сквозной процесс работы с любым оператором доставки: от подключения по договору до ежедневной сверки. Один и тот же процесс применим к курьерке, ПВЗ и постаматам; различаются только детали шагов (например, точка выдачи вместо адреса). Интеграционные коды, вебхуки и справочники — часть контура интеграций; здесь зафиксирован процесс и распределение ролей.

Что решить до интеграции

Какие продукты оператора подключаются (курьер, ПВЗ, постаматы) и для каких регионов.
Кто платит за доставку в заказе: покупатель, магазин или смешанная схема.
Габаритно-весовые границы каталога и что делать с товарами «на грани».
Формат вручения отказа: продолжение продажи или стоп до решения по клиенту.
Как в витрине обещаются сроки: строго по расчёту оператора или с запасом.

Сквозной процесс и распределение ответственности

#	Шаг	Решает магазин	Решает оператор
1	Договор и матрица услуг	Выбирает оператора, подписывает договор, фиксирует продукты (курьер/ПВЗ/постамат) и тарифную сетку	Предоставляет личный кабинет, доступы, документацию API
2	Весогабариты и склады оператора	Проверяет, что товары проходят ограничения по весу и габаритам; узнаёт, на каких складах принимает оператор	Публикует ограничения по продуктам, список приёмных складов/терминалов
3	Расчёт тарифа и срока в checkout	Показывает покупателю варианты и стоимости на checkout, закладывает доставку в цену	Даёт калькулятор тарифа и сроков по направлениям
4	Создание отправления	Формирует заказ на доставку: адрес/точка выдачи, габариты, содержимое, стоимость	Принимает заявку, возвращает идентификатор отправления
5	Подтверждение	Проверяет итоговую стоимость и номер, фиксирует отправление в системе	Подтверждает заявку, закрепляет тариф
6	Ярлыки	Печатает и наклеивает ярлыки на упаковку	Генерирует печатные формы по данным отправления
7	Забор / сдача	Вызывает курьера на забор или отвозит отправления на склад/терминал	Приём по заранее опубликованному графику складов
8	Трекинг	Транслирует статусы оператора в свой жизненный цикл заказа, информирует покупателя	Отдаёт историю статусов (polling) или события (вебхуки)
9	Вручение / невыкуп	Принимает факт вручения или невыкупа, запускает возврат товара	Доставляет до адреса/точки, хранит в ПВЗ установленный срок, фиксирует результат
10	Сверка	Сверяет выставленный счёт с фактически исполненными отправлениями, оспаривает расхождения	Предоставляет акты и реестры исполненных услуг

Правило распределения простое: магазин отвечает за данные и готовность отправления, оператор — за перемещение и факт результата.

Шаги, где чаще всего теряют деньги

Шаг 3. Срок доставки показан без учёта дня оформления (зовут «доставка за 2 дня», а работает только с понедельника по пятницу) — покупатель разочарован до вручения.
Шаг 4. Адрес введён с ошибкой вручную; валидация адреса до создания отправления дешевле изменения в пути.
Шаг 7. Отправление собрано, но курьер не вызван, а склад оператора закрыт — отправление лежит на складе магазина и «висит» в неопределённом статусе.
Шаг 8. Статусы приходят позже, чем покупатель пишет в поддержку, — задержка трансляции события в уведомление.
Шаг 10. Сверка не сравнивает тариф подтверждения с тарифом расчёта: расхождения всплывают на счёте через месяц, оспорить их сложнее.

Технические требования интеграции

Идентификатор точки и оффера. Выбор ПВЗ/постамата передаётся идентификатором точки, а выбранного тарифа — идентификатором оффера, полученного при расчёте. Код точки действителен, пока справочник оператора актуален.
Срок расчёта тарифа. Калькулятор вызывается на checkout, где важна скорость ответа; расчёт кешируется на уровне витрины с учётом зоны и веса.
Fallback при недоступном калькуляторе. Если расчёт недоступен, checkout обязан показать доставку по сохранённым тарифным правилам или «уточнит менеджер», а не блокировать оформление.
Единые внутренние статусы. Статусы операторов маппятся в единый внутренний набор магазина (собран → передан → в пути → в пункте выдачи → вручён), чтобы витрина и персонал работали без знания специфики каждого оператора.
Повторные события. Каждый входящий статус должен обрабатываться идемпотентно: вебхуки и polling дублируются, и повторное событие не должно создавать второй записи или уведомления.
Асинхронность. Создание отправления может подтверждаться позже запроса: система должна хранить промежуточное состояние «создан, ожидает подтверждения» и обрабатывать отказ.
Отдельный вызов курьера. Заявка на забор — самостоятельная операция, а не следствие создания отправления; у неё свои дата, интервал и статус.

Соблюдение этих условий важно и при смене оператора: единый внутренний статусный слой и отделённые от оператора данные заказа позволяют добавить новый канал без переписывания витрины и отчётности.

Мониторинг интеграции

Интеграция доставки — операционно критичная и потому нуждается в наблюдении, а не только в настройке:

Наблюдаемая величина	Тревожный признак	Действие
Доступность калькулятора	Рост ошибок расчёта на checkout	Включить fallback, оповестить витринную команду
Доля необработанных вебхуков	События приходят, но обработка падает	Ретрай и разбор ошибок обработчика
Свежесть справочника ПВЗ	Обновление не приходило более суток	Принудительный запрос и проверка содержимого
Отказы создания заказов	Рост доли отвергнутых заявок	Проверка данных отправлений и лимитов продукта
Задержка статусов	Покупатель знал раньше системы	Проверить очередь событий обработчика

B2C и B2B в интеграции

Один и тот же интеграционный каркас обслуживает оба сценария, но данные, которые передаются оператору, различаются:

B2C. Плательщик — физлицо; на витрине передаются адрес или код ПВЗ, контакт, габариты и стоимость отправления; вручение подтверждается курьером или точкой выдачи.
B2B. Плательщик — юрлицо; вместе с данными отправления передаются товаросопроводительные документы, доверенность на получение и требования приёмки. Процесс приёмки расписан в разделе ниже.

Исключения и граничные случаи

Отказ расчёта тарифа — направление не обслуживается или габариты вне продукта; витрина скрывает недоступный вариант, а не продаёт невозможное.
Невручение — истечение срока хранения в ПВЗ или два неудачных визита курьера; отправление возвращается оператором, магазин фиксирует проблемную отгрузку и решает вопрос с клиентом.
Изменение адреса — правка отправления в пути возможна не для всех продуктов; дешевле проверить данные до создания отправления, чем править после.
Частичный выкуп — в заказе из нескольких позиций покупатель принимает часть; товары, не принятые покупателем, проходят процесс возврата (фулфилмент и возвраты), а деньги — платёжный контур.
Повторное вручение — курьерская попытка не удалась, назначается новая; каждый повтор — отдельное событие трекинга, и уведомления покупателю не должны дублироваться.
Ошибочные данные содержимого — расхождение заявленных позиций с фактом на приёмке оператора задерживает отправление: данные содержимого сверяются до сдачи.

Сверка и экономика сверки

Сверка (шаг 10) — единственный контроль, что подтверждённые тарифы совпали со счётом. Она строится на данных интеграции:

Источник	Данные	Что сверяется
История статусов	Факт вручения, дата	Отправление исполнено и когда
Акты / реестры	Партии, отправления, тарифы	Тариф подтверждения против тарифа расчёта
Собственные записи	Создание, содержание, габариты	Позиции счёта против отправлений магазина

Сверка ищет три класса расхождений: исполнено, но не выставлено; выставлено, но не исполнено; исполнено по другому тарифу. Периодичность — по циклу счёта оператора, но не реже месяца, иначе споры накапливаются.

B2B-доставка

Доставка между юрлицами требует большего, чем «курьер довёз»:

Документы. Отправление сопровождается товаросопроводительными документами; комплект и подписи согласуются между контрагентами.
Приёмка по количеству и качеству. Получатель проверяет комплектность и состояние; расхождения оформляются актом приёмки, а не устной претензией курьеру.
Экспедирование. Допускается согласование погрузки/разгрузки, подъём на этаж, работа в интервал; тарифицируется отдельно.
Планирование. Отгрузки идут по графику договора, а не по одному заказу; интеграция должна поддерживать плановые заявки.

B2C-правила дистанционной продажи (например, автоматическое право отказаться от покупки) на B2B-поставки не переносятся — см. различия в фулфилменте и возвратах.

Связанные страницы

Обзор контура логистики — карта операторов и критерии выбора канала.
Заказы и остатки — куда ложатся статусы доставки и как связаны системы данными.
Каталог и checkout — где покупатель видит варианты и стоимость доставки.
Жизненный цикл платежа — что происходит с деньгами при невыкупе и частичном выкупе.

Материалы и источники

API СДЭК — асинхронное создание заказа, вебхуки статусов, заявка на курьера как отдельная операция.
Яндекс Доставка: API — расчёт тарифа, сценарий создания и подтверждения отправления.
Почта России: спецификация API — пример процессного API отправки и трекинга.
ПЭК: публичный API — расчёт и оформление грузовых отправлений для B2B-сценария.