Skip to main content
ホームブログガイド開発環境でのTracking API連携のテスト:サンドボックス、テスト番号、モックWebhook

開発環境でのTracking API連携のテスト:サンドボックス、テスト番号、モックWebhook

17TRACK

開発環境で追跡API連携をテストするには、3つの補完的な方法を使用します。APIの動作確認にはプロバイダーのサンドボックスまたは文書化されたテスト番号、再現可能な出荷シナリオにはローカルフィクスチャ、受信エンドポイントにはモックWebhookを使用します。その後、シミュレーションでは証明できない認証情報、サブスクリプション設定、実際のイベント配信などを検証するため、制御された本番環境でのライブチェックを実行します。

開発サンドボックスでの追跡API連携のテスト、テスト番号

このガイドは、出荷追跡をECプラットフォーム、注文管理システム、ERP、または顧客通知サービスに接続する開発者向けです。目的は、単にAPIから成功レスポンスを受け取ることではありません。追跡更新によって、重複メッセージ、イベントの消失、実際の顧客への誤通知なしに、正しい注文状態が生成されることを証明することです。

プロバイダーの動作とアプリケーションの動作を分離する

追跡連携には少なくとも2つの境界があります。アプリケーションがプロバイダーに送信するリクエストと、その後アプリケーションが受信または取得する更新です。最初の境界でリクエストが成功しても、2つ目の境界が機能することは証明できません。

システム全体を1つのテスト追跡番号で検証しようとするのではなく、これらの境界を中心にテスト計画を作成します。

テスト方法検証できること単独では確認できないこと
プロバイダーのサンドボックスプロバイダーが説明する、サポート対象のリクエスト形式、認証、シミュレーション動作本番の配送業者データの可用性や本番の配信動作
文書化されたテスト番号それらの番号に割り当てられた特定のシナリオその他のステータス、配送業者、Webhookシーケンス
ローカルフィクスチャとAPIモックパーサー、マッピングルール、永続化、障害処理実際のプロバイダーがリクエストを受け入れるか、同じペイロードを送信するか
モックWebhookリクエストエンドポイント処理、検証、重複排除、下流への影響プロバイダー側のコールバック設定や実際の再配信
制御されたライブテスト実際の接続性と観測された出荷ワークフローすべてのまれなエラー、例外、配信シーケンス

推奨アプローチ:ローカルテストを決定論的にし、利用可能な場合はプロバイダーがサポートするテストを使用し、システム間の接続確認にはライブ出荷を限定して使用します。

フィクスチャを作成する前にプロバイダーの契約を確認する

使用する予定のAPIバージョンの公式ドキュメントから始めます。ベースURL、認証方式、登録要件、レスポンススキーマ、Webhook設定、文書化されたテスト機能を確認します。プロバイダーがAPIを提供しているからといって、独立したサンドボックスが存在すると推測してはいけません。

17TRACK連携では、出発点として17TRACK Tracking APIページと公式APIドキュメントを使用します。プロバイダー固有の例を作成する前に、そこで該当するリクエスト仕様とコールバック仕様を確認してください。以下の例は、17TRACK APIスキーマを表すものではなく、意図的にアプリケーション側で所有するフィクスチャです。

開発コードを外部アカウントに接続する前に、次の疑問を解決します。

  • 開発用と本番用の認証情報は分離されていますか。また各認証情報はどの環境にアクセスしますか。
  • サンドボックスはコールバックをサポートしますか、それともリクエストとレスポンスのテストだけですか。
  • テスト番号は文書化されていますか。また、それらは正確にどのような結果を生成しますか。
  • 登録やその他のテストリクエストによって、アカウントの割り当て枠が消費されたり、永続的なレコードが作成されたりしますか。
  • コールバック認証、確認応答、タイムアウト、再試行について、どのようなルールが文書化されていますか。
  • 追跡登録、出荷、配送業者、コールバックイベントを結び付ける識別子はどれですか。

