인증 및 API 응답

API 자격 증명 사용

v3 요청은 HTTPS 를 통해 전송하며, 전송 대상은 https://api.multitel.net입니다. 이 가이드의 모든 엔드포인트는 인증이 필요합니다. 자격 증명은 서버에 보관하고, 브라우저 JavaScript, 공개 페이지, 스크린샷 또는 소스 관리에 절대 포함하지 마십시오.

다음 중 하나의 자격 증명 형식을 사용하십시오:

• HTTP Basic에서는 API 사용자 이름과 MultiTEL 계정용으로 구성된 비밀번호를 사용합니다.
• Bearer 토큰을 Authorization: Bearer YOUR_API_TOKEN헤더로 전송합니다. 이는 토큰 인증용으로 구성된 활성화된 API 계정용입니다. 토큰 요청은 해당 API 계정에 허용된 주소에서만 허용됩니다.

IP 허용 목록이 API 계정에 구성된 경우, 허용된 주소에서 모든 요청을 전송하십시오.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

이 예제의 변수는 환경에 비공개로 저장하는 자격 증명의 자리 표시자입니다.

인증 실패 처리

인증 실패는 HTTP 상태 401로 전송됩니다. 본문은 표준 엔벌로프를 사용하며, status.code 값을 401로 설정하고, 빈 문자열을 response로 합니다.

• 자격 증명 없음: status.msg 값은 Username and password are required이며, 응답에는 Basic 인증 챌린지가 포함됩니다.
• Bearer 토큰 거부:만약 Authorization헤더가 Bearer방식을 사용하고, 토큰을 알 수 없거나, 비활성화되었거나, 귀하의 주소에서 허용되지 않은 경우, status.msg 값은 Invalid bearer token입니다. Bearer 헤더가 있는 경우 다른 자격 증명을 시도하지 않습니다.
• 잘못된 Basic 자격 증명: status.msg 값은 A valid username and password pair are required.로 시작하며, 응답에는 Basic 인증 챌린지가 포함됩니다. 메시지에는 추가 진단 텍스트가 포함될 수 있으므로 구문 분석하지 마십시오.

동일한 자격 증명으로 자동으로 다시 시도하지 마십시오. 짧은 기간에 하나의 주소에서 많은 실패가 발생하면 해당 주소의 이후 요청이 차단될 수 있습니다.

응답 본문 읽기

대부분의 v3 엔드포인트(getcountries, getstates, getareas 및 other 포함)는 다음 엔벌로프로 JSON을 반환합니다:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

이는 예시적인 국가 목록 응답이며, 현재 인벤토리나 기능을 설명하는 것이 아닙니다.

오류 응답은 다음과 같습니다:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

응답을 인코딩할 수 없는 경우, 본문은 status.code 500, status.msg Response encoding error, 빈 객체를 response로 포함합니다.

레거시 GET /v3/countries엔드포인트는 {"code": 200, "data": [...]}를 대신 반환합니다. 각 엔드포인트의 문서화된 응답을 확인하십시오. 본문이 유효한 JSON이 아닌 경우(예: 예기치 않은 서버 오류 후)에는 요청을 실패로 처리하고 나중에 다시 시도하십시오.

API 결과 코드 및 HTTP 상태

status.code 값은 API 결과 코드입니다. HTTP 상태가 아닙니다. 인증 실패는 HTTP 401로 전송됩니다. 그 외의 경우, 검색 엔드포인트는 다음과 같은 결과(404 및 500)를 status.code에서만 보고하며, 일치하는 HTTP 상태를 설정하지 않습니다. 찾을 수 없거나 매개변수가 누락된 결과는 성공적인 HTTP 상태로 도착할 수 있습니다. 반드시 status.code 값을 확인한 후 response를 사용하십시오.

결과 코드 500(메시지: ISO Code parameter is required)은 필수 매개변수가 누락되었음을 의미합니다. 서버 장애로 처리하는 대신 요청을 수정하십시오.

next_function 따르기

검색 결과에는 next_function이 포함됩니다. 이는 선행 슬래시 없는 상대 경로이며, 쿼리 문자열이 포함될 수도 있습니다(예: v3/getareas/US 또는 v3/getareas/US?state=NY) 다음 요청을 만들려면 다음 접두사를 추가하십시오: https://api.multitel.net/. 해당 요청도 동일한 방식으로 인증하십시오. 전송한 선택적 필터(예: pid)는 next_function에 전달되지 않습니다. 필요한 경우 다시 추가하십시오.

선택적 인벤토리 선택기(pid)

getcountries, getstates 및 getareas 엔드포인트는 선택적 pid쿼리 매개변수를 허용합니다. 이는 결과를 하나의 인벤토리 소스로 좁힙니다. MultiTEL이 제공한 값으로만 사용하고, 숫자 형식 또는 32자 십육진수 형식 중 하나로 지정하십시오. 일반적인 사용에서는 생략하십시오. 전송 대상은 pid입니다. 쿼리 문자열로 전송하십시오. 엔드포인트가 값을 인식하거나 허용하지 않는 경우, 오류 없이 무시되며, 요청은 pid가 생략된 경우와 동일하게 동작합니다.

검색과 주문 분리

국가, 주 및 지역 조회는 계정을 변경하지 않습니다. 특수 번호 카탈로그(other)는 카탈로그 세부 정보를 새로 고치고 계정용 가격 견적을 저장하지만, 주문하지는 않습니다. 검색 요청으로 번호가 예약되지 않으며, 인벤토리는 요청 사이에 변경될 수 있습니다. 주문 엔드포인트를 사용하기 전에 번호의 요구 사항과 가격을 검토하십시오.

구매, 할당, 메시지, 팩스 전송 및 기타 작업의 경우, 해당 엔드포인트의 자체 재시도 규칙을 따르십시오. 제출 후 작업 시간이 초과되면 반복하기 전에 해당 상태 또는 계정 기록을 확인하십시오. 손실된 응답은 작업이 실패했음을 증명하지 않습니다.