Advanced Integrated Visibility Tracking Number Subscription APIにより、Advanced Integrated Visibilityの登録者は、APIエンドポイントを使用して追跡番号をWebhookプロジェクトに関連付けることができます。追跡番号協会機能は、以下の2つの処理方法をサポートしています。

• 追跡番号の関連付け - 同期処理は、同じHTTPレスポンス内で処理結果を返します。このオプションは、少数の追跡番号を関連付ける際に、即座に確認が必要な用途に最適です。
• 追跡番号の関連付け - 非同期処理は、バックグラウンド処理のためのリクエストを送信し、後で処理状況や結果を取得するために使用できるジョブIDを返送します。このオプションは、大量の追跡番号を一括で処理する場合に最適です。

アプリケーションのパフォーマンスおよびワークロードの要件に最も適した処理方法をお選びください。

注：

• Advanced Integrated Visibilityプロジェクトに対する管理者またはコントリビューターのアクセス権が必要です。
• Advanced Integrated Visibilityおよびその機能の詳細については、Advanced Integrated Visibilityのドキュメントページをご覧ください。

Advanced Integrated Visibility Tracking Number Subscription APIには、次のようなメリットがあります：

• APIエンドポイントを使用すれば、Advanced Integrated VisibilityのWebhookプロジェクトにおける追跡番号の関連付け、更新、管理を簡単に行うことができる
• 各追跡番号を個別に処理するのではなく、1回のAPIリクエストで複数の追跡番号を関連付ける
• 即座に結果が得られる同期処理と、大規模なバッチ処理に適した非同期処理のいずれかを選べる

Advanced Integrated Visibilityプロジェクトを管理するには、以下のエンドポイントを使用してください。

• 追跡番号の関連付け - 同期処理：これにより、追跡番号をWebhookに関連付け、同じHTTPレスポンス内で最終的な処理状況を受け取ることができます。
• 追跡番号の関連付け - 非同期処理：これにより、追跡番号をWebhookに関連付け、返されたjobIdを使用して、後で非同期ジョブのステータスを確認したり、関連するエンドポイントを利用して詳細情報をダウンロードしたりすることができます：
  • 追跡番号のジョブステータス
  • 追跡番号 ジョブの詳細

これらのAPIは、Advanced Integrated Visibilityプロジェクトの概要画面からご利用いただけます。

これらのAPIには、上記のスクリーンショットに示されているように、プロジェクトの概要画面からのみアクセスできます。

以下の表は、同期型および非同期型の追跡番号の関連付けエンドポイントの違いをまとめたものです。
 

少量の追跡番号について、即座に確認が必要な場合は、同期型エンドポイントをご利用ください。即時の応答を必要としない、より大規模なバッチを処理する際は、非同期エンドポイントをご利用ください。

このエンドポイントを使用すると、1つまたは複数の追跡番号を「Advanced Integrated Visibility」のWebhookプロジェクトに関連付け、同じHTTPレスポンス内で処理結果を受け取ることができます。

このエンドポイントは、即時の確認が必要なアプリケーションを対象としており、最大150件の追跡番号を含むリクエストに対応しています。

必要な入力：

• subscriptionID
• trackingNumber

利点

同期エンドポイントには、次のような利点があります。

• 即時処理結果
• 1回の応答で得られる詳細な成功・失敗情報
• 1回のリクエストにつき、最大150件の追跡番号に対応
• 処理の前に、検証とビジネスルールの適用を行う
• 機械で読み取り可能なエラーコードと、具体的なエラーメッセージ
• リクエストの追跡およびトラブルシューティングのためのトランザクションID

追跡番号の関連付け – 同期エンドポイントは、以下を含む複数の検証ルールを適用します。

• 有効かつアクティブな subscriptionId が必要
• 1回のリクエストにつき subscriptionId を1つだけ許可
• trackingNumber の指定が必要
• 追跡番号が、6桁から22桁という最大桁数の制限を含め、FedExの形式要件を満たしていることを確認

エラー応答は一貫した構造になっており、`errors[]` にはコードとメッセージが含まれているため、解析が容易です。

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

トランザクション番号の関連付け – 同期エンドポイントでは、部分的な成功が許容されます。一部の追跡番号でエラーが発生した場合でも、Synchronous API は依然として 200 OK を返し、次のように表示されます。

• failedTrackingNumbers
• 説明的なメッセージ

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Below tracking numbers failed to upload due to validation or system errors"

      }

    }

