Skip to main content
ホームブログガイド1つのAPIリクエストで複数の追跡番号を送信する方法(バッチ制限と部分的な失敗)

1つのAPIリクエストで複数の追跡番号を送信する方法(バッチ制限と部分的な失敗)

17TRACK

1回のAPIリクエストで複数の追跡番号を送信するには、バッチを明示的に受け付けるTracking APIエンドポイントを使用し、各配送情報をそのリクエストスキーマに従って整え、より大きなリストはドキュメントに記載された制限以内のバッチに分割します。その後、HTTPレスポンスと各配送情報の結果の両方を確認してください。HTTPリクエストが成功しても、すべての追跡番号が受け付けられたとは限りません。再試行するのは対象となる失敗だけにし、バッチ全体を再送信する前に、不確実な結果を照合してください。

1回のAPIリクエストで複数の追跡番号を送信する方法

このガイドは、配送追跡を注文管理システム、倉庫プラットフォーム、ECアプリケーション、または社内ダッシュボードに接続する開発者向けです。目的は単にリクエスト数を減らすことではありません。重複作業や失敗した記録の紛失を発生させず、すべての配送情報を確実に処理することです。

まず、バッチエンドポイントが実際に行う処理を確認する

追跡連携には、いくつかの異なる操作が含まれる場合があります。配送情報の登録、最新の追跡情報の取得、その後の更新の受信は、同じものではありません。

  • 登録:サービスが配送情報の追跡を開始または継続できるよう、配送情報を送信します。
  • 照会:エンドポイントの取得ルールに従い、配送情報の追跡情報をリクエストします。
  • 配送更新:Webhookなどの対応メカニズムを通じて後続の変更を受信するか、スケジュールされたリクエストで取得します。

必要な操作を正確に確認するには、ドキュメントを参照してください。複数のレコードを受け付ける登録エンドポイントがあっても、照会エンドポイントが同じ件数を受け付けること、同じスキーマを使用すること、または同じレート制限を共有することを意味しません。

17TRACKとの連携では、まずTracking API製品ページを確認し、公式APIドキュメントで操作、認証方法、リクエスト形式、レスポンスフィールドを確認してください。以下の例は実装パターンであり、そのAPI契約の代わりになるものではありません。

バッチ制限は配送情報の最大件数だけではない

Tracking APIに共通のバッチ制限はありません。制限はプロバイダー、エンドポイント、APIバージョン、アカウント設定によって異なる場合があります。バッチ処理を実装する前に、これらの制約を個別に記録してください。

制約確認事項実装上の影響
1リクエストあたりの項目数対象操作で許可される最大レコード数送信前に入力リストを分割する
リクエストボディサイズ記載されたバイト数制限オプションフィールドとシリアライズ後のサイズを考慮する
リクエストレート定められた期間内に許可されるリクエスト数共有リミッターでリクエスト速度を調整する
同時実行数同時リクエストに関する制限アクティブなワーカー数を制限する
利用量の計上リクエスト、配送情報、その他の単位のどれで利用量が計上されるかリクエスト数とは別に消費量を見積もる

たとえば、仮想的なエンドポイントが1リクエストあたり25レコードを許可する場合、63レコードには25、25、13件を含む3つのリクエストが必要です。これらの数値は分割方法を示すためだけのものであり、17TRACKの制限を示すものではありません。

バッチ処理によって請求対象の利用量が減ると想定しないでください。HTTPリクエストのオーバーヘッドは削減できますが、料金への影響はプロバイダーの実際の計上ルールによって異なります。同様に、有効なバッチサイズが無制限の並列リクエストを許可するわけでもありません。

リクエストを作成する前にレコードを準備する

