個別のプレフィックスを選択する
国とエリアを取得するAPIを呼び出し、続いて getprefixes をグループ化せずに呼び出します。選択したプレフィックスの uuid をコピーします。returns_numbers が 0 の場合、そのプレフィックスでは注文時に番号が割り当てられます。個々の番号の一覧を必須とせず、返された next_function を使用してください。
件数を限定して結果を閲覧する
通常の検索では compact=1 を使用し、以下の例のように、希望する取得件数をパスと quantity クエリの両方に指定します。ページやカーソルを指定するパラメーターはありません。コンパクト形式の結果はサンプルです。同じリクエストを繰り返しても、前の結果と重複しない次のページが得られるとは限りません。結果が空、または少数であっても、それを在庫の総件数と解釈しないでください。
覚えやすい数字のパターンを探す
次のいずれかを指定します：number_filter_mode=contains または ends_with。併せて number_filter_value を指定してください。値は 1–15 桁の数字である必要があります。検索では、フィルターを適用する前に件数を限定した候補を取得する場合があるため、条件に一致する他の在庫が見つからないことがあります。対応する供給元で必要な検索を確実に適用する必要がある場合は、pid セレクターをMultiTELから取得し、filter_required=1 を使用してください。供給元の指定がない場合、または指定した供給元が非対応の場合は、APIエラーが返されます。
選択した番号を確認する
同じ検索結果から、number、info.uuid、選択した price[].uuid、利用可能な機能名、および登録要件を確認します。price 配列には、チャネル数や料金が異なる複数のプランが含まれる場合があります。金額フィールドや数量が文字列としてエンコードされる場合があります。info.state を含む任意のメタデータは供給元によって異なります。stateの形式がすべて共通であることを前提としたり、IDから料金を推測したりしないでください。
ストリーミングを使用しない処理では、候補の重複を除去し、供給元間で取得枠を割り当てた後、選択された一群の結果を最初のプランの月額料金で並べ替えます。他の処理では、それより早い段階でストリーミングを開始する場合があるため、すべてのリクエストで結果全体の並び順や重複の除去が保証されるわけではありません。また、並べ替えられていても、返されたサンプルにカタログ全体で最も安い番号が含まれていることを示すものではありません。
別途注文し、結果を確認する
検索では購入も予約も行われません。同じアカウントで注文手続きを行うために、返された番号とプランの識別子を保存してください。注文を送信する前に、実際のプラン、要件、および料金を確認してください。登録要件によって利用開始が遅れる場合があります。検索結果によって一定の利用開始期限が確定することはありません。
リクエスト
有効なMultiTEL APIアカウントを使用してください。パスワード方式のアカウントではHTTP Basic認証の認証情報を、トークン方式のアカウントでは Authorization: Bearer を使用します。アカウントの権限とIP制限が適用されます。共通の認証ガイドを参照してください。
パスパラメーターとURLクエリパラメーターを使用します。公開の検索手順では GET を使用してください。ハンドラーは一部のフォーム値やリクエスト値も受け付けますが、JSON本文を使う検索APIではありません。
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
prefix_id | string | はい | グループ化されていない getprefixes レスポンスで返された個別のプレフィックスIDです。そのまま正確にコピーしてください。国、エリア、グループ化されたプレフィックス、または料金プランのIDで代用しないでください。 |
quantity | integer | いいえ | 取得目標件数で、既定値は 1 です。正でない値は 1 になります。パスの quantity だけでは、結果全体の件数を確実に制限できません。供給元を固定せず、quantity クエリも指定しない検索では、取得範囲が広がり、他の処理を行う前に供給元ごとに最大 50 件が返される場合があります。通常、件数を限定して閲覧する場合は、例のように compact=1 を使用し、希望する件数をクエリにも指定してください。 |
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
quantity | integer | いいえ | 最終的に返す希望件数です。空でない値は整数に変換され、最小値は 1 となります。供給元を固定せず、ストリーミングを使用しない処理では、これによって最終的な割り当て件数が制限されます。サービスが必ずその件数の番号を見つけることを保証するものではありません。供給元を固定したコンパクト検索では、この制限ではなく、その供給元のコンパクト形式の一群の結果が返される場合があります。 |
compact | string | いいえ | 1、true、または on を指定すると、ストリーミングを使用しない小さなレスポンスになり、最終的な割り当て前の件数は供給元ごとに最大 10 件となります。結果はその時点で取得された在庫のサンプルであり、カタログ全体ではありません。 |
number_filter_mode | string | いいえ | 任意の数字パターン指定モードです。contains または ends_with を指定します。number_filter_value も指定してください。正規化された電話番号の数字に対して結果を照合します。検索では在庫をすべて列挙するわけではなく、該当し得る番号がすべて見つかることは保証されません。 |
number_filter_value | string | いいえ | 1 桁以上 15 桁以下の数字で指定し、空白、+、句読点などの記号は含めないでください。先頭のゼロにも意味があるため、テキストとして送信してください。 |
filter_required | string | いいえ | 詳細設定：1、true、yes、または on を指定する場合、そのフィルターモードに対応する在庫供給元を明示的に選択する必要があります。それ以外の場合、APIは status.code に 422 を返します。通常のカタログ閲覧では不要です。 |
pid | string | いいえ | MultiTELが提供する詳細設定用の在庫セレクターです。数値形式と、対応している 32 文字の十六進数形式を受け付けます。認識されない値は通知なく無視されます。通常の利用では省略してください。料金IDからセレクターを導き出したり、任意のセレクターを指定すれば在庫がその対象のみに制限されると考えたりしないでください。 |
レスポンス
status と response を含む単一のJSONオブジェクトです。成功時は status.code が 200 となり、response は番号エントリの配列になります。status.results は返された配列の件数です。status.msg は Results: N、ストリーミングレスポンスの場合は OK となることがあります。compact=1 を指定しない場合、一部の検索では response 配列を段階的に書き込み、最後に status を出力するため、JSON本文全体の受信を待ってください。これは改行区切りのJSONではありません。HTTP通信が成功していても status.code を確認してください。代表的なフィールドを以下に示します。供給元固有のメタデータや任意のフィールドは異なります。すべての識別子を、その内容に意味を見いださずに扱い、番号と、その番号で選択した price[].uuid を一緒に保存してください。
レスポンス構造を示す例です。実際のアカウントデータや現在の見積もりではありません。
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}エラー
- 401：認証に失敗しました。認証情報が無効または未指定の場合や、APIアカウントのアクセスが拒否された場合、検索結果は返されません。
- 404：Invalid prefix ID、Invalid country、Invalid area、または No numbers found。status.msg を確認してください。エラーレスポンスは番号の配列ではありません。
- 400：NUMBER_FILTER_INVALID が response.code に返されます。モードが無効、値が 1–15 桁の数字ではない、またはモードと値の両方を指定せずに filter_required を指定した場合です。
- 422：NUMBER_FILTER_UNSUPPORTED が response.code に返されます。プレフィックスが注文時に番号を割り当てる場合（reason=order_only_prefix となり、next_function が注文先のルートを示します）、または明示的に指定した供給元が必須のフィルターに対応できない場合です。
在庫状況と副作用
- このハンドラーは検索と見積もりの作成を行います。番号の注文を送信したり、番号購入代金を引き落としたりすることはありません。カタログのキャッシュの更新、キャッシュ内の古い在庫の削除、アカウント単位の料金プランの保存、および検索ログの書き込みを行う場合があります。
- 在庫状況は特定の時点での結果であり、予約ではありません。その後の注文が失敗したり、異なる在庫状況が返されたりする場合があります。購入を再試行する前に、注文結果を照合して確認してください。
- 料金はアカウントごとに異なります。同じアカウントで使用するために選択したプランIDを保存し、注文条件と料金は別途確認してください。このエンドポイントだけでは、その後の注文時まで料金が有効であり続けることは確認できません。
- 例にある番号と料金は、レスポンス構造を示すための架空のものであり、実際の見積もりではありません。対応機能、チャネル数、契約期間、および登録情報は、実際に選択した結果から確認する必要があります。
- 登録に関する説明には、書式付きテキストやリンクが含まれる場合があります。自身のアプリケーションで表示する際は、返された文字列を信頼できないデータとして扱ってください。
- 携帯電話番号の提供可否とフラグは、アカウントの利用資格と在庫によって異なります。カタログのプレフィックスや is_mobile フラグだけでは、特定の番号が携帯電話としてどの機能に対応しているかは確定しません。