テスト動作が明確に文書化されていない場合は、プロバイダーに確認を依頼します。その間も、モックを使って自分の処理ロジックのテストを続けます。確認されていないサンドボックス機能は計画上の不確実性であり、プロバイダーにその機能がない証拠ではありません。

分離された開発環境を構築する

個別のデータベースまたは分離されたテナント、個別のシークレット、合成注文を使用します。メール、SMS、その他の通知はテスト先または通知シンクにルーティングします。フィクスチャで配達済みになった出荷が、実際の購入者にメッセージを送信してはいけません。

内部レコードとログに明示的な環境マーカーを追加します。プロバイダーの認証情報はサーバー上で管理し、ソース管理の外部に置き、リクエストキャプチャからシークレットをマスキングします。コールバックのために一時的な公開アクセスが必要な場合は、意図した開発用ルートだけを公開し、認証制御を維持します。

イベントを送信する前に、既知の注文を少数作成します。1つの注文に紐付く2つの出荷と、アプリケーションが対応している場合は、異なる配送業者コンテキストで同じ追跡番号文字列を含めます。これらのケースにより、追跡番号だけで常に一意の業務レコードを識別できるという前提が明らかになります。

各テストで期待される効果をあらかじめ定義します。出荷状態、注文との関連付け、タイムラインエントリ、通知数、監査記録などです。これにより、デモが合否を判定できるアサーションになります。

テスト番号は文書化された目的にのみ使用する

追跡番号には2つの異なるテスト上の役割があります。登録を検証する入力として使用できる一方、追跡イベントを生成する出荷を識別することもできます。形式検証に通る番号が、役立つイベント履歴を提供するとは限りません。

公式テスト番号が利用できる場合

各番号に対して、プロバイダーが示したシナリオを記録します。配達済み出荷用に文書化された番号が、例外、返品、配達失敗の試行をシミュレートすると想定してはいけません。また、結果が固定されているか、時間とともに変化するか、特定の配送業者の選択が必要かも確認します。

これらの番号は専用の統合テスト設定に保存します。外部動作の変更によって、それまで決定論的だったテストが不安定になり得る単体テスト内に分散させないでください。

公式テスト番号が確認できない場合

自分のアプリケーション内で合成識別子を使用し、プロバイダーとの境界をモックします。もっともらしい番号を作り、テスト用に確保されていると想定してはいけません。実際の出荷と一致する可能性があります。

ライブ検証には、自分が管理し、アクセス権限を持つ出荷を使用します。公開スクリーンショットや顧客との会話から追跡番号をコピーすることは避けます。出荷履歴には場所、タイムスタンプ、配達情報が含まれる可能性があるため、潜在的に機微な情報として扱います。

古い配達済み出荷はパースの検証に役立つ場合がありますが、継続的インテグレーションの依存先としては適していません。履歴データの可用性や外部レスポンスは変化する可能性があります。再現可能なテストのためにサニタイズ済みフィクスチャを保存し、ライブチェックとは分離します。

意味のある出荷遷移を中心にフィクスチャを作成する

文書化されたスキーマと、利用可能な場合はサニタイズ済みの実際のレスポンスからフィクスチャを作成します。プロバイダーのペイロードフィクスチャは、内部の正規化イベントモデルとは分離します。両者の間のアダプターをテストし、内部モックによって壊れたプロバイダーパーサーが隠されないようにします。

有用な開始セットには、次のシナリオを含めます。

  • 追跡イベントがまだない:移動中または配達済みと主張せずに出荷を保持する。
  • 輸送中:タイムラインを更新し、正しい注文との関連付けを維持する。
  • 配達に出発:配達完了として扱わず、通知ポリシーを適用する。
  • 配達済み:完了を記録し、意図した業務アクションを1回だけ発行する。
  • 例外または配達試行:配達完了との違いを維持する。
  • 返品移動:後続のすべてのスキャンを元の受取人に向かう進行と解釈しない。
  • 不明なステータス:ステータスマッピングを勝手に作らず、診断に十分な情報を保持する。