詳細やルールについては、「ビジネスルール」のセクションをご参照ください。

このエンドポイントを使用して、登録済みの追跡番号を1つ以上送信し、バックグラウンドで処理を行ってください。

このリクエストでは、ジョブIDが返されます。このジョブIDは、追跡番号のジョブステータスエンドポイントを使用して処理状況を監視したり、ジョブ完了後に追跡番号のジョブ詳細エンドポイントを使用して処理結果をダウンロードしたりする際に利用できます。

必要な入力：

• 処理
• 追跡番号の詳細

1回のリクエストで、最大1,000件の追跡番号を関連付けることができます。

利点

非同期エンドポイントには、次のような利点があります。

• 最大1,000件の追跡番号をまとめて一括送信
• 長時間かかるリクエストをバックグラウンドで処理
• ジョブのステータス監視と、処理レポートのダウンロードが可能
• 大規模なワークロードにおけるリクエストのタイムアウトに関する懸念を解消

このエンドポイントを使用して、非同期ジョブ（キューにある1つ以上の連続したリクエスト）のステータス、または送信されたすべてのジョブのステータスを取得します。

このリクエストに必要な入力情報は：

• ジョブID –スステータスを取得する対象のジョブIDを指定してください。

注：このエンドポイントではジョブIDはオプションの入力です。ジョブIDを指定しない場合、送信されたすべてのジョブのステータスが返されます。

このリクエストが正常に完了すると、ジョブID、現在のジョブステータス、およびジョブの作成と完了のタイムスタンプが返送されます。応答には、ジョブの現在のステータスが表示されます。さらに、応答には、ユーザーが確認してトラブルシューティングを行うための成功メッセージ、エラー、または警告も含まれます。

• ジョブステータスが「COMPLETED」と表示されている場合は、すべての追跡番号が検証され、正常に処理されたことを意味します。
  • 「COMPLETED」ステータスは、ステータスは、追跡番号が検証され、正常に処理されたことを意味します。これは、すべての追跡番号が Advanced Integrated Visibilityプロジェクトに正常に追加されたことを意味するものではありません。
  • 複数の追跡番号がある案件については、一部の番号がプロジェクトに関連付けられなかった場合でも、他の番号が正常に関連付けられていれば、ステータスは「完了」とみなすことができます。元の関連付けリクエストに含まれる各追跡番号のステータスを確認するには、バッチレポートをダウンロードしてください。

注：ジョブステータスが「FAILED」と表示されている場合は、さまざまな理由／ハードエラーによりリクエストが処理できなかったことを意味し、ユーザーは再試行する必要があります。

次の表は、ジョブのステータスとそれぞれの説明を示しています。

このエンドポイントを使用して、「COMPLETED」ステータスの非同期ジョブのJSON レポートをダウンロードします。

本リクエストに関連して求められる提供情報とは、以下のものです。

• jobID –スステータスを取得する対象のジョブIDを指定してください。このエンドポイントでは、ジョブIDの指定が必須です。

注：

• 非同期ジョブのレポートは、一度に1つしかダウンロードできません。
• ジョブが「COMPLETED」状態でない場合、レポートをダウンロードしようとするとエラーメッセージが表示されます。

このリクエストの成功応答では、ジョブのレポートがJSON形式で提供されます。

一般的なビジネスルール

• Advanced Integrated Visibilityプロジェクトに関連付けられる追跡番号の総数に制限はない
• Advanced Integrated Visibility プロジェクトに関連付けられた追跡番号は、Webhook への関連付けが正常に完了してから 40 日後に関連付けが解除される
• 荷受人の住所、荷受人の署名、および機密性の高い配達情報などのセキュリティ保護された追跡情報は、Tracking Number Subscription APIでは利用できない

同期エンドポイントのビジネスルール

• 1回のリクエストにつき、最大150件の追跡番号まで
• すべての追跡番号には、同じ subscriptionId を使用する必要がある
• 指定されたAdvanced Integrated VisibilityのWebhookサブスクリプションは、有効かつアクティブな状態である必要がある
• リクエストには30秒のタイムアウトが設定されている

非同期エンドポイントのビジネスルール

• 1回のリクエストにつき、最大1,000件の追跡番号まで
• 非同期リクエストのジョブステータスおよびジョブの詳細は、追跡番号が「Advanced Integrated Visibility」Webhookに正常に関連付けられた後、90日間保持される