API経由で追跡番号を登録する方法:リクエストフィールド、配送業者コード、レスポンス
API経由で追跡番号を登録するには、配送の追跡番号と、必要な場合は配送業者識別子を含む認証済みの登録リクエストを送信します。その後、HTTPステータスだけでなく、送信した各配送についてレスポンスを確認し、登録が成功したか、失敗したか、または不確実な状態かを保存します。登録は追跡ワークフローを開始するものであり、配送業者が荷物をスキャンしたことや、追跡イベントがすでに利用可能であることを証明するものではありません。
このガイドは、注文管理システム、倉庫アプリケーション、またはeコマースプラットフォームを追跡APIに接続する開発者を対象としています。具体的な統合例として17TRACKを使用し、選択したAPIバージョンのドキュメントで確認すべき詳細を説明します。
登録でできること、できないこと
登録リクエストは、追跡サービスにどの配送を追跡したいかを伝えます。これは、配送ラベルの購入、集荷の予約、または配送業者への配送作成依頼とは異なります。一般的な統合では、まず配送ワークフローによって追跡番号が生成され、その後アプリケーションがその番号を登録します。
アプリケーション内では、次の3つのイベントを分けて管理してください。
- 配送作成済み:配送システムが追跡番号を割り当てた状態。
- 登録受付済み:追跡サービスが配送を追跡対象として受け付けた状態。
- 追跡情報受信済み:配送業者のイベントが追跡サービスを通じて利用可能になった状態。
登録が成功しただけで注文を「輸送中」に更新しないでください。新しく作成されたラベルには、まだ実際の引受スキャンがない可能性があります。顧客向けの配送ステータスは、登録レスポンスではなく、ステータスマッピングルールを通じて解釈した追跡イベントに基づくべきです。
17TRACKとの統合では、まずTracking API overviewを確認し、エンドポイント、フィールド定義、認証、レスポンスコードについては公式APIドキュメントを基準にしてください。以下の例では、結果の取得や更新の受信といった別の作業ではなく、登録に焦点を当てています。
API呼び出しを記述する前にリクエストフィールドを準備する
最も有効な準備は、配送システムと追跡統合の間で小規模なフィールド契約を定めることです。各値の発生元、欠落する可能性、検証方法を決めてください。
| フィールドまたは値 | 目的 | 実装ルール |
|---|---|---|
| 追跡番号 | 追跡対象の配送を識別します。 | 文字列として保存・送信し、先頭のゼロを保持します。 |
| 配送業者識別子 | 追跡プロバイダーのシステム内で配送業者を識別します。 | 社内倉庫コードではなく、プロバイダーが文書化した識別子を使用します。 |
| 内部参照 | 登録と配送レコードを紐付けます。 | 利用可能な場合はサポートされた参照フィールドを使用し、それとは別に自社データベースの対応関係も保持します。 |
| 追加識別データ | 配送業者が追跡番号以外の情報を必要とする場合に、配送の識別に役立つことがあります。 | その統合および配送業者について文書化されたフィールドのみ送信します。 |
| API認証情報 | 呼び出し元アカウントを認証します。 | サーバー上で管理し、アプリケーションログから除外します。 |
追跡番号を識別子として扱う
追跡番号を整数に変換しないでください。数値変換によって先頭のゼロが失われる可能性があり、一部のプログラミング環境では大きな値の精度が失われることがあります。誤って付いた前後の空白は削除しますが、関連するドキュメントまたは配送業者の形式で正規化がサポートされていない限り、句読点を削除したり大文字・小文字を変更したりしないでください。
APIを呼び出す前に、空文字列、予期しない改行、追跡番号フィールドに注文番号がコピーされている場合など、明らかな入力エラーを検証してください。すべての配送業者に共通する長さや文字ルールを設定することは避けてください。ある配送業者に適した検証ルールが、別の配送業者の正当な番号を拒否する可能性があります。
注文参照と配送識別情報を分けて管理する
1つの注文に複数の荷物が含まれる場合があり、交換品の配送によって別の追跡番号が発生することもあります。1注文につき追跡番号は1つだと仮定せず、配送または荷物単位で登録をモデル化してください。
プロバイダーがサポートするタグまたは参照フィールドを使用する場合は、顧客のメールアドレスや住所ではなく、意味を持たない配送参照を優先してください。注文、配送、追跡番号、配送業者マッピング間の正式な紐付けは、自社データベースで維持してください。
適切な配送業者コードを選択する
配送業者コードは、必ずしも業界共通の識別子ではありません。追跡プラットフォームが認識する値は、配送ソフトウェアに保存されている配送業者名と異なる場合があります。数値コードを使用する2つのシステムであっても、同じ配送業者に異なる番号を割り当てることがあります。
自社の配送サービスから追跡プロバイダーの配送業者識別子への明示的なマッピングを維持してください。必要に応じて、配送業者の地域運用やサービスを、より広いブランド名と区別します。表示名だけに基づくマッピングは、配送システムが別名を使用する場合に曖昧になる可能性があります。
- 配送業者が判明している場合:サポートされている場合は、文書化された配送業者識別子を使用します。特に追跡番号の形式が重複する場合に有効です。
- 配送業者が不明な場合:自動検出は文書化された仕組みでのみ使用します。省略、空文字列、ゼロ、nullが同じ意味だと仮定しないでください。
- 結果が正しくないように見える場合:同じ番号を繰り返し登録する前に、元のラベル、配送サービス、マッピングを確認します。
自動検出は便利ですが、特定の配送業者が実際に荷物を保管している証拠ではありません。同様に、有効な配送業者コードが、指定した追跡番号がその配送業者に属することを保証するわけでもありません。
配送業者マッピングは、アプリケーションコード全体に分散させず、設定可能にしてください。マッピングを最後に確認した日時を記録し、変更するたびに既知の配送を回帰テストに含めます。
例:17TRACK登録リクエストを送信する
次の例では、17TRACK v2.2の登録エンドポイント、17token認証ヘッダー、1つの追跡番号オブジェクトを含む配列を示します。デプロイ前に、このバージョンとリクエスト要件が自分のアカウントおよび公式ドキュメントと一致することを確認してください。追跡番号はプレースホルダーであり、実際の配送識別子に置き換える必要があります。
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
この最小限の例では、配送業者の選択や配送業者固有の補足フィールドは示していません。配送業者フィールドを省略した場合の配送業者検出方法と、配送に追加情報が必要かどうかを登録ドキュメントで確認してください。配送業者を指定する場合は、文書化されたcarrierフィールドと、そのAPIバージョンが想定する識別子を使用します。
このリクエストはサーバー側の環境から実行してください。トークンを公開ストアフロント、ブラウザスクリプト、または顧客に配布するモバイルアプリケーションに埋め込まないでください。ローカルの例では環境変数が便利ですが、本番環境では組織のシークレット管理機能を使用してください。
処理量を増やす前に、既知の配送を1件テストして完全なレスポンスを確認します。次に、無効な入力と、有効・無効な項目を両方含むバッチをテストしてください。これらの確認により、統合がHTTP成功レスポンスを認識するだけでなく、項目単位の結果を実際に処理しているかを確認できます。
レスポンスを3つのレベルで読み取る
信頼性の高いレスポンスハンドラーは、3つの別々の質問に答えます。リクエストはサービスに到達したか、サービスは操作を受け付けたか、各配送に何が起きたか、です。
1. HTTPおよび通信の結果
接続タイムアウト、TLSエラー、またはレスポンスの中断だけでは、サーバーがリクエストを処理したかどうかは必ずしも分かりません。照合できるまで、その結果を不確実として扱います。HTTP成功ステータスはHTTP通信が成功したことを示すだけであり、アプリケーションレスポンスも確認する必要があります。
2. リクエストレベルの結果
APIで文書化されたトップレベルの結果フィールドとエラーフィールドを確認してください。認証エラー、不正なJSON、アカウント制限には、それぞれ異なる対応が必要です。すべての失敗を「追跡利用不可」にまとめるのではなく、プロバイダーの元のエラーコードとメッセージを保存します。
数値のアプリケーションコードがHTTPステータスコードと同じ意味を持つと仮定しないでください。両者は異なる層に由来するため、別々に解釈する必要があります。
3. 配送レベルの結果
一括登録では、送信したすべての項目を処理してください。レスポンスによっては、受け付けられた配送と拒否された配送を区別します。パーサーは、選択したバージョンで文書化された正確なスキーマに従う必要があります。1件が成功しただけでバッチ全体を登録済みにしないでください。
プロバイダーのレスポンスを、自社の安定したアプリケーション状態に正規化します。たとえば、データベースではaccepted、rejected、uncertainを使用できます。これらは内部状態の例であり、17TRACKの文字どおりのレスポンス値ではありません。開発者が不一致を調査できるよう、適切な保持期間とアクセス方針のもとで元のプロバイダーレスポンスを利用可能な状態にしておきます。
有用な登録レコードには、内部配送ID、送信した番号、配送業者の選択、試行時刻、APIバージョン、結果、プロバイダーのエラー詳細が含まれます。登録ステータスと配送ステータスは分けて管理してください。
無限ループを作らずに再試行を処理する
再試行ポリシーは、例外が発生したかどうかだけでなく、失敗の内容に基づいて決めるべきです。
- 無効な入力:再試行する前にフィールドを修正します。変更されていない不正なリクエストを繰り返しても、改善する可能性は低いです。
- 認証失敗:認証情報とアカウント設定を確認します。同じ失敗するバッチを繰り返し送信しないでください。
- レート制限:文書化された制限と、該当する再試行指示に従います。即時の並列再試行ではなく、上限付きのバックオフを使用します。
- 一時的なサービス障害:定義した試行回数と時間の予算内で再試行します。
- 送信後のタイムアウト:最初の試行が失敗したと判断する前に、文書化されたAPI動作に基づいて配送の登録状態を照合します。
- 重複関連のレスポンス:配送がすでに登録されているか、自社のアプリケーションレコードと正しく関連付けられているかを確認します。
ドキュメントで動作が定義されていない限り、登録がべき等であると仮定しないでください。アプリケーション側の重複排除は、誤った再送を減らしますが、プロバイダーの重複処理ポリシーを確立するものではありません。
配送モデルに適した内部一意性ルールを使用してください。配送業者や長期保持期間をまたぐ場合、追跡番号だけでは永続的なキーとして十分でないことがあります。配送業者のコンテキストと自社の配送識別子を保持し、交換品や訂正された番号の扱いを文書化します。
登録を追跡更新とは別に監視する
API監視では、統合の失敗と、配送業者の新しいイベントが単に存在しない配送を区別する必要があります。これらの状態には、それぞれ異なる担当者と修正方法が必要です。
登録については、受付件数と拒否件数、エラーカテゴリ、不確実な結果、再試行待ち件数、レスポンス遅延を監視します。その後の追跡については、更新の受信または取得の失敗を別に監視してください。通常のトラフィックとプロバイダーが文書化した運用上限を理解する前に、数値によるアラート閾値を設定することは避けます。
本番環境で実施すべき確認では、次の質問に答えられるようにします。
- 追跡待ちのすべての配送に登録レコードがありますか。
- 受け付けられたすべての登録を正しい荷物まで追跡できますか。
- 拒否された項目は、元のデータを修正できる担当者に振り分けられていますか。
- 不確実なリクエストは放棄または無期限の再試行ではなく、照合されていますか。
- 顧客向けステータスは登録受付ではなく配送イベントから生成されていますか。
- 認証情報と不要な個人情報はログから除外されていますか。
eコマース運用では、API呼び出しと同じくらい運用上の引き継ぎが重要です。開発者は通信および解析の失敗を担当し、配送・フルフィルメントチームは不正確なラベル、配送業者マッピング、配送情報の不足を調査できる必要があります。
FAQ
最初の配送業者スキャン前に追跡番号を登録できますか。
登録と配送業者のスキャンは別のイベントです。サービスは、検証ルールに従い、追跡イベントが利用可能になる前に番号を受け付けることがあります。受付済みであることを、配送業者が荷物を受け取った証拠と解釈しないでください。
配送業者コードは常に指定する必要がありますか。
これは、APIで文書化された検出動作と対象の配送によって異なります。配送業者が判明している場合は、明示的で正しくマッピングされた識別子により曖昧さを減らせます。不明な場合は、配送業者の値を推測するのではなく、文書化された自動検出方法を使用してください。
配送が失敗したのに、なぜAPIはHTTP成功を返したのですか。
HTTPリクエストが成功しても、アプリケーションが個別の項目を拒否することがあります。トップレベルのアプリケーション結果と配送レベルの結果を読み取ってください。この区別は、バッチリクエストで特に重要です。
登録リクエストがタイムアウトした場合、どうすべきですか。
結果を不確実として扱います。接続が失敗する前にサーバーがリクエストを処理していた可能性があります。プロバイダーの重複動作と利用可能な登録または追跡照会方法を確認し、上限付きのポリシーに従って照合または再試行してください。
登録によって追跡通知も自動的に設定されますか。
そうだと仮定しないでください。登録、追跡情報の取得、Webhook設定は別々の統合事項です。関連ドキュメントを確認し、顧客通知に依存する前に更新経路全体をテストしてください。
情報源
- 17TRACK API documentation — 登録エンドポイント、認証、リクエストフィールド、配送業者識別子、レスポンススキーマ、エラー処理の参照先です。実装の詳細をデプロイするAPIバージョンに合わせてください。
- 17TRACK Tracking API overview — 追跡API製品と開発者向け統合リソースの公式スタート地点です。


