Skip to main content
ホームブログガイド配送追跡 API ワークフロー:出荷の登録から追跡詳細の取得まで

配送追跡 API ワークフロー:出荷の登録から追跡詳細の取得まで

17TRACK

出荷追跡APIのワークフローは、追跡番号と必要な配送業者情報を送信し、登録が成功したかを確認し、追跡データが利用可能になるのを待ち、出荷状況とイベント履歴を取得することから始まります。本番環境で統合する場合、開発者は各追跡レコードを注文に関連付け、部分的な失敗を処理し、更新を安全に処理し、登録が受け付けられた状態と実際の配送業者によるスキャンを区別する必要もあります。

出荷追跡APIワークフロー:出荷登録から取得まで

このガイドでは、ECプラットフォーム、注文管理システム、倉庫アプリケーション、またはカスタマーサービスツールを接続する開発者向けに、このワークフローを説明します。アプリケーション設計に関する推奨事項と、プロバイダー固有のAPI要件を分けて説明します。17TRACKとの統合では、以下の例を実装する前に、公式APIドキュメントでリクエストスキーマ、認証、サポートされている操作、レスポンスフィールドを確認してください。

登録で実行されること、実行されないことを理解する

配送サービスに出荷を登録するとは、追跡サービスがAPI契約に従ってその出荷を追跡または管理できるよう、識別子を送信することを意味します。これは、送料の購入、配送ラベルの生成、集荷の予約、または荷物の配送業者への引き渡しと同じ操作ではありません。

アプリケーションでは、次の3つの結果を分けて扱ってください。

  • リクエスト受信:APIがHTTPリクエストに対するレスポンスを返した。
  • 登録受付:サービスが個々の追跡レコードを処理対象として受け付けた。
  • 追跡情報利用可能:サービスに、アプリケーションが取得または受信できる出荷情報がある。

これらの結果を単一の「成功」フラグにまとめないでください。受け付けられた追跡番号に、まだ配送業者のイベントが存在しない場合があります。同様に、バッチリクエストに対するHTTPレスポンスが成功したからといって、バッチ内のすべての項目が受け付けられたとは限りません。プロバイダーが定義するアプリケーションレベルの結果構造を確認してください。

1. 出荷識別情報とAPI設定を準備する

登録リクエストを送信する前に、自社システム内で出荷をどのように識別するかを決めます。1つの注文が複数の荷物に分割される可能性があるため、注文識別子だけでは通常不十分です。各出荷または荷物に独自の内部レコードを付与し、そのレコードを該当する注文に関連付けてください。

有用な内部レコードには、次の情報が含まれます。これらは推奨されるアプリケーションフィールドであり、17TRACKのリクエストスキーマではありません。

  • 内部出荷ID:荷物を識別する安定した識別子。
  • 注文参照:その出荷が属する注文またはフルフィルメントレコード。
  • 追跡番号:配送業者が発行した識別子。先頭のゼロを保持するため、テキストとして保存します。
  • 配送業者情報:既知であれば、フルフィルメントシステムから提供される配送業者の識別情報。
  • プロバイダー参照:後続の操作に必要となる、追跡サービスから返される識別子。
  • 登録状態:送信が保留中、受付済み、拒否、または照合待ちのいずれであるかを示す自社レコード。
  • 追跡状態:登録状態とは別に管理する最新の出荷状況。

送信前に入力を検証してください。誤って付加された前後の空白は削除しますが、配送業者の形式に関する推測で追跡番号を書き換えないでください。トラブルシューティングのため、元の値を保持します。配送業者が判明している場合は、非公式な表示名ではなく、プロバイダーが文書化した配送業者識別子にマッピングしてください。

認証はサーバー側で設定してください。認証情報をソース管理の外部に保管し、開発環境と本番環境の設定を分離し、ログから秘密情報をマスキングします。関係のない統合から値を流用せず、文書化されたAPIバージョン、リクエスト制限、バッチ制限、アカウント要件を確認してください。

