전화번호 등록 프로필 제출하기

저장된 프로필과 전화번호 준비하기

이 절차를 사용하면 저장된 등록 프로필을 구매한 전화번호에 연결하고, 통신사 등록 심사가 지원되는 번호에 대해 심사를 요청할 수 있습니다. 모든 번호 제공업체를 위한 범용 개통 API는 아닙니다. 요청이 성공해도 서류가 승인되었거나 번호가 개통되었다는 증거는 아닙니다.

활성화된 MultiTEL API 계정에 설정된 인증 정보와 IP 제한을 적용하여 HTTPS로 접속하세요. 삭제되지 않은 프로필과 구매 후 무효화되지 않은 번호가 모두 본인 계정에 속해야 합니다.

1. 새로 등록 프로필을 만들거나 기존 프로필을 선택하세요. 로컬 프로필의 uuid는 create_document에서 받아 보관하세요. get_document는 동일한 로컬 참조값을 id로 반환합니다.
2. 통신사에 심사를 요청하려면 프로필에 저장된 신원 정보 및 주소 참조값이 필요합니다. 필요한 증빙 자료와 보충 서류를 각각 알맞은 절차에 따라 제출 전에 첨부하세요.
3. 번호와 프로필이 해당 국가 및 번호에 적용되는 요건을 충족하는지 확인하세요. 저장된 프로필이 모든 번호에 대해 승인되었다고 가정하지 마세요.

연결 요청 제출하기

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

경로에는 구매한 전화번호를 넣습니다. 해당 번호의 UUID, PBX 내선번호 또는 신원 정보 ID를 넣는 것이 아닙니다. 핸들러는 번호에서 숫자가 아닌 문자를 제거합니다. 국가 코드를 포함한 전체 국제 전화번호를 사용하세요. 예시는 가상의 값이므로 본인의 번호와 저장된 로컬 프로필 참조값으로 바꿔야 합니다.

멀티파트 요청에서는 onetime_files[] 필드를 반복하여 배열을 지정합니다. Content-Type: application/json을 지정한 JSON 요청도 허용되며, 해당 속성은 폼 페이로드에 병합됩니다. 경로에서 번호를 생략한 경우 페이로드에 number를 지정할 수 있습니다. 모호함을 피하려면 위 예시처럼 경로에 명시하는 방법을 권장합니다.

연결과 승인 구분하기

HTTP 결과와 JSON의 status.code를 모두 확인하세요. HTTP 200과 함께 JSON 오류가 반환될 수 있습니다. 통신사 심사 요청이 성공하면 Address verification task created; awaiting carrier review. 메시지가 반환됩니다. 이 예시의 참조값은 가상의 값입니다.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

제공업체 관련 식별자는 마스킹된 참조값이며, 로컬 프로필 ID와 서로 바꿔 쓸 수 없습니다. document_uuid는 제출한 로컬 프로필 참조값을 그대로 유지합니다. 이 핸들러에서 통신사 처리를 수행하는 경로의 registration_details_id는 해당 로컬 참조값을 추가로 해시한 값입니다. 이후 프로필 관련 요청이나 제출 요청에서 document_uuid를 이 값으로 대체하지 마세요.

일부 할당된 번호는 통신사 확인 작업을 생성하는 대신 로컬에서 신원 정보를 연결합니다. 이 경우 성공 결과는 Identity associated.이며, response는 빈 배열입니다. 통신사 심사 작업을 생성하지 않으며 승인되었다는 의미도 아닙니다. 포털에는 이 엔드포인트와 제공업체 처리 방식 및 재제출 검사가 다른 최신 연결 절차가 있습니다.

작업을 중복 생성하지 않고 오류 처리하기

API 코드 400은 번호 또는 프로필 참조값이 누락된 경우에 해당합니다. 코드 404는 해당 계정에서 프로필이나 번호를 사용할 수 없거나 통신사 번호 재고에 번호가 없는 경우에 해당합니다. 코드 422는 신원 정보 또는 주소 참조값의 누락, 판매자 요건, 통신사 검증 거부를 알릴 수 있습니다. 콜백 설정이 없으면 503이, 생성 시 통신 실패가 발생하면 502가 반환될 수 있습니다. 모든 실패를 동일하게 처리하지 말고 메시지와, requirement_diagnostics가 있으면 그 내용도 확인하세요.

통신사 처리를 수행하는 경로에서는 요건 검증, 콜백 설정 확인 또는 작업 생성이 끝나기 전에 로컬 등록 대기 플래그를 업데이트할 수 있습니다. 따라서 오류가 발생했다고 해서 로컬 상태가 그대로라는 뜻은 아니며, 대기 플래그만으로 작업이 존재한다고 판단할 수도 없습니다. 이 플래그를 승인이나 요청 전달의 확인 근거로 사용하지 마세요.

이후 로컬 데이터베이스 작업이 실패하더라도 제공업체가 작업을 접수했을 수 있으며, 이 헬퍼는 성공을 보고하기 전에 모든 로컬 쓰기 결과를 확인하지는 않습니다. 이 핸들러에는 클라이언트 멱등성 매개변수나 중복 제출 방지 장치가 없습니다. 시간 초과나 오류가 발생했거나 결과가 불확실하다면 다시 제출하기 전에 포털에서 해당 번호의 등록 이력을 확인하거나 지원팀에 문의하세요. 로컬 기록이 없다는 사실만으로 제공업체가 아무것도 받지 않았다고 판단할 수는 없습니다.

일회성 서류 관련 제한 사항

핸들러는 onetime_files를 받아 비어 있지 않은 각 문자열을 통신사의 암호화 파일 연결 관계로 전달합니다. 소유 계정의 업로드 레코드를 조회하거나 외부용으로 마스킹된 업로드 ID를 제공업체 파일 ID로 변환하지 않습니다. 오프라인 감사에서 확인한 것은 전달 동작이며, 통신사 측 첨부 성공 여부는 아닙니다.

create_encrypt_files에서 받은 파일 ID를 이 필드에 복사하면 일회성 동의서 절차를 완료할 수 있다고 가정하지 마세요. 해당 번호에 이러한 서류가 필요하다면 포털을 사용하거나 지원되는 식별자 처리 절차를 MultiTEL에 확인하세요. 이 부분은 API 검토에서 아직 해결되지 않았으며, 처음부터 끝까지 동작이 검증된 예시가 아닙니다.

등록 정보 보호하기

해당 번호에 사용할 권한이 있는 정보와 서류만 제출하세요. 프로필 및 확인 작업의 참조값을 올바른 계정에 연결하여 관리하고, 등록 페이로드 전체를 로그에 기록하지 마세요. 이 요청이 이전의 모든 증빙 자료나 확인 작업을 삭제하거나 대체하는 것은 아닙니다. 통신사 심사, 개통, 보관은 각각 별도의 절차입니다.