메시징 등록용 카탈로그 불러오기

등록 양식을 만들기 전에 선택 항목 불러오기

레지스트리 값을 하드코딩하지 말고 최신 메시징 등록용 카탈로그를 사용해 선택 항목을 채우세요. 브랜드 양식의 경우 포털은 사업체 유형, 업종, 대체 사업체 식별자 유형, 브랜드 관계, 국가, 미국 주 및 증권거래소 카탈로그를 불러옵니다. 캠페인 양식의 경우 사용 사례, 유효한 하위 사용 사례 및 연결 파트너를 불러옵니다. 반환된 각 기계 처리용 값을 해당 표시 이름과 함께 보관하세요. 나중에 요청을 구성할 때는 번역된 표시 이름이 아니라 이 값을 사용하세요.

카탈로그 선택하기

포털에서 사용하는 카탈로그
이름	용도
usecase	캠페인 사용 사례의 정의입니다. 하위 사용 사례 선택 항목을 불러올 때는 validSubUsecase=true를 추가하세요.
entityType	브랜드의 사업체 또는 조직 유형입니다.
vertical	브랜드의 업종 선택 항목입니다.
altBusinessIdType	대체 사업체 식별자 분류입니다.
brandRelationship	등록 양식에서 사용하는 관계 선택 항목입니다.
country	레지스트리의 국가 선택 항목입니다. 전화번호를 이용할 수 있는 국가 목록과는 별개입니다.
usState	등록 주소에 사용할 미국 주 선택 항목입니다.
stockExchange	브랜드의 사업체 유형에 따라 지정이 필요한 증권거래소 선택 항목입니다.
cnp	연결 파트너 식별자입니다. 계정의 캠페인 처리 흐름에서 지원하는 파트너를 선택하세요.

TCR 응답 직접 처리하기

응답 본문은 TCR API가 직접 반환하는 본문입니다. 기존의 여러 /v3 엔드포인트와 달리, 별도의 status/response 래퍼가 추가되지 않습니다. 본문을 해석하기 전에 HTTP 상태를 확인하세요. 카탈로그에는 문자열 표시 이름이나 구조화된 정의가 포함될 수 있으므로 모든 값에 동일한 필드가 있다고 가정하지 마세요. HTTP 요청이 성공했더라도 본문이 예상한 구조의 유효한 JSON이 아니면, 알리지 않고 빈 목록으로 대체하지 말고 조회 실패를 보고하세요.

카탈로그 선택 항목과 자격 요건·요금 구분하기

일반 사용 사례 카탈로그만으로는 개별 브랜드가 어떤 사용 사례의 자격 요건을 충족하는지 알 수 없습니다. 현재 포털은 캠페인을 만들기 전에 브랜드별 자격을 조회하고 선택한 통신사의 요구 사항을 확인합니다. 마찬가지로 공급업체의 수수료 메타데이터는 해당 계정에 적용되는 최종 고객 요금이 아닙니다. 적용되는 계정 요금과 등록 조건을 별도로 검토하세요. 카탈로그를 불러온다고 해서 브랜드, 캠페인 또는 메시징 번호가 승인되는 것은 아닙니다.

카탈로그를 이용할 수 없는 경우 처리하기

조회에 실패하더라도 고객이 양식에 입력한 내용을 유지하세요. 오류를 표시하고, 다음 헤더가 반환되면 그 지침을 따르세요: Retry-After. 또한 재시도 대기 시간을 점차 늘리세요. 모든 카탈로그를 반복해서 다시 불러오거나, 요청 속도 제한 오류 또는 전송 오류를 유효한 빈 카탈로그로 취급하지 마세요. 이 GET 요청에는 멱등성 키가 필요하지 않으며, 변경 작업용 멱등성 저장소에서 재실행되지도 않습니다.

요청

허용된 출발지 IP 주소에서 활성화된 API 계정을 사용해 HTTPS로 요청하세요. 현재 경로는 Basic 인증 및 활성화된 베어러 토큰 인증 API 계정을 포함한 계정 인증 정책을 지원합니다. 제공업체의 인증 정보는 사용하지 마세요.

