Shipping API 配送ステータス：ステータスコード、Webhook、例外アラート

配送 API の配送ステータスは、荷物の進捗を示すものであり、API リクエストが成功したかどうかを示すものではありません。信頼性の高い追跡を構築するには、HTTP レスポンスコードと配送ステータスを分離し、Webhook は一度だけ、または順序どおりに届くとは限らないことを前提に処理し、対応が必要な例外を明確な担当者付きのアラートに変換します。エンジニアリングチームと e コマース運用チームにとっての目標は、配送会社からの更新が遅延、重複、訂正された場合でも信頼性を保つ配送記録です。

このガイドでは、その記録の構成方法、受信した追跡イベントの処理方法、配送上の問題と追跡連携の問題を区別する方法を説明します。

HTTP コード、API 結果、配送ステータスを分離する

「ステータスコード」という言葉は、3 つの異なる層を指す場合があります。これらを混同すると、誤解を招くダッシュボードや不要な顧客通知が発生します。

層	示す内容	解釈例
HTTP レスポンス	HTTP リクエストの結果	200 レスポンスは HTTP レベルでの成功を示しますが、荷物が配達されたことを意味しません。
API ビジネス結果	プロバイダーのアプリケーションルールに基づき、要求された操作が成功したかどうか	API がそのような設計を採用している場合、HTTP レスポンス自体が成功していても、レスポンス本文で追跡登録が拒否されたことが報告される場合があります。
配送ステータス	荷物の報告された物理的または運用上の状態	輸送中、集荷待ち、配達済みなど。

HTTP セマンティクス標準は、HTTP レスポンスの意味を定義しています。たとえば、202 Accepted はリクエストが処理のために受け付けられたことを意味しますが、処理が完了したとは限りません。これは配送会社が荷物を受け付けた証拠ではありません。

同様に、追跡リクエストの失敗は、配送が停止したことを証明するものではありません。物理的な配送が正常に続いている間、一時的にアプリケーションから追跡情報が見えなくなることがあります。これらの層は独立して監視してください。

配送会社の詳細を破棄せずにステータスモデルを作成する

すべての配送 API と配送会社で共通して使用される、普遍的な数値の配送ステータスコードはありません。ある連携の値を、別のプロバイダーのマッピングで解釈してはいけません。実装する特定の API バージョンのドキュメントを使用してください。

実用的な内部モデルでは、少数の正規化されたステータスと、元の配送会社イベントを組み合わせます。正規化は一貫したレポートを可能にし、元のイベントは調査に必要な詳細を保持します。

内部ステータスの例	意味	運用上の注意
情報受信済み	電子的な配送情報が存在する。	ラベルの作成を、物理的な引き渡しが確認されたものとして扱わないでください。
輸送中	追跡記録が配送ネットワーク内での移動を示している。	この広いカテゴリには、異なる輸送段階が含まれる場合があります。
配達中	荷物が配達ルート上にあると報告されている。	これを無条件の配達保証に変換しないでください。
集荷待ち	受取人が荷物を受け取ることが想定されている。	情報源で裏付けられている場合にのみ、集荷方法や期限を含めてください。
配達済み	追跡元が配達を報告している。	配達スキャンだけでは、顧客の未着申告は解決しません。
例外	イベントに対応が必要、または通常の進行が中断される可能性がある。	すべての例外を紛失として扱うのではなく、理由を保持してください。
返送中または返送済み	荷物が戻る途中、または返送完了が報告されている。	元の受取人への配達と返送の進行を区別してください。
不明	利用可能な情報を確実にマッピングできない。	配送状態を作り出すのではなく、マッピングまたはデータの欠落を調査してください。

これらのラベルは推奨されるアプリケーションモデルであり、公式の 17TRACK コード一覧ではありません。プロバイダーのステータスコード、サブステータス、説明、イベント時刻、タイムゾーン情報、場所、利用可能な場合は受信時刻を保持してください。また、後で行われるマッピング変更を監査できるよう、マッピングのバージョンも保持してください。

マルチキャリア実装では、17TRACK Tracking APIが関連する連携オプションです。プロバイダー固有のフィールドに例示ラベルをコピーするのではなく、公式 API ドキュメントを使用して実装契約を確立してください。アダプターを構築する前に、適用されるステータス定義、Webhook 設定、認証要件、レスポンスの意味を確認してください。

永続的な受信を中心に Webhook 処理を構築する

Webhook は、イベントを報告するためにエンドポイントへ送信される HTTP リクエストです。繰り返しポーリングする必要性を減らせますが、即時、順序どおり、または正確に一度だけ配信される保証として扱ってはいけません。プロバイダーが別途明示的に保証していない限り、再試行、中断、予期しないペイロードに耐えられるよう受信処理を設計してください。

