사용 가능한 전화번호 찾기

개별 프리픽스 선택

국가 및 서비스 제공 영역을 조회하는 API를 호출한 다음, getprefixes를 그룹화 없이 호출하세요. 선택한 프리픽스의 uuid를 복사하세요. 만약 returns_numbers 값이 0이면 해당 프리픽스는 주문 시 번호를 할당합니다. 개별 번호 목록을 요구하지 말고 반환된 next_function을 사용하세요.

크기를 제한한 결과 묶음 조회

일반적인 검색에는 compact=1을 사용하고, 아래 예시처럼 원하는 결과 묶음 크기를 경로와 quantity 쿼리 양쪽에 지정하세요. 페이지나 커서 매개변수는 없습니다. 간략한 응답의 결과는 표본이며, 요청을 반복해도 이전 결과와 겹치지 않는 다음 페이지가 반환된다고 보장되지 않습니다. 결과가 비어 있거나 적다고 해서 이를 전체 재고 수로 해석하지 마세요.

기억하기 쉬운 숫자 패턴 찾기

다음 중 하나를 지정하세요: number_filter_mode=contains 또는 ends_with. 함께 지정할 매개변수는 number_filter_value입니다. 값은 1–15자리 숫자여야 합니다. 검색은 제한된 후보 묶음을 가져온 후 필터를 적용할 수 있으므로, 조건에 맞는 다른 재고를 놓칠 수 있습니다. 필요한 검색을 지원하는 공급원에서 해당 검색을 수행하도록 해야 한다면 MultiTEL에서 pid 선택자를 받아 filter_required=1을 사용하세요. 선택이 없거나 지원되지 않는 선택이면 API 오류가 반환됩니다.

선택한 번호 검토

동일한 결과에서 다음 항목을 확인하세요: number, info.uuid, 선택한 price[].uuid, 사용 가능한 기능 이름 및 등록 요건. price 배열에는 채널 수와 요율이 서로 다른 여러 요금제가 포함될 수 있습니다. 금액 필드와 수량은 문자열로 인코딩될 수 있습니다. 선택적 메타데이터는 공급원에 따라 다르며, 여기에는 info.state도 포함됩니다. 모든 경우에 동일한 주 정보 구조를 요구하거나 ID에서 가격을 추론하지 마세요.

비스트리밍 처리 경로에서는 후보의 중복을 제거하고 공급원 간에 할당한 후, 선택된 결과 묶음을 첫 번째 요금제의 월 요금을 기준으로 정렬합니다. 다른 처리 경로에서는 더 이른 시점에 스트리밍이 시작될 수 있으므로, 모든 요청에 대해 전체 결과의 정렬이나 중복 제거가 보장되지는 않습니다. 정렬되었다고 해서 반환된 표본에 전체 카탈로그에서 가장 저렴한 번호가 포함되어 있다는 뜻도 아닙니다.

별도로 주문하고 결과 확인

검색만으로는 아무것도 구매되거나 예약되지 않습니다. 동일한 계정에서 주문 절차를 진행할 수 있도록 반환된 번호와 요금제 식별자를 보관하세요. 주문을 제출하기 전에 실제 요금제, 요건 및 비용을 검토하세요. 등록 요건으로 인해 개통이 지연될 수 있으며, 검색 결과가 특정 개통 기한을 확정하지는 않습니다.

요청

활성화된 MultiTEL API 계정을 사용하세요. 비밀번호 방식 계정에는 HTTP Basic 인증 정보를, 토큰 방식 계정에는 Authorization: Bearer를 사용합니다. 계정 권한과 해당 계정의 IP 제한이 적용됩니다. 공통 인증 안내를 참조하세요.

경로 매개변수와 URL 쿼리 매개변수를 사용합니다. 공개 검색 절차에는 GET을 사용하세요. 핸들러는 일부 폼/요청 값도 허용하지만, JSON 본문을 사용하는 검색 API는 아닙니다.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

응답

status와 response를 포함하는 하나의 JSON 객체입니다. 성공 시 status.code는 200이고 response는 번호 항목의 배열입니다. status.results는 반환된 배열의 항목 수입니다. status.msg는 Results: N일 수 있으며, 스트리밍 응답에서는 OK일 수 있습니다. compact=1을 지정하지 않으면 일부 검색은 response 배열을 점진적으로 출력하고 마지막에 status를 출력하므로, 전체 JSON 본문을 받을 때까지 기다리세요. 이는 줄바꿈으로 구분된 JSON이 아닙니다. HTTP 전송이 성공해도 status.code를 확인하세요. 일반적인 필드는 아래에 나와 있으며, 공급원별 메타데이터와 선택적 필드는 달라집니다. 모든 식별자는 내부 의미를 추론하지 말고 그대로 취급하며, 번호와 해당 번호에 대해 선택한 price[].uuid를 함께 보관하세요.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

오류

• 401: 인증에 실패했습니다. 인증 정보가 잘못되었거나 누락된 경우, 또는 API 계정 접근이 거부된 경우에는 검색 결과가 제공되지 않습니다.
• 404: Invalid prefix ID, Invalid country, Invalid area 또는 No numbers found. status.msg를 확인하세요. 오류 응답은 번호 배열이 아닙니다.
• 400: NUMBER_FILTER_INVALID가 response.code에 반환됩니다. 모드가 잘못되었거나, 값이 1–15자리 숫자가 아니거나, 모드와 값을 모두 지정하지 않은 채 filter_required를 지정한 경우입니다.
• 422: NUMBER_FILTER_UNSUPPORTED가 response.code에 반환됩니다. 해당 프리픽스가 주문 시 번호를 할당하거나(reason=order_only_prefix이며 next_function이 주문 경로를 나타냄), 명시적으로 선택한 공급원이 필수 필터를 지원할 수 없는 경우입니다.

가용성과 부수 효과

• 이 핸들러는 검색하고 견적을 준비하며, 번호 주문을 제출하거나 번호 구매 대금을 차감하지 않습니다. 카탈로그 캐시를 갱신하고, 오래된 캐시 재고를 제거하고, 계정별 요금제를 저장하고, 검색 로그를 기록할 수 있습니다.
• 가용성은 특정 시점의 결과이며 예약이 아닙니다. 이후 주문이 실패하거나 다른 가용성 결과가 반환될 수 있습니다. 구매를 다시 시도하기 전에 주문 결과를 대조하여 실제 처리 상태를 확인하세요.
• 가격은 계정별로 다릅니다. 동일한 계정에서 사용할 수 있도록 선택한 요금제 ID를 보관하고, 주문 조건과 비용을 별도로 검토하세요. 이 엔드포인트만으로는 이후 주문 시점까지 가격이 유효하게 유지된다는 것을 확인할 수 없습니다.
• 예시 번호와 가격은 응답 구조를 보여 주기 위한 가상의 예시이며 실제 견적이 아닙니다. 기능, 채널 수, 계약 기간 및 등록 정보는 실제로 선택한 결과에서 확인해야 합니다.
• 일부 등록 설명에는 서식이 있는 텍스트나 링크가 포함되어 있습니다. 자체 애플리케이션에 표시할 때는 반환된 문자열을 신뢰할 수 없는 데이터로 취급하세요.
• 모바일 번호의 제공 여부와 플래그는 계정의 이용 자격 및 재고에 따라 달라집니다. 카탈로그의 프리픽스나 is_mobile 플래그만으로 특정 번호의 모바일 기능을 확인할 수는 없습니다.