既存の番号ポータビリティプロジェクトに番号を追加する

アカウントとプロジェクトへのアクセス

許可されたIPアドレスから、有効なAPIアカウントを使用してHTTPSで接続してください。プロジェクトはそのアカウントに属し、削除されていない必要があります。プロジェクトの識別には、数値のデータベースIDや電話番号ではなく、番号移行申請のワークフローで取得したプロジェクト固有のIDを使用してください。リクエストを組み立てる際は、プロジェクトIDをURLエンコードしてください。

番号追加の準備

この操作は既存の番号ポータビリティプロジェクトを変更します。まず、番号移行申請のワークフローで対象の番号と顧客の承認を確認してください。各番号は国番号を含む完全な国際電話番号の数字列にし、重複を自分で除去したうえで、プロジェクトの既存の番号一覧を確認してください。このエンドポイントを任意の番号のテストに使用しないでください。

現在のポータルは、このルートを呼び出す前に番号を検証し、正規化します。従来のエンドポイントを直接使用した場合、同じ保護機能はありません。入力の前後の空白は除去しますが、電話番号の形式、国コード、重複、プロジェクトのワークフロー上の状態は検証しません。

POSTリクエスト

ローカルに numbers.json を次の構造で作成してください。番号は架空のものです。選択したプロジェクトで承認されている番号に置き換えてください。

{
  "numbers": [
    "12025550123",
    "12025550124"
  ],
  "isocode": "US"
}

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header "Content-Type: application/json" \
  --data-binary @numbers.json \
  "https://api.multitel.net/v3/lnp/project/$PROJECT_ID/addnumbers"

番号追加リクエストのフィールド
フィールド	意味
numbers	必須です。番号を文字列として格納した空でない配列、または改行で区切って各行に番号を記述した文字列を指定します。空の項目は破棄され、前後の空白は除去されます。カンマ区切りのテキストは個別の番号に分割されません。
isocode	追加する行の国コードを任意で指定します。省略した場合や空の場合は、プロジェクトの所在地が使用されます。ハンドラーは指定値の前後の空白を除去しますが、大文字への変換や値の検証は行いません。正しい国コードを自分で大文字で指定してください。

この例では、POSTをapplication/jsonで使用します。フォーム形式のPOST入力も読み取られます。このメソッドには、冪等性キーも、このエンドポイントで安全に処理できるバッチサイズの明確な保証も定義されていません。上限を推測して頼るのではなく、管理できる規模のバッチごとに結果を照合してください。

報告される結果

架空のレスポンス例です。

{
  "status": {
    "code": 200,
    "msg": "Success add numbers"
  },
  "response": {
    "uniqueid": "PROJECT_EXAMPLE",
    "count": 2,
    "numbers": [
      {
        "id": 21,
        "number": "12025550123",
        "status": 0,
        "status_str": "Pending",
        "isocode": "US"
      },
      {
        "id": 22,
        "number": "12025550124",
        "status": 0,
        "status_str": "Pending",
        "isocode": "US"
      }
    ]
  }
}

レスポンスでは、追加を試みた番号にPendingという状態が付けられます。結果を報告する前に、データベースへの各挿入結果を検証することはありません。そのため、件数や返されたIDだけでは、すべての行が永続保存された証拠にはなりません。Pendingの追加は、通信事業者による受け付け、移行日程の確定、または利用開始の完了を意味しません。

再試行する前に照合する

番号を追加する前にプロジェクトの番号一覧を取得し、追加する予定の番号を自分のリクエスト記録に残してください。
追加リクエストを一度だけ送信してください。
プロジェクトの番号一覧を再度取得し、追加する予定だった番号をすべて照合してください。重複と各番号の状態を確認してください。
リクエストがタイムアウトした場合、エラーが返された場合、または結果が曖昧な場合は、再試行する前にデータを再取得して確認してください。一部の番号はすでに追加されている可能性があります。
リクエスト全体を確認せずに繰り返すのではなく、番号移行申請のワークフローまたはサポートを通じて、欠落した行や重複した行を解消してください。

ハンドラーは、トランザクションや重複防止機能を使用せずに、項目を個別に挿入します。処理が中断されても、それまでの書き込みが残る場合があります。挿入に失敗してfalseが返された項目も、報告される件数に含まれることがあります。リクエストを繰り返すと、重複する行が追加される可能性があります。ハンドラー自体は、イベントの記録や通信事業者による番号移行の完了処理を行いません。

従来のエラー

POST以外のメソッドでは、APIコード403が返されます。プロジェクトが存在しない場合、削除済みの場合、またはそのアカウントに属していない場合は、APIコード404が返されます。番号の入力が空の場合も、APIコード404が返されます。認証と接続元IPアドレスの制限が適用されます。これらの従来のコードは、処理開始後にそれまでの挿入が一切行われていないことを保証するものではありません。

課金と番号移行の範囲

レビュー済みのハンドラーは、プロジェクトの番号行を挿入するもので、アカウントへの直接の課金や通信事業者への申請処理は含みません。ただし、番号ポータビリティサービス全体が無料になるわけではなく、合意済みの番号移行料金が無効になるわけでもありません。番号移行を期待する前に、プロジェクトに必要な承認、書類、および審査の要件をすべて満たしてください。