API を使用したリソースの要求
自動化とスケーリングのために、 リソース要求 API を使用してプログラムでリソースを要求します。API を使用して、要件の取得、ドキュメントのアップロード、リクエストの送信、ステータス更新の受信、ライフサイクル全体の管理を行います。
前提条件
必要なもの:
- 有効なNTT CPaaSアカウント
- リソースと数字の概要の完了
- リソース要求手順の理解
- HTTP 要求と JSON に精通している
API の概要
リソース要求 API は、英数字の送信者と電話番号のプログラムによる要求をサポートします。ライフサイクル全体を通じて、要件の取得、ドキュメントのアップロード、リクエストの送信、更新の受信、リクエストステータスの管理など、構造化されたワークフローを提供します。
この API により、大規模な自動化が可能になります。リソースリクエストをプラットフォームワークフローに直接統合し、Webhook を介してステータスを追跡し、検証フィードバックにプログラムで応答します。
Numbers API は、購入前に特定の番号を参照または選択する必要がある番号購入ワークフローでも使用できます。リソース要求 API は、要件、ドキュメントのアップロード、ステータスの更新、ライフサイクル管理を含む構造化された要求フローが必要な場合に使用します。
サポートされている要求の種類 [#supported-request-types-api-overview]
リソース要求 API は、それぞれ異なるパラメーター要件を持つ 3 種類の要求をサポートしています。
英数字の送信者登録
ALPHANUMERIC_REGISTRATION
SMSのカスタム送信者名。国コードが必要です。
番号購入
NUMBER_PURCHASE
SMS、Voice、MMS の電話番号。国コード、番号タイプ、および機能が必要です。
RCS 送信者の起動
RCS_SENDER_LAUNCH
RCS 送信者をアクティブ化します。送信者名、国コード、トラフィックの発信元、連絡先の電子メールが必要です。
WhatsApp番号は、リソースリクエストAPIを通じて直接購入されるものではありません。代わりに、この API を通じて標準の仮想ロング番号を購入し、WhatsApp マルチステップ ワークフロー に従って登録し、WhatsApp で使用できるようにします。
この API を介して米国番号 (10DLC またはフリーダイヤル) をリクエストすることは、最初のステップにすぎません。番号の購入が承認されたら、USA Sender Registrationからブランド登録とキャンペーン登録を完了してください。トラフィックを送信する前に登録を完了してください。ショートコードは、API ではなく Web インターフェイスから購入する必要があります。
APIのワークフロー
API を介してリソースを要求するプロセスは、構造化されたエンドポイントのシーケンスに従います。
要件を取得する
リソースタイプのすべてのデータとドキュメント要件を取得します。
ドキュメントをアップロードする
必要書類(該当する場合)を提出してください。
リクエストの送信
必要なすべてのデータを含むリソース要求を送信します。
更新プログラムの受信
Webhook を介してステータスの変更の通知を受け取ります。
更新またはキャンセル
検証のフィードバックに応答するか、必要に応じてキャンセルします。
要求ステータス [#request-statuses-api-workflow]
APIを介してリソース要求を送信すると、検証および処理中に複数のステータスが進行します。
| ステータス | 説明 |
|---|---|
| 「保留中」 | NTT CPaaSでお申し込みいただいております。チームは、追加のデータや最新情報について電子メールで連絡する場合があります。 |
PENDING_REVIEW | 提出後、NTT CPaaSによる審査を待っています。自動検証または手動評価に先行します。 |
AUTOMATIC_VALIDATION | リクエストは自動検証中です (データ形式、フィールド要件、値制限、正規表現への準拠)。 |
IN_REVIEW | この要求は、NTT CPaaSのチームメンバーによって積極的にレビューされ、詳細、コンプライアンス、および完全性が検証されています。 |
IN_PROGRESS | 要求は初期検証に合格し、内部で処理されています。承認、割り当て、またはプロビジョニングが進行中です。 |
UPDATE_REQUESTED | 自動検証により、送信されたデータで問題が検出されました。リクエスタは情報を更新する必要があります。フィードバックは requirementsFeedback 配列を通じて提供されます。 |
UPDATE_REQUESTED_BY_INTERNAL_REVIEWER | NTT CPaaSのレビュアーから、追加情報や修正が求められました。更新が送信されるまで、要求は続行できません。フィードバックは requirementsFeedback 配列を通じて提供されます。 |
| 「完了」 | 要求は正常に処理され、確定しました。リソースを使用する準備ができています。 |
| 「拒否」 | NTT CPaaSは、この要求を拒否しました。更新できません。新しいリクエストを送信する必要があります。 |
| 「キャンセル済み」 | 要求が要求者またはシステムによって取り消されました。 |
UPDATE_REQUESTEDまたはUPDATE_REQUESTED_BY_INTERNAL_REVIEWERステータスの場合は、リソース要求エンドポイントの更新 を使用して修正を送信します。
要件エンドポイントの取得
送信する前に、特定のリソースタイプと国に必要なすべてのデータとドキュメントフィールドを取得します。これにより、必要な情報をすべて事前に収集できるため、検証の失敗が防止されます。
- 要求タイプ (
ALPHANUMERIC_REGISTRATION、NUMBER_PURCHASE、またはRCS_SENDER_LAUNCH) を指定します。 - リソースの種類に必要なパラメーターを指定します。
- API は、必須フィールドのリストとそのデータ型と検証ルールを返します。
考えられる回答:
- 要件は必要ありません (数値): 空のオブジェクトが返されます。この番号には、追加の文書やデータは必要ありません。
- オファーなし (数値): 指定されたパラメーターに適切なオファーがありません (エラー:
RES-NUM-LOOKUP404)。 - 登録なし (英数字の送信者): この国では英数字の登録は利用できません (サポートされていないか、どの国でも送信者が許可されています)。
すべての要求は、構文の正確性、承認と権限、必要なフィールドの存在、フィールド固有のルール (長さ、形式、パターン)、およびコンプライアンス要件について検証されます。
もっと詳しく知るドキュメントのアップロードエンドポイント
リソース要求に添付される必要なドキュメント ファイルを送信します。このエンドポイントは、Get requirements 応答に DOCUMENT 型のフィールドが含まれている場合にのみ使用してください。
- 要件で特定された必須ドキュメント フィールドごとに、ドキュメント ファイルを準備します。
- ファイルを使用して [ドキュメントのアップロード] エンドポイントを呼び出します。
- API はドキュメント ID を返します。
- リソース要求を送信するときに、このドキュメント ID を使用します。
この 2 段階のプロセス (最初にアップロードし、次にリクエストで参照) により、ドキュメントが適切に保存され、リクエストにリンクされます。
もっと詳しく知るリソース要求エンドポイントの送信
要件を収集し、ファイルをアップロードした後、必要なすべてのデータとドキュメントを添えてリソース要求を送信します。
提出する前に:
- すべての要件を収集し、必要な書類をアップロードした後にのみ提出してください。
- 一部の番号は追加のデータを必要としません。常に最初に Get requirements を呼び出します。
- 送信には、リソースの種類によっては料金が発生する場合があります。
もっと詳しく知る更新の受信 Webhook
ステータス更新 Webhook をサブスクライブすると、API をポーリングする代わりに、リクエストのステータスが変更されたときに通知されます。リクエストのステータスが変更されると、Webhook は新しいステータス (COMPLETED、REJECTED、UPDATE_REQUESTED など) を指定するイベントを配信します。
これにより、次のことが可能になります。
- リクエストの進行状況をリアルタイムで監視
- ステータスが変化したときにアクションを自動的にトリガーする
- プッシュ通知を受信してポーリングのオーバーヘッドを削減
リソース要求エンドポイントの更新
検証に失敗した場合、またはNTT CPaaSが明確化を要求した場合に、修正または追加情報を送信します。このエンドポイントは、自動検証で送信されたデータに問題が検出された場合 (UPDATE_REQUESTEDステータス)、または NTT CPaaS レビュアーが追加情報を要求した場合 (UPDATE_REQUESTED_BY_INTERNAL_REVIEWERステータス) に使用します。
- Get resource requests を呼び出して、
requirementsFeedback配列内の検証フィードバックを取得します。 - フィードバックに基づいて問題のあるフィールドを更新します。
- 要求識別子と修正されたデータを使用して Update resource request を呼び出します。
- 要求は、検証およびレビューのプロセスに再入ります。
代替: 英数字の送信者リクエストの場合のみ、Web インターフェイスの [マイリクエスト] ページから直接編集することもできます。
リソース要求エンドポイントのキャンセル
リソース要求は、完了前にいつでも取り消してください。
- 要求識別子を使用して Cancel resource request を呼び出します。
- 要求の状態が
CANCELEDに変わります。 - 要求は処理キューから削除されます。
代替: 英数字の送信者と番号の購入の両方について、Web インターフェイスからキャンセルすることもできます。
もっと詳しく知る