Интеграция доставки: расчёт, отправления и статусы заказа

Что проверить при интеграции доставки в интернет-магазин: адрес, упаковка, тариф, создание отправления, повторы, отмены и обновление статусов.

Автор: Александр Поркулевич, CEO и основатель, 404gen.

Разложите путь заказа на отдельные решения

Сначала нарисуйте последовательность от корзины до получения. Где определяется доступность товара, когда известны габариты упаковки, на каком этапе покупатель выбирает способ доставки и кто создаёт отправление? В небольшом магазине несколько шагов может делать один сотрудник, но данные и подтверждения всё равно различаются. Эта карта показывает, какие операции можно автоматизировать первыми.

Разделите предварительный расчёт и подтверждённую операцию. Покупатель видит оценку при определённом составе корзины и адресе. После изменения товара, количества или точки получения расчёт может стать неактуальным. Магазин должен явно решить, когда пересчитывать вариант и как согласовать изменение итоговой суммы. Нельзя продолжать использовать старую цену только потому, что она уже сохранена в браузере.

Проверьте роли учётной системы и сайта. Если отправление создаётся из ERP после комплектации, кнопка на сайте может лишь сохранить выбранный способ и необходимые сведения. Если сайт создаёт заявку сам, ERP должна получать его идентификатор и состояние. Два независимых инициатора без общего правила легко создадут две перевозки для одного заказа.

Что выяснить до чтения методов API

Уточните обслуживаемые направления, способы передачи, требования к упаковке, ограничения по товарам и доступные сценарии отмены. Для расчёта может иметь значение склад отправления, вариант забора и параметры каждого места. Всё это относится к реальной логистике магазина. Технический доступ к API не подтверждает, что любой предлагаемый интерфейсом маршрут допустим по условиям обслуживания.

У перевозчика могут существовать разные продукты и разные API: экспресс-доставка, доставка на другой день, пункты выдачи и другие схемы. Не смешивайте их модели заявок и статусов. В документации проекта зафиксируйте, какой продукт используется для каждого сценария, где проходит тестирование и какие ограничения есть у тестового окружения. Смена логистического продукта может потребовать отдельного проектирования.

До разработки распределите ответственность: кто отвечает за тарифную настройку, кто за адреса складов, кто разбирает отказ перевозчика и кто согласует изменение с покупателем. У технической команды должен быть контакт владельца процесса. Иначе интеграция будет технически отвечать, но операторы не поймут, что делать с заказом, для которого нет доступного варианта.

Адрес и упаковка определяют качество расчёта

Сохраните адрес так, чтобы он был пригоден и человеку, и выбранному сервису. Текст из комментария «как в прошлый раз» не является достаточным источником для автоматического расчёта. В интерфейсе нужны понятные поля, проверка обязательных частей и возможность исправить результат подсказки. Координаты и формат адреса передаются по требованиям конкретного API, а не по предположению разработчика.

Вес товара и вес готового отправления могут отличаться. Добавляются упаковка, защитные материалы и несколько мест. Если на сайте известны только размеры карточки товара, договоритесь, как формируется предварительная оценка и когда её заменяет фактическая упаковка. Не скрывайте эту неопределённость за точной суммой, которую невозможно подтвердить после комплектации.

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

Калькулятор показывает вариант, а не завершённую доставку

В документации Яндекс Доставки предварительная оценка вынесена в отдельный метод. Это конкретный пример разделения расчёта и создания заявки. При проектировании собственного магазина зафиксируйте состав входных данных, результат и условие повторного расчёта. Не переносите параметры одного логистического продукта на другой без проверки документации.

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

Не используйте усреднённый срок как гарантированную дату без оснований. API может возвращать диапазон или условия, которые зависят от доступности. Интерфейс передаёт смысл этих данных и различает время отгрузки магазина и перемещения перевозчиком. Если товар ещё нужно изготовить или собрать, срок доставки не должен начинаться раньше его готовности к передаче.

Как сохранить выбор при оформлении заказа

