登録プロファイルを作成する

プロファイルは一度だけ作成する

このリクエストは、キャリア側のアイデンティティと住所のレコードとともに、ローカルの登録プロファイルを作成します。まず、現在の登録国、番号の種類および要件を確認してください。要件は、登録する予定の国と番号の種類によって異なります。

作成レスポンスが成功しても、規制当局の承認や番号の有効化を意味するものではありません。書類 UUID、アイデンティティ ID、住所 ID は用途が異なるため、それぞれ別々に保存してください。このリクエストはアカウントデータを変更するものであり、検証のみの操作ではありません。

作成リクエスト

有効化済みの MultiTEL API アカウントと、そのアカウントで許可された IP アドレスを使用して認証してください。例では、環境変数に保存した HTTP Basic 認証情報を使用しています。HTTP レスポンスと JSON の status.code の両方を確認してください。HTTP 200 レスポンスだけでは成功とは判断できません。例の値はすべて架空のものです。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data @registration-profile.json \
  https://api.multitel.net/v3/create_document

{
  "identity_type": "Personal",
  "first_name": "Example",
  "last_name": "Person",
  "phone_number": "12025550123",
  "email": "end-user@example.com",
  "city": "Example City",
  "postal_code": "00000",
  "country": "US",
  "address": "1 Example Street",
  "nationality": "US",
  "signature": "BASE64_PNG_OF_THE_AUTHORIZED_END_USER_SIGNATURE"
}

この JSON は例示用の Personal プロファイルであり、そのまま送信できる実在のアイデンティティではありません。詳細と署名は、選択した登録ルールで求められるエンドユーザー情報に置き換えてください。フォームエンコード形式の入力もサポートされています。

登録プロファイルのフィールド
フィールド	必須条件と形式
`identity_type`	必須。正確な値 Personal または Business を使用してください。条件付き検証は大文字・小文字の区別に依存します。
`first_name, last_name`	必須。それぞれ最大 64 文字です。法人の場合は、選択した国で求められる代表者の情報を指定してください。
`phone_number`	必須の数値形式の電話番号で、八文字以上です。国番号を含む数字のみの国際番号であればこの検証を通過します。これは連絡先番号であり、番号の購入ではありません。
`city, postal_code, address`	必須。それぞれ最大 64 文字です。
`country`	必須。登録カタログに含まれる住所の国の ISO コードです。サービスがこれをキャリア側の国レコードに解決します。
`signature`	必須の署名データです。現在のポータルは、data:image/png;base64, プレフィックスを付けない Base64 PNG 画像バイトを送信します。エンドユーザーの署名は、承認されたワークフローを通じて取得してください。空でないプレースホルダーは有効な署名ではありません。
`nationality`	Personal の場合は必須で、国の ISO コードを指定します。国の UUID で代用しないでください。
`company_name, incorporation_country`	Business の場合は必須です。会社名は最大 64 文字で、incorporation_country は国の ISO コードです。
`email`	任意のエンドユーザー連絡先メールアドレスで、最大 254 文字です。メールアドレスを省略した場合や空の場合でも、基本アカウントのメールアドレスは引き継がれません。
`company_reg_number, vat_id, id_number, personal_tax_id, birth_date, description`	このハンドラーでは任意ですが、選択した国やキャリアによっては一部が必須となる場合があります。その登録で求められる形式で指定してください。API を直接呼び出す場合、ポータルが行うすべての正規化が自動的に適用されるわけではありません。

この直接の v3 ハンドラーは住所フィールドを必須とし、住所を作成します。ポータルの住所後回しオプションがこのハンドラーで利用できると想定しないでください。

三つの識別子をすべて保持する

以下は選択したレスポンスフィールドのみを示しています。実際のレスポンスには、送信したプロファイル情報と署名データも含まれます。レスポンス全体を機密情報として扱ってください。

{
  "status": {
    "code": 200,
    "msg": "Success Create Registration Detail."
  },
  "response": {
    "uuid": "11111111111111111111111111111111",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "country_iso": "US",
    "email": "end-user@example.com"
  }
}

response.uuid はローカルプロファイルを識別します。これは get_document で使用します。documents および get_document のレスポンスでは、同じプロファイル識別子は id という名前になります。
response.identity_id は、後続の本人確認証明および補足書類のためにアイデンティティを識別します。
response.address_id は作成された住所を識別します。これは別に保管してください。ローカルプロファイルの UUID は住所 ID ではありません。新規作成したプロファイルに対する後続の住所証明添付の互換性は、まだ確認中です。

二つのプロファイル読み取りエンドポイントは identity_id や address_id を返さないため、成功した元の作成レスポンスを保持してください。紛失した場合は、代わりのプロファイルを作成する前にポータルの書類ビューを使用するか、サポートにお問い合わせください。

高度な使い方: 作成時に事前アップロード済みの証明を添付する

必要に応じて、identity_encryptfiles と address_encryptfiles を、create_encrypt_files から返された ID の配列として指定できます。対応するエンティティ区分の証明タイプを使用してアップロードし、ファイル参照の有効期限（約 20 分）が切れる前に送信してください。作成ハンドラーは、指定された各参照のアカウント、区分、有効期限を確認します。

これらのフィールドは、後続の添付エンドポイントの encrypted_file_ids とは名前が異なります。作成時には、複数のファイルが一つの証明タイプを共有する場合でも、各ファイルは個別の証明リクエストとして送信されます。複数のファイルをまとめて含める必要がある本人確認証明の場合は、後続の create_proof リクエストで一つの配列として送信してください。プロファイル作成が成功しただけでは、個々の証明の承認結果は得られません。

新規作成した住所に対する後続の住所証明が拒否された場合、プロファイル UUID で代用したり、アイデンティティを繰り返し作成し直したりしないでください。作業を中止し、ポータルまたはサポートを通じてプロファイルを確認してください。住所証明の読み取りおよび検索経路は、引き続きレビュー上の制限事項です。

失敗と部分的な作成

API コード 400 は、フィールド検証、キャリア側での作成失敗、ローカル保存の失敗を対象とします。検証エラーは response 内にフィールド名をキーとするエントリとして表示される場合があります。コード 500 は登録国が利用不可または無効な場合に、コード 404 は事前アップロード済みの参照が存在しないか期限切れの場合に使用されます。コードだけでなく status.msg も確認してください。

ローカルプロファイルと上流のキャリア操作は、一つのアトミックなトランザクションではありません。失敗したリクエストは、ローカルプロファイルが一覧に表示されていなくても、上流に状態を残す可能性があります。クライアント側の冪等性キーは公開されていません。タイムアウトや結果が不確かな失敗の後は、作成を繰り返す前に既存のプロファイルを確認し、サポートにお問い合わせください。空の documents 一覧は、上流に何も作成されなかったことの証明にはなりません。