Накладную лучше создавать не при появлении корзины и не при каждом сохранении заказа, а после явного события 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.
Контрольный сценарий заканчивается на складе
- Создать тестовый paid order и перевести его в ready_to_ship один раз.
- Сравнить snapshot с ожидаемыми адресом, местами и единицами.
- Получить label_ready, tracking и закрытый файл правильного формата.
- Повторить событие ready_to_ship и не купить вторую накладную.
- Сымитировать таймаут после ответа провайдера и восстановить transaction.
- Отменить тестовую накладную предусмотренной операцией и сохранить audit trail.
Для проектирования подготовьте пример заказа без персональных данных, правила выбора тарифа, обязательные поля перевозчика, форматы печати и переход, после которого адрес нельзя менять незаметно. По ним можно собрать адаптер API и очередь без привязки бизнес-модели ко всему ответу одного провайдера.