Webhookを待たずにAPIで最新の配送状況を取得する方法
Webhookを待たずに利用可能な最新の配送状況を取得するには、認証済みのリクエストを追跡プロバイダーの配送情報照会APIに送信します。レスポンスを使用してアプリケーションを直ちに更新し、その後の変更に備えてWebhookを有効にしておきます。重要な違いは、照会では通常、プロバイダーに保存されている最新の追跡情報を取得するだけであり、新たな配送業者への確認が必ずしも実行されるわけではないという点です。

この方法は、顧客が注文ページを開いた場合、サポート担当者が更新を必要とする場合、またはシステムが通知の取りこぼしから復旧する必要がある場合に役立ちます。信頼性の高い実装では、オンデマンド照会、明確な鮮度表示、重複更新や順序が前後した更新に対する保護を組み合わせます。
「最新の配送状況」の意味を決める
エンドポイントを選ぶ前に、似たように聞こえても結果が異なる3つの操作を区別してください。
| 操作 | 実行すること | 確認できないこと |
|---|---|---|
| 自分のデータベースを読み取る | アプリケーションがすでに保持している追跡情報を返します。 | プロバイダーがより新しい更新を受信しているかどうか。 |
| 追跡APIに照会する | プロバイダーの照会操作で利用可能な情報を取得します。 | そのリクエスト中に新たな配送業者照会が行われたかどうか。 |
| 追跡情報の更新をリクエストする | プロバイダーがその操作を提供している場合、上流への再確認をリクエストします。 | 配送業者に新しいスキャンがあること、または更新が同期的に完了すること。 |
今すぐ回答が必要な場合は照会を使用してください。プロバイダーに上流への再確認を試みさせる必要がある場合にのみ、更新操作を調査してください。キャッシュ回避パラメーターの追加、リクエストの繰り返し、HTTPのcache-controlヘッダーの送信によって、配送業者が新しい情報を提供するよう強制できるとは考えないでください。
配送状況の可視化には複数の段階があります。配送業者がイベントを記録し、追跡プロバイダーがそれを取得し、アプリケーションが受信または取得します。直接APIリクエストを送信すれば通知配信を待つ必要はなくなりますが、その連鎖の前段階にある遅延をなくすことはできません。
コードを書く前に照会の契約を確認する
追跡サービスを統合する開発者がこのワークフローを担当します。古い統合例からコピーしたエンドポイントではなく、プロバイダーの最新ドキュメントから始めてください。次の詳細を確認します。
- 配送情報の識別子:照会では追跡番号、内部配送ID、または追跡番号と配送業者識別子の組み合わせのどれを受け付けるか。
- 登録要件:照会する前に配送情報を登録する必要があるか。
- 認証:どのヘッダーまたは認証メカニズムが必要か。
- レスポンスの意味:保存済み情報を返すのか、収集を開始するのか、後で確認するジョブを返すのか。
- 結果の処理:HTTPレスポンスが成功していても、配送単位の失敗や保留中の結果を含む可能性があるか。
- 利用制限:どのようなレート制限、バッチ制限、アカウント固有の制約が適用されるか。
- 鮮度に関するフィールド:配送業者のイベント、プロバイダーの更新、レスポンス生成を示すタイムスタンプはどれか。
17TRACKを統合する場合、関連する製品は、一般消費者向けの追跡ページやストアフロントの追跡インターフェースではなく、Tracking APIです。公式APIドキュメントで、統合に必要な追跡情報の照会操作、認証、リクエストフィールド、レスポンス構造を確認してください。照会処理とWebhook処理は、同じ配送情報レコードを更新する別々のアプリケーションパスとして扱います。
更新動作や照会頻度について、前提をハードコーディングしないでください。これらの詳細は、実際に使用する操作およびサービス条件に合わせる必要があります。
バックエンドを通じてオンデマンド照会を構築する
実用的な設計は、自社アプリケーションに認証済みエンドポイントを公開することです。ブラウザーはそのエンドポイントに配送情報の更新をリクエストし、サーバーは認可を確認し、プロバイダーへの照会が必要かどうかを判断して、正規化された結果を返します。
次のルートは、アプリケーション内に作成するエンドポイントの例です。これは17TRACKのエンドポイントでも、プロバイダーのリクエスト仕様でもありません。
GET /api/orders/{order_id}/shipment-status注文識別子を使用して、サーバー上で配送情報を検索します。リクエスト内の追跡番号を置き換えるだけで、呼び出し元が別の顧客の追跡履歴を取得できるようにしないでください。プロバイダーAPIの認証情報は、ブラウザーのJavaScriptやモバイルアプリケーションのバンドルではなく、バックエンドに保持してください。
実装できるリクエストフロー
- アクセスを認可する。顧客またはスタッフが注文を閲覧できることを確認します。
- 配送情報を解決する。保存されている追跡識別子と、該当する場合は配送業者情報を読み取ります。
- ローカルの鮮度を確認する。最近成功した照会がすでに存在する場合は、アプリケーションの鮮度ポリシーに従って再利用します。
- 必要に応じてプロバイダーに照会する。文書化された操作と、上限を設けたリクエストタイムアウトを使用します。
- 結果を検証する。HTTPの結果と配送単位の結果の両方を確認します。
- 情報を統合する。Webhookイベントに使用しているものと同じ正規化および照合ルールを適用します。
- 状況と鮮度を返す。利用可能な場合は、最新イベントの時刻と、プロバイダーへの確認に最後に成功した時刻を含めます。
ローカルの鮮度ポリシーはエンジニアリング上の判断であり、配送業者の更新頻度に関する声明ではありません。インターフェース要件、プロバイダーの制限、配送量、照会の有用性の実測値に基づいて決定してください。顧客が更新ボタンを繰り返しクリックしても、上流へのリクエストが無制限に発生しないようにします。
鮮度を推測せずにレスポンスを正規化する
プロバイダーごとにレスポンス構造が異なっていても、アプリケーションは安定した内部形式を返せます。次の例示オブジェクトは、実際のプロバイダーペイロードではなく、アプリケーション独自の契約です。
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}各タイムスタンプは、その意味が判明している場合にのみ設定します。サーバーがレスポンスを受信した時刻は照会メタデータに属するものであり、荷物が移動した時刻として表示してはいけません。プロバイダーが更新時刻を提供しない場合は、別のタイムスタンプで代用せず、そのフィールドを省略するかnullにしてください。
顧客向けインターフェースでは、メッセージを分けてください。「最新の配送業者イベント」は配送活動を示し、「追跡確認済み」はアプリケーションによる取得活動を示します。この区別により、変化していないスキャンが新たに記録されたように見えるのを防げます。
API照会とWebhookによる上書きを防ぐ
両方の仕組みを有効にすると、同じイベントが照会とWebhookの両方で届く場合があります。また、開始した順序とは異なる順番で完了することもあります。先に開始した照会が、Webhookによってすでに新しい情報が提供された後に完了する可能性があります。
最後に受信したレスポンスを採用するロジックは使用しないでください。最後に受信したペイロードが、必ずしも最新の配送状態とは限りません。
- 1つの更新パイプラインを共有する。照会結果とWebhookペイロードを、同じ検証、正規化、永続化関数に通します。
- イベントを重複排除する。文書化されたイベント識別子を優先します。存在しない場合は、イベント時刻、ステータス、場所、説明など、利用可能なフィールドから慎重に定義したフィンガープリントを作成します。
- 意味が既知の順序フィールドを使用する。文書化されたリビジョンまたはシーケンスは、到着時刻がイベント順を表すと想定するより有用です。
- 履歴を保持する。新たに受信したイベントが履歴上の空白を埋めても、現在の配送概要を変更するとは限りません。
- 訂正を許容する。ステータスは普遍的な直線状の段階ではありません。見かけ上後退するすべての遷移を永続的に拒否するのではなく、文書化された訂正動作に従ってください。
イベントの順序が不確かな場合は、調査のために元のペイロードとその出所を保持してください。イベント時刻を作り出したり、すべての配送業者のタイムスタンプが同じタイムゾーンを共有すると仮定したりして、曖昧さを解消しないでください。
データ欠落とリクエスト失敗を別々に処理する
空の結果、変化のない結果、失敗したリクエストは、同じ顧客メッセージになってはいけません。
照会は成功したが、ステータスが変わっていない
既存の配送ステータスを維持し、最後に照会に成功した時刻を更新します。別の照会が完了しただけで、新しい配送イベントを生成しないでください。顧客が詳細を必要とする場合は、既存のイベント履歴を表示し、より新しい追跡イベントが返されなかったことを説明します。
配送情報にまだ追跡情報がない
登録が必要か、識別子と配送業者が正しいか、プロバイダーが収集保留をどのように表現するかを確認します。イベントがないことだけで、追跡番号が無効である、または荷物が紛失したと証明されるわけではありません。不明な識別子、情報を待っている登録済み配送情報、処理できなかったリクエストの違いを、プロバイダーの定義に従って保持してください。
プロバイダーへのリクエストがタイムアウトまたは失敗する
以前の有効なステータスがある場合は、最新の確認が成功しなかったことを明示して、そのステータスを返します。以前に照会に成功した時刻は変更しないでください。ネットワークエラーは配送上の例外ではなく、荷物の業務上のステータスを変更してはいけません。
適切な一時的失敗には、バックオフとジッターを伴う上限付きリトライを使用します。無効な認証情報や不正なリクエストを繰り返し再試行しないでください。レスポンスにRetry-Afterが含まれる場合は、プロバイダーの契約とHTTPの意味に従って解釈します。HTTP仕様では、この値を秒単位の遅延またはHTTP日付として表現できます。
同じ配送情報に対して複数のリクエストが届く
同時実行される照会をまとめ、1つの上流リクエストを共有できるようにします。アカウント単位および配送単位で制限を適用し、自動リトライが複数のアプリケーション層で増幅しないようにします。バッチ処理がサポートされている場合は、HTTPリクエストが完了したからといってバッチ全体を成功とみなさず、各配送情報の結果を確認します。
ポーリングを管理されたフォールバックとして使用する
Webhookがない場合、スケジュールされたポーリングによってデータベースを最新に保てますが、明確な運用ポリシーが必要です。どの配送情報を対象にし続けるか、失敗がスケジュールにどう影響するか、通常のポーリングをいつ停止するかを決めてください。
多くの統合では、ハイブリッド設計が妥当な出発点です。Webhookはバックグラウンドの変更を処理し、オンデマンド照会は対話的なリクエストに対応し、照合ジョブは注意が必要なレコードを確認します。これはアーキテクチャ上の推奨であり、すべてのアカウントでコストを最小化できる保証ではありません。
- 配送中の配送情報と、取得エラーが未解決のレコードを優先します。
- スケジュールされた実行のたびに、過去のすべての配送情報を照会することは避けます。
- 必要な訂正期間を含め、完了した配送情報をどのように扱うかを定義します。
- 照会によって実際に新しい情報が見つかる頻度を追跡します。
- ポーリングの頻度を高めてWebhook配信の問題を隠すのではなく、Webhook配信の問題を調査します。
プロバイダーへのリクエスト遅延、失敗した照会、レート制限レスポンス、照会データとWebhookから取り込んだレコードの差異を監視します。最新の配送業者イベントの経過時間も別途監視してください。APIレスポンスが成功していても、追跡情報が変化していない場合があります。
リリース前にワークフローをテストする
リクエストが成功することは最初のテストにすぎません。誤解を招くステータス更新につながる可能性がある状況を確認してください。
- オンデマンド照会の実行中にWebhookが届く。
- 2人の顧客またはスタッフのセッションが同じ配送情報を同時にリクエストする。
- プロバイダーがHTTP成功を返すが、配送単位のエラーを報告する。
- アプリケーションが有効な追跡情報をすでに保持している状態でリクエストが失敗する。
- イベントにタイムゾーンがない、または不明なステータスコードが含まれる。
- 配送業者の訂正によって、以前に表示された結果が変わる。
- ユーザーが別のアカウントに属する配送情報へのアクセスを試みる。
リリース基準は、アプリケーションが既知の中で最も適切な配送情報を返し、その鮮度を正確に説明し、リクエストの失敗や順序が前後した到着によってその情報を破損させないことです。
よくある質問
APIに照会すると、配送業者に荷物のスキャンや更新を強制できますか?
いいえ。追跡情報を取得しても、物理的なスキャンを発生させることはできません。リクエストが上流への照会を引き起こすかどうかは、文書化された操作によって決まります。サポートされている更新操作であっても、配送業者に新しいイベントがなければ、変化していない情報が返されることがあります。
Webhookを設定せずにAPI照会を使用できますか?
プロバイダーが必要な照会ワークフローをサポートしていれば、オンデマンドリクエストまたはポーリングを中心に統合を構築できます。まず登録と照会の要件を確認してください。その後、いつ確認するかの判断、リクエスト量の制御、変更の検出をアプリケーションが担当します。
配送状況はどのくらいの頻度でポーリングすべきですか?
一律の間隔はありません。プロバイダーの制限、配送量、より早く更新を見つけることのビジネス上の価値に合ったスケジュールを選択します。ポーリングによって新しいイベントが返される頻度を測定し、頻繁なリクエストがより新しい配送業者データを生むと想定するのではなく、それに基づいて調整してください。
APIが、Webhookですでに受信した情報を返すのはなぜですか?
どちらの経路も、同じ基盤となる配送情報レコードを公開する可能性があります。Webhookは通知を配信し、照会はオンデマンドで情報を取得します。同じイベントを両方から受信しても必ずしもエラーではありません。アプリケーションで重複排除する必要があります。
更新ボタンには「追跡を更新」と表示すべきですか?
その表現が操作を正確に説明している場合に限ります。ボタンがプロバイダーに保存されたデータを取得するだけなら、「更新を確認」の方が明確です。最後の配送業者イベントと、アプリケーションが最後に確認に成功した時刻は分けて表示してください。
情報源
- 17TRACK Tracking API — このガイドで説明した追跡API統合に関する公式製品リファレンス。
- 17TRACK APIドキュメント — プロバイダー固有の操作、認証、リクエストフィールド、レスポンス処理に関するリファレンス。
- RFC 9110、セクション10.2.3:Retry-After — HTTPヘッダーのdelay-seconds形式とHTTP-date形式を定義。