回避可能なバッチ失敗の多くは、入力準備から始まります。各配送情報をバッチに追加する前に検証します。ただし、異なる配送業者の正当な追跡番号を誤って拒否するルールは避けてください。

  1. 追跡番号を文字列として保持する。数値に変換すると、先頭のゼロが削除されたり、長い識別子が変更されたりする可能性があります。
  2. 誤って付いた前後の空白を削除する。該当する仕様で正規化が許可されていない限り、内部文字を削除したり、大文字と小文字を変更したりしないでください。
  3. 必須フィールドを検証する。配送業者識別子や追加の配送情報が必要なワークフローもあります。ドキュメントに記載されたフィールド名と値だけを使用してください。
  4. 重複排除の範囲を明示的に決める。同じ追跡番号が、すべての配送業者、販売者、過去の配送情報にまたがって自動的に重複するとは限りません。
  5. ローカル配送情報識別子を保持する。APIがカスタム参照フィールドを受け付けない場合でも、送信対象と注文または配送記録との関係を保存してください。

複数ネットワークにまたがるCarrier Trackingでは、特定のワークフローで信頼できる場合を除き、追跡番号の長さや接頭辞だけから配送業者を推測しないでください。APIが配送業者識別をサポートしている場合は、曖昧さの処理方法に関するドキュメントに従ってください。

例示的なリクエスト構造

以下のJSONは、バッチペイロードの概念を示しています。ラッパー、プロパティ名、識別子は例示であり、17TRACKのリクエストスキーマではありません。APIによっては、配列を含むオブジェクトではなく、トップレベル配列を要求します。

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

文字列を連結するのではなく、JSONシリアライザーを使用してペイロードを作成してください。認証情報はドキュメントに記載された方法で送信し、ソース管理、ブラウザーに配信されるコード、通常のログには含めないでください。

レスポンスを2つのレベルで処理する

バッチリクエストには、トランスポートレベルの結果とアプリケーションレベルの結果があります。連携処理では両方を評価する必要があります。

レベル1:リクエストは利用可能なレスポンスを受け取ったか

まずHTTPステータス、レスポンスヘッダー、レスポンスボディを確認します。認証エラー、不正なリクエスト、レート制限、サーバー障害により、通常の項目処理が妨げられる場合があります。ネットワークタイムアウトは別の問題です。クライアントは、サーバーがリクエストを受信または処理したかどうかを把握できない可能性があります。

HTTPのセマンティクスはRFC 9110で定義されています。ただし、アプリケーションレベルの結果フィールドが実際の配送結果にどのように対応するかは、プロバイダーのドキュメントによって決まります。

レベル2:各配送情報に何が起きたか

レスポンスが項目単位の結果をサポートしている場合は、送信したすべてのレコードを分類します。HTTP 200がすべてのレコードの成功を意味すると仮定したり、契約で明示的に保証されていない限り、結果リストがリクエスト順を維持すると仮定したりしないでください。

  • 受理:エンドポイントのドキュメント上の定義に従って操作が成功した。
  • 永続的な入力失敗:再試行する前にレコードを修正または調査する。
  • 再試行可能な失敗:プロバイダーの再試行ガイダンスに従って、もう一度試行する。
  • 結果不明:レスポンスがない、不完全である、または送信レコードと安全に照合できない。

「すでに登録済み」などの重複関連レスポンスは、ドキュメント上の意味を理解するまで別に扱ってください。目的の状態がすでに存在することを示す場合がありますが、所有、設定、購読の確認が成功したものとして自動的に扱うべきではありません。

レスポンスの処理後、すべての入力レコードにはローカル上で正確に1つの結果が必要です。有用な照合チェックは、送信レコード数が、受理レコード数、永続的な失敗、再試行可能な失敗、結果不明の合計に等しいことです。これはローカルの計上ルールであり、APIレスポンス形式の要件ではありません。

成功したレコードを再送信せず、部分的な失敗を処理する

例として、10件の配送情報を含むバッチで、7件が受理され、2件に必須フィールドの不備があり、1件で文書化された一時的なエラーが発生したとします。7件の成功結果を保存し、2件の不正なレコードを修正処理に回し、一時的な失敗だけを再試行します。

