프리픽스로 전화번호 주문하기

프리픽스로 주문하기

프리픽스 카탈로그에서 사용 가능한 번호를 개별적으로 선택하는 대신 프리픽스에서 수량을 지정해 주문하도록 안내하는 경우 이 작업을 사용합니다. 먼저 국가, 지역 또는 주, 그리고 프리픽스부터 확인하세요. 동일한 최신 조회 결과의 프리픽스 식별자와 요금제를 함께 보관하세요. 사용 가능한 번호 목록에서 선택한 특정 번호를 구매하려면 다음 안내를 사용하세요: 선택한 전화번호 구매하기.

이 요청으로 번호가 구매되고 요금이 발생할 수 있습니다. 가격 견적, 예약 또는 모의 실행이 아닙니다. 제출하기 전에 개통비와 월 요금, 수신 통화의 분당 요금, 기본 제공 통화 시간, 채널, 등록 요건 및 계정의 구매 한도를 검토하세요. 카탈로그 조회 결과는 재고를 예약하거나 가격을 고정하지 않습니다. 주문 이행 전에 계정 자금 충전 관련 확인이 이루어질 수 있으며, 오류가 발생했다는 사실만으로 구매나 계정 자금 충전이 이루어지지 않았다고 단정할 수는 없습니다.

구매 요청 제출하기

허용된 출발지 IP 주소에서 HTTPS를 통해 활성화된 API 계정을 사용하세요. 현재 카탈로그에서 선택한 항목과 승인된 전달 설정을 바탕으로 변수를 설정하세요. 다음 명령은 번호 하나를 구매합니다.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

위 예시는 폼 POST 방식입니다. 조정 처리기는 Content-Type이 application/json인 경우 JSON 객체도 읽습니다. JSON 필드는 일치하는 폼/요청 필드보다 우선합니다. 하나의 인코딩 방식을 일관되게 사용하고, 쿼리와 본문에 서로 충돌하는 값을 보내지 마세요.

전달 및 갱신 설정

포털에서 해당 번호에 사용할 것과 동일한 전달 설정을 선택하세요. 이는 고급 설정값이며, 호스팅 PBX나 오리지네이션 트렁크를 생성하라는 지침이 아닙니다. 정상 작동이 확인된 계정 설정을 재사용하고 구매 후 저장된 번호를 확인하세요. 구매가 수락되었다는 사실만으로 음성 또는 SMS 전달이 작동한다고 확인할 수는 없습니다.

이 필드들은 정규화되어 구매 처리에 전달되지만, 저장 여부와 방식은 재고 처리 경로에 따라 다릅니다. 현재 주문 경로는 선택한 번호 구매 안내의 엄격한 견적 상한 필드를 동등한 보호 장치로 제공하지 않습니다. 계정의 구매 권한과 가격 한도를 사용하고, 최종적으로 저장된 번호 설정을 확인하세요.

전체 결과 확인하기

HTTP 요청이 성공하더라도 JSON 본문을 파싱하고 status.code 및 status.msg를 확인하세요. 이 경로는 자체 JSON 응답을 작성하며, 공통 응답 도우미 역시 애플리케이션 코드를 HTTP 상태에 반드시 대응시키지는 않습니다. 애플리케이션 코드는 JSON 숫자 또는 숫자로 된 문자열일 수 있습니다. status.results를 필수 항목으로 간주하지 마세요. 일반적인 주문 결과에는 이 항목이 없습니다.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

위의 식별자, 번호 및 가격은 가상의 예시입니다. 주문 ID는 내부 구조나 의미를 해석하지 않는 불투명한 값으로 취급하세요. numbers에는 이 응답에서 구매되었다고 보고하는 번호가 나열됩니다. 목록의 길이를 요청한 수량과 비교하세요. 가격 금액은 문자열이며, 이 응답은 per_minute를 포함한 금전적 요율을 소수점 둘째 자리로 반올림합니다. 원래 요율의 정밀도를 확인하려면 최신 카탈로그를 사용하세요. 기본 제공 통화 시간과 채널 수는 숫자 값 또는 숫자로 된 문자열로 반환될 수 있습니다.

