選択した電話番号を購入する

番号と料金をセットで選ぶ

最新の購入可能番号の検索結果から選んだ、特定の番号を一つ購入します。選択した項目の info.uuid を番号IDとし、同じ項目にある price[].uuid の値のいずれかを料金IDとして使用します。このルートでは保存済みの完全な番号も指定できますが、国、地域、プレフィックスのIDで番号の選択を代替することはできません。

検索や保存済み料金の参照によって、番号が予約されたり料金が固定されたりすることはありません。選択した初期費用、月額料金、着信の分単価、含まれる通話分数とチャネル数に加え、アカウントの購入権限と登録要件を確認してください。レビュー対象のヘルパーでは、初回の基本金額は初期費用と月額料金の合計です。選択したプランについて、プロバイダー固有のすべての料金と条件を確認する必要があります。

ガード付きの購入リクエストを POST で送信する

有効なAPIアカウントを使用し、許可された送信元IPアドレスからHTTPSでアクセスしてください。次のコマンドは購入を実行するものであり、見積もりや試行実行ではありません。すべての変数には、同じ最新の番号と料金の選択結果に基づく値を設定してください。上限フィールドには従来の restore_quote_ プレフィックスが引き続き使用されています。現在のポータルでも、特定の番号をガード付きで購入する際にこれらのフィールドを使用します。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "restore_quote_price_id=$PRICE_ID" \
  --data-urlencode "restore_quote_setup=$SETUP_PRICE" \
  --data-urlencode "restore_quote_monthly=$MONTHLY_PRICE" \
  --data-urlencode "restore_quote_per_minute=$PER_MINUTE_PRICE" \
  --data-urlencode "restore_quote_channels=$CHANNELS" \
  "https://api.multitel.net/v3/rentnumber/$NUMBER_ID/$PRICE_ID"

例に示すとおり、フォーム形式の POST を使用してください。ヘルパーはJSONやオプションラッパーの解析にも対応していますが、見積もりとプロバイダーに関するすべての処理経路で完全に同等に動作することは、このレビューでは確認されていません。この従来のコーディネーターには明示的なメソッド制限がありませんが、購入に GET を使用しないでください。

見積もり料金IDを指定する場合は、数値の見積もりフィールドをすべて指定してください。IDの変更、上限を超える料金、上限の欠落または無効な値、チャネル数の変更、見積もりロックの使用中のいずれかに該当すると、選択した番号貸与プロバイダーへの処理依頼前にAPIコード409が返されます。比較では浮動小数点数のわずかな誤差が許容されます。手作業で丸めた料金ではなく、実際に表示されたプランの値を使用してください。

これらのガードによって、ワークフロー全体が試行実行やトランザクションになるわけではありません。これらのチェックの前に、登録情報の検索、本人情報のプロビジョニング、その他のヘルパー処理が行われる場合があります。また、外部の番号在庫を固定したり、アカウント単位の購入制限を代替したりするものでもありません。

登録と開通

必要な場合は、RegistrationID フォームフィールドを追加し、顧客が所有する登録プロフィールのUUIDを指定してください。アップロードした証明書類、供給元の住所、別個の本人情報エンティティのIDではありません。ヘルパーは認証済みアカウントに照らしてプロフィールを解決し、プロフィールが存在しない場合や利用できない場合は拒否します。

対応する番号在庫の中には、登録完了前に購入できるものもあれば、購入前にプロフィールが必要なものもあります。通信事業者固有の検証やプロビジョニングが引き続き必要な場合もあります。購入の成功や事前チェックの省略を、登録の免除や即時開通を意味するものと解釈しないでください。

レスポンスに含まれる場合、registration_requirements は、国と番号種別による構造化された要件の照会先を示します。登録カタログと証明書類の手続きを使用して、該当する要件を満たしてください。返されたテキストやメタデータ自体がプロフィールを承認するわけではありません。

知らないうちにプランが置き換わるのを防ぐ

従来のコーディネーターは、省略された料金をキャッシュ済みの番号データから推定できます。また、明示的に指定された料金IDが存在しなくなっている場合、キャッシュ済みプレフィックスに対する最新のアカウント料金にフォールバックし、キャッシュ内の許可された料金の選択内容を更新することがあります。顧客が承認したプランを選択するために、これらのフォールバックに頼らないでください。

選択した料金を明示的に指定し、それに一致する見積もりガードのフィールドを送信してください。見積もりIDのガードは、番号貸与の処理依頼前に別のIDへのフォールバックを拒否します。古くなった料金による競合が発生したら、ガードを外して購入を強行するのではなく、再検索して選択内容の承認を改めて得てください。

すべての処理経路で保証される予約期間や、一律に適用されるキャッシュの有効期間はありません。ワークフロー内で番号の購入可否、アカウントの料金制限、購入ポリシーが再確認されますが、プロバイダー固有の動作全体については引き続きレビュー中です。

詳細設定：アカウントのルーティング既定値

購入時には、アカウントの既存の音声宛先、フェイルオーバー先、SMS宛先、オリジネーショントランクの優先設定が引き継がれる場合があります。注文前にこれらの既定値を確認してください。ルーティングオプションを省略しても、未設定の番号になるとは限りません。レビュー対象のヘルパーでは、自動更新が既定で有効になります。

これらは共通ヘルパーの動作上の意味を示すものであり、すべての供給元がすべての任意設定を同じように保存することを保証するものではありません。ほかにも従来の音声、留守番電話、FAX、SMS用のフィールドがありますが、プロバイダーごとの全面的なレビューが引き続き必要です。通話やメッセージの利用を前提とする前に、アカウントの手順を通じて購入した番号の保存済み設定を確認してください。

レスポンス

複雑な条件のない購入を想定した架空の例です。値と機能は選択したプランによって異なります。

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "price": {
      "per_minute": "0.0100",
      "free_minutes": "100",
      "setup_price": "2.00",
      "monthly_price": "4.00",
      "channels": "2",
      "overflow": "0"
    },
    "features": [
      "voice"
    ],
    "needs_registration": 0,
    "registration_requirements": null
  }
}

コーディネーターは独自の status.code/status.msg と response エンベロープを使用しますが、status.results フィールドが含まれる保証はありません。エラー時のレスポンスリストは通常空です。成功した場合は、返された番号と料金を確認してから、アカウントの番号在庫と登録状態を照合してください。プロバイダーによる受け付けは、実際の音声、SMS、FAXの動作テストではありません。

エラーと結果が不確かな場合

HTTPステータスに加えて、実際のAPIレスポンス本文も確認してください。ローカルの通知、登録、その他の処理が失敗する前に、外部プロバイダーが番号貸与を受け付けている場合があります。一部のローカル番号在庫の割り当てではデータベーストランザクションを使用しますが、外部プロバイダーへの注文を一律にロールバックする仕組みはありません。このコーディネーターには、クライアント用の冪等性キーはありません。

再試行する前に照合する

1. 一度だけ送信する前に、承認済みの番号、料金、見積もり上限をアプリケーションの注文記録に保存してください。
2. リクエスト後は、タイムアウトやエラーが発生した場合も含め、同じアカウントの購入済み番号一覧と番号の詳細を参照してください。
3. 番号が存在する場合は、購入リクエストを再送するのではなく、その料金、更新、ルーティング、登録状態を確認してください。
4. 結果が依然として不確かな場合は、再試行する前に、サポートにプロバイダーへの注文とアカウントの請求を照合してもらってください。エラーメッセージや従来のログの成功フラグだけでは、十分な証拠になりません。
5. 所有状況と開通を確認したら、アカウントの通常のルーティング確認とサービステストを完了してください。