프로필은 한 번만 만들기
이 요청은 통신사 측 신원 및 주소 레코드와 함께 로컬 등록 프로필을 만듭니다. 먼저 최신 등록 국가, 번호 유형 및 요구 사항을 확인하세요. 요구 사항은 등록하려는 국가와 번호 유형에 따라 다릅니다.
작성 응답이 성공했다고 해서 규제 승인이나 번호 활성화가 이루어진 것은 아닙니다. 문서 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 목록은 상위 시스템에 아무것도 생성되지 않았다는 증거가 아닙니다.