MultiTEL
開発者

POST/v3/directory/{number}

電話番号の電話帳掲載を申請する

承認済みの情報で通信事業者に電話帳掲載を申請し、実装上の料金を把握して、結果が不明な場合は再試行前に照合します。

このページの内容
  1. 通信事業者に電話帳掲載を申請する
  2. アカウントと番号の要件
  3. フォームのPOSTリクエスト
  4. 課金と再試行の動作
  5. レスポンス
  6. 従来のエラー
  7. 再試行前に確認する

通信事業者に電話帳掲載を申請する

MultiTELで所有している対象電話番号について、電話帳に掲載する氏名と住所を送信します。これは通信事業者による有料の更新であり、発信者名の検索、個人用アドレス帳への登録、ポータルの番号在庫にあるLIDBフィールドの一般的な更新ではありません。

電話帳への掲載について顧客が承認した情報のみを送信してください。この従来のルートを使用する前に、その番号が通信事業者の対応対象であることを確認してください。確認したハンドラーは、プロバイダーの対応可否や国際電話番号形式を検証しません。通信事業者へのリクエストでは北米の番号を前提とし、保存されている番号の先頭の桁を削除します。

アカウントと番号の要件

許可された送信元IPアドレスから、利用可能なAPIアカウントを使用してHTTPSで接続してください。指定する番号は、そのアカウントに属する、無効化されていない購入済み番号のレコードと完全に一致する必要があります。対応する北米番号なら国番号1を含めるなど、番号在庫にある国際形式の数字全体を使用してください。料金プランID、番号のUUID、別のアカウントに属する番号を使用しないでください。

フォームのPOSTリクエスト

次の項目 NUMBER に所有する番号を設定してください。架空のサンプル情報を、掲載について承認された情報に置き換えてください。このルートはPOSTのフォームフィールドを読み取ります。application/jsonの本文は解析しません。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "lastname=EXAMPLE" \
  --data-urlencode "firstname=EXAMPLE" \
  --data-urlencode "streetnum=1" \
  --data-urlencode "streetname=Example" \
  --data-urlencode "streetpredir=N" \
  --data-urlencode "streetpostdir=W" \
  --data-urlencode "city=Example City" \
  --data-urlencode "state=NY" \
  --data-urlencode "postalcode=10001" \
  "https://api.multitel.net/v3/directory/$NUMBER"
電話帳掲載のフォームフィールド
フィールドこのAPIで必須か意味
lastnameはい掲載する姓、または該当する掲載名のフィールド。
cityはい掲載住所の市区町村。
postalcodeはい掲載住所の郵便番号。
stateはい対応する通信事業者が受け付ける、掲載住所の州または地域。
streetnameはい通りの名称。
streetnumはい通り沿いの建物番号。
firstnameいいえ追加の名の要素。
streetpredir, streetpostdirいいえ該当する場合に指定する、通りの名称の前後の方角要素。
streettype, locationいいえ該当する場合に指定する、通りの種別または追加の所在地情報。

サンプルの方角と住所は仮の値であり、推奨される郵送先住所ではありません。実際の顧客データに架空の方角を追加しないでください。APIの必須フィールドのチェックは簡易的なもので、住所が有効であることや通信事業者が受け付けることを確認するものではありません。また、従来のウェブサイトでは異なるフォーム要件が適用されていました。

この実装では、任意の方角要素が指定されていないか空の場合、配列キーの欠落を示す警告が出ることがあります。レスポンスの形式が不正な場合や通信事業者が住所を拒否した場合は、推測で住所を修正して繰り返し送信せず、リクエストの参照情報を保管し、サポートに掲載内容の確認を依頼してください。

課金と再試行の動作

確認したハンドラーは、残高が少なくとも 10.00残高単位 あることを確認してから通信事業者に接続します。通信事業者とローカルの番号更新の両方が成功を報告した後、次の金額 10.00 をアカウント残高から差し引き、電話帳掲載設定の取引を記録します。これらは現在実装されている金額であり、新しい料金の提案ではありません。送信前に、アカウントの契約条件で適用される請求通貨と対応サービスを確認してください。

この処理には、冪等性キー、重複注文の防止機能、通信事業者への送信・ローカル更新・課金をまとめるトランザクションがありません。リクエストを繰り返して成功すると、通信事業者への再送信と追加の課金が発生する可能性があります。タイムアウトやAPIエラーが発生しても、通信事業者が先のリクエストを拒否したとは限りません。ローカル更新が失敗する前に、プロバイダーが受け付けている可能性があります。

レスポンス

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": ""
}

通常の成功レスポンスでは、空文字列が設定されるフィールドは response であり、掲載IDや完了の詳細は返されません。これは通信事業者側とローカル更新の処理経路が成功を報告したことを意味します。すべての外部電話帳への掲載、即時の反映、将来の発信者ID表示を証明するものではありません。

従来のエラー

電話帳掲載APIの結果コード
APIコード意味
404アカウントに番号が見つからないか、必須のフォームフィールドのいずれかが空です。
400アカウント残高が実装上の料金を下回っています。
500通信事業者へのリクエストが失敗したか、通信事業者がすでにリクエストを受け付けた可能性がある状態でローカル更新が失敗しました。
200成功が報告されていますが、レスポンスに掲載の確認は含まれていません。

HTTPステータスに加えて、JSON内の次の項目も確認してください： status.code/status.msg。認証や送信元IPの制限によっても、利用可能なレスポンスを得られないことがあります。従来のハンドラーにHTTPメソッドの明示的な制限がないという理由で、GETやクエリパラメーターを使用して更新を要求しないでください。

再試行前に確認する

  1. リクエストの送信前に、所有する番号、通信事業者の対応可否、掲載について承認された情報、料金を確認してください。
  2. 送信は一度だけ行い、顧客の住所を公開ログや分析データに露出させずに、アカウント側の結果を保管してください。
  3. 正式にサポートされているアカウント操作手順またはサポート窓口を通じて、保存された掲載内容と取引履歴を確認してください。通信事業者が確認した処理時間を見込んでください。このAPIは、反映期限を保証していません。
  4. 結果が不明な場合は、再試行する前に、通信事業者への注文とローカルの課金をサポートに照合してもらってください。リクエストの再送は、冪等性のあるステータス確認ではありません。