2. 出荷を登録し、項目単位の結果を記録する

プロバイダーのドキュメントに記載された登録操作を使用して追跡レコードを送信します。必須フィールドと、明確な目的に役立つ任意情報だけを含めてください。注文データベースに存在するという理由だけで、顧客名、住所、その他の個人データを送信しないでください。

次の擬似コードはアプリケーションの処理順序を示しています。関数名は説明用であり、APIエンドポイントやSDKメソッドではありません。

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

何が起きたかを説明できるだけの情報を保存してください。内部出荷ID、送信時刻、試行回数、項目単位の結果、プロバイダーのリクエスト参照などです。一時的なワーカーログだけに依存しないでください。カスタマーサービスや運用チームは、出荷が正常に登録されたかどうかを永続的に確認できる必要があります。

バッチ送信は個別に処理する

APIがバッチ登録をサポートしている場合、返された各項目を元の出荷に関連付けてください。HTTPリクエストが正常に完了したという理由で、バッチ全体を受付済みにしないでください。受付済みの項目を保存し、拒否された項目を分離し、曖昧な結果は個別に調査します。

これにより、形式が不正な1つの追跡番号によって、すでに成功しているレコードまで不要に再試行されるのを防げます。また、修正が必要なレコードの一覧を運用担当者に提供できます。

タイムアウトは不明な結果として扱う

タイムアウトは、登録が失敗したことを証明するものではありません。接続が中断される前に、プロバイダーがリクエストを受け付けていた可能性があります。盲目的に再送信する前に、文書化された冪等性の動作、重複処理、または照会操作を利用して結果を照合してください。

プロバイダーの重複処理が不明確な場合は、管理されたレコードでテストし、自動再試行を有効にする前に契約内容を確認してください。登録ジョブを内部で重複排除することは有用ですが、リモートサービスが繰り返しリクエストをどのように処理するかを理解する代わりにはなりません。

3. 最初の追跡情報が届くまで待つ

登録が受け付けられた後も、追跡詳細がすぐに利用できるとは限りません。配送業者が物理的な取扱イベントを記録する前に、ラベルが存在することがあります。情報がない場合は、追跡番号、配送業者の選択、または出荷固有の照会要件を確認する必要もあります。

この状態を明示的に表現してください。「登録済み、追跡情報待ち」は、「輸送中」や「登録失敗」より正確です。空のインターフェースを埋めるために、配達予定や移動イベントを作り出さないでください。

レコードが空のままの場合は、実務上、次の順序で調査します。

  1. 個々の登録が受け付けられたことを確認する。
  2. 送信した追跡番号とフルフィルメントレコードを比較する。
  3. 配送業者のマッピングと、文書化された追加照会要件を確認する。
  4. 同じ出荷について、配送業者独自の追跡ページを確認する。
  5. 配送業者にはイベントがあるのに統合側にない場合は、取得レスポンスを調査し、診断情報をマスキングしてAPIプロバイダーに問い合わせる。

根拠のない一律の待機期間を採用しないでください。エスカレーションルールは、配送サービス、想定される引き渡しプロセス、自社の運用上の約束を反映させる必要があります。

4. 追跡詳細を取得し、正しく解釈する

レコードが利用可能になったら、必要な識別子を使って、文書化された追跡詳細取得操作を呼び出します。登録と取得で同じフィールドを受け付けるとは限りません。API契約によっては、追跡番号、配送業者識別子、プロバイダーが生成したレコード参照を区別します。

アプリケーションでは、次の3層の情報を区別してください。

  • 出荷概要:ダッシュボード、注文ページ、運用フィルターで使用する全体的な状態。
  • イベント履歴:提供される場合のイベント説明、タイムスタンプ、場所を含む個々の観測情報。
  • 取得メタデータ:アプリケーションが情報を受信または取得した時刻と、リクエストが正常に完了したかどうか。

照会が成功したということは、取得操作が成功したという意味です。前回の照会以降に荷物が移動したという意味ではありません。通知や後続ワークフローを生成する前に、返された追跡情報と保存済みレコードを比較してください。

