Skip to main content
ホームブログガイド初めてのTracking APIリクエスト:PostmanとCurlを使ったRESTクライアントの手順

初めてのTracking APIリクエスト:PostmanとCurlを使ったRESTクライアントの手順

17TRACK

最初のトラッキング API リクエストを実行するには、REST クライアントでエンドポイント、認証ヘッダー、JSON ボディを設定し、リクエストを送信して、HTTP ステータスとレスポンスボディの両方を確認します。このチュートリアルでは、17TRACK’s Tracking API を使用し、Postman と curl で同じワークフローを実行する方法を説明します。出荷情報を登録し、追跡情報をリクエストし、その結果をアプリケーションで利用できる状態かどうかを確認します。

初めての Tracking API リクエスト:REST クライアントの操作手順

目的は本番環境へのデプロイではなく、小規模で再現可能な統合テストを行うことです。API 認証情報と、処理する権限を持つ追跡番号が必要です。以下のコマンドでは v2.2 のエンドポイント形式を使用しています。実行する前に、17TRACK API documentation でエンドポイントのバージョンとアカウント固有の要件を確認してください。

最初のリクエストで実現すべきことを理解する

荷物追跡の統合には、追跡対象の荷物をサービスに伝えることと、その荷物に関連付けられた追跡情報を取得することという、2 つの別々の処理があります。ここで説明するワークフローでは、これらは別々のリクエストです。登録したからといって荷物がすでに移動したことにはならず、登録が成功したからといって配送業者のイベントがすぐに利用できるとは限りません。

最初のテストでは、バッチではなく 1 件の荷物を使用してください。これにより、認証エラー、無効な追跡番号、レスポンスの解釈を簡単に切り分けられます。最初に目指すべき有用な基準は、単に「HTTP 200 を受信した」ことではありません。「API が意図した操作を受け付け、荷物単位の結果を説明できる」ことです。

Postman では、リクエストを編集してレスポンスを確認するための視覚的なインターフェースを利用できます。curl では、同じ HTTP 通信をターミナルから再現できます。どちらも API の認証ルール、荷物データ、処理動作を変更するものではありません。リクエストを明確に調査できる方を使い、動作する設定をもう一方のツールでも再現してください。

認証情報、荷物、リクエストの詳細を準備する

いずれかのクライアントを開く前に、次のものを用意します。

  • 認証済みの API 認証情報:17TRACK API アカウントの設定から取得します。一般ユーザー向けの追跡セッションは、API 認証情報の代わりにはなりません。
  • 実際の追跡番号:自分が所有している、またはアクセス許可を得ている荷物を使用します。実際の追跡データをテストする場合、最近利用された荷物の方が、作成した番号より一般的に有用です。
  • 配送業者(判明している場合):診断のため、配送業者名を確認できるようにしておきます。配送業者識別子が必要な場合は、推測せず、API ドキュメントで定義されている値とフィールドを使用します。
  • 現在のリクエスト仕様:API バージョン、認証ヘッダー、リクエストスキーマ、アカウント上の制限を確認します。
  • 安全な作業環境:認証情報、顧客情報、完全な追跡レスポンスを、公開リポジトリ、スクリーンショット、共有サポートメッセージに載せないでください。

最小限のリクエスト例では、次の設定を使用します。

設定設定例
ベース URLhttps://api.17track.net/track/v2.2
登録操作POST /register
追跡情報取得操作POST /gettrackinfo
認証ヘッダー17token: YOUR_API_TOKEN
ボディ形式Content-Type: application/json、荷物オブジェクトの JSON 配列

追跡番号は文字列として保持してください。数値型に変換すると、先頭のゼロが削除されたり、値が変更されたりする可能性があります。以下のプレースホルダー YOUR_TRACKING_NUMBER は実際にテストする荷物番号に置き換える必要があります。動作するサンプル番号ではありません。

Postman で登録リクエストを作成する

1. 小規模なテスト環境を作成する

Postman で、base_url、tracking_token、tracking_number という 3 つの変数を持つ環境を作成します。base_url には上記のベース URL を設定し、他の変数には認証情報と荷物番号を入力します。リクエストを送信する前に、その環境を選択してください。

トークンには Postman で利用できる秘密情報の取り扱い機能を使用し、ワークスペースで何が共有または同期されるかを確認してください。インターフェース上で値を非表示にするだけでは、アクセスできるユーザーを制御したことにはなりません。入力済みの認証情報を、同僚向けまたは公開ドキュメント向けのコレクションとともにエクスポートしないでください。