10件すべてを再送信すると、不要なトラフィックが発生し、重複処理が複雑になる可能性があります。また、最初の拒否と後続の重複関連レスポンスを区別しにくくなります。

結果推奨アクション
無効なフィールドまたはサポートされていない値入力を修正し、変更なしで再試行しない
認証または権限エラー影響を受ける処理を停止し、認証情報またはアクセスを修復する
レート制限レスポンスドキュメントのガイダンスと該当するレスポンスヘッダーに従って遅延させる
一時的な項目レベルエラー回数とバックオフに上限を設け、その項目を再試行する
送信後のタイムアウト不確実として扱い、照合するか、文書化された再試行安全性の保証を利用する
認識できない、または不完全な結果成功と仮定せず、証拠を保持して調査する

HTTP 429はリクエストが多すぎることを示し、RFC 6585に記載されているように、レスポンスにRetry-Afterヘッダーが含まれる場合があります。このヘッダーが常に存在すると仮定しないでください。明示的な再試行遅延がない場合は、APIドキュメントに沿った上限付きバックオフポリシーを使用します。

複数のワーカーからの再試行を分散するためにジッターを追加し、最大試行回数または再試行期間を設定して、上限に達したレコードをレビューキューに送ってください。無期限の再試行は、継続的な設定問題を隠す可能性があります。

タイムアウトに特別な処理が必要な理由

タイムアウトは拒否を証明するものではありません。接続が失敗する前に、サーバーがバッチを受け付けていた可能性があります。そのため、状態を変更するリクエストを自動的に再送信すると、処理が重複する可能性があります。

エンドポイントが文書化された冪等性キーをサポートしている場合は、キーの範囲や保持期間を含め、そのルールに従ってください。冪等性ヘッダーを独自に作成し、サーバーがそれを受け付けると仮定しないでください。それ以外の場合は、再送信前に目的の状態が存在するかどうかを確認するため、対応している照会または照合ワークフローを使用します。ローカル重複排除は自分のワーカーの調整には役立ちますが、サーバー側の冪等性を保証するものではありません。

実用的なバッチ処理ワークフロー

プロバイダー固有の詳細はアダプターに集約し、キュー、再試行スケジューラー、監視ロジックが生のレスポンスフィールド名に依存しないようにします。

レコードを検証し、ローカル配送情報IDを保持する
意図したビジネス範囲内で重複を解決する
文書化された項目数とペイロードの制限に従ってレコードを分割する

上限付きワーカープールを通じて各バッチを処理する:
    送信前に試行記録を保存する
    共有レートリミッターの許可を待つ
    プロバイダー固有のアダプターを使用して送信する

    結果が不確実な場合:
        照合キューに追加する
        継続する

    リクエストレベルと項目レベルの結果を分類する
    送信した各レコードについて1つの結果を保存する
    対象となる失敗だけを再試行に回す
    無効または上限到達レコードをレビューに回す

結果の保存と再試行スケジュールは復旧可能にしてください。たとえば、永続ジョブレコードやトランザクション型のキュー処理パターンを使用すると、プロセスのクラッシュによって再試行判断が失われるのを防げます。ワーカーの再起動時には、未送信の処理と、リモート結果がまだ不確実な処理を区別できる必要があります。

バッチサイズはコードベース全体に散在する定数ではなく、対象エンドポイントに紐付いた設定可能な値にしてください。問題のあるレコードのトラブルシューティングや切り分けでは、小さなバッチが役立つ場合があります。許可される最大バッチが、常に最適な運用サイズとは限りません。

HTTPの稼働状況だけでなく配送結果を監視する

