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

Первый безопасный прототип запускайте в тестовом режиме провайдера на одном заказе. Сравните адрес и габариты в snapshot с тем, что видит оператор, получите label и tracking number, но не включайте массовый автоматический запуск, пока повтор одного и того же события не возвращает тот же результат.

Заказ и отправление живут в разных состояниях

СостояниеЧто уже зафиксированоДопустимое действие
order_paidОплата подтвержденаПодготовить комплектацию
ready_to_shipАдрес и места провереныСоздать shipment snapshot
label_requestedВыбран тариф и отправлен запросЖдать или запросить transaction
label_readyЕсть provider ID, tracking и файлПечатать и передать на склад
label_failedСохранена безопасная причинаИсправить данные или повторить
label_voidedОтправление отменено у провайдераСоздать новое только по команде

Один заказ может иметь несколько мест или повторную отправку, поэтому provider shipment не стоит хранить единственным полем в заказе. Создайте отдельную сущность с order_id, версией snapshot и техническим статусом. Исправление адреса после покупки не меняет старую накладную молча — оно запускает отмену либо новое отправление по правилам перевозчика.

Снимок не читает изменяющиеся данные повторно

  • Нормализованный получатель и адрес без лишних внутренних комментариев.
  • Список мест с весом, габаритами и единицами измерения.
  • Код услуги и склад отправления, выбранные по правилам магазина.
  • Declared value и данные таможни только для сценариев, где они нужны.
  • Версия заказа и checksum полей, влияющих на доставку.

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

Расчёт тарифа и покупка label — две операции

snapshot = buildShipmentSnapshot(order, version)
rates = carrier.quote(snapshot)
rate = selectAllowedRate(rates, deliveryPolicy)
requestKey = hash(orderId + snapshot.version + rate.id)
transaction = buyLabelOnce(requestKey, rate.id)
store(transaction.id, transaction.status, trackingNumber, labelObjectKey)

В документации Shippo покупка накладной оформлена transaction, а EasyPost отделяет shipment и операцию buy. Названия у провайдеров различаются, но риск одинаков: после сетевого таймаута нельзя считать, что покупка не состоялась. Сначала ищите ранее созданную transaction по своему ключу или сохранённой связи, и только затем решайте, допустим ли новый POST.

Файл накладной сохраняется как артефакт

Ссылка провайдера может быть временной. После подтверждённого успеха скачайте label сервером, проверьте формат и размер, сохраните в закрытом хранилище под собственным document ID и выдавайте складу через авторизованный маршрут. В журнале оставьте checksum, но не адрес и не содержимое PDF.

Очередь различает временную и постоянную ошибку

Таймаут, 429 и временная недоступность получают ограниченный retry с backoff. Ошибка адреса, неподдерживаемая услуга или отрицательный вес переводят запись в label_failed и ждут исправления человеком. Число попыток, следующий запуск и последний класс ошибки видны оператору; кнопка ручного повтора использует тот же request key.

Контрольный сценарий заканчивается на складе

  1. Создать тестовый paid order и перевести его в ready_to_ship один раз.
  2. Сравнить snapshot с ожидаемыми адресом, местами и единицами.
  3. Получить label_ready, tracking и закрытый файл правильного формата.
  4. Повторить событие ready_to_ship и не купить вторую накладную.
  5. Сымитировать таймаут после ответа провайдера и восстановить transaction.
  6. Отменить тестовую накладную предусмотренной операцией и сохранить audit trail.

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

Проверенные источники