配送ラベルが消える？ラベル発行APIのデバッグ実践ガイド

2019年、カリフォルニア州オンタリオの3PL倉庫で、私はこんな光景を目にしました。梱包ステーションに30〜40個の荷物が積み上がり、オペレーターがハンディで一つずつスキャンする。システムは全注文に「ラベル発行済み」と表示しているのに、机の上に実際にあるラベルは半分だけ。プリンターはちゃんと用紙を送っている。ただ……足りない。カスタマーサービスにはすでに問い合わせが来ていました。購入者から「追跡が更新されないのはなぜ」と。午後、チェーン全体を総ざらいした結果、配送会社には何の落ち度もありませんでした。原因は自前のリトライロジックで、冪等性キーを送っていなかった。タイムアウトしたリクエストは実は配送会社側で成功していたのに、システムは失敗と判断して再送信。二回目の呼び出しは同じラベルを返し、最初の一件を上書き。最初の荷物はすでに、貼り替えた方のラベルを付けて出荷済みでした。つじつまが合わなかったのは、上書きされたラベルだったのです。

まず結論を言います。配送会社のラベル発行APIがラベルを「なくす」場合、90%は配送会社のせいではなく、自前のリトライロジックとステートマシンのせいです。残り10%のうち、7割が印刷キュー、3割が配送会社側。過激に聞こえますか？私は米国の倉庫現場で20年働き、両手では数えきれないほど多くのラベル発行APIを連携してきました。根本原因は必ず下の6ステップのどれかです。症状から原因へ、順番にたどるデバッグ手順を示します。半日あれば特定できます。

まず配送会社を疑うな——リクエストログを見ろ

壊れたら、まず見るのはログです。配送会社のダッシュボードではなく、自前のシステムに残る「ラベル発行リクエストが実際に出たのか、配送会社から何が返ってきたのか」の記録です。

見る場所：WMSやミドルウェアのAPIログテーブル。健全な状態：全呼び出しにタイムスタンプ・注文番号・リクエスト本文・レスポンス本文・HTTPステータスコード・レイテンシの記録がある。チェックは3つ。

一つ目：リクエストとレスポンスは全文保存されているか？「成功/失敗」だけ保存してレスポンス本文を捨てるシステムは少なくありません。それはブラックボックスです。完全なリクエスト/レスポンスのペアなしに消えたラベルをデバッグするのは、ほぼ当てずっぽうです。私が見た最悪のケースは注文番号と「OK」だけをログに残すもので、壊れたらチームは配送会社のポータルで一件ずつ突き合わせるはめになりました。半日で済む作業が3日になりました。

二つ目：タイムアウトはあったか、リトライは何回か？ラベル発行APIのタイムアウトは日常茶飯事です。配送会社はピーク時に遅くなり、10秒を超えることもあります。本当の問い：タイムアウト後にリトライしたか、そのリトライに冪等性キーを付けたか？タイムアウトは失敗ではありません。自前のシステムがレスポンスを受け取れていない間に、配送会社側ではリクエストが成功している可能性があります。無計画なリトライは2枚のラベルを発行します。さらに悪いのは、同じ追跡番号を共有する2枚のラベルで、システムが認識するのは二枚目だけというケースです。一枚目はゴーストになります。荷物に物理的に貼られているのに、システムには見えない。

三つ目：レスポンスの追跡番号はシステムに保存されたものと一致しているか？配送会社のマスター追跡番号と荷物レベルの番号を混同して、間違ったフィールドを保存する連携もあります。ラベルは消えていません。見る場所が間違っているだけです。

ログが完全なら、このステップだけで80%の問題が露呈します。ログが不完全なら、他のデバッグの前にまずログを直してください。データなしの結論は迷信です。

一つの注文がAPIを二回叩いたら、何枚のラベルが出る？

ステップ2：冪等性。ここは災害地帯であり、冒頭の話の根本原因です。

