電話番号の登録プロファイルを送信する

保存済みのプロファイルと電話番号を準備する

この手順では、保存済みの登録プロファイルを購入済みの電話番号に関連付け、通信事業者による登録審査に対応している番号については審査を依頼します。すべての番号提供事業者に対応した汎用の開通APIではありません。リクエストが成功しても、書類が承認されたことや番号が開通したことの証明にはなりません。

有効なMultiTEL APIアカウントを使用し、そのアカウントに設定されている認証情報とIP制限に従ってHTTPSで接続してください。削除されていないプロファイルと、購入済みかつ無効化されていない電話番号の両方が、ご自身のアカウントに属している必要があります。

新しく登録プロファイルを作成するか、既存のものを選択してください。ローカルプロファイルのuuidはcreate_documentから取得し、保存しておいてください。get_documentは、同じローカル参照値をidとして返します。
通信事業者への審査依頼には、プロファイルに保存済みの本人情報と住所の参照値が必要です。必要な証明書類と補足書類を、それぞれに適した手順で送信前に添付してください。
電話番号とプロファイルが、該当する国および番号の要件を満たしていることを確認してください。保存済みのプロファイルがすべての番号で承認済みであるとは考えないでください。

関連付けのリクエストを送信する

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

パスには、購入済みの電話番号を指定します。そのUUID、PBXの内線番号、本人情報のIDを指定するものではありません。ハンドラーは番号から数字以外の文字を取り除きます。国番号を含む完全な国際電話番号を使用してください。この例は架空のものであり、ご自身の電話番号と保存済みのローカルプロファイル参照値に置き換える必要があります。

登録リクエストのフィールド
フィールド	必須	説明
`document_uuid`	はい	保存済みのローカルプロファイルの正確なuuidです。マスクされたリモートのidentity_id、address_id、アップロードID、または返されたregistration_details_idの値で代用しないでください。
`service_description`	いいえ	利用予定のサービスの説明です。通信事業者による確認のために転送されます。先頭と末尾の空白は取り除かれます。
`onetime_files`	手順による	通信事業者に提出する一回限りの書類用に受け付ける配列です。現在のハンドラーは、ローカルのアップロード参照値を解決せずに、配列内の文字列の前後の空白を取り除いて転送します。create_encrypt_filesが返すマスクされたIDとの互換性は確認されていません。このフィールドを使用する前に、後述の一回限りの書類に関する制限を確認してください。

マルチパートリクエストでは、onetime_files[]フィールドを繰り返して配列を指定します。Content-Type: application/jsonを指定したJSONリクエストも受け付けられ、そのプロパティはフォームのペイロードに統合されます。パス内の番号を省略した場合は、ペイロードにnumberを指定できます。曖昧さを避けるため、上記のようにパスで明示する方法を推奨します。

関連付けと承認を区別する

HTTPの結果とJSONのstatus.codeの両方を確認してください。HTTP 200でもJSONでエラーが返されることがあります。通信事業者への審査依頼が成功すると、Address verification task created; awaiting carrier review.というメッセージが返されます。この例では架空の参照値を使用しています。

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

事業者関連の識別子はマスクされた参照値であり、ローカルプロファイルIDと相互に置き換えることはできません。document_uuidは、送信したローカルプロファイル参照値のままです。このハンドラーで通信事業者への処理を行う経路では、registration_details_idはそのローカル参照値をさらにハッシュ化した値です。以後のプロファイル関連リクエストや送信リクエストで、document_uuidをこの値に置き換えないでください。

割り当て済みの番号の中には、通信事業者による確認処理を作成する代わりに、ローカルで本人情報を関連付けるものがあります。その場合、成功時にはIdentity associated.が返され、responseは空の配列になります。通信事業者の審査タスクは作成されず、承認済みであることも意味しません。ポータルには、このエンドポイントとは事業者の処理方法や再送信のチェックが異なる、より新しい関連付け手順があります。

タスクを重複作成せずにエラーに対処する

APIコード400は、番号またはプロファイル参照値が指定されていない場合に返されます。コード404は、そのアカウントでプロファイルや番号を利用できない場合、または通信事業者の番号在庫に番号が存在しない場合に返されます。コード422では、本人情報や住所の参照値の不足、販売者の要件、通信事業者による検証の拒否が報告されることがあります。コールバック設定がない場合は503、作成時の通信障害では502が返されることがあります。すべての失敗に同じ対応をするのではなく、メッセージと、requirement_diagnosticsがあればその内容を確認してください。

通信事業者への処理を行う経路では、要件の検証、コールバック設定の確認、タスクの作成が完了する前に、ローカルの登録保留フラグが更新されることがあります。そのため、エラーが発生してもローカル状態が変わっていないとは限らず、保留フラグだけではタスクの存在を証明できません。これらのフラグを、承認やリクエストの到達を確認する根拠にしないでください。

後続のローカルデータベース操作が失敗しても、事業者がタスクを受け付けている可能性があります。また、このヘルパーは、成功を報告する前にすべてのローカル書き込み結果を確認するわけではありません。このハンドラーには、クライアント側の冪等性パラメーターも重複送信を防ぐ仕組みもありません。タイムアウト、エラー、結果が不確かな場合は、再送信する前にポータルでその番号の登録履歴を確認するか、サポートにお問い合わせください。ローカルに記録がないというだけでは、事業者が何も受信していないことの証明にはなりません。

一回限りの書類に関する制限

ハンドラーはonetime_filesを受け付け、空でない各文字列を通信事業者の暗号化ファイルの関連付け先に転送します。所有元アカウントのアップロードレコードを検索したり、外部向けのマスクされたアップロードIDを事業者のファイルIDに変換したりすることはありません。オフライン監査で確認したのは転送の動作であり、通信事業者側で添付が成功することではありません。

create_encrypt_filesのファイルIDをこのフィールドにコピーすれば、一回限りの同意書の手続きを完了できるとは考えないでください。番号にこれらの書類が必要な場合は、ポータルを使用するか、対応している識別子の取り扱い手順をMultiTELに確認してください。この点はAPIレビューで未解決のままであり、最初から最後まで動作を確認した例ではありません。

登録情報を保護する

その番号に使用する権限がある情報と書類だけを送信してください。プロファイルと確認処理の参照値は正しいアカウントに関連付けたまま管理し、登録ペイロード全体をログに記録しないでください。このリクエストによって、それ以前の証明書類や確認処理がすべて削除または置換されるわけではありません。通信事業者による審査、開通、保管はそれぞれ別のプロセスです。