API Monitoringでは、配送情報が意図した状態に到達しているかを確認できる必要があります。HTTP成功率だけを表示するダッシュボードでは、成功したように見えるレスポンス内部の部分的な失敗を見逃す可能性があります。

  • 項目受理率:再試行の扱いを明確に定義したうえで、送信レコードに対する受理レコードの割合。
  • 失敗分布:エンドポイント、文書化されたエラーコード、関連する配送業者のコンテキスト別の件数。
  • 結果不明:未照合レコードと、未解決のまま経過した時間。
  • 再試行バックログ:保留中の再試行、最も古い再試行の経過時間、上限到達試行。
  • リクエストの健全性:レイテンシ、タイムアウト、レート制限、サーバーエラー。
  • 追跡情報の鮮度:受理された配送情報が、その後利用可能な追跡情報を受信しているか。

登録が受理されたことは、新しい配送業者スキャンの証明ではありません。API処理ステータスを配送の移動状況やデータの鮮度から分離し、連携障害と配送遅延を混同しないようにしてください。

ローカルバッチID、配送情報参照、試行回数、文書化されたエラーコード、利用可能な場合はプロバイダーのリクエストIDをログに記録します。認証情報と不要な個人情報はマスキングしてください。追跡識別子は運用上必要な場合にのみ使用し、生の配送識別子をカーディナリティの高いメトリクスラベルに含めないでください。

本番前にこれらのケースをテストする

利用可能な場合は、文書化されたサンドボックスまたは管理されたテスト環境を使用してください。作成した追跡番号が本番で予測可能なレスポンスを返すとは限りません。

  1. 文書化された項目数の上限で有効なバッチを送信し、その後、クライアントが過大なバッチを防止する方法をテストする。
  2. 先頭にゼロがある追跡番号がシリアライズと保存後も維持されることを確認する。
  3. 受理された項目と拒否された項目が混在するケースを、成功したレコードを再試行せずにテストする。
  4. レート制限をシミュレートし、複数のワーカーが同じ制限を守ることを確認する。
  5. 送信後のタイムアウトをシミュレートし、照合経路を検証する。
  6. レスポンス受信からローカル保存までの間にワーカーを再起動する。
  7. 項目結果が欠落している、未知である、または照合できないケースをテストする。
  8. 無効なレコードが無限に再試行されず、確認可能な修正キューに到達することを確認する。

本番対応の連携では、結果が一時的に不明なものも含め、送信したすべての配送情報の状態を説明できる必要があります。リクエスト数の削減は有用ですが、その説明責任を維持することがより重要な設計目標です。

FAQ

1回のリクエストで何件の追跡番号を送信できますか?

正確なエンドポイントとAPIバージョンに対して文書化された制限を使用してください。リクエストサイズ、レート制限、アカウント固有の制約も確認してください。追跡API全体、または1つのAPI内の異なる操作に適用できる安全な共通件数はありません。

1件の無効な追跡番号によってバッチ全体が失敗することはありますか?

はい、エンドポイントの検証ルールによっては発生します。個別の拒否を返すAPIもあれば、項目処理の前にリクエスト全体を拒否するAPIもあります。リクエストレベルのエラーと項目レベルの結果の両方を確認し、すべてのバッチエンドポイントが部分受理をサポートしていると仮定しないでください。

HTTPレスポンスが成功した場合、バッチを再試行すべきですか?

自動的に再試行してはいけません。まず、文書化されたアプリケーションレベルのステータスと項目結果を解析してください。成功したレコードを保存し、対象となる失敗だけを再試行します。結果を安全に解釈できない場合は、不確実として分類して調査してください。

同じバッチに複数の配送業者を混在させられますか?

エンドポイントがそのリクエスト構造をサポートしている場合に限ります。配送業者情報を配送情報ごとに指定するのか、自動識別をサポートしているのか、識別が曖昧な場合にどうなるのかを確認してください。マルチキャリアサービスであることだけでは、すべてのエンドポイントのバッチルールは確定しません。

バッチ処理によって追跡更新の到着は速くなりますか?

バッチ処理によってアプリケーションが送信するリクエスト数は減らせますが、それだけで配送業者のイベントが早く表示されるわけではありません。登録、データ取得、配送業者スキャンの利用可能性、更新の配信は、ワークフロー内の別々の要素です。

情報源