健全な状態：同じ注文番号が何回APIを叩いても、配送会社側には有効なラベルがちょうど一枚。新規のラベルを発行する代わりに、繰り返しの呼び出しは最初の結果を返します。この保証は冪等性キーから来ます。通常は注文番号＋業務上の一意識別子で、リクエストと一緒に送ります。

見る場所：自前のAPIラッパー。ラベル発行リクエストは本当に冪等性フィールドを送っているか？ほとんどの配送会社ラベル発行APIが対応しています（正確なフィールド名は配送会社の最新ドキュメントで確認してください）が、送っていない倉庫連携は少なくありません。さらに厄介なパターン：送ってはいるが、粒度が間違っている。「注文番号＋タイムスタンプ」をキーにする例。タイムスタンプは毎回変わるので、送っていないのと同じです。リトライのたびに新しいラベルが発行されます。

検証方法：消えたラベルの注文を取り上げ、ログの中でAPIが何回呼ばれ、各呼び出しが同じ追跡番号を返したか数えます。2回の呼び出しが2つの異なる追跡番号を返し、システムに保存されたのが二回目だけの場合、一回目の追跡番号のラベルが「消えた」ラベルです。実際には存在し、どこかの荷物に貼られています。荷物は出荷済み。システムは知らない。カスタマーサービスが見ているのは「ラベル発行済みなのに追跡が更新されない」です。

もう一つ、データベースレベルの安全策：ラベル/追跡番号カラムにユニーク制約が必要です。これがないと、重複書き込みはエラーになりません。汚いデータが静かに積み上がり、気づいたときには何もつじつまが合いません。この制約の追加はタダで、すぐ効果が出ます。

ラベルは発行されたのに、ステータスが書き戻されない：ステートマシンを見ろ

ステップ3：非同期コールバックとステートマシン。一部のラベル発行APIは非同期です。リクエストを送ると、配送会社は「受付済み」と返し、実際のラベルファイルと追跡番号は数秒〜数分後にコールバックで届きます。

健全な状態：注文ステータスがきれいに遷移します。例えば、pending → creating → created → printed。各遷移にタイムスタンプ。コールバックがまだ来ていなければ、注文は「creating」にとどまるべきで、なぜか「created」になっていてはいけません。

見る場所：ステータス遷移ログ。スキップされた状態に注意：コールバックは来ていないのに、ステータスが「created」になっている。これは大抵、楽観的すぎるポーリングジョブか、リクエスト送信の瞬間に成功とみなすフロントエンドのロジックが原因で、コールバックを待っていません。

さらに厄介なパターン：コールバックは来たのに、自前のコールバックエンドポイントでエラーが発生した。署名検証の失敗、DBロックのタイムアウトなど。配送会社側は「配信済み」、自前は保存できていない。両者が別々の物語を語ります。コールバックエンドポイントのエラーログを見てください。証拠はほぼ必ずそこにあります。誰も読んでいなかっただけです。

結論：ステートマシンは、ラベル発行パイプラインで最も正しく作る価値がある部分です。状態のスキップを許すステートマシンは、ステートマシンではありません。

プリンター：最も濡れ衣を着せられた犯人

最初の3ステップがきれいなら、印刷を見ましょう。Zebraプリンターは思っている以上にジョブを落とします。

健全な状態：ラベルファイルが印刷キューに入り、プリンターが一枚ずつ吐き出し、各用紙に印刷確認が付きます。見る場所：プリントサーバーのキューログ。各ジョブは「完了」か、それとも「エラー/キャンセル」に停滞しているか？Zebraプリンターには古典的な癖があります。リボンやラベル用紙が切れ、ヘッドが過熱しても、誰かに大声で知らせる代わりに、フロントエンドが「送信済み」と表示する間にジョブはキューで静かに停滞します。オペレーターは用紙が出ないのを見て、システムがラベルを作らなかったと判断し、もう一度印刷を押します。印刷確認の握手がなければ、それは重複印刷です。