Свяжите выбранный вариант с версией корзины и адреса. Если пользователь меняет количество, точку получения или состав товаров, система проверяет применимость выбора заново. Не достаточно сохранить строку «курьер» и сумму в скрытом поле формы. На сервере должны быть проверяемые основания расчёта, а итог перед оплатой должен соответствовать текущему заказу.

Для пункта выдачи сохраняют устойчивый идентификатор и сведения, необходимые человеку для проверки. Название «пункт у метро» без адреса может быть неоднозначным. Если точка закрылась или перестала принимать нужный тип отправления, заказ не должен продолжать использовать её как доступную. Продумайте уведомление и повторный выбор с сохранением остальных введённых сведений.

На мобильном экране человек должен понимать, к какой части заказа относится срок и стоимость. Карта может помогать выбрать точку, но не должна быть единственным доступным способом. Предусмотрите список с адресами и условиями. При ошибке внешнего виджета полезно сохранить введённые данные и предложить допустимый следующий шаг, а не начинать весь checkout заново.

Создание отправления требует устойчивой связи

У каждой попытки создания должна быть связь с внутренней операцией. В записи сохраняют заказ, состав мест, инициатора, параметры и внешний результат. После ответа перевозчика добавляют его идентификатор. Если запрос завершился таймаутом, отсутствие ответа не доказывает отсутствие созданного отправления. Сначала нужно определить фактический результат предусмотренным способом, затем принимать решение о повторе.

Правило повтора зависит от API. Где-то предусмотрен ключ идемпотентности, где-то клиентский идентификатор или поиск заявки. Не придумывайте универсальную гарантию поверх любого сервиса. В техническом задании укажите, как интеграция отличает новую операцию от повторной и как восстанавливает связь, если ответ потерян после выполнения. Общий принцип разобран в статье про идемпотентность.

Кнопка оператора «Повторить» должна показывать, что именно повторяется. Это может быть проверка состояния уже отправленного запроса, передача непринятого события или создание новой заявки после подтверждённой отмены. Одинаковая подпись для разных операций опасна. В журнале сохраняют основание, чтобы другой сотрудник мог разобраться без переписки с тем, кто нажал кнопку.

Создание, подтверждение и назначение курьера

В начальном сценарии API экспресс-доставки Яндекса перечислены создание, подтверждение и отслеживание заявки. Такая последовательность относится к указанному продукту. Для своего обмена явно опишите обязательные шаги и допустимое время между ними по текущим условиям сервиса. Успешное создание записи не должно автоматически превращаться в сообщение «курьер уже назначен».

Оператору полезно видеть незавершённые заявки отдельно от переданных в работу. Если требуется подтверждение после проверки стоимости, интерфейс показывает актуальное предложение и ожидаемое действие. При истечении его срока понадобится новая проверка, а не повтор старого подтверждения без понимания результата. Статус и доступные действия должны поступать из серверной модели.

Назначение курьера также не равно фактической передаче товара. До передачи могут измениться обстоятельства, состав заказа или доступность сотрудника склада. Сохраняйте соответствующие подтверждения и время. Если в системе есть ручная отметка оператора, она должна отличаться по происхождению от статуса, полученного от перевозчика. Смешение источников затрудняет разбор спорных ситуаций.

Не переводите все статусы в одно «Доставляется»

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

Статусная модель экспресс-доставки Яндекса показывает, что доступные переходы и отмены зависят от стадии заявки. В статье мы не устанавливаем эти условия за перевозчика. При интеграции используйте актуальную модель выбранного продукта и воспроизводите нужные ветви на допустимом тестовом окружении, сохраняя ограничения теста в отчёте.

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

Уведомления и контрольная сверка

Если перевозчик отправляет webhooks, проверьте способ подтверждения их происхождения и обработки повторов. Адрес обработчика не становится доверенным только потому, что его сложно угадать. Состав и механизм проверки определяются документацией сервиса. В журнале достаточно безопасных идентификаторов и результата обработки; персональные сведения получателя не должны без необходимости копироваться в диагностические логи.