これらのシナリオには独自の正規化された名称を使用し、プロバイダーの文書化された値を明示的にマッピングします。異なるAPIが同じステータスラベルを使用する、またはラベルがどこでも同じ業務上の意味を持つとは想定しないでください。

データの形状も変化させます。空のイベントリスト、欠落したオプションフィールド、追加の未知フィールド、Unicodeの場所名、タイムゾーンオフセット付きタイムスタンプ、形式が不正な必須値などです。パーサーは互換性のある追加を許容しつつ、安全に処理できないデータは拒否する必要があります。

実際の受信経路を通してモックWebhookを送信する

モックWebhookは、最終的なステータス更新関数を単に呼び出すのではなく、受信ルート、認証ミドルウェア、検証、保存、ワーカー処理を実行する必要があります。

次のペイロードは合成された内部イベントを表します。フィールド名、イベントID、ステータスは例示であり、プロバイダーのコールバック契約ではありません。

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

これをtracking-event.jsonとして保存し、ローカルテスト受信先にPOSTします。

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

このコマンドで検証できるのは、ローカルのルーティングと処理だけです。プロバイダー認証を証明するものではありません。開発専用ルートは本番環境からアクセスできないようにするか、プロバイダーが文書化した認証方式と別のテスト用シークレットを使用して本番受信先をテストします。

本番の制御を弱めずに認証をテストする

プロバイダーが署名付きコールバックを指定している場合は、任意の署名ヘッダーやアルゴリズムを選ばず、正確な方式を実装します。リクエストバイトに署名する方式では、検証のために元の本文を保持します。JSONをパースして再シリアライズすると、バイト列が変化する可能性があります。

該当する場合は、正しい認証、認証情報の欠落、改ざんされた本文、不正な署名をテストします。文書化された方式にタイムスタンプやリプレイ防止が含まれる場合は、それらのルールもテストします。HMACは標準化されたメッセージ認証構造ですが、HMACが存在することだけでは、特定の追跡プロバイダーがそれを使用しているとは証明できません。

重複、順序、復旧をテストする

同じ更新が繰り返し届いた場合や、イベントが予期しない順序で届いた場合でも、出荷処理は正しく動作する必要があります。これらは防御的なテストシナリオであり、特定のプロバイダーの配信保証についての主張ではありません。

テスト期待されるアプリケーション動作
同じイベントを2回送信する1つの論理イベントとして保持し、顧客への重複通知を避ける。
配達後に古い輸送スキャンを送信する有用な履歴を保持しつつ、配達済み状態を自動的に戻さない。
同時に更新を送信する同時実行ワーカーでも一貫した状態遷移を適用する。
永続的な受信前に処理を停止する新しいコールバックを要求せず、保存されたイベントを復旧して処理する。
受信が永続化される前に保存に失敗する受け入れ成功を誤って確認応答しない。
未知の出荷を送信する定義済みの隔離または拒否ポリシーに従い、注文との関連付けを推測しない。

提供されている場合は、重複排除に文書化された安定したイベント識別子を優先します。それ以外の場合は、関連フィールドから慎重に範囲を定めた識別情報を定義し、衝突をテストします。1つの出荷は多くの正当な更新を生成できるため、追跡番号だけではイベント識別子になりません。

イベント履歴と現在の出荷プロジェクションを分離します。履歴スキャンを保持しても、遅れて到着したすべてのスキャンで表示ステータスを上書きする必要はありません。「最新のタイムスタンプを使う」だけでも完全なルールではありません。訂正、返品フロー、異なるタイムスタンプの意味には明示的な処理が必要です。

非同期処理では、アーキテクチャに従い、コミット済みのインボックスレコードや永続キューなど、イベントが永続的な引き渡し地点に到達した後にのみ確認応答します。プロバイダーが文書化した確認応答要件に従います。HTTPはステータスコードの意味を定義しますが、特定の送信元の再試行スケジュールはその契約から取得する必要があります。