경로에 지원되는 카탈로그 이름을 지정하여 GET 요청을 보내세요. 적용할 카탈로그 필터는 쿼리 문자열로 전달하세요. 요청 본문은 필요하지 않습니다.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

경로 매개변수
이름	유형	필수 여부	설명
`type`	문자열	예	원래 대소문자를 그대로 유지한 카탈로그 이름입니다. 포털에서는 usecase, entityType, vertical, altBusinessIdType, brandRelationship, country, usState, stockExchange 및 cnp를 사용합니다. 이는 카탈로그 이름이며, 브랜드나 캠페인 식별자가 아닙니다.

쿼리 매개변수
이름	유형	필수 여부	설명
`validSubUsecase`	불리언	아니요	usecase 카탈로그의 경우 포털은 유효한 하위 사용 사례 선택 항목을 불러오기 위해 true를 지정해 요청합니다. 일반 사용 사례 카탈로그를 불러올 때는 이 매개변수를 생략하세요. 이용 가능 여부와 정의는 레지스트리에서 제공합니다.

응답

이 TCR 경로는 레지스트리 본문을 해당 HTTP 상태와 함께 직접 반환합니다. 기존 v3의 status.code/status.msg/response 응답 래퍼는 사용하지 않습니다. 카탈로그 구조는 서로 다릅니다. 값을 설명 객체에 매핑하는 카탈로그도 있고, 문자열에 매핑하는 카탈로그도 있습니다. 나중에 양식을 제출할 때 기계가 읽을 수 있는 키를 유지하세요. 축약된 가상의 usecase 예시는 객체를 값으로 갖는 맵을 보여 주며, 실제 카탈로그나 완전성이 보장된 스키마가 아닙니다. HTTP 상태와 예상한 JSON 구조를 모두 확인하세요.

응답 구조를 설명하기 위한 예시이며, 실제 계정 데이터나 현재 견적이 아닙니다.

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

오류

401: 계정 인증에 실패했습니다. API 인증 정보, 활성화 상태 및 적용되는 출발지 IP 제한을 확인하세요.
400/404 및 기타 레지스트리 오류: 카탈로그나 필터가 유효하지 않거나 이용할 수 없습니다. 현재 경로는 상위 서비스의 HTTP 상태와 응답 본문을 그대로 유지합니다. 공통으로 적용되는 v3 오류 응답 래퍼는 없습니다.
429: 계정의 요청 한도 또는 제공업체의 공유 요청 한도에 도달했습니다. Retry-After 지침을 따르고 대기 시간을 점차 늘려 재시도하세요.
502: 레지스트리에 연결할 수 없습니다. 이용 가능 여부를 알 수 없으므로, 성공 결과 대신 빈 선택 항목을 반환하지 마세요.
503: 요청 제한 장치 또는 상위 서비스를 이용할 수 없습니다. 재시도하기 전에 본문을 확인하고, Retry-After 헤더가 있으면 함께 확인하세요.

이용 가능 여부와 부수 효과

검토된 처리 경로에서 이 카탈로그 GET 요청은 브랜드나 캠페인을 만들거나, 등록을 제출하거나, 리소스를 예약하거나, 등록 수수료를 부과하지 않습니다. 제공업체에 접속하고 요청 감사 기록을 작성합니다.
카탈로그 정의와 공급업체의 수수료 메타데이터는 고객에게 제시하는 요금 견적이 아닙니다. 현재 포털은 고객용 캠페인 요금을 별도로 가져옵니다. 기존 getCampaignPrice 도우미나 오래된 열거형의 가격 주석을 이 경로의 요금 명세로 취급해서는 안 됩니다.
카탈로그에 지원 항목이 있다고 해서 특정 브랜드가 해당 사용 사례의 자격 요건을 충족한다는 증거가 되지는 않습니다. 나중에 등록 요청을 보내기 전에 브랜드별 자격 확인, 신고, 동의 및 계정 요금 검토를 완료하세요.