ТЗ на доставку в магазине: тариф, отправление, трекинг и повтор

Разделите расчёт, оформление и отслеживание

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

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

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

Подтвердите договоры, географию и исходные данные

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

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

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

Согласуйте жизненный цикл тарифа и срока

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

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

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

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

Определите момент оформления: после оплаты, резервирования товара, подтверждения менеджером или завершения упаковки. Укажите, какие данные на этом этапе уже окончательны. Если отправление создаётся слишком рано, последующее изменение заказа потребует отмены или корректировки; эти действия нужно включить в требования, а не считать редкой случайностью.

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

Особенно важен неопределённый результат: перевозчик мог создать накладную, но ответ потерялся. В приёмке проверьте порядок выяснения состояния до повторного оформления. Конкретный API может предоставлять свой механизм идемпотентности или поиска; если его нет, нужен согласованный способ сверки и ручной разбор. Безусловный повтор после любого тайм-аута способен создать лишнее отправление и запутать склад.

Обрабатывайте трекинг как последовательность фактов

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

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

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

Предусмотрите отмену, возврат и ручную сверку

Отмена заказа, отмена накладной и возврат уже переданного груза — разные операции. Укажите допустимые действия на каждом этапе и источник подтверждения. Сотрудник не должен видеть «доставка отменена» только потому, что магазин отправил запрос. Если перевозчик отказал или результат неизвестен, нужно отдельное состояние и ответственное действие.

Разберите частичные сценарии: одна посылка получена, другая возвращается; товар переотправлен; покупатель изменил способ получения. Сохраняйте историю и связи между исходным и новым отправлением. Не перезаписывайте старый трек-номер так, чтобы служба поддержки потеряла возможность объяснить предыдущие события.

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

Соберите приёмочный набор с ошибками

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

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

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

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

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

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

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

Передайте поддержку и правила изменения

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

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

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