Приём уведомления и применение изменения являются разными шагами. Обработчик может принять сообщение, а последующая операция временно не выполниться. Согласуйте, когда отправляется подтверждение доставки события и где сохраняется задача на повтор. Для такой логики полезен отдельный журнал обмена с состояниями и причиной ошибки. Подробности общего механизма есть в статье про webhooks в интеграциях.

Подумайте о контрольной сверке зависших отправлений. Нельзя предполагать, что каждое внешнее уведомление обязательно дойдёт и будет обработано без сбоя. Периодичность и условия запроса состояния выбирают с учётом ограничений API и нагрузки. В отчёте по эксплуатации должны быть видны записи, требующие вмешательства, а не только общий зелёный признак доступности сервера.

Несколько мест и частичная доставка

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

Упаковочный лист связывает товары с местами. Это помогает оператору разобраться, что именно потеряно, отменено или возвращается. Если состав меняется после создания отправления, сначала определите допустимую процедуру изменения у перевозчика. Не редактируйте внутреннюю карточку так, будто внешняя заявка автоматически узнает о новом весе и составе.

В концепте интеграционного рабочего места «Развоз» разделены расчёт, части заказа и разбор неподтверждённой попытки. Все данные учебные, перевозчики условные, реальные заявки не создаются. Интерфейс помогает обсуждать связи и исключения; доступность тарифов, обмен и отсутствие дублей нужно доказывать на технической реализации.

Отмена, изменение адреса и возврат

Отмена заказа магазина и отмена транспортной заявки не всегда происходят одновременно. Если покупатель отказался от товара, оператору нужно видеть, принял ли перевозчик отмену и что осталось сделать. Интерфейс не должен скрывать внешнее отправление сразу после изменения внутреннего статуса. Иначе товар может продолжить путь, а сотрудники уже будут считать вопрос закрытым.

Изменение адреса после создания заявки проверяется как самостоятельный сценарий. Возможность и условия зависят от сервиса и текущей стадии. Если требуется новая заявка, сохраните связь с прежней и основание перехода. Покупателю сообщают итоговый согласованный вариант, а не каждую промежуточную техническую попытку, которая может завершиться отказом.

Возврат может быть отдельным логистическим маршрутом с другим отправителем, составом и подтверждениями. Не переиспользуйте исходный статус доставки как универсальное состояние возврата. Факт возврата денег также относится к платёжному процессу, а не выводится автоматически из перемещения коробки. Эти процессы связывают через заказ, сохраняя самостоятельные основания каждого действия.

Рабочее место для ошибок обмена

Список ошибок должен отвечать на вопросы: какой заказ затронут, где остановилась операция, что уже подтверждено и кто принимает решение. Сообщение внешнего API можно сохранить для технического разбора, но оператору требуется понятная причина и доступное действие. «Ошибка 500» не объясняет, создана ли заявка и можно ли нажать повтор безопасно.

Разделите ошибки исходных данных, временную недоступность и неоднозначный результат. Неверный адрес требует уточнения, недоступный сервис может допускать повтор, а потерянный ответ после создания требует сверки. Автоматический повтор для всех трёх случаев одинаковым способом не подходит. Для каждой категории должны быть ограничение повторов, путь эскалации и сохранённая история.

Ручной обход также должен сохранять связь. Если оператор оформил перевозку во внешнем кабинете, он добавляет её идентификатор в заказ и прекращает автоматическое создание для этой операции. После восстановления обмена система не должна считать отсутствие собственного ответа основанием для второго отправления. Такой сценарий часто важнее декоративной диаграммы доступности интеграции.

Что проверить до production

Подготовьте матрицу: город, способ передачи, состав упаковок, изменение корзины, результат расчёта и последующие переходы. Включите не только обычный небольшой заказ, но и многоместный, недоступное направление и прерывание ответа. Тестовые ограничения перевозчика запишите отдельно: успешный стенд не подтверждает реальное движение посылки и доступность маршрута в рабочем контуре.