イベント時刻と取得時刻を分ける

配送業者のイベントに関連付けられた時刻と、システムがその情報を受信した時刻を別々に保存してください。午後に取得したイベントが、それより前のスキャンを示している場合があります。イベント時刻を取得時刻で置き換えると、古い更新が新しい物理的移動のように見えてしまいます。

元のタイムスタンプと、提供されたオフセットを保持してください。タイムゾーンが判明している場合に限り、比較のためにタイムスタンプを正規化します。イベントにタイムゾーン情報がない場合は、サーバーのタイムゾーンを黙って割り当てず、その不確実性を保持してください。

正規化されたステータスとともに元の意味を保持する

正規化されたステータスは、配送業者をまたいで出荷をグループ化するのに便利ですが、元のイベント説明は運用上の問題をより正確に説明できます。利用可能な場合は両方を保持してください。広範な例外カテゴリーだけでは、サポート担当者が次に住所を確認すべきか、受取人に連絡すべきか、別の更新を待つべきか判断できないことがあります。

曖昧なステータスから、配達保証、紛失の確定、特定の通関結果を推測しないでください。根本となる情報と自社の運用ポリシーに従ってエスカレーションしてください。

5. ポーリングまたはWebhookでレコードを更新し続ける

接続テストには詳細を一度取得すれば十分ですが、出荷の可視性を維持するには不十分です。本番環境の設計には更新メカニズムが必要です。選択したプロバイダーがサポートするメカニズムと、それに付随する条件を確認してください。

ポーリングでは、アプリケーションがスケジュールに従って追跡詳細をリクエストします。文書化された制限内でリクエストをスケジュールし、理由なく変更のないレコードを繰り返し照会せず、再試行可能な失敗にはバックオフを使用してください。顧客が注文ページを開いたことをきっかけに、制限のない上流リクエストを自動的に発生させてはいけません。保存済みの追跡ビューをページ表示に使用し、管理されたバックグラウンド処理で更新できます。

Webhookを使用する場合は、プロバイダーが文書化した検証メカニズムで受信リクエストを検証してください。Webhook契約に従って応答する前に、受け付けたメッセージを保存するか、永続的なキューに入れ、その後イベントを非同期で処理します。

文書化された配信契約で別途保証されていない限り、受信側は重複や予期しない到着順序に耐えられるように設計してください。利用可能であれば、重複排除にプロバイダーのイベント識別子を使用します。そうでなければ、適切なイベントフィールドに基づくフィンガープリントを定義してテストしてください。ただし、そのフィンガープリントはデータに合わせて調整が必要になる場合があります。

Webhook主導の統合でも、照合のために管理された取得を利用できます。たとえば、復旧ジョブで受信側の障害の影響を受けたレコードを確認できます。これはレジリエンスのパターンであり、レート制限やプロバイダー固有の指針を無視してよいという意味ではありません。

6. 追跡情報を安全な業務アクションにつなげる

顧客向けのアクションを実行する前に、内部の出荷レコードを更新してください。通知とワークフローの遷移を永続的に記録し、同じイベントが繰り返し発生しても同じメッセージが重複して送信されないようにします。

すべてのAPIレスポンスではなく、意味のある変更に業務アクションを紐付けてください。新たに確認された配達イベントは、配達完了通知を送る根拠になります。同じイベントを含む繰り返しレスポンスは根拠になりません。例外は社内確認の理由になりますが、顧客向けメッセージはイベントが実際に示している内容を反映させるべきです。

出荷が完了したと見なされた後に受信したイベントの扱いを定義してください。概要が終端状態に達したという理由だけで、イベント履歴を削除したり、後続の更新を永久にブロックしたりしないでください。保持、照合、通知のルールでは、完了済みワークフローを何度も再開することなく、正当な訂正に対応できるようにします。

17TRACK統合にこのワークフローを適用する