2. メソッド、URL、ヘッダーを設定する

HTTP リクエストを作成し、POST を選択して、URL に {{base_url}}/register を入力します。Headers タブで次を追加します。

17token: {{tracking_token}}
Content-Type: application/json

この例では、認証情報をカスタム 17token ヘッダーに入れます。他の API でその方式が使われていたからといって、Bearer トークン設定に置き換えないでください。また、コレクションから継承された設定によって意図しない Authorization ヘッダーが追加されていないか確認してください。

3. JSON ボディを追加する

Body を開き、raw を選択して JSON を指定します。次を入力します。

[
  {
    "number": "{{tracking_number}}"
  }
]

外側の角括弧は重要です。このリクエストは荷物が 1 件だけであっても配列を使用します。二重引用符を使い、末尾のカンマを削除し、JSON 内にコメントを入れないでください。配送業者または荷物に関して追加情報が必要な場合は、送信前にドキュメントで指定されたフィールドを追加します。

4. 送信して結果を確認する

Send をクリックします。まず、HTTP レスポンスを受信できたかどうかを確認します。DNS エラー、TLS エラー、プロキシの問題、タイムアウトは、リクエストが無効であることを説明するレスポンスとは異なります。次に、操作結果と、荷物単位の受け付けまたは拒否に関する情報をレスポンスボディで確認します。

リクエストを「Register test shipment」として保存します。トークンをコピーせずに、HTTP ステータス、API の結果、エラーメッセージを記録します。登録に失敗した場合は、先にその問題を解決してください。変更していないリクエストを繰り返し送信すると診断が難しくなり、アカウントのリソースを消費する可能性があります。

curl でリクエストを再現する

以下のコマンドでは、Bash や Zsh などの POSIX 形式のシェルを使用します。PowerShell と Windows Command Prompt では、引用符と変数の規則が異なります。PowerShell では、必要に応じてシェル固有のコマンドエイリアスではなく curl の実行ファイルを呼び出すために curl.exe を使用してください。

ベース URL を設定し、通常の秘密情報管理手順で認証情報を環境変数に読み込みます。

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

環境変数を使うことで、再利用可能な例に認証情報を直接記載せずに済みますが、完全な秘密情報管理システムではありません。ローカルテストでは、シェル履歴に残るコマンドに実際のトークンを入力しないでください。自動化では、プラットフォームの秘密情報ストアを使用し、ログ出力を制限します。

shipment.json という名前のファイルを作成し、プレースホルダーをテスト用の追跡番号に置き換えます。

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

登録リクエストを送信します。

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

これによりレスポンスボディは register-response.json に保存され、HTTP ステータスは別に表示されます。接続および合計のタイムアウトはローカルテスト用の設定であり、17TRACK サービスの保証ではありません。保存したファイルを開いて API の結果を確認してください。ステータス行だけでは不十分です。

サーバーが HTTP エラーレスポンスを返しても、curl は転送を正常に完了することがあります。反対に、通信障害によって利用可能な API レスポンスが届かない場合もあります。スクリプトでは、curl の終了ステータス、HTTP ステータス、アプリケーションレベルの結果を別々のシグナルとして処理してください。

荷物の追跡情報をリクエストする

登録を確認したら、Postman のリクエストを複製し、URL を {{base_url}}/gettrackinfo に変更します。POST メソッド、認証ヘッダー、コンテンツタイプ、荷物のボディは維持してください。取得するつもりで誤って荷物を再登録しないよう、別のリクエストとして保存します。

同等の curl リクエストは次のとおりです。

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

新しく登録した荷物が、すぐに完全なイベント履歴を返すと想定しないでください。データの利用可能性は、荷物とサービスの処理状況によって異なります。情報がまだ利用できない場合は、同じ番号を繰り返し登録したり、短い間隔でポーリングを繰り返したりせず、ドキュメントに記載された取得および更新のガイダンスに従ってください。

レスポンスを 3 つの層で読む

  1. 通信:クライアントは接続し、HTTP レスポンスを受信できたか。
  2. 操作:API はリクエストを受け付けたか、また個々の荷物の処理は成功したか。
  3. 荷物情報:返されたデータは対象の荷物を識別しているか、そのステータスやイベント履歴から実際に何が確認できるか。

ステータス、配送業者、イベントの各フィールドを確認するには、公式のレスポンススキーマを使用します。正規化された荷物ステータスと、配送業者が元々返したイベント説明を区別してください。検索が成功したことは配達済みの証拠ではなく、イベントがないことは荷物紛失の証拠でもありません。

