結論から先に言います。配送ラベルが消えたとき、配送業者が悪いことはほぼありません。注文は、WMSと配送業者のラベルAPIの間にある自社の連携チェーンのどこかで死んでいます。まず配送業者に電話するのはやめましょう。次の順序でデバッグしてください。WMS出荷→API/キュー層→配送業者の応答→ステータスの書き戻し→印刷ステーション。注文が止まった場所、そこが問題のありかです。順番を間違えると、3日間無駄に燃えます。
注文が「消える」理由
ラベル要求は、荷物に届くまでに5つのリンクを通過します。
- WMSが出荷要求を生成する。
- 連携層（ミドルウェア）が配送業者のAPIに送信する。
- 配送業者がラベルデータと追跡番号を返す。
- WMSが追跡番号を注文に書き戻し、「印刷待ち」に移す。
- 梱包ステーションがラベルを印刷し、作業者が箱に貼る。
各リンクが注文を飲み込む可能性があります。要求が外に出ない、消費されないキューで腐る、自社側が配送業者の応答を読む前にタイムアウトする、書き戻しが失敗する、プリンタがオフライン——。エラーは簡単なケースです。少なくとも見えますから。致命的なのはサイレント障害です。自社のWMSは要求を送ったと思い込み、配送業者は来ていないと思い込み、注文はその隙間に座り込み、どちらにも主張されない。だから倉庫は「注文が消えた」と叫び、ITは「ログは正常に見える」と主張するのです。
私は3回見た：2つの修羅場
1つ目は昨年の11月、UPSのラベルAPIを使った中国東部の3PLアパレル倉庫での話。1日に20〜30枚のラベルが消え、配送業者はバックエンドに要求が来ていないと断言しました。午後の調査で原因が判明。タイムアウトは5秒、繁忙期の配送業者APIの応答は8〜10秒でした。タイムアウトのたびにWMSは注文を「ラベル失敗」とマーク——一方で配送業者はすでにラベルと追跡番号を生成していました。1つの注文に2つの物語。WMSは手動再印刷待ちの失敗を表示し、配送業者の請求にはすでにラベル代が計上。さらに悪いことに、倉庫は「失敗」と見て再試行を押し、再試行は同じ注文に2つ目の追跡番号を生み出しました。1荷物に2つの候補ラベル——間違った方を選べば、紛失荷物と怒った顧客の出来上がりです。
2つ目は今年の3月、国際配送業者のAPIを使う中国南部の越境EC倉庫。深夜0時から2 AMの間の注文が大量に消え、昼間は完璧でした。より厄介な根本原因。配送業者のAPIには夜間のメンテナンスウィンドウがあり「サービス利用不可」を返していましたが、WMS連携層には障害キューがまったくありませんでした。失敗した要求はそのまま破棄——再試行なし、アラートなし、記録なし。2時間分の注文はシステムに痕跡を残さず、注文は「ラベル待ち」に止まり、倉庫はシステムの遅延だと思い込んで朝まで待ちました。ログが真実を示しました。丸2時間分の要求はそもそも送信されていなかったのです。連携層が飲み込んでいました。
症状は違っても根本原因は同じ。ラベルチェーンのリコンサイルを誰もやっていなかった。お金はリコンサイルする。在庫はリコンサイルする。ラベルは？誰の仕事でもなかった。
プレイブック：5つのリンクのデバッグチェーン
これは私の本番稼働の夜のチェックリストです。稼働前にすべての項目にチェックを入れてもらいます。
**ステップ1：WMSの出荷ログを確認。**出荷可能なすべての注文に、注文番号・荷物の重量と寸法・サービス商品を含む出荷要求レコードがあることを確認。出荷要求がWMS内に生成されていないなら、問題は内部——注文の状態遷移が詰まっているか、出荷スケジューラが死んでいる。APIは飛ばして。
**ステップ2：連携層のキューを確認。**非同期出荷なら、キューの滞留、コンシューマが生きているか、デッドレターキューに何が溜まっているかを見る。同期呼び出しなら、タイムアウトと再試行の設定を見る。タイムアウトは配送業者のSLA応答上限より短くしてはならない——繁忙期は余裕を持って倍に。アパレル倉庫の5秒タイムアウトはここで見つかりました。
**ステップ3：配送業者の応答を確認。**すべての要求に要求-応答のペアログが必要。何を送ったか、タイムスタンプはいつか、何が返ってきたか、追跡番号は何か。応答なしで要求だけ記録するのは、何も記録しないのと同じ——私が見た最悪のシステムは「呼び出し成功」という言葉だけを保存し、追跡番号すらありませんでした。
**ステップ4：ステータスの書き戻しを確認。**配送業者が追跡番号を返した後、WMSはそれを注文に書き戻し、ステータスを「印刷待ち」に進めなければならない。書き戻しの失敗は再試行キューに入れ、決して黙ってスキップしない。書き戻しは最大の犠牲ゾーンです——多くのシステムでは要求と書き戻しは独立した2つのトランザクション。要求は成功し、書き戻しは死に、注文は宙に浮く。配送業者は持っている、WMSは持っていない。
**ステップ5：プリンタを確認。**梱包ステーションのプリンタがオフラインになる、用紙切れ、ドライバがクラッシュ、ラベルが出てこない、作業者が「再印刷」をクリック。再印刷は再印刷フローで——既存の同じ追跡番号、新しい用紙。新しいラベル要求を発行してはならない。1つの注文が2つの追跡番号になり、月末のリコンサイルがあなた個人の悪夢になります。
**ステップ6：チェーン全体をリコンサイル。**日次締め後に4方向リコンサイルを実行。WMS出荷件数＝連携層要求件数＝配送業者成功件数＝印刷件数。不一致があれば、それが失われたラベル、定量化された。このリコンサイルスクリプトは本番稼働初日に存在しなければならない——最初のインシデントの後ではない。遅れて書けば「何枚失ったか」にも答えられなくなります。
**ステップ7：冪等キー。**すべてのラベル要求に、グローバルに一意な冪等キーを付ける。注文番号＋荷物連番を使い——注文番号単体は絶対にダメ、複数荷物の注文で衝突する。配送業者側も自社の連携層も、このキーで重複排除しなければならない。「再試行が重複ラベルを印刷する」ことへの唯一の防御です。2つ目はありません。
| リンク | 典型的な症状 | デバッグアクション |
|---|---|---|
| WMS出荷 | 「ラベル待ち」で止まった注文、要求レコードなし | 注文の状態遷移、出荷スケジューラを確認 |
| APIキュー | レイテンシ増大、デッドレターキューの滞留 | コンシューマの健全性、キュー深さアラートを確認 |
| 配送業者の応答 | 頻発するタイムアウト、散発的な失敗 | タイムアウト設定、配送業者のステータスページ、ペアログを確認 |
| ステータスの書き戻し | 追跡番号はあるが注文ステータスが変わらない | 書き戻しトランザクション、再試行キューを確認 |
| 印刷ステーション | 作業者から「印刷されない」との報告 | プリンタの状態を確認、再印刷フローを使用、新規要求は出さない |
よくある失敗ポイント（本番前のセルフチェック）
- タイムアウトが短すぎる。繁忙期に必ず爆発する。私は3回見ましたが、毎回「大セールまでは動いていた」で始まります。
- 失敗をキューに入れず破棄する。深夜のメンテナンスウィンドウや配送業者のランダムな500が「注文が見つからない」になります。
- 冪等キーなしの再試行。再試行は気持ちいい。月末のリコンサイルが二日酔い——配送業者は重複ラベル1枚ごとに課金します。
- お金と在庫はリコンサイルするのにラベルはしない。財務は合う、在庫は合う、顧客から「荷物が届かない」と報告されるまで、数十枚のラベル紛失に誰も気づきません。
- 「呼び出し成功」を「ラベル生成」とみなす。配送業者APIからの200は、ラベルが生成された意味ではありません。応答ボディ内の業務ステータスコードを読んでください——配送業者はHTTP 200で業務失敗を包むのが常套です。
直感に反する部分
最も危険な失敗モードはエラーではありません——偽の成功です。エラーはアラートを鳴らし、誰かが見ます。でも「要求は送信済み、WMSは成功表示、配送業者は受信していない」は何週間も静かに座り込み、大セールの朝に爆発します。これを防ぐルールは1つ。配送業者が返した追跡番号だけが真実の源泉。追跡番号のない注文は、すべて未出荷扱い。本番前に倉庫とカスタマーサービスと足並みを揃えないと、インシデント後に三者で言い争いになります——ITが罪を被る形で。
正直に語るべきトレードオフが1つ。同期呼び出しと非同期キューの選択。同期はシンプル——作業者が印刷をクリックして結果を知る——でも配送業者の応答が1つ遅いと梱包ライン全体が止まります。非同期はスループットを稼ぎ、スパイクを吸収しますが、チェーンが長くなり、デバッグは2倍難しくなります。私のルール。1日5,000件未満なら、短いタイムアウトの同期＋失敗は手動レビューキューへ。それ以上なら非同期——ただし上記のフルチェーンのリコンサイルとアラートを先に整えてから。非同期は銀の弾丸ではありません。「目の前のエラー」を「事後のリコンサイル」に変えるだけ。リコンサイルが弱ければ、非同期の損失は同期より見つけにくくなります。
ラベルAPIは、セールの日の3 AMまでは平和に見えます。このチェックリストを印刷して梱包ステーションの横に貼ってください。どんなダッシュボードより頼りになります。
Lin Xiao（WMS導入コンサルタント）著
英語版からの翻訳。内容に相違がある場合は英語版を優先します。
