メッセージング登録用カタログの取得

登録フォームを作成する前に選択肢を取得する

レジストリの値をハードコードせず、最新のメッセージング登録用カタログを使って選択肢を設定してください。ブランドのフォームでは、ポータルは事業形態、業種、代替事業識別子の種類、ブランドとの関係、国、米国の州、証券取引所のカタログを取得します。キャンペーンのフォームでは、用途、有効なサブ用途、接続パートナーを取得します。返された機械処理用の値は、それぞれの表示ラベルと組み合わせて保持してください。後でリクエストを作成する際は、翻訳されたラベルではなく、その値を使ってください。

カタログを選ぶ

ポータルで使用するカタログ
名前	目的
usecase	キャンペーンの用途の定義です。サブ用途の選択肢を取得する場合は、validSubUsecase=trueを追加してください。
entityType	ブランドの事業形態または組織種別です。
vertical	ブランドの業種の選択肢です。
altBusinessIdType	代替事業識別子の区分です。
brandRelationship	登録フォームで使用する関係性の選択肢です。
country	レジストリに登録する国の選択肢です。電話番号を利用できる国の一覧とは別です。
usState	登録住所に使用する米国の州の選択肢です。
stockExchange	ブランドの事業形態に応じて指定が必要となる証券取引所の選択肢です。
cnp	接続パートナーの識別子です。アカウントのキャンペーン処理フローでサポートされているパートナーを選んでください。

TCRのレスポンスを直接処理する

レスポンス本文は、TCR APIが直接返すものです。従来の多くの /v3 エンドポイントとは異なり、追加の status/response ラッパーはありません。本文を解釈する前に、HTTPステータスを確認してください。カタログには文字列のラベルや構造化された定義が含まれることがあるため、すべての値が同じフィールドを持つと想定しないでください。HTTPリクエストが成功しても、本文が想定した構造の有効なJSONでない場合は、黙って空のリストに置き換えず、取得の失敗を報告してください。

カタログの選択肢と適格性・料金を区別する

一般的な用途カタログから、個々のブランドがどの用途の適格性を満たすかを判断することはできません。現在のポータルは、キャンペーンの作成前にブランド固有の適格性を照会し、選択した通信事業者の要件を確認します。同様に、供給元の手数料メタデータは、そのアカウントに適用される最終的な顧客向け料金ではありません。適用されるアカウント料金と登録条件を別途確認してください。カタログを取得しても、ブランド、キャンペーン、メッセージング用電話番号が承認されるわけではありません。

カタログを取得できない場合に対処する

取得に失敗した場合も、顧客がフォームに入力した内容を保持してください。エラーを表示し、次のヘッダーが返された場合はその指定に従ってください：Retry-After。また、再試行の待機時間を段階的に延ばしてください。すべてのカタログを繰り返し再取得したり、レート制限エラーや通信エラーを有効な空のカタログとして扱ったりしないでください。このGETには冪等性キーは不要で、更新処理用の冪等性ストアから再実行されることもありません。

リクエスト

許可された送信元IPアドレスから、HTTPS経由で有効なAPIアカウントを使用してください。現在のルートは、Basic認証や、有効化されたベアラートークン認証のAPIアカウントを含む、アカウントの認証ポリシーに対応しています。プロバイダーの認証情報は使用しないでください。

パスにサポート対象のカタログ名を指定してGETを実行してください。適用するカタログフィルターはクエリ文字列で渡します。リクエスト本文は不要です。

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

パスパラメーター
名前	型	必須	説明
`type`	文字列	はい	元の大文字・小文字を維持したカタログ名です。ポータルでは、usecase、entityType、vertical、altBusinessIdType、brandRelationship、country、usState、stockExchange、cnpを使用します。これらはカタログ名であり、ブランドやキャンペーンの識別子ではありません。

クエリパラメーター
名前	型	必須	説明
`validSubUsecase`	真偽値	いいえ	usecaseカタログでは、ポータルは有効なサブ用途の選択肢を取得するためにtrueを指定してリクエストします。通常の用途カタログを取得する場合は、このパラメーターを省略してください。利用可否と定義はレジストリから提供されます。

レスポンス

このTCRルートは、レジストリの本文をそのHTTPステータスとともに直接返します。従来のv3のstatus.code/status.msg/responseエンベロープは使用しません。カタログの構造は一様ではなく、値を説明用のオブジェクトに対応付けるものもあれば、文字列に対応付けるものもあります。後でフォームを送信する際は、機械可読なキーを維持してください。簡略化した架空のusecaseの例は、オブジェクトを値に持つマップを示すものであり、実際のカタログや、完全性を保証するスキーマではありません。HTTPステータスと、想定したJSONの構造の両方を確認してください。

レスポンス構造の説明用の例です。実際のアカウントデータや現在の見積もりではありません。

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

エラー

401: アカウント認証に失敗しました。APIの認証情報、有効化状態、適用される送信元IP制限を確認してください。
400/404およびその他のレジストリエラー：カタログまたはフィルターが無効か、利用できません。現在のルートは、上流のHTTPステータスとレスポンス本文をそのまま保持します。共通のv3エラーエンベロープはありません。
429: アカウントのリクエスト上限、またはプロバイダーの共有リクエスト上限に達しました。Retry-Afterに従い、待機時間を段階的に延ばして再試行してください。
502: レジストリに接続できませんでした。利用可否は不明です。成功結果として空の選択肢を代わりに返さないでください。
503: リクエスト制限機構または上流サービスを利用できません。再試行する前に、本文と、返されている場合はRetry-Afterヘッダーを確認してください。

利用可否と副作用

レビュー済みの処理経路では、このカタログのGETは、ブランドやキャンペーンの作成、登録の送信、リソースの予約、登録料の課金を行いません。プロバイダーに接続し、リクエストの監査記録を書き込みます。
カタログの定義や供給元の手数料メタデータは、顧客向け料金の見積もりではありません。現在のポータルは、顧客向けのキャンペーン料金を別途取得します。従来のgetCampaignPriceヘルパーや古い列挙値の料金注釈を、このルートの料金仕様として扱ってはいけません。
カタログにサポート対象の項目があることは、特定のブランドがその用途の適格性を満たす証拠にはなりません。後で登録リクエストを行う前に、ブランド固有の適格性確認、申告、同意、およびアカウント料金の確認を完了してください。