プレフィックスを指定して電話番号を注文する

プレフィックスから注文する

プレフィックスカタログで、購入可能な番号を個別に選ぶのではなく、プレフィックスと数量を指定して注文するよう案内されている場合に、この操作を使用します。まず、国、地域または州、およびプレフィックスを確認してください。プレフィックス識別子と料金プランは、同じ最新の取得結果から保持してください。購入可能な番号の一覧から選んだ特定の番号を購入する場合は、「選択した電話番号を購入する」を使用してください。

このリクエストによって番号が購入され、料金が発生する可能性があります。料金の見積もり、予約、試行実行ではありません。送信前に、初期費用と月額料金、着信の分単価、含まれる通話分数、チャネル数、登録要件、およびアカウントの購入制限を確認してください。カタログの取得結果によって在庫が確保されたり、料金が固定されたりすることはありません。注文の履行前にアカウントへの入金に関するチェックが行われる場合があります。エラーが返されたというだけでは、購入もアカウントへの入金も行われなかったことの証明にはなりません。

購入リクエストを送信する

有効化されたAPIアカウントを使用し、許可された送信元IPアドレスからHTTPSで接続してください。現在のカタログでの選択内容と、承認済みの着信・メッセージ配信設定に基づいて変数を設定してください。次のコマンドは番号を一件購入します。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

上記はフォーム形式のPOSTです。調整処理は、Content-Typeがapplication/jsonの場合、JSONオブジェクトも読み取ります。JSONフィールドは、対応するフォーム／リクエストのフィールドを上書きします。エンコード方式は一貫して単一の方式を使用し、クエリと本文に矛盾する値を送信しないでください。

着信・メッセージ配信と更新の設定

ポータルでその番号に使用するものと同じ着信・メッセージ配信設定を選択してください。これらは詳細設定の値であり、ホステッドPBXや着信用トランクを作成するための指示ではありません。動作が確認されているアカウント設定を再利用し、購入後に保存された番号の設定を確認してください。購入が受け付けられたというだけでは、音声やSMSが正しく届くことは確認できません。

これらのフィールドは正規化されて購入処理に渡されますが、保存のされ方は在庫の処理経路によって異なります。現在の注文ルートでは、選択した番号の購入ガイドにある厳密な見積もり上限フィールドを、同等の保護手段として利用することはできません。アカウントの購入権限と料金制限を使用し、処理後の番号設定を確認してください。

結果全体を確認する

HTTPリクエストが成功した場合でも、JSON本文を解析してstatus.codeとstatus.msgを確認してください。このルートは独自にJSONレスポンスを出力し、共通のレスポンスヘルパーも、アプリケーションコードを必ずしもHTTPステータスに対応付けるわけではありません。アプリケーションコードはJSONの数値または数値文字列の場合があります。status.resultsの存在を必須としないでください。通常の注文結果には含まれません。

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

上記の識別子、番号、料金は架空のものです。注文IDは内部構造を解釈せずに扱ってください。numbersには、このレスポンスが購入済みとして報告する番号が一覧で含まれます。その件数をリクエストした数量と比較してください。金額は文字列で、このレスポンスではper_minuteを含む料金が小数点以下二桁に丸められます。元の精度の料金は最新のカタログで確認してください。含まれる通話分数とチャネル数は、数値または数値文字列として返される場合があります。

料金ブロックは、レスポンスの作成に使用された選択済みプランを示すものであり、各番号の詳細な請求明細や注文の合計額ではありません。複数の在庫候補に異なるプランが設定されている場合があります。このブロックの金額に数量を掛けて最終合計額が確定したと考えるのではなく、購入した個々の番号とアカウントの取引履歴を照合してください。

一部のみの購入と結果が不確かな場合

アプリケーションコードが200でも、警告が付いたり、購入された番号がリクエストした数量より少なかったりする場合があります。後続の処理が失敗しても、すでに購入された番号は取り消されません。返された注文ID、番号、メッセージを保存してください。残りの数量を注文するか判断する前に、それらの番号を保有番号一覧およびアカウントの取引履歴と照合してください。

送信後のタイムアウト、接続切断、不正な形式のレスポンス、エラーは、何も起きなかったことの証拠にはなりません。同じ参照値を使用する場合でも、購入リクエストを自動的に再送信しないでください。元のリクエスト、参照値、返された注文IDがあればそのIDを保存し、保有番号一覧とアカウントの取引履歴を確認してください。それでも結果が不明な場合は、サポートに問い合わせてください。

未確定の注文では、確認処理中であることを示す文言とともにアプリケーションコード400が返される場合があります。返された注文IDを保存し、その購入内容を照合してください。これは再送信を指示するものではありません。記録済み注文の復旧処理は、元の注文を内部で追跡します。この操作への新たなリクエストは、参照値に基づいて注文を再開するのではなく、別の購入試行を作成するため、追加の番号が購入され、課金される可能性があります。ステータスの確認や在庫の検索のために、購入リクエストを繰り返さないでください。

登録と利用開始

購入済みまたは割り当て済みの番号でも、登録や利用開始の手続きが必要な場合があります。needs_registrationが1の場合は、restrictionsとregistration_requirementsを確認してください。後者には、次のAPIが示される場合があります：v3/get_requirements（countryとnumber_typeの値を伴います）。着信やメッセージの受信に利用する前に、該当する本人確認・住所確認の手続きを完了し、番号のステータスを確認してください。

featuresは提供機能として案内されている内容を示します。実際のルーティング、キャンペーンの承認、SMSの配信、FAXの受信を確認するものではありません。保存された着信・メッセージ配信設定を確認し、番号が利用可能になった時点で適切なサービステストを実施してください。

注文のコールバック

コールバックでは、注文のステータスとレスポンスを含むJSONがPOSTで送信されます。参照値を指定した場合は、それも追加されます。一部のみの結果を含め、購入が報告された場合に送信されます。コールバックが失敗しても、購入は取り消されません。配信が再試行される場合があるため、注文IDを使って重複を処理し、別の購入を行うのではなく番号を照合してください。

このルートは、コールバックに暗号学的な署名を追加しません。コールバックは、認証済みの保有番号情報と照合するための通知として扱い、課金、サービスの設定、アクセス権の付与を単独で承認するものとして扱わないでください。コールバックURLにAPI認証情報を含めないでください。異なるコールバックURLで別の購入リクエストを送信しても、元の注文は更新されず、別の購入試行が作成されます。サポートにコールバックの調査を依頼する際は、元の注文IDを保持してください。

対処が必要な失敗