가격 블록은 응답을 구성하는 데 사용된 선택 요금제를 설명하며, 각 번호의 상세 청구서나 주문 총액을 나타내는 것이 아닙니다. 여러 재고 후보의 요금제는 서로 다를 수 있습니다. 이 블록의 금액을 곱한 결과가 최종 총액을 입증한다고 가정하지 말고, 구매한 개별 번호와 계정 거래 내역을 대조하여 확인하세요.

부분 구매 및 불확실한 결과

애플리케이션 코드 200과 함께 경고가 표시되고 요청한 수량보다 적은 번호가 반환될 수 있습니다. 이후에 실패가 발생하더라도 이미 구매한 번호가 취소되지는 않습니다. 반환된 주문 ID, 번호 및 메시지를 보관하세요. 남은 수량을 주문할지 결정하기 전에 해당 번호를 보유 번호 목록 및 계정 거래 내역과 대조하여 확인하세요.

제출 후 발생한 시간 초과, 요청 연결 끊김, 잘못된 형식의 응답 또는 오류는 아무 일도 일어나지 않았다는 증거가 아닙니다. 동일한 참조값을 사용하더라도 다른 구매 요청을 자동으로 제출하지 마세요. 원래 요청과 참조값, 반환된 주문 ID가 있다면 그 ID를 보관하고, 보유 번호 목록과 계정 거래 내역을 확인하세요. 결과가 여전히 불확실하면 지원팀에 문의하세요.

확정되지 않은 주문은 아직 확인 중이라는 문구와 함께 애플리케이션 코드 400을 반환할 수 있습니다. 반환된 주문 ID를 보관하고 해당 구매 내역을 대조하여 확인하세요. 이는 요청을 다시 제출하라는 지시가 아닙니다. 기록된 주문의 복구 처리는 내부적으로 원래 주문을 추적합니다. 이 작업에 대한 새 요청은 참조값을 바탕으로 주문을 재개하는 것이 아니라 별도의 구매 시도를 생성하므로, 추가 번호가 구매되고 요금이 청구될 수 있습니다. 상태 확인이나 재고 검색을 위해 구매 요청을 반복하지 마세요.

등록 및 활성화

구매되거나 할당된 번호도 등록 또는 활성화가 추가로 필요할 수 있습니다. needs_registration이 1이면 restrictions 및 registration_requirements를 확인하세요. 후자는 다음 항목을 지정할 수 있습니다: v3/get_requirements 및 해당 country, number_type 값. 수신 통화나 메시징을 사용하기 전에 해당 신원/주소 확인 절차를 완료하고 번호의 상태를 확인하세요.

features는 제공된다고 안내된 기능을 설명합니다. 실제 라우팅, 캠페인 승인, SMS 전달 또는 팩스 수신을 검증하지는 않습니다. 저장된 전달 설정을 확인하고 번호가 활성화되면 해당 서비스에 적합한 테스트를 수행하세요.

주문 콜백

콜백은 주문 상태와 응답을 포함하는 JSON을 POST 방식으로 전송하며, 참조값이 제공된 경우 이를 추가합니다. 부분 결과를 포함하여 구매되었다고 보고된 건에 대해 전송됩니다. 콜백 실패로 구매가 롤백되지는 않습니다. 전달이 재시도될 수 있으므로, 다른 구매 요청을 보내는 대신 주문 ID를 기준으로 중복을 처리하고 번호를 대조하여 확인하세요.

이 경로는 콜백에 암호학적 서명을 추가하지 않습니다. 콜백은 인증을 거쳐 조회한 보유 번호 목록과 대조하여 확인하기 위한 알림으로 취급하고, 요금 청구, 서비스 개통 또는 접근 권한 부여를 독립적으로 승인하는 근거로 삼지 마세요. 콜백 URL에 API 인증 정보를 넣지 마세요. 다른 콜백 URL로 구매 요청을 다시 제출해도 원래 주문이 갱신되지 않으며, 별도의 구매 시도가 생성됩니다. 지원팀에 콜백 조사를 요청할 때는 원래 주문 ID를 보관하여 사용하세요.

처리해야 할 실패 상황