1. リクエストを認証する。プロバイダーが文書化している検証方法を適用します。署名がサポートされている場合は、指定されたアルゴリズムと生のリクエストバイトを使用して検証してください。署名ヘッダーを独自に作成したり、すべてのサービスが HMAC を使用すると想定したりしないでください。
2. ペイロードを検証する。必須フィールド、型、ペイロードサイズ、およびアカウントが管理する配送との関連付けを確認します。将来の互換性を不必要に壊さないよう、未知のオプションフィールドを処理してください。
3. 確認前に永続化する。文書化された成功レスポンスを送信する前に、受け付けたイベントを保存するか、永続的なキューに入れます。永続化に失敗した場合は、イベントを安全に受信したと確認してはいけません。
4. 非同期で処理する。可能な場合、ステータスマッピング、注文更新、通知判断はリクエストハンドラーの外で実行します。
5. 副作用を冪等にする。同じイベントが繰り返されても、別のサポートチケットを作成したり、同じ顧客メッセージを再送したりしないようにします。

確認コード、タイムアウト、再試行スケジュール、再生動作の正確な内容はプロバイダーによって異なります。これらの詳細を明示的に確認してください。「200 を返す」という一般的な指示は、Webhook の契約の代わりにはなりません。

HTTPS を使用し、認証情報を URL や通常のログに含めないでください。追跡データには個人情報が含まれる可能性があるため、保存されたペイロードにアクセス制御を適用します。OWASP REST Security Cheat Sheetには、通信の保護、入力検証、エンドポイントセキュリティに関する関連ガイダンスがあります。

実際の更新を抑制せずにイベントを重複排除する

利用可能な場合は、文書化された安定したイベント識別子を優先してください。それ以外の場合は、配送の識別情報、イベントタイムスタンプ、イベントコード、場所を慎重に選び組み合わせて重複排除キーを作成します。正当な 2 つのイベントが同じタイムスタンプを共有する場合や、同じイベントが少し異なる説明文で届く場合があるため、実際のペイロードでこの方法をテストしてください。

イベント取り込みと下流アクションには、別々の重複排除制御を使用します。訂正としてステータス更新を再度保存する必要があっても、顧客通知は抑制すべき場合があります。各通知またはチケットアクションに、それぞれ固有の永続的な識別情報を付与してください。

イベント時刻と受信時刻を分けて保持する

輸送中のイベントが配達中イベントの後にシステムへ届いたものの、配送会社のタイムスタンプはそれより前だったとします。そのイベントを履歴に保存し、現在のステータスを自動的に輸送中へ戻してはいけません。

すべてのケースでタイムスタンプの順序だけでは不十分です。タイムゾーンの欠落、訂正されたスキャン、競合する情報源には明確なルールが必要です。タイムスタンプの精度とオフセットを保持し、各イベントをシステムが受信した時刻を記録し、利用可能な場合は文書化されたプロバイダーの順序情報を使用してください。厳格な一方向のみのステータス階層を設けないでください。配達試行、転送、返送、訂正によって、後戻りしたように見える正当な遷移が発生することがあります。

例外を担当者が実行するアクションに変換する

例外アラートには、何が起きたか、必要なアクション、次のステップの担当者を示す必要があります。一般的な「配送例外」というメッセージでは、運用スタッフが同じ調査を繰り返すことになり、顧客を不安にさせるだけで問題解決には役立ちません。

まずは小規模な振り分けポリシーから始めます。

• 住所またはアクセスの問題: カスタマーサポートに振り分け、問題を確認し、配送会社が利用できる訂正手続きを確認します。変更可能であることを確認する前に、住所変更を約束しないでください。
• 集荷が必要: 情報源が利用可能な集荷指示を提供している場合は、受取人に通知します。確認済みの期限があれば保持してください。
• 通関対応が必要: 要求された書類や情報を提出すべき担当者に基づいてケースを割り当てます。通関関連イベントだけでは、支払い義務があるとは確定しません。
• 配達試行が不成功: 再配達や集荷を案内する前に、報告された次のステップを確認します。
• 差出人へ返送: 運用レビューを開始します。ポリシーで明示的に認められていない限り、広範な追跡ラベルだけを根拠に自動で返金しないでください。
• 配送会社が報告した紛失または破損: 請求担当者に振り分け、イベントの証拠を保持します。請求の判断と一般的な遅延検出を分離してください。

各アラートには、配送識別子、注文参照情報、イベント理由、元のタイムスタンプ、最新の既知の状態、割り当てられた担当者、次のアクションを含める必要があります。共有メッセージングチャネルで不要な顧客情報を公開するのではなく、関連する内部記録へのリンクを含めてください。

「更新なし」を別の状態として扱う

最近のスキャンがない荷物は、自動的に紛失したわけではありません。チェックポイント間にある、初回の物理スキャンを待っている、または可視性の欠落の影響を受けている可能性があります。

一律のタイマーを適用するのではなく、サービス、経路、配送段階、ビジネス上の約束に基づいて非アクティブのしきい値を定義します。受領スキャンを一度も受けていない荷物と、ネットワークに入った後に更新が停止した荷物を区別してください。過去の証拠が限られている場合は、紛失を宣言するのではなく、調査を開始するためにしきい値を使用します。

変更のないケースが開いたままの間は、繰り返しアラートを抑制します。新たな証拠が現れた場合、合意したフォローアップが行われなかった場合、または顧客への配送約束に対応が必要な場合はエスカレーションします。

