ラベルは印刷された。荷物は発送されなかった。10回中9回、注文はAPIチェーンのどこかで消えている。
2023年のピークシーズン、ロサンゼルスの3PL倉庫から相談を受けた。1日12,000件の注文を処理し、ラベルプリンタはフル稼働——それなのに毎晩、キャリアの実際の引き取り数がシステム上の発送数より300個以上少なかった。クレーム、返金、再出荷：毎日数千ドルが燃えていた。ピッキングは問題ない。印刷も問題ない。消えた注文はすべて、WMSとキャリアのラベルAPIの間のチェーンで死んでいた。
結論を先に言う。消えたラベルがプリンタで死ぬことはほとんどない。真の犯人は3つだ。リクエストが自社を出ていない、タイムアウトリトライで重複ラベルが作られた、誰もリコンサイルしていない。このトラブルシューティングの手順は、キャリアのラベルAPI連携を長年やってきた経験から生まれた。順番にたどれば、断裂点が見つかる。
ステップ1：リクエストは自社を出たのか？
注文を消す一番間抜けな方法は、WMSがリクエストを送らないこと——あるいは送ったのに応答が返ってこず、通ったものと決めつけてしまうことだ。
私が最初に見るのは必ずローカルのリクエストログだ。WMS上の注文ステータスではない。送信ゲートウェイの呼び出し記録だ。この注文について、「キャリアへのラベルリクエスト」の記録はあるか。なければ、APIドキュメントを読むのもタイムアウト調整もやめてくれ。問題は自社側にある。よくある犯人は、メッセージキューのコンシューマが死んでキューが静かに溜まっている、定期ジョブが起動していない、注文がステータス遷移で詰まっている——OMSは注文を渡したのに、WMSはウェーブ解放待ちのままで、ラベルリクエストが発火しなかった。何度も見てきた。ピークシーズンの混乱、誤ったウェーブポリシー設定、そして数百件の注文が「解放待ち」に静かに積み上がり、ラベルリクエストは一度も送られていなかった。
もっと厄介なパターンもある。リクエストは出たのに、ログに残っていない。成功だけを記録するシステムもある。ログのローテーションが激しすぎて、肝心な時間帯の記録がもう消えていることもある。クライアントへの私の鉄則はこうだ。ラベルAPIの呼び出しはすべてフルで記録する——何を送り、いつ、応答は何で、どれだけ時間がかかったか。キャリアと料金の食い違いを争うとき、顧客クレームに対応するとき、ログが唯一の証拠になる。ログが不完全では、断裂点を見つける手伝いは誰にもできない。
ステップ1の結論はシンプルだ。ログに記録がなければ、問題は自社の壁の内側——まず内部チェーンを直す。記録があれば先に進む。
タイムアウトこそ真の犯人：キャリア側ではラベルが作られていたかもしれない
注文を消す最も致命的で、最も不公平な方法がこれだ。
場面はこうだ。WMSがキャリアのラベルAPIを呼び出し、キャリアの処理が遅すぎて、タイムアウトを超える（キャリアごとに違う——各社のドキュメントに従うこと）。WMSはタイムアウトと判定して自動リトライする。2回目の呼び出しは成功し、ラベルが返ってきて、みんなで喜ぶ——しかし1回目のリクエストは実はキャリア側でラベルを作っていた。応答が戻ってこなかっただけだ。こうしてこの注文にはラベルが2枚、追跡番号が2つある。
2つの結果が待つ。1つ目、料金を二重に払う。ラベル作成ごとに課金するキャリアもあり、ボイド（無効化）の手続きがあまりに面倒で、小規模倉庫は1件ずつ潰すのを諦める——お金は静かに漏れていく。2つ目、倉庫は1枚のラベルだけを荷物に貼って発送する。もう1枚はゴーストラベルになる——システム上は作られ、顧客は追跡できるのに、その荷物に引き取りスキャンがつくことは永遠にない。カスタマーサービスが調べる。有効な追跡番号、追跡イベントはゼロ。誰も説明できない。コストを飲み込んで再出荷する。腹が立つのは、WMSは正常に見え、キャリアの追跡も「正常」に見えることだ——両方とも正常なのに、貨物は動いていない。
対策は2語だ。冪等性（idempotency）とリトライポリシー。
冪等性とは、ラベルリクエストごとに業務上のユニークキーを付けること——たとえば注文番号＋パッケージ連番——同じキーでの繰り返しリクエストには、キャリアのAPIが同じラベルを返すことだ。連携時にキャリアと確認すること。一部のAPIは冪等性がデフォルトで有効になっていない。契約や設定で要求しなければならない。これなしにリトライを投げるのは、自分で地雷を埋めるようなものだ。何かが壊れた後ではなく、交渉の段階で契約書に書かせる。
リトライポリシーとは、タイムアウト後に盲目的に再送しないことだ。私のやり方はこうだ。最初のタイムアウトではまずキャリアに問い合わせる——注文やパッケージの参照番号で、ラベルが実際に作られたかを確認する。作られていれば既存のものを使う。作られていなければ再送する。1回の問い合わせは、ゴーストラベルの山を掃除するよりずっと安い。リトライ回数に上限を設け、間隔を空け、キャリアのシステムが苦しんでいるときに畳み掛けない。ピークシーズンはキャリアのAPI自体が遅い——盲目的なリトライはさらに遅くするだけの悪循環だ。
プリンタはどうか。プリンタが注文を消すことはめったにない。印刷したのに貼られていないラベル、違う荷物に貼られたラベル——それは現場管理の問題で、カメラとピッキング記録で解決する。APIの問題ではない。APIチェーンで死ぬ注文のうち、10回中9回は「タイムアウト」という言葉で死ぬ。
リコンサイルを毎日回して、残りは全部拾わせる
最初の2ステップは「壊れたときにどう調べるか」だ。これは「壊れたらすぐにどう気づくか」だ。
チェーンがどんなに堅牢でも、私はクライアントに日次リコンサイルジョブを必ず回させる。ロジックは3行だ。キャリアのラベル作成数を取り出す（リコンサイルAPIか請求データのダウンロードで）、WMSの実発送数を取り出す、注文番号か追跡番号で突き合わせる。差分が消えた注文だ。定義に注意する。ボイド済みラベルは除外する。キャリアごとに別々に突き合わせる——キャリアAのラベルをキャリアBに数えない。そして毎日決まった時間に回す。私は早朝を勧めることが多い。キャリアの締め処理の時間帯を外して。
アラートの閾値はどう決めるか。私の経験則はこうだ。差分がその日の出荷量の0.5%を超えたらアラート、2%を超えたら誰かの電話を鳴らす。差分が出るたびにアラートしない——キャリアは夜間の締め処理のようにバッチでラベルを作ることがあり、今日作ったラベルが請求ファイルに載るのは明日かもしれない。ゼロ許容はアラート無視の訓練にしかならない。本当に大事なときに誰も見なくなる。閾値は使うためにある。崇めるためではない——敏感すぎる設定は、設定なしと同じだ。
あのロサンゼルスの3PLは、このリコンサイルジョブで生き延びた。導入前は、1日に何件消えているかすら言えなかった——それが一番怖い。問題の大きさが分からないことだ。稼働後は、消えた注文は1日300件以上から1桁に減り、残りは現場での貼り間違いだけになった——APIとは無関係だ。毎朝、現場はリコンサイルレポートで1日を始める。差分は当日中に調査する。問題を一晩寝かせない。
この手順を覚えてくれ。まずログ、次にタイムアウト、そしてプリンタ——リコンサイルは毎日だ。
英語版からの翻訳。内容に相違がある場合は英語版を優先します。
