REST API ドキュメント
LRN ルーティング検索 REST API
北米の電話番号について、ルーティング番号と利用可能なキャリア情報を一定の単価で検索できます。
API と認証情報を合わせて選択する
承認済みの「開発者・自動化」「ビジネス」「通信事業者」のアカウントは、有効化されたサービスを連携できます。個人の開発者が企業を装う必要はありません。アプリケーションからの SMS/MMS には、該当する送信承認と登録が必要です。「パーソナル＆ファミリー」サービスには、お客様が利用できるメッセージ発信用 API はありません。
| API ファミリー | ベース URL | 認証と結果 |
|---|---|---|
| Communications v3 | https://api.multitel.net/v3 | 承認済みの Basic 認証情報。プロビジョニングされた対象のトークンは、それをサポートする操作でのみ使用できます。JSON の status と response。 |
| 緊急通報の登録 | https://api.multi.tel/emergency | 承認済みの Basic 認証情報、または個別にプロビジョニングされたベアラーアクセス。JSON の code、message、data。 |
| ポータルの REST 連携 | お客様のアカウントの開発者向けリファレンスに表示されるホストと操作 | その操作について文書化されている認証情報、スコープ、スキーマを使用してください。ブラウザーのセッションによるリクエストは、別のインターフェースを使用します。 |
例を使用する前に、サーバーのシークレット設定で MULTITEL_API_USERNAME と MULTITEL_API_PASSWORD を設定してください。これらを公開ブラウザーの JavaScript、URL、ソース管理に埋め込まないでください。専用の認証情報は API 連携設定で管理します。
番号を照会する
GET /v3/lrn/{number} は、パス内で宛先番号を受け付けます。発信元に依存する情報が必要な場合は、任意の発信元番号を /v3/lrn/{number}/{ani} として指定できます。北米の電話番号を数字のみで表し、該当する場合は国番号を含めてください。例では、予約済みの架空の番号を使用しています。
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/lrn/12025550123"curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/lrn/12025550123/12025550124"有効な認証情報で照会を実行すると課金されます。料金は1 回の照会あたり $0.00025（1,000 件あたり $0.25、または 100 万件あたり $250）です。ボリュームディスカウントはありません。これはルーティング情報の照会であり、電話の発信は行いません。
結果を読み取る
{
"status": {
"code": 200,
"msg": "Success"
},
"response": {
"lrn": "12025550123",
"ported": 0,
"ocn": "",
"lata": "",
"rc": "",
"cost": "$0.00025"
}
}この架空の例はレスポンスの形式を示すだけのものであり、実測のルーティング結果ではありません。response を使用する前に status.code を確認してください。cost フィールドは通貨記号が付いた文字列であり、JSON の数値ではありません。
| フィールド | 意味 |
|---|---|
lrn | ルーティング先を識別するために使用される Location Routing Number。 |
ported | この照会が提供するポータビリティの指標で、通常は 0 または 1 です。所有権やサービス利用資格の証明として使用しないでください。 |
ocn | Operating Company Number（提供される場合）。 |
lata | Local Access and Transport Area（提供される場合）。 |
rc | レートセンター（提供される場合）。 |
city, state, lec, lectype, jurisdiction, local | 利用可能な場合の、追加の所在地、キャリア、または発信元に関連する詳細。存在しない場合や空白の場合があります。 |
すべてのルーティングフィールドが存在することを前提にしないでください。特に、フリーダイヤル（toll-free）の結果では、ローカルのレートセンターやキャリアコードの詳細が含まれない場合があります。返された LRN は、到達可能性のリアルタイムでの保証でも、通話品質のテストでもありません。
ルーティングのワークフローで照会を使う
- 送信前に、要求する番号を検証し、正規化してください。
- HTTP ステータスとアプリケーションのステータスを確認してください。トラブルシューティングのために、番号、時刻、結果を、機密情報を伏せた形で記録しておいてください。
- ルーティングルールに関係するフィールドだけを使用し、値が存在しない場合は明示的に処理してください。
- 結果が不確かなレスポンスの後は、再試行の回数を制限してください。照会を繰り返すと、再度課金される可能性があります。このエンドポイントには、文書化された冪等性キーはありません。
LRN 製品と均一の照会単価を見る。公開されている OpenAPI のパスには ANI セグメントが含まれていますが、デプロイ済みの LRN 実装では、ANI を含まない短い形式のリクエストも受け付けます。lrninfo は別の操作であり、このエンドポイントの代わりに使用しないでください。
エラーと再試行の扱い
- 認証または権限の失敗
- API 認証情報の有効状態、許可されているサービス、送信元 IP の制限を確認してください。ポータルのセッション Cookie は連携用の認証情報ではありません。
- クレジット不足または承認の未完了
- 操作を繰り返す前に、アカウント残高、送信の承認、または書類要件を解決してください。
- 結果なし
- 在庫が空であることや発信者名が見つからないことは、通常の結果として処理してください。構文上有効な番号だからといって、すべてのサービスが利用できると想定しないでください。
- ネットワークのタイムアウトまたはサービス障害
- 読み取りには、バックオフを伴う回数制限付きの再試行を使用してください。購入、送信、登録の場合は、まず操作の状態を確認してください。受理済みのリクエストを再試行すると、課金対象の操作が重複する可能性があります。
冪等性のサポートは API ファミリーごとに異なります。Emergency API は再試行キーをサポートしていますが、それによって任意の v3 リクエストが冪等になるわけではありません。サポート対応のために、タイムスタンプ、返された ID、機密情報を伏せたレスポンスを保管してください。
アカウント専用リファレンスに進む
サインイン後のリファレンスでは、お客様の権限と有効なサービスに応じて操作が絞り込まれます。正確なホスト、認証情報の種類、リクエストフィールド、レスポンススキーマは、そのリファレンスの記載に従ってください。コンソールでは、購入やメッセージ送信を含む本番の操作を実行できます。