制御されたライブチェックを実行し、リリース基準を設定する

決定論的なテストに合格したら、実際の連携を通じて認証済みの出荷を登録し、完全な経路を確認します。プロバイダーが意図したレコードを受け入れたこと、コールバック設定が正しい環境を指していること、受信データが期待される出荷にマッピングされることを確認します。

ライブチェック中にすべての出荷ステータスが表示されることを要求してはいけません。実際の出荷は制御可能なフィクスチャではありません。ライブ実行では接続性と観測された契約互換性を検証し、まれなシナリオや破壊的なシナリオは再生可能なフィクスチャでカバーします。

リリース前に、次の結果を必須とします。

  • APIがバッチ操作をサポートしている場合は項目レベルの失敗を含め、文書化された成功レスポンスとエラーレスポンスが処理される。
  • 最初のリクエストがすでに成功している可能性がある場合、タイムアウトによって盲目的な作成リトライが発生しない。
  • 重複イベントによって重複する業務アクションが作成されない。
  • 不正なコールバックによって出荷状態が変更されない。
  • ワーカーの失敗時にイベントが黙って失われず、復旧可能な状態で残る。
  • 開発トラフィックによって実際の顧客に通知されたり、本番注文が変更されたりしない。
  • シークレットを露出させずに、ログがリクエスト、受信イベント、処理結果、通知試行を関連付ける。

不確実なリクエスト、繰り返されたコールバック、または中断されたワーカーの後にシステムがどのように復旧するかと、通常のワークフローの両方を説明できれば、リリースの準備が整っています。追跡を1回正常に照会できただけでは不十分です。

FAQ

サンドボックスなしで追跡連携をテストできますか。

はい。送信APIの境界をモックし、文書化されたコールバックフィクスチャを再生し、正規化と業務ルールをローカルでテストします。その後、実際の接続性を確認するため、認証済みのライブ出荷を使用します。これにより十分な範囲をカバーできますが、文書化されていないプロバイダーの動作を再現することはできません。

追跡リクエストは成功するのにイベントが返らないのはなぜですか。

リクエストの受け入れと追跡データの可用性は異なる結果です。プロバイダーのレスポンス詳細、登録要件、配送業者の識別ルール、イベントのない出荷に関する文書化された動作を確認します。空のタイムラインを埋めるために、移動や配達の情報を作り出してはいけません。

モックWebhookが成功すれば、実際のWebhookが届くことを証明できますか。

いいえ。モックによって実行された経路だけが証明されます。実際の配信は、プロバイダー設定、公開到達性、TLS、認証、実際のコールバック契約にも依存します。プロバイダーがサポートするテスト配信または認証済みのライブワークフローで検証してください。

処理が完了する前にHTTP 200を返すべきですか。

プロバイダーが文書化した確認応答契約に従います。非同期設計では、永続的に受け入れた後に確認応答し、その後ワーカーで処理します。永続化前に成功を返すと、その直後にプロセスが失敗した場合にイベントを失う可能性があります。

顧客通知はどのようにテストすべきですか。

開発環境の通知はすべて制御されたシンクに送信します。送信先、テンプレート、トリガーとなる遷移、送信回数をアサートします。同じイベントを再生し、ワーカーのリトライをシミュレートして、1つの出荷更新から顧客メッセージが繰り返し生成されないことを確認します。

出典

  • 17TRACK Tracking API — 追跡API製品の公式出発点。
  • 17TRACK API documentation — プロバイダー固有の連携契約のリファレンス。該当するテスト要件とコールバック要件はここで確認してください。
  • RFC 9110: HTTP Semantics — HTTPレスポンスの意味とリクエスト再試行に関する考慮事項。
  • RFC 2104: HMAC — コールバックセキュリティのガイダンスで説明した標準化メッセージ認証構造。