• Изменение адреса или состава делает прежний расчёт неактуальным.
• Недоступный вариант нельзя выбрать только подменой данных формы.
• Потеря ответа после создания не приводит к слепому созданию дубля.
• Частичное завершение не закрывает все части заказа.
• Отмена остаётся неподтверждённой до предусмотренного внешнего результата.
• Повторное и запоздавшее событие обрабатываются по согласованной модели.
• Ручное оформление связано с заказом и блокирует ненужное повторное создание.

На передачу нужны карта полей, статусов и владельцев данных, инструкция разбора ошибок и доступы в установленном владельцем проекта порядке. Ключи API не должны находиться в браузерном коде или скриншотах документации. Техническая команда передаёт способ безопасной настройки, проверки и замены доступа без публикации секретов в репозитории.

С чего начать интеграцию доставки

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

Если сайт ещё проектируется, увяжите доставку с разработкой интернет-магазина: моделью корзины, остатками, оплатой и кабинетом покупателя. Исправлять уже запущенный checkout сложнее, когда стоимость доставки записана в произвольное поле без связи с упаковками. Раннее согласование данных помогает избежать ручной сверки после каждого изменения заказа.

Запуск оценивайте по полному пути: покупатель выбирает допустимый вариант, магазин создаёт предусмотренную операцию, оператор видит внешний результат, а ошибка имеет владельца и следующий шаг. Сам факт подключения к API подтверждает технический доступ. Работоспособность логистического процесса проверяется на согласованных историях и затем наблюдается на реальных заказах.

Частые вопросы

Достаточно ли добавить калькулятор доставки?

Калькулятор решает только предварительный выбор. Если магазин хочет создавать отправления и получать статусы автоматически, нужны отдельные операции, связи с заказом, обработка повторов и ошибок. Состав первой версии можно ограничить расчётом, но тогда ручное оформление и сверка должны быть явно описаны и закреплены за ответственными сотрудниками.

Почему стоимость после комплектации может отличаться?

Предварительные данные о товаре и фактической упаковке могут различаться. Влияют состав мест, вес, габариты, склад и выбранный маршрут в пределах правил перевозчика. Магазин заранее определяет точку пересчёта и порядок согласования изменения. Нельзя выдавать приблизительную оценку за подтверждённую окончательную стоимость без оснований.

Что делать после таймаута создания заявки?

Сначала определить, выполнил ли внешний сервис операцию. Для этого используют предусмотренный API способ: устойчивый идентификатор, ключ повтора или поиск состояния. Отсутствие ответа не доказывает отсутствие отправления. Автоматическое создание новой заявки без сверки может привести к дублю, поэтому порядок восстановления результата входит в требования интеграции.

Можно ли объединить все статусы перевозчика?

Для покупателя можно упростить названия, если смысл остаётся корректным. Внутри системы сохраняют исходное состояние и связь с внешним событием. Отмена, неудачная попытка и завершение имеют разные последствия и доступные действия. Таблица соответствия должна объяснять, что видят покупатель и оператор и когда требуется ручное решение.

Нужно ли тестировать реальные отправления?

Сначала используют разрешённое тестовое окружение и проверяют его ограничения. Рабочую проверку с реальной перевозкой согласуют отдельно, поскольку она создаёт внешнюю операцию и возможные расходы. Скриншот интерфейса и успешный стенд не подтверждают движение посылки. В отчёте следует разделять интерфейсную, интеграционную и фактическую логистическую проверку.

Сколько перевозчиков включать в первую версию?

Количество определяется задачей магазина и покрытием нужных маршрутов. Начать можно с одного продукта и полного проверяемого пути. Каждый дополнительный перевозчик добавляет собственные поля, состояния, ограничения и поддержку ошибок. Общий интерфейс не устраняет различия договорных условий и API, поэтому расширение оценивают после работы первого маршрута.

Источники и актуальность

Документация Яндекс Доставки проверена 18 октября 2026 года. Ссылки ведут на разные продукты: предварительный расчёт доставки на другой день и сценарий экспресс-доставки. Они приведены как отдельные примеры, а не единый взаимозаменяемый контракт API. Карта заказа, сценарии приёмки и рекомендации рабочего места являются проектными предложениями для вашего процесса.