국가별 서비스 제공 지역 목록 조회

국가를 선택하세요(미국이나 캐나다의 경우 선택적으로 주를 선택할 수도 있습니다. 주 목록 조회: getstates). 번호가 제공되는 지역을 확인하려면 다음을 호출하세요: getareas. 다음 단계에서 사용할 지역 식별자를 보관하세요: uuid.

각 지역에서는 다음 두 단계 중 하나로 진행합니다:

• available > 0: next_function 값: v3/getprefixes/{uuid}. 주로 필터링한 경우 뒤에 추가되는 문자열: ?state=. 이 경로를 사용하여 접두 번호를 탐색하세요.
• available = 0: 해당 지역에 접두 번호는 있지만 재고는 없습니다. next_function 값: v3/order/{uuid}. 이 단계에 필요한 사항은 주문 문서를 참조하세요.

available 값은 주로 필터링한 경우에도 지역 전체의 합계입니다. 주 필터에는 코드나 전체 이름을 사용할 수 있지만, US 및 CA에서만 작동합니다. 주 필터를 적용했을 때 반환된 메시지가 No areas found이면 주 필터를 빼고 다시 시도하세요. 검사는 국가 코드 누락, 알 수 없는 국가, 다른 국가에 대한 주 필터 사용, 유효하지 않은 주, 일치하는 지역 없음 순으로 수행됩니다. 각각의 경우 반환되는 코드 값은 500 또는 404이며, 이 값이 담기는 필드는 status.code입니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.

요청

필수: HTTP Basic 인증 또는 Bearer 토큰(인증 및 API 응답 문서 참조). 인증에 실패하면 조회를 실행하기 전에 HTTP 401로 응답합니다.

GET 요청의 경로에 isocode를 지정하고, 선택 사항인 state 및 pid 매개변수는 쿼리 문자열에 지정합니다. 경로 세그먼트를 생략하면 대신 폼 인코딩된 isocode 필드를 읽습니다.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

응답

표준 응답 구조를 사용합니다. 성공 시 status.code는 200, status.msg는 'Results: N', status.results는 N이며, response는 지역 이름순으로 정렬된 목록입니다. 필드: uuid(다음 단계에서 사용하는, 내부 구조를 해석할 필요가 없는 지역 식별자); country_uuid(내부 구조를 해석할 필요가 없는 32자 국가 식별자이며 이후 단계에서는 필요하지 않음); name; area_type 및 number_type(카탈로그의 분류 정보이며, 항목이 반드시 시내 전화번호 유형인 것은 아님); country_iso; is_mobile(0 또는 1로, 해당 지역의 모바일 플래그에서 가져온 값이며, US의 경우 계정에서 US 모바일 번호 사용이 활성화되어 있지 않으면 항상 0); available(해당 지역의 조건에 맞는 모든 접두 번호의 재고 합계이며, 요청한 주로 한정되지 않음); sms_coverage(0 또는 1); returns_numbers(0 또는 1로, 해당 지역의 접두 번호에 설정된 플래그 중 최댓값); latitude 및 longitude; state_iso; next_function. state_iso: 주 필터가 있으면 해당 필터를 해석하여 얻은 코드입니다. US 및 CA에서 필터가 없으면 지역 이름과 이름이 같은 주의 코드이며, 그런 주가 없으면 저장된 지역 값을 사용하고, 그 값도 없으면 해당 지역의 접두 번호 데이터에서 도출한 코드를 사용합니다. 다른 국가에서는 저장된 값을 사용하며 비어 있을 수 있습니다. next_function 값으로 'v3/getprefixes/{uuid}'(필터 적용 시 '?state={code}' 추가)가 반환되는 조건은 available 값이 0보다 큰 경우이며, 그렇지 않으면 'v3/order/{uuid}'가 반환됩니다. 조건에 맞는 접두 번호가 전혀 없는 지역은 제외합니다. 접두 번호는 있지만 재고가 없는 지역은 available 값이 0인 상태로 반환합니다.

응답 구조를 보여 주는 예시이며, 실제 계정 데이터나 현재 견적이 아닙니다.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

오류

• 500: msg 'ISO Code parameter is required': isocode가 누락되었거나 비어 있습니다. 요청을 수정하여 해결할 수 있는 오류입니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.
• 404: msg 'Error: no such country': 알 수 없는 국가 코드입니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.
• 404: msg 'State filter is only available for US and CA': 다른 국가에 대해 비어 있지 않은 state 값을 전송했습니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.
• 404: msg 'Invalid state': state 값이 해당 국가에 등록된 코드도 이름도 아닙니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.
• 404: msg 'No areas found': 국가, 공급원 및 주 필터에 일치하는 지역이 없습니다. 이에 대응하는 HTTP 상태는 설정되지 않습니다.
• 401: 인증 정보가 누락되었거나 인증에 실패했습니다. HTTP 상태 401로 전송합니다.

가용 재고 및 부수 효과

• 고객 계정에서 조회 용도로만 사용합니다. 예약이나 주문을 수행하지 않으며 어떤 것도 변경하지 않습니다.
• available 값은 참고용이며 다음 단계로 진행하기 전에 바뀔 수 있습니다.