カスタム追跡統合では、開始点として17TRACK Tracking APIページとその開発者向けドキュメントを参照してください。サービス内容の評価には製品ページを使用し、実際の統合契約の確認にはドキュメントを使用します。一般消費者向けの追跡ページは、API仕様の代替にはなりません。

アダプターを作成する前に、認証形式、登録および取得操作、配送業者の識別ルール、項目単位のレスポンス処理、適用されるリクエスト制限を確認してください。Webhookベースの処理では、ペイロードスキーマ、検証プロセス、応答要件、再試行動作も確認します。

プロバイダー固有の詳細は、注文システム全体にレスポンスフィールドの前提を分散させず、アダプター内に保持してください。そうすれば、アプリケーションの他の部分では、登録結果、出荷状況、イベント履歴、最後に成功した同期時刻といった内部概念を扱えるようになります。

リリース前の確認で高コストなミスを防ぐ

  • 受付済みだが空のレコード:インターフェースには追跡情報が保留中であることを表示し、荷物が移動中とは表示しない。
  • バッチ結果が混在:各出荷に固有の結果が永続化される。
  • 送信後のタイムアウト:ワーカーは不確実な結果を照合し、失敗と決めつけない。
  • イベントの重複:出荷タイムラインと顧客通知が重複排除される。
  • 古いイベントが後から到着:新しい概要を無条件に置き換えず、イベントを保持する。
  • 上流サービスが利用できない:顧客ページには、適切な鮮度表示とともに最後に保存された結果を表示できる。
  • 配送業者のマッピングが不正:文書化された復旧経路でレコードを修正できる。
  • 分割注文:各荷物が独自の追跡状態とイベント履歴を保持する。
  • 認証情報またはペイロードの漏えい:ログには秘密情報や不要な個人情報を漏らさず、診断用参照だけを記録する。

実務上の完了基準は、登録成功のレスポンスを受け取ることだけではありません。送信から更新まで荷物を追跡し、空または失敗した結果を説明し、イベントを失ったり顧客向けアクションを重複させたりせずに中断した処理から復旧できることが基準です。

よくある質問

追跡番号を登録すると出荷が作成されますか?

ここで説明するワークフローでは作成されません。追跡登録は、既存の識別子を追跡サービスに送信するものです。特定のAPIが明示的に統合していない限り、ラベル作成、送料購入、配送業者の予約は別の操作です。

登録が成功した後も追跡詳細が空なのはなぜですか?

登録の受付と追跡データの利用可能性は異なる状態です。配送業者がまだイベントを記録していないか、追跡番号、配送業者のマッピング、追加の照会情報を確認する必要がある可能性があります。レコードが正常に登録されたと判断する前に、項目単位の結果を確認してください。

ステータスを取得するたびに出荷を登録すべきですか?

繰り返し登録を通常の更新方法として使用しないでください。受付済みの登録状態を保存し、文書化された取得または更新メカニズムを使用します。訂正、再有効化、重複送信については、プロバイダーの明示的なルールに従ってください。

ポーリングとWebhookのどちらを使うべきですか?

文書化されたAPI契約と自社の運用要件に合うメカニズムを使用してください。ポーリングには管理されたリクエストスケジュールが必要です。Webhookには安全で永続的な受信側と、重複に安全な処理が必要です。サポートされている場合、Webhook更新と対象を絞った照合を組み合わせることで、実用的な復旧経路を構築できます。

追跡番号だけをデータベースの出荷識別子にできますか?

代わりに内部出荷識別子を使用してください。追跡番号と関連する配送業者情報は、そのレコードの属性として保存します。これにより、内部出荷の識別子を変更せずに、分割注文、修正された追跡番号、プロバイダー固有の参照を簡単に管理できます。

出典

  • 17TRACK Tracking API — 17TRACK API統合を評価するための公式製品ページ。
  • 17TRACK API documentation — 実装固有のリクエスト形式、操作、レスポンス、統合要件に関する公式リファレンス。このガイドの擬似コードと内部フィールドの提案は、アプリケーション設計の例であり、このAPI契約からの引用ではありません。