1つのAPIで中国からヨーロッパおよび米国への配送を追跡する方法
1つのAPIで中国からヨーロッパおよび米国への発送を追跡するには、注文システムを複数の配送業者に対応した追跡サービスに接続し、各荷物を追跡番号と必要な配送業者情報とともに登録して、追跡更新情報を共有の出荷記録に取り込みます。この連携では、国際的な引き渡し、スキャンの遅延、別のラストマイル追跡番号を考慮する必要があります。1つのAPIで追跡情報へのアクセスを統合できますが、配送業者が報告していないイベントを作成することはできません。
開発者やEC運用チームにとって、目的は単にステータスを表示することではありません。各物理的な荷物を正しい注文に紐付け、誤解を招く更新を送信せずに顧客へ情報を提供し、対応が必要な発送を特定することが重要です。このガイドでは、そのワークフローの構築方法と、実際の配送ルートに照らして17TRACK Tracking APIなどのサービスを評価する方法を説明します。
仕向国だけでなく、まず配送ルートから始める
中国からヨーロッパまたは米国の住所へ向かう荷物は、集荷サービス、国際輸送ネットワーク、通関処理、仕向地の配送業者を経由する場合があります。こうした移動を1つの追跡番号で提供する配送サービスもあります。一方、輸送の途中で別の配達参照番号が付与されるサービスもあります。
このため、国単位の対応範囲だけでは追跡連携を検証するには不十分です。プロバイダーが配送業者を認識していても、特定の配送商品に必要なすべてのイベントを返すとは限りません。同様に、出発地でのスキャンがあっても、仕向地での配達スキャンが利用できることを示すものではありません。
連携する前に、実際に自社が発送する荷物を使ってルート一覧を作成します。出発地の物流プロバイダー、配送サービス、仕向地市場、既知の配達業者、追跡番号の形式を記録します。テストでは、ある国で配達に成功したからといって地域全体をカバーしていると仮定せず、ヨーロッパの各市場を個別に扱います。
- 運用担当者向け：現在どこで追跡の欠落が手作業や顧客からの問い合わせを生んでいるかを特定します。
- エンジニアリング向け：どのシステムが出荷を作成し、どのシステムが更新を必要としているかを特定します。
- 調達担当者向け：そのルート一覧に含まれる特定の配送業者とサービスがサポートされていることを確認します。
1つの追跡APIが行うべきこと、行えないこと
複数配送業者対応のTracking APIは、配送業者ごとに個別の接続を処理する代わりに、アプリケーションへ共通の連携レイヤーを提供します。サービスと連携方法によっては、アプリケーションで更新情報を取得したり、コールバックを受信したり、両方を組み合わせたりできます。本番ワークフローを設計する前に、プロバイダーのドキュメントでサポートされている仕組みを確認してください。
有用な抽象化は、一貫した出荷モデルです。注文管理システムは配送業者ごとに異なる表現に対応するビジネスロジックを必要とすべきではありません。ただし、サポートや調査のために元の情報は保持する必要があります。
追跡情報を統合しても、物理的な可視性の継続、配達予定、完全な通関履歴が保証されるわけではありません。配送業者から新しいスキャンが報告されていなくても、API接続自体は正常に動作する場合があります。また、追跡は配送ラベルの購入、通関申告書の作成、配達サービスの手配とは別のものです。これらの機能が含まれていると想定しないでください。
荷物単位の記録を中心に連携を構築する
1. 注文、出荷、追跡識別子を分離する
1つのEC注文に複数の荷物が含まれ、それぞれ異なるタイミングで到着する場合があります。安定した識別子として、社内の荷物IDまたは出荷IDを使用します。顧客の注文をその記録に関連付け、配送業者の追跡識別子を紐付けます。
実用的な社内モデルには、次の項目を含めます。
- 社内注文IDと荷物ID。
- 元の追跡番号と、APIが使用する配送業者識別子。
- 確認済みの仕向地配送業者の追跡番号。
- 配送サービスと仕向国。
- 現在の正規化済みステータスと配送業者の元の説明。
- イベント時刻、提供されている場合はイベント場所、システムが更新情報を受信した時刻。
- 登録状態、最後に成功した同期、未解決の連携エラー。
これらは推奨されるアプリケーション項目であり、すべてのプロバイダーが返すことを意味するものではありません。社内スキーマをプロバイダーのレスポンス形式から分離し、将来APIが変更されても注文データベースを再設計せずに済むようにします。
2. 信頼できる業務イベントから荷物を登録する
注文ページが閲覧されるたびに登録するのではなく、有効な番号が荷物に割り当てられた時点で追跡を登録します。通常は、倉庫または注文システムからの出荷作成イベントをトリガーにする方が適切です。ラベルが無効化または交換された場合は、使用されなくなった番号を唯一の追跡参照として残すのではなく、荷物の識別子間の関連を更新します。
番号が存在し、表計算ソフトの書式設定によって破損していないことを確認します。意味のある先頭ゼロを保持します。配送システムが配送業者を把握している場合は、自動識別だけに頼らず、その情報を保持します。番号形式が重複する場合があるためです。
登録レスポンスを個々の出荷単位で読み取ります。HTTPリクエストが成功しても、バッチ内のすべての項目が受け付けられたとは限りません。失敗した項目を再試行キューに保存し、無効または曖昧な登録を解決できる手段を運用担当者に提供します。
3. 顧客通知に接続する前に更新配信を設計する
選択したサービスがwebhookをサポートしている場合は、文書化されたコールバック機構を使用して更新情報を受信します。検証用ヘッダーを独自に作成するのではなく、利用可能な認証または署名方式を確認します。認証情報はサーバー上で管理し、HTTPSを必須とし、APIシークレットをブラウザーコードや顧客向けリンクに含めないでください。
受信側は、更新を承認する前に永続的に受け入れ、その後非同期で処理します。重複配信や順序が前後して到着するイベントを想定します。利用可能であればプロバイダーのイベントIDを使用し、そうでなければ安定したイベント属性を使った重複排除ルールを文書化します。
ポーリングが必要な場合は、プロバイダーが文書化した制限と運用上のニーズの範囲内でスケジュールします。レート制限のレスポンス後はバックオフし、同期した再試行の集中を避け、保持および照合ポリシーに従って完了済みの出荷への不要な確認を停止します。サービスが取得を許可している場合、定期的な照合ジョブによって未受信の更新を検出することもできます。
4. 意味を失わずにステータスを正規化する
注文システムとサポートチームが一貫して解釈できる、少数の社内ステータスを使用します。例として、情報受領、輸送中、配達中、配達完了、配達例外、返送などがあります。これらは推奨されるアプリケーション上の分類であり、特定のプロバイダーの正確なステータスコードを説明するものではありません。
詳細な配送業者イベントを正規化済みステータスとともに保持します。配達試行の失敗、住所の問題、通関関連の遅延はすべて対応が必要になる可能性がありますが、同じ対応を必要とするわけではありません。すべてを一般的な例外にマッピングすると、保存は容易になりますが、行動に役立つデータではなくなります。
ラベル作成を物理的な集荷と訳してはいけません。同様に、イベントに通関施設への言及があるだけで、荷物を通関済みと表示してはいけません。イベントの実際の意味に合った表現を使用します。
国際的な引き渡しを明示的に処理する
最も重要な連携テストは、出発地ネットワークと仕向地の配達との間の移行であることが多いです。元の参照番号と、確認済みのラストマイル参照番号の両方を保持します。新しい追跡番号は同じ荷物の別の識別子として扱い、自動的に2つ目の出荷にしないでください。
物流プロバイダー、追跡レスポンス、配送システムなど、信頼できる情報源から関係が得られた場合のみ識別子を関連付けます。イベント時刻が似ていることや仕向国が一致することだけでは、2つの番号が同じ荷物に属する証明にはなりません。
イベント時刻と取り込み時刻を分けて保持します。特に情報がネットワーク間を移動する場合、新しいイベントの後に古いイベントがシステムへ到着することがあります。提供されたタイムゾーンのオフセットを保持し、処理用にタイムスタンプを正規化し、裏付けのないタイムゾーンを割り当てるのではなく、曖昧な元の値を保持します。
顧客には、最新の意味のあるステータスと更新時刻を明確に表示します。仕向地の配送業者がまだスキャンを報告していない場合は、追跡が次の更新を待っていることを説明します。荷物が紛失した、最後のスキャン場所に物理的に留まっている、またはすでに仕向国に到着していると推測しないでください。
このワークフローにおける17TRACKの位置付け
アプリケーションに複数配送業者対応の追跡連携が必要な場合、17TRACKのTracking API提供サービスが適しています。認証、登録、レスポンス処理、サポートされている更新ワークフローの実装には、公式APIドキュメントを使用してください。消費者向け追跡ページを連携インターフェースとして扱うのではなく、文書化されたAPI契約を使用します。
自社で実装する場合と同じ運用要件で評価します。正確な配送業者識別、実際のルートで有用なイベント、引き渡しの継続性、エラー復旧、管理可能な更新配信などです。本番設計を確定する前に、商用条件、利用量の計算、リクエスト制限、必要なアカウント設定を確認します。
統合APIを選ぶ最大の理由は、実際に運用するルートにおける連携の複雑さを軽減できることです。ただし、そのメリットは代表的な荷物で検証する必要があります。一般的な対応範囲の説明が広いという理由だけでプロバイダーを選ぶべきではありません。
展開前にルートベースのパイロットを実施する
通常の配達と難しいケースを含むテストセットを使用します。過去の出荷はステータスマッピングのテストに役立ち、実際の出荷は更新配信と運用上のタイミングを明らかにします。どちらか一方のテストだけですべての疑問に答えることはできません。
- 中国から米国への配達：出発地イベント、国際的な引き渡し、最終配達イベントを確認します。
- 中国からヨーロッパへの配達：実際に利用する仕向国と配送サービスをテストします。
- 新しいラベル：物理的なスキャンがない荷物が移動中として表示されないことを確認します。
- 配達参照番号の変更：関連付けが正しい荷物に維持されることを確認します。
- 配達例外：詳細な理由が適切な運用キューに届くことを確認します。
- 分割注文：1つの荷物の配達によって注文全体が完了扱いにならないことを確認します。
- 重複または遅延した更新：同じメッセージが繰り返し生成されたり、新しいステータスが誤って上書きされたりしないことを確認します。
- 一時的な連携障害：再試行、照合、サポートからの可視性を確認します。
結果を確認する前に受け入れ基準を設定します。登録成功率、誤った配送業者の割り当て、欠落したマイルストーン、更新処理の遅延、重複した顧客メッセージを測定します。根拠のない普遍的な基準を借用するのではなく、自社にとって許容できるしきい値を定義します。イベントが欠落している場合は、APIの問題と判断する前に配送業者自身の記録と照合します。
APIの可用性とは別にデータの鮮度を監視する
API Monitoringでは、連携が機能しているか、出荷情報が有用かという2つの異なる質問に答えられる必要があります。リクエストの成功が答えるのは最初の質問だけです。登録エラーが蓄積していないか、コールバックが失敗していないか、あるいはルートで期待されるマイルストーンが生成されなくなっていないかも把握する必要があります。
- 連携の健全性：認証失敗、リクエストエラー、レート制限レスポンス、コールバック失敗、キューの滞留。
- データ品質：不明なステータス、不正なタイムスタンプ、未解決の配送業者識別子、予期しない識別子の変更。
- 出荷の鮮度：最新の配送業者イベントからの経過時間を、ルートと配送サービス別に分類。
- ビジネスへの影響：例外対応の負荷、通知失敗、誤って完了扱いになった注文。
スキャンが長時間ないことが、ある配送サービスでは正常で、別のサービスでは異常である場合があります。ルートごとの期待値と過去の出荷履歴を使って調査の優先順位を決めます。適切なチームに通知が届くよう、連携エラーのアラートと出荷遅延のアラートを分けます。
顧客通知は、すべての生イベントではなく、確認済みのマイルストーンに従うべきです。重複を抑制し、配達試行と配達完了を区別し、基礎データが裏付けていない到着日を約束しないでください。追跡ペイロードへのアクセスを制限し、ワークフローに必要な場合にのみ個人情報を保持します。
FAQ
1つのAPIで中国側の出発地配送業者と仕向地の配達業者の両方を追跡できますか？
複数配送業者対応サービスは、関連するサービスと識別子間の関係がサポートされていれば、輸送の両方の部分からイベントを統合できる場合があります。実際の荷物でルート全体を検証してください。出発地の追跡番号が認識されるだけでは、仕向地の配達情報が利用できることの証明にはなりません。
荷物が中国を出た後に追跡の更新が止まるのはなぜですか？
物理的なスキャンの間隔、報告の遅延、別の配達参照番号への引き渡しなどが考えられます。元のイベントと提供されたラストマイル番号を確認し、関連する配送業者の記録と比較します。追跡の空白だけでは、荷物が紛失した、または税関で保留されているとは判断できません。
アプリケーションはwebhookとポーリングのどちらを使用すべきですか？
プロバイダーが文書化している仕組みを使用します。サポートされている場合、webhookは繰り返しの確認を減らせます。一方、許可された取得リクエストは照合に利用できます。どちらの設計でも、更新情報を顧客コミュニケーションに利用する前に、重複処理、再試行制御、監視を構築してください。
追跡APIで配達日や通関を保証できますか？
追跡データはどちらも保証するものではありません。推定配達日が提供される場合は、その情報源を保持し、推定値として提示します。通関関連のスキャンは、明示的に通関完了を示していない限り、実際の文言に従って説明し、通関済みと解釈しないでください。
APIプランを選ぶ前に何を確認すべきですか？
利用する配送業者と配送サービス、登録要件、更新方法、利用量の計算、リクエスト制限、データの可用性、サポート体制を確認します。交換番号、重複登録、過去データの照会が商用上どのように扱われるかを確認してください。予算やアーキテクチャに影響する要件については、最新のドキュメントと書面による確認を使用します。
出典
- 17TRACK Tracking API — 追跡API提供サービスの公式製品リファレンス。
- 17TRACK API documentation — 連携実装の公式技術リファレンス。開発前に、正確なリクエスト形式、サポートされているワークフロー、制限をここで確認してください。