タイムスタンプを保存するときは、提供されたタイムゾーンまたはオフセット情報を保持してください。異なる形式の生の日付文字列を並べ替え、それらが正しい時系列を表すと想定しないでください。また、アプリケーションが記録を取得した時刻と、荷物イベントが発生した時刻も区別してください。

すべてを一度に変更せずにトラブルシューティングする

  • レスポンスがない:ホスト名、ネットワークアクセス、プロキシ設定、TLS 設定、ローカルのタイムアウトを確認します。通常の対処として証明書検証を無効にしないでください。
  • 認証に失敗する:トークンが有効であること、17token ヘッダーが存在すること、選択した Postman 環境で変数が正しく解決されることを確認します。意図しない空白がないか確認してください。
  • 無効なリクエスト:ドキュメントに照らして、API バージョン、操作パス、POST メソッド、コンテンツタイプ、JSON 配列の構造を確認します。
  • 荷物が拒否される:荷物固有のエラーを読みます。すべての拒否を認証問題として扱わず、番号と必要な配送業者情報を確認してください。
  • 追跡イベントがない:登録と対象荷物の識別情報を確認します。配送業者情報が必要か、再試行前に更新が利用可能かを確認してください。
  • Postman では動作するが curl では失敗する:解決済み URL、実際のヘッダー、ボディのバイト列を比較します。シェルの引用符と未設定の環境変数は、リクエストが異なる一般的な原因です。

テストごとに 1 つの変数だけを変更し、結果を簡単に記録してください。Postman のコンソールを確認したり、curl の詳細出力を使用したりする場合は、出力を機密情報として扱います。リクエストヘッダーから認証情報が漏れる可能性があります。診断情報を共有する前に、秘密情報と顧客情報を伏せてください。

チュートリアルが完了したと判断する基準

両方のクライアントが意図したリクエストを送信し、登録内容を理解でき、取得によって解釈可能な結果が返され、API の失敗と新しい情報がない荷物を区別できれば、意味のある最初の統合テストは完了です。HTTP ステータスコードが一致しただけでは、2 つのクライアントが同じ動作をしたことは証明できません。

ワークフローをアプリケーションに移す前に、認証情報をサーバー側で管理し、入力値を検証し、構造化されたエラー処理を使用してください。アカウントに適用されるレート制限、バッチ制限、再試行に関するガイダンス、更新配信オプションを確認します。タイムアウト後に登録を無条件で再試行しても安全だと想定しないでください。クライアントがレスポンスを受信できなくても、サーバーがリクエストを処理済みである可能性があります。

無効な認証情報、形式が不正な JSON、無効な荷物番号、すでに登録された荷物、利用できない追跡データ、ネットワークタイムアウトに対するテストを追加します。それぞれのケースで、未処理の例外や誤解を招く顧客向けステータスではなく、意図したアプリケーション上の結果になるようにしてください。

FAQ

実際の追跡番号なしでテストできますか?

無効な値を使って一部のリクエスト検証動作をテストすることはできますが、荷物追跡の検証にはなりません。実際のイベントをテストするには、権限のある荷物、またはサービスが提供している場合は公式のテストフィクスチャを使用してください。任意のサンプル番号がサンドボックスに属していると想定しないでください。

HTTP 200 のレスポンスに失敗が含まれるのはなぜですか?

HTTP ステータスとアプリケーション結果は、異なる層を表します。サーバーがリクエストを正常に受信して処理しながら、個々の荷物が拒否されたと報告することがあります。HTTP ステータスだけでなく、レスポンスボディとドキュメントに記載された荷物単位の結果を確認してください。

追跡情報の取得に POST が使われるのはなぜですか?

エンドポイントの仕様で指定されたメソッドを使用してください。この取得例では、POST による JSON リクエストボディで荷物識別子を受け付けます。データを読み取る操作だからといって GET に変更しても、文書化されたリクエストは維持されません。

API トークンをブラウザーの JavaScript に入れてもよいですか?

公開配信されるフロントエンドコードに、非公開の API 認証情報を埋め込まないでください。認証情報を保護し、入力値を検証し、各ユーザーがアクセスできる荷物情報を制御する、認証済みのバックエンド経由でリクエストを送信してください。

本番環境で Postman と curl の両方が必要ですか?

いいえ。これらはテストと診断に役立つツールです。本番アプリケーションでは、適切な HTTP クライアントを使用できます。実際のトークンや不要な顧客データを含めず、サニタイズした Postman リクエストまたは curl コマンドを再現可能なリファレンスとして保管してください。

出典