配送実績とは別に連携の健全性を監視する

API 監視は、追跡連携が機能しているかどうかに答えるものです。配送監視は、荷物に何が起きているかに答えるものです。正常なエンドポイントでも古い配送会社データを受信することがあり、利用できないエンドポイントでは、正常に移動中の荷物の更新を取り逃すことがあります。

• リクエストの健全性: 認証失敗、タイムアウト、レート制限レスポンス、サーバーエラー、アプリケーションレベルの拒否を追跡します。
• Webhook の健全性: 検証失敗、確認応答の遅延、永続化失敗、重複配信、処理エラーを追跡します。
• 処理の健全性: キューの経過時間、未処理イベント、マッピング失敗、通知失敗を監視します。
• 追跡の鮮度: 元のイベントからの経過時間と、最後に正常に取り込んでからの経過時間を分けて測定します。
• 運用結果: 未解決の例外、担当者決定までの時間、期限超過したフォローアップを追跡します。

リクエストの再試行については、プロバイダーのレート制限および再試行ガイダンスに従ってください。重複登録やその他の副作用を生じる可能性のある操作を盲目的に繰り返さないでください。利用可能な場合は、文書化された冪等性メカニズムを使用します。

サポートされている場合は、障害後またはイベントの取り逃しが疑われる場合に、最新の追跡記録を取得する照合プロセスを使用します。頻度は契約上の制限とレート制限の範囲内に設定してください。Webhook と照合は異なる目的を持ちます。前者は変更を届け、後者は欠落を検出して修復するのに役立ちます。

顧客通知を有効にする前に障害ケースをテストする

まずは内部のみの処理から始め、ステータス変更によって顧客メッセージを送信できるようにする前に、代表的な配送を確認します。輸送中から配達済みまでの通常の進行以外もテストしてください。

• 重複した Webhook が、意図した顧客通知を 1 件だけ作成する。
• 古いイベントが遅れて到着しても、現在の状態を誤って置き換えない。
• 未知のステータスが保持され、配達済みへ黙ってマッピングされずにフラグ付けされる。
• 永続的な書き込みに失敗した場合、成功の確認応答を生成しない。
• 一時的な下流障害が発生しても、イベントを再試行可能な状態で保持する。
• 配達済みイベントの後に訂正が届いても、監査可能な状態を維持する。
• 複数個口の注文が、1 個だけ配達された時点で完全配達にならない。
• API 障害がエンジニアリングチームにアラートを送り、荷物が遅延していることを顧客へ自動通知しない。

リリース基準は運用上の一貫性であるべきです。配送記録、顧客メッセージ、サポートアクションが、同じ基礎証拠と一致していなければなりません。Webhook の成功レスポンスだけでは、配送体験が機能していることを証明できません。

FAQ

HTTP 200 は荷物が配達されたことを意味しますか？

いいえ。リクエストが HTTP レベルで成功したことを示します。API のビジネス結果と配送ステータスのフィールドを別々に確認してください。Webhook の場合、成功した確認応答が示すのは通知の受信であり、荷物の物理的な配達ではありません。

追跡更新には Webhook とポーリングのどちらを使うべきですか？

プロバイダーがサポートしている場合は、イベント駆動型の更新に Webhook を使用します。サポートされ、運用上正当化できる場合は、欠落を回復するために制限付きの照合ポーリングを追加します。Webhook を利用できない場合はポーリングだけでも適切なことがありますが、その頻度はプロバイダーの制限と必要な鮮度を尊重する必要があります。

「配達済み」の後に追跡ステータスが変わるのはなぜですか？

情報源がイベントを訂正したり、連携が遅延した情報や競合する情報を受信したりする可能性があります。履歴を保持し、配達済みを技術的に変更不可能なものとして扱うのではなく、新しい証拠を評価してください。報告された配達と顧客による受取確認も、別の事実です。

例外アラートはどのくらい早く送信すべきですか？

必要なアクションと確認済みの期限に基づいて緊急度を決めます。受取人の対応が必要な問題は、情報提供のみの遅延とは異なる扱いが必要です。処理速度だけでは、遅れて公開された配送会社イベントを補うことはできないため、元のタイムスタンプと受信タイムスタンプの両方を保持してください。

顧客に配送会社の生のステータスを表示すべきですか？

通常、顧客には説明のないコードよりも、明確な説明と実行可能な次のステップを示す方が有益です。サポートと監査の目的で生の詳細を保持してください。基礎となるイベントが裏付ける以上に強い約束へ、ステータスを単純化してはいけません。

出典

• RFC 9110: HTTP Semantics — 200 や 202 を含む HTTP ステータスコードの意味に関するリファレンス。
• OWASP REST Security Cheat Sheet — API および Webhook エンドポイントに関連するセキュリティガイダンス。
• 17TRACK Tracking API — 本稿で説明した追跡連携オプションの公式製品リファレンス。
• 17TRACK API Documentation — プロバイダー固有の連携要件に関する公式リファレンス。本ガイドの例示スキーマやワークフローの推奨事項は、この契約の代替ではありません。