もう一つの古典的なパターン：ネットワークプリンターが切断・再接続し、キューにたまったバックログが一気に出てきます。オペレーターは数枚を剥がして貼り、残りはごちゃ混ぜに。貼り間違いと貼り忘れがあちこちで発生します。だから私の予防チェックリストは印刷確認の領収書を必須にしています。プリンターが各用紙を確認して初めて、システムはステータスを「printed」に進めます。領収書のない印刷は、印刷していないのと同じです。

配送会社側：レート制限と住所検証、静かに飲み込まれる

最後に、配送会社。正直な結論：真の配送会社側の原因はまれです。年に数回がいいところです。でも調査が一番難しい。問題が自分の手の届くところにないからです。

見る場所：配送会社の開発者ポータルのAPI呼び出し記録とエラーコード。2つのカテゴリに注目します。

一つ目、レート制限。販促期やピークにQPSがアカウントの上限を超えると、配送会社はリクエストを拒否します。きれいな429を返すところもあれば、はっきり言いますが、大手の一社はスロットル時に特定のエンドポイントで200を返し、静かなエラーメッセージを本文に忍ばせています。コードがHTTPステータスだけを見ていると、ラベルが発行されたと信じます。発行されていません。それは静かな失敗です。調査するときはステータスコードだけでなく、レスポンス本文を読んでください。

二つ目、住所検証の失敗。米国の住所はややこしいです。部屋番号やスイート番号の一桁間違い、ZIP+4の不一致で、配送会社側の検証が注文を却下します。本来なら明確な住所エラーとして返るはずですが、一部の連携は検証エラーを汎用例外として飲み込み、「ラベル発行失敗」とだけログに残します。オペレーターは失敗を見て手動で注文を入力します。システム記録とは少し違う住所で。荷物は出荷され、何もつじつまが合いません。このカテゴリでは、事後のデバッグより事前の住所検証が10倍重要です。

具体的なレートやスロットル数の数値はここでは引用しません。配送会社のポリシーは速く変わるので、公式サイトの最新公開ポリシーに従ってください。

日次照合：最後の安全網、そして最初に作るべきもの

ステップ6、そして明日まず出荷してほしいもの：毎日、配送会社の請求書とラベル数を照合してください。

ロジックは単純です。昨日の自前システムの「ラベル発行済み」件数は、昨日の配送会社の請求書のラベル件数と等しくなければなりません。差があれば、その差分が消えたラベルです。チェーンのどのステップが飲み込んだにせよ、数字は嘘をつきません。

やり方：毎日深夜に配送会社の請求書や利用レポートを取得し（ほとんどの配送会社ポータルはエクスポートできます）、自前のシステムのラベル記録と追跡番号で一件ずつ突き合わせる日次照合ジョブを書きます。例外リストは毎朝、オペレーションとITの受信箱に届きます。初回実行で驚くかもしれません。それは過去の負債が一気に表面化したということです。良いことです。仕組みが今まで丸裸で動いていたということです。

アラートは2段階を推奨します。業務レベル：営業時間中に10分間ラベルが発行されなければアラート。通常の稼働で梱包ステーションが10分間ラベル一枚も発行しないことはありえません。発報すればほぼ確実にAPIダウンです。照合レベル：日次例外件数が5件を超えたら人にエスカレーション。しきい値は自社の量に合わせて調整してください。ただし、しきい値は必ず設ける。しきい値のない監視は監視ではありません。

予防チェックリスト：この5つをやれば、消えるラベルはほぼなくなる

デバッグは病気を治し、予防は健康を保ちます。5項目、費用対効果の順：

あと一つ：完全なリクエスト/レスポンスのログを最低90日間保持してください。ストレージの文句は言わないでください。消えたラベルの紛争が机に届いたとき、そのログが証拠になります。

最後に、実際に考えてほしい問いを一つ。今夜、過去1か月でラベル発行APIを2回以上叩いた注文が何件あるか調べてみてください。その数が、あなたのゴーストラベル母数の上限です。眠れなくなるかもしれません。でも、カスタマーサービスに叩き起こされるよりはましです。

英語版からの翻訳。内容に相違がある場合は英語版を優先します。