API 認証情報を使用する
v3 リクエストは HTTPS 経由で送信し、送信先はhttps://api.multitel.netです。本ガイドのすべてのエンドポイントは認証が必要です。認証情報はサーバー上に保管し、ブラウザーの JavaScript、公開ページ、スクリーンショット、ソース管理には絶対に含めないでください。
次のいずれかの認証情報形式を使用してください:
- HTTP Basicでは、 API ユーザー名とパスワードを使用します。これらは MultiTEL アカウント用に設定されています。
- Bearer トークンを
Authorization: Bearer YOUR_API_TOKENヘッダーで送信します。これはトークン認証用に設定された有効な API アカウント向けです。トークンリクエストは、その API アカウントに許可されたアドレスからのみ受け付けられます。
IP 許可リストが API アカウントに設定されている場合は、許可されたアドレスからすべてのリクエストを送信してください。
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'これらの例の変数は、環境内に非公開で保管する認証情報のプレースホルダーです。
認証失敗の処理
認証失敗は HTTP ステータス 401 で送信されます。本文は標準のエンベロープを使用し、status.codeを401に設定し、空文字列をresponseとします。
- 認証情報なし:
status.msgはUsername and password are requiredであり、応答には Basic 認証チャレンジが含まれます。 - Bearer トークン拒否:もし
AuthorizationヘッダーがBearer方式を使用し、トークンが不明、無効、またはお客様のアドレスからは許可されていない場合は、status.msgはInvalid bearer tokenです。 Bearer ヘッダーが存在する場合、他の認証情報は試行されません。 - 無効な Basic 認証情報:
status.msgはA valid username and password pair are required.で始まり、応答には Basic 認証チャレンジが含まれます。メッセージには追加の診断テキストが含まれる場合があるため、解析しないでください。
同じ認証情報で自動的に再試行しないでください。短期間にひとつのアドレスから多数の失敗があると、そのアドレスからの以降のリクエストがブロックされる可能性があります。
応答本文の読み取り
ほとんどの v3 エンドポイント（getcountries、getstates、getareasおよびotherを含む）は、次のエンベロープで JSON を返します:
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"countrycode": "1",
"name": "United States",
"description": "United States",
"isocode": "US",
"is_mobile": 0,
"sms_coverage": 1,
"latitude": "38.0000",
"longitude": "-97.0000",
"next_function": "v3/getareas/US"
}
]
}これは例示的な国リスト応答であり、現在の在庫や機能を示すものではありません。
| フィールド | 意味 |
|---|---|
status.code | API 結果コード（例:200、401、404または500）。 |
status.msg | 人が読めるメッセージです。空の場合があります。プログラムのロジックはstatus.codeに基づかせ、メッセージテキストには基づかせないでください。 |
status.results | エントリ数です。ここで説明する検出エンドポイントでは、responseが JSON リスト（空リスト（0）を含む）の場合に存在します。responseが空文字列またはnullの場合には存在しません。他のエンドポイントのペイロードではカウントの報告方法が異なる場合があります。それぞれの応答ドキュメントに従ってください。 |
response | エンドポイントのペイロードです。その型はエンドポイントと結果によって異なります。エラーの場合は空文字列です。 |
エラー応答の例は次のとおりです:
{
"status": {
"code": 404,
"msg": "No areas found"
},
"response": ""
}応答をエンコードできない場合、本文はstatus.code 500、status.msg Response encoding error、空オブジェクトをresponseとして含みます。
レガシーのGET /v3/countriesエンドポイントは{"code": 200, "data": [...]}を代わりに返します。各エンドポイントのドキュメント化された応答を確認してください。本文が有効な JSON でない場合（予期しないサーバー障害後など）は、リクエストを失敗として扱い、後で再試行してください。
API 結果コードと HTTP ステータス
status.codeは API 結果コードです。 HTTP ステータスではありません。認証失敗は HTTP 401 で送信されます。それ以外の場合、検出エンドポイントは次のような結果（404および500）をstatus.codeでのみ報告し、対応する HTTP ステータスは設定しません。存在しない場合やパラメーター不足の結果は、成功の HTTP ステータスで届く可能性があります。必ずstatus.codeを確認してからresponseを使用してください。
結果コード500（メッセージ:ISO Code parameter is required）は必須パラメーターの不足を意味します。サーバー障害として扱うのではなく、リクエストを修正してください。
next_function をたどる
検出結果にはnext_functionが含まれます。これは先頭にスラッシュのない相対パスであり、クエリ文字列を含む場合もあります（例:v3/getareas/USまたはv3/getareas/US?state=NY）。次のリクエストを作成するには、次のプレフィックスを付けます:https://api.multitel.net/。そのリクエストも同じ方法で認証してください。送信した任意のフィルター（例:pid）はnext_functionに引き継がれません。必要に応じて再度追加してください。
任意の在庫セレクター（pid）
getcountries、getstatesおよびgetareasは任意のpidクエリパラメーターを受け付けます。これは結果をひとつの在庫ソースに絞ります。 MultiTEL が提供する値でのみ使用し、数値形式または32文字の十六進形式のいずれかで指定します。通常の使用では省略してください。送信対象はpidです。クエリ文字列内で送信してください。エンドポイントが値を認識または受け付けない場合、エラーなしで無視され、リクエストはpidが省略された場合と同様に動作します。
検出と注文の分離
国、州、地域の検索ではアカウントは変更されません。特殊番号カタログ（other）はカタログ詳細を更新し、アカウント用の価格見積もりを保存しますが、注文は確定しません。検出リクエストで番号が確保されることはなく、在庫はリクエスト間で変動する可能性があります。注文エンドポイントを使用する前に、番号の要件と価格を確認してください。
購入、割り当て、メッセージ、ファクス送信、その他の操作については、そのエンドポイント固有の再試行ルールに従ってください。送信後に操作がタイムアウトした場合は、繰り返す前にそのステータスまたはアカウント記録を確認してください。応答の喪失は操作の失敗を証明するものではありません。