追跡APIはどのようなデータを返すべきか?現在のステータス以外に必要な12のフィールドとは?
追跡APIは、「輸送中」のようなラベルだけでなく、より多くの情報を返すべきです。現在のステータスに加えて、出荷識別子、配送業者情報、詳細なステータス情報、配送業者からの元のメッセージ、イベント履歴、イベントのタイムスタンプ、所在地、配達予定、例外、配送業者間の引き継ぎ、配達詳細、データの鮮度に関するメタデータを確認してください。これら12のデータグループを組み合わせることで、開発者は信頼性の高いワークフローを構築でき、運用チームは対応に必要な十分なコンテキストを得られます。

これは開発者、技術担当の購買担当者、EC運用チーム向けに推奨するレスポンス契約であり、すべての配送業者やAPIがすべての項目を提供するという主張ではありません。一部の値が正当に利用できない場合もあります。より優れた設計では、推測で値を補うのではなく、そのような不足を明示します。
追跡データを役立つものにする要素とは?
現在のステータスが答えるのは、「この配送の要約された状態は何か」という一つの限定的な質問です。それだけでは、何が起きたのか、いつ起きたのか、情報が新しいのか、次に何をすべきなのかまでは必ずしも説明できません。
たとえば、2つの配送がどちらも「輸送中」と表示されていても、必要な対応は異なる場合があります。一方には最近の施設スキャンがあり、報告された問題がないかもしれません。もう一方には、イベント履歴に未解決の住所問題が記録されている可能性があります。見出しのステータスだけを読むアプリケーションでは、この違いを見落とすことがあります。
レスポンスを、配送を正しい注文に紐付けること、進捗を正確に説明すること、対応が妥当かどうかを判断することという、3つの実務上の作業に照らして評価してください。以下の項目がこれらの作業を支えます。項目名は例示であり、世界共通の標準や特定プロバイダーのスキーマではありません。
現在のステータス以外に評価すべき12項目
1. 出荷および追跡識別子
レスポンスには、説明対象の配送を特定できる情報が必要です。役立つ値には、送信した追跡番号、APIの追跡レコード識別子、そしてシステムでフルフィルメントまたは荷物レコードに紐付けられる顧客側の参照番号が含まれます。
1つの注文が1つの配送に等しいとは限りません。注文は複数の荷物に分割されることがあり、交換品によって別の配送が発生することもあります。追跡レコードは荷物またはフルフィルメント単位で保存し、その後注文に関連付けてください。形式や先頭のゼロが失われないよう、追跡番号は文字列として保持します。
2. 配送業者情報
読みやすい配送業者名とともに、安定した配送業者識別子を確認してください。利用可能な場合、レスポンスでは、アプリケーションが明示的に指定した配送業者と、自動検出によって選択された配送業者を区別できるようにする必要があります。
追跡番号やイベントを解釈する際には、配送業者のコンテキストが重要です。検出結果が曖昧な場合、連携には解決手段を用意し、不確かな一致を確認済みのように表示しないようにします。サービスレベルの情報は分けて保持してください。配送業者名だけでは、配送が速達、郵便、その他のサービスのいずれを利用しているかは判断できません。
3. 正規化されたステータス詳細
メインステータスに加えて、文書化された詳細コードまたはサブステータスを要求してください。大まかなカテゴリでは配送を「例外」と表現し、詳細で配達試行、住所の問題、通関による保留などを特定できます。
ビジネスロジックには安定したコードを、表示には読みやすいラベルを使用します。未知またはマッピングされていないイベントをどのように処理するかを含め、プロバイダーが配送業者のイベントをそれらのコードにどうマッピングしているか確認してください。正規化されたラベルにより異なる配送業者のフィードを扱いやすくなりますが、サポートチームに必要な違いまで消してはいけません。
4. 配送業者の元のメッセージとコード
提供されている場合は、元のイベント説明と配送業者のイベントコードを保持してください。これらの値は、特に配送業者が特定の業務用表現を使用している場合に、正規化されたステータスにはないコンテキストをサポート担当者に提供します。
元のテキストは、翻訳または書き換えた説明とは分けて保持してください。そうしないと、顧客向けの説明が配送業者の正確な文言と誤認される可能性があります。表示時には配送業者のテキストを信頼できない入力として扱い、適切にエスケープし、実行可能なHTMLとしてレンダリングしないでください。
5. 追跡イベント履歴
有用なレスポンスでは、最新のイベントだけでなく配送のタイムラインを公開する必要があります。各イベントには、理想的には識別子、ステータスまたはコード、説明、タイムスタンプ、利用可能な所在地情報を含めます。
APIが完全な履歴を返すのか、限定された期間のみを返すのか、ページ分割された結果を返すのかを確認してください。また、訂正や重複した観測結果がどのように表現されるかも確認します。レスポンス契約で順序が明示的に保証されていない限り、最初の項目が常に最新であると仮定してはいけません。
6. イベントのタイムスタンプとタイムゾーン情報
イベントが発生した時刻は、APIがそれを受信または返した時刻とは異なります。利用可能な場合は両方を保持してください。この違いにより、新たに受信した更新が、以前に発生した事象を説明している理由を明確にできます。
明示的なUTCオフセットまたはUTC表記を含むタイムスタンプを要求してください。RFC 3339は、数値のタイムオフセットを含む、インターネットプロトコルに適したタイムスタンプ形式を定義しています。ソースが既知のオフセットなしで現地時刻のみを提供する場合は、その不確実性を保持し、黙ってUTCとして扱わないでください。基となるソースが日付しか提供していない場合に、秒単位の精度があるように示してはいけません。
7. イベントの所在地と配送の地理情報
提供されている場合は、市区町村、地域、国、郵便番号などの構造化された所在地要素を確認してください。構造化フィールドへの変換で意味が失われる可能性がある場合は、元の所在地文字列も保持します。
スキャンされた所在地が、必ずしも荷物の現在位置とは限りません。同様に、最後に報告された施設に荷物が今もあるとは限りません。顧客向けページでは、最新の報告所在地として説明してください。不完全なスキャンテキストから座標や正確な配達先住所を推測しないでください。
8. 配達予定日または期間
配達予定の項目には、単一の日付なのか期間なのか、誰が生成したのか、最後にいつ更新されたのかを示す必要があります。配送業者が提供した予定と、別途計算された予測は区別できるようにしてください。
日付のみの予定を正確な到着時刻に変換しないでください。また、更新または撤回された予定を処理し、追跡ページに古い約束を残さないようにする必要があります。予定が存在しない場合は、根拠のない推測から計算するのではなく、利用できないことを表示してください。
9. 例外の理由と必要な対応
例外情報では問題を説明し、ソースが対応している場合は、対応、責任者、期限を特定してください。一般的な遅延通知と、受取人情報の要求は、運用上異なるものです。
報告された事実と、独自のワークフロー上の判断を分けて保持してください。たとえば、更新が設定期間内にない場合に、社内でサポートタスクを作成することがあります。これは社内のエスカレーションルールであり、配送業者が荷物の紛失を宣言した証拠ではありません。曖昧な追跡テキストから支払い指示や機密情報の要求を生成しないでください。
10. 配送業者間の引き継ぎと関連する追跡番号
配送が事業者間で移管される場合、次の配送業者、関連する追跡番号、元のレコードと後続レコードの関係などが有用です。配送区間で異なる識別子が使用される場合でも、継続性を維持するのに役立ちます。
報告された引き継ぎは、元の配送業者を上書きするのではなく、関係として扱ってください。配送先や追跡番号が似ているというだけでレコードを統合しないでください。関係が提供されていない、または別途確認されていない場合は、連続した配送経路を作り出さず、未解決のままにします。
11. 配達結果と証明参照情報
配達が報告された場合、レスポンスには記録された配達時刻と、安全な置き場所の説明や受取人の区分など、利用可能な配達詳細を含める必要があります。配送業者とサービスが対応している場合は、配達証明の参照情報も役立ちます。
配達済みステータスは、意図された受取人が自分で荷物を受け取った証拠として扱ってはいけません。署名、写真、氏名、正確な所在地には個人情報が含まれる可能性があります。アクセスを制限し、公開追跡ページでこれらの詳細を公開することを避け、証明リンクに必要な認証や有効期限を確認してください。
12. 鮮度、取得状態、レスポンスメタデータ
配送の最新イベントと、最後に成功したデータ取得を区別できる十分なメタデータを要求してください。役立つ値には、最後に成功した確認、最後に失敗した試行、レスポンス生成時刻、返されたデータがキャッシュまたは部分データかどうかが含まれます。
APIリクエストが成功したからといって、それだけで配送業者が新しいスキャンを公開したことにはなりません。HTTPレスポンスの意味はリクエストの結果を表すものであり、配送の進捗はアプリケーションデータに属します。取得エラーは配送例外とは別に保持し、一時的な接続問題が誤った配達アラートにならないようにしてください。
データ欠落には定義された意味が必要
項目が存在するかどうかは、契約の一部にすぎません。値がないことが何を意味するのかも、チームは理解する必要があります。配達予定がソースから提供されていない、まだ取得されていない、配達後は該当しない、といった場合があります。これらの状況に対して、同じ顧客メッセージを自動的に表示してはいけません。
- 不明:値が確定していません。
- 未提供:ソースが取得データ内で値を提供していません。
- 該当なし:このレコードまたは状態には項目が適用されません。
- 取得失敗:システムが関連する照会を完了できませんでした。
これらは推奨される区別であり、文字どおりの必須値ではありません。どの表現を選ぶ場合でも、文書化してください。有効なレコードに見えるプレースホルダーの日付や空のオブジェクト、実在の所在地と誤認される可能性のあるデフォルト座標は避けてください。
統合前にレスポンスをテストする方法
実際に利用する配送業者、サービス、配送ルートから得た実際のペイロードを評価してください。スキーマに任意項目を記載していても、基盤となるすべてのソースがその項目を設定するとは限りません。17TRACKとの連携では、このガイドの概念的な項目名をそのまま使用できるパラメータとして扱うのではなく、公式Tracking APIドキュメントでレスポンス契約を確認してください。
- 代表的なサンプルを作成する。新しく登録された配送、進行中の配送、配達試行、完了した配達、利用可能な引き継ぎ事例を含めます。
- 項目をイベントまで追跡する。表示されたステータス、最新イベント、配達詳細が一貫したレコードを説明していることを確認します。不一致を隠さず調査してください。
- 遅延した更新と重複した更新をテストする。同じペイロードを再処理し、新しいイベントの後に古いイベントを受信します。どちらの場合も、重複通知が作成されたり、表示状態が誤って逆戻りしたりしないことを確認します。
- 欠落値と不正形式の値をテストする。予定の欠落、不明な所在地、見慣れないステータスコード、不完全なタイムスタンプを含めます。アプリケーションは、代替値を作り出さずに利用可能な状態を維持する必要があります。
- 通信障害と追跡結果を分離する。認証失敗、タイムアウト、不正なレスポンスは、配送例外のワークフローではなく、連携エラーの経路に送る必要があります。
- 顧客向け表示を検証する。内部参照、診断用の生データ、個人情報が公開ページや通知に漏れないことを確認します。
Webhookベースの更新については、プロバイダーのドキュメントで配信識別子、認証、再試行動作、リプレイ処理も確認してください。これらは配送の事実ではなく、連携要件です。受信側は重複配信を安全に処理し、到着順がイベント順と同じだと仮定してはいけません。
受け入れ基準は実務的なものにする必要があります。アプリケーションは根拠のない主張をせずに配送を説明できるか、そして運用チームは次に取るべき妥当な対応を特定できるか、という点です。説明のない任意値で満たされた大きなレスポンスより、定義が明確な小さなペイロードのほうが有用な場合があります。
FAQ
すべての配送で12のデータグループをすべて設定する必要がありますか?
いいえ。配達証拠、後続の追跡番号、配達予定日は利用できない、または該当しない場合があります。すべての項目を埋めることではなく、明確な項目定義と予測可能な欠落値の動作を求めてください。実際の配送構成に照らして、最も重要な項目を確認します。
生のレスポンスと正規化された項目のどちらを保存すべきですか?
アプリケーションロジックには正規化された項目を保存してください。関連するソースペイロードを保持すると、プライバシー、セキュリティ、契約、保存要件の範囲内で、デバッグやマッピング変更にも役立ちます。アクセスを制限し、レスポンスに含まれているというだけの理由で機密コンテンツを保存しないでください。
最新イベントを決定するには、どのタイムスタンプを使用すべきですか?
タイムゾーンと訂正を考慮し、文書化されたイベントの時系列とプロバイダーの並べ替えルールを使用してください。受信時刻はシステムがイベントを知った時刻を示すもので、必ずしもイベントが発生した時刻ではありません。タイムスタンプが不完全または矛盾している場合は、正確な順序を主張せず、曖昧さを保持してください。
追跡APIで荷物の紛失を確認できますか?
ソースがその解釈を明示的にサポートしている場合に限り、配送業者が報告した紛失として扱ってください。長期間スキャンがない場合は、運用ルールに基づく調査の根拠にはなりますが、沈黙だけで紛失が確定するわけではありません。「追跡情報が古い」ことと「紛失が報告された」ことは別の概念として扱ってください。
配達済みステータスだけで顧客の苦情を終了できますか?
自動的にはできません。報告された追跡結果は確定しますが、受取人の異議が解決するとは限りません。利用可能な配達詳細、顧客のアカウント、サポートプロセスを確認してください。矛盾する情報の調査を、ステータスラベルで代替しないでください。
出典
- 17TRACK Tracking APIドキュメント — 連携で文書化された項目と動作を確認するための製品固有のリファレンスです。上記の12グループは編集上の推奨事項であり、そのスキーマを再現したものではありません。
- RFC 3339: インターネット上の日付と時刻:タイムスタンプ — タイムスタンプの表現とタイムオフセットの規則。
- RFC 9110: HTTPセマンティクス — 配送レベルのビジネスステータスとは異なる、HTTPレスポンスの意味。


