API

가상번호 업계의 사실상 표준 프로토콜을 그대로 따르는 REST API입니다. 기존 클라이언트의 기본 URL과 키만 바꾸면 바로 동작합니다.

쓰던 클라이언트를 그대로 연결하세요

기본 URL과 토큰, 두 줄만 바꾸면 기존 호출이 그대로 동작합니다. 경로, 쿼리 파라미터, JSON 필드명, 오류 문자열까지 동일합니다.

기본 URL

https://otphub-api.43.203.247.133.nip.io/v1

인증

모든 요청에 API 키를 Bearer 토큰으로 보내세요.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" -H "Accept: application/json" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

빠른 시작

계정 페이지에서 키를 만들고 환경 변수로 내보낸 뒤, 번호를 구매하면 됩니다.

빠른 시작

export OTPHUB_KEY="your-api-key"

# 1. what is in stock
curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

# 2. buy a number
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook"

# 3. poll it until the code lands
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

엔드포인트

비로그인

GET/v1/guest/countries토큰 불필요

취급하는 모든 국가와 국가번호, 지원 통신사 목록입니다.

요청

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/countries"

응답

{
  "england": {
    "iso": { "gb": 1 },
    "prefix": { "+44": 1 },
    "text_en": "England",
    "text_ru": "England",
    "vodafone": { "activation": 1 }
  }
}

GET/v1/guest/products/{country}/{operator}토큰 불필요

특정 국가와 통신사에서 이용 가능한 서비스, 수량, 가격입니다. 두 구간 모두 any를 쓸 수 있습니다.

요청

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

응답

{
  "1day":     { "Category": "hosting",    "Qty": 14,  "Price": 80 },
  "facebook": { "Category": "activation", "Qty": 133, "Price": 21 }
}

GET/v1/guest/prices?country=&product=토큰 불필요

국가 → 서비스 → 통신사 순으로 중첩된 전체 가격표입니다. country나 product로 필터링할 수 있습니다.

요청

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/prices?country=england&product=facebook"

응답

{
  "england": {
    "facebook": {
      "vodafone": { "cost": 21, "count": 1260, "rate": 99.99 }
    }
  }
}

GET/v1/guest/flash/{lang}토큰 불필요

요청한 언어로 된 현재 사이트 공지입니다.

요청

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/flash/en"

계정

GET/v1/user/profileBearer 토큰

잔액, 보류 금액, 평점, 기본 설정입니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

응답

{
  "id": 1,
  "email": "you@example.com",
  "vendor": "otphub",
  "default_forwarding_number": "",
  "balance": 100,
  "rating": 96,
  "default_country": { "name": "england", "iso": "gb", "prefix": "+44" },
  "default_operator": { "name": "" },
  "frozen_balance": 0
}

GET/v1/user/orders?category=&limit=&offset=&order=&reverse=Bearer 토큰

최신순 주문 내역입니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/orders?category=activation&limit=25"

응답

{ "Data": [ /* orders */ ], "ProductNames": [], "Statuses": [], "Total": 3 }

GET/v1/user/payments?limit=&offset=&order=&reverse=Bearer 토큰

충전과 조정에 대한 원장 기록입니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/payments?limit=25"

응답

{
  "Data": [
    {
      "ID": 30011934,
      "TypeName": "charge",
      "ProviderName": "admin",
      "Amount": 100,
      "Balance": 100,
      "CreatedAt": "2026-08-17T15:37:08.149895Z"
    }
  ],
  "PaymentTypes": [{ "Name": "charge" }],
  "PaymentProviders": [{ "Name": "admin" }],
  "Total": 1
}

GET/v1/user/max-pricesBearer 토큰

서비스별로 설정한 가격 상한입니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices"

응답

[{ "id": 14, "product": "facebook", "price": 11, "CreatedAt": "2026-08-17T15:37:08Z" }]

POST/v1/user/max-pricesBearer 토큰

서비스 하나에 상한을 설정합니다. 상한을 넘는 구매는 거부됩니다.

요청

curl -X POST "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook","price":30}'

DELETE/v1/user/max-pricesBearer 토큰

상한을 삭제합니다.

요청

curl -X DELETE "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook"}'

구매

GET/v1/user/buy/activation/{country}/{operator}/{product}Bearer 토큰

일회용 인증 번호를 구매합니다. 전화번호가 포함된 주문을 반환합니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" \
  "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook?maxPrice=30"

응답

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/buy/hosting/{country}/{operator}/{product}Bearer 토큰

3hours, 1day, 10days, 1month 중 한 기간으로 번호를 대여합니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/hosting/england/any/1day"

GET/v1/user/reuse/{product}/{number}Bearer 토큰

통신사가 허용하는 경우 같은 서비스로 같은 번호를 다시 구매합니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/reuse/facebook/447350690992"

주문 관리

GET/v1/user/check/{id}Bearer 토큰

새 메시지가 있는지 주문을 조회합니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

응답

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/finish/{id}Bearer 토큰

다 쓴 주문을 닫습니다. 보류 금액이 결제됩니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/finish/11631253"

GET/v1/user/cancel/{id}Bearer 토큰

SMS가 오기 전에 취소합니다. 보류가 해제됩니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/cancel/11631253"

GET/v1/user/ban/{id}Bearer 토큰

이미 사용된 번호로 신고합니다. 보류가 해제되고 번호는 재고에서 제외됩니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/ban/11631253"

GET/v1/user/sms/inbox/{id}Bearer 토큰

대여한 번호로 수신된 모든 메시지입니다.

요청

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/sms/inbox/11631253"

응답

{
  "Data": [
    {
      "ID": 1,
      "created_at": "2026-08-17T17:23:25.106597Z",
      "date": "2026-08-17T17:23:15Z",
      "sender": "Facebook",
      "text": "Use 415127 as your login code",
      "code": "415127",
      "is_wave": false,
      "wave_uuid": ""
    }
  ],
  "Total": 1
}

주문 상태

모든 구매는 아래 상태를 거칩니다. 표기된 문자열은 API가 실제로 반환하는 값과 같습니다.

상태	설명
`PENDING`대기 중	번호가 활성 상태이며 SMS를 기다리고 있습니다.
`RECEIVED`인증번호 수신	인증번호가 한 건 이상 도착했습니다.
`CANCELED`취소됨	취소되었습니다. 보류 금액이 해제되었습니다.
`TIMEOUT`시간 초과	제한 시간 안에 SMS가 오지 않아 환불되었습니다.
`FINISHED`완료	종료되었습니다. 구매 금액이 결제되었습니다.
`BANNED`신고됨	이미 사용된 번호로 신고되어 환불되었습니다.

오류

실패하면 표준 프로토콜과 동일하게 사유만 담긴 평문을 반환합니다.

오류 본문	반환 조건
`no free phones`	해당 국가·통신사·서비스 조합의 재고가 없습니다.
`not enough user balance`	잔액이 가격에 미치지 못합니다.
`not enough rating`	평점이 0입니다. 24시간 뒤에 다시 주문할 수 있습니다.
`select country`	국가 구간이 비어 있습니다.
`select operator`	통신사 구간이 비어 있습니다.
`bad country`	카탈로그에 없는 국가 슬러그입니다.
`bad operator`	카탈로그에 없는 통신사 슬러그입니다.
`no product`	카탈로그에 없는 서비스 슬러그입니다.
`server offline`	공급사에 연결할 수 없습니다.
`order not found`	해당 ID의 주문이 이 계정에 없습니다.
`order expired`	주문이 유효 시간을 넘겼습니다.
`order has sms`	이미 메시지가 도착해 주문을 취소할 수 없습니다.
`hosting order`	대여 주문에는 사용할 수 없는 호출입니다.
`reuse not possible`	통신사가 이 번호의 재사용을 허용하지 않습니다.
`reuse false`	원 주문이 재사용 옵션 없이 구매되었습니다.
`reuse expired`	이 번호의 재사용 기간이 끝났습니다.

요청 제한

API 키당 초당 100회입니다. 반복적인 과다 호출은 일시적으로 차단됩니다.

IP당 초당 100회, 초과하면 503을 반환합니다.
API 키당 초당 100회, 초과하면 429를 반환합니다.
계정 전체 기준 초당 100건까지 구매할 수 있습니다.
10분 안에 제한에 다섯 번 걸리면 해당 키가 10분 동안 차단됩니다.

무수정 호환성

경로, JSON 구조, 오류 문자열까지 업계 표준 프로토콜과 동일합니다. 대문자로 시작하는 키와 평문 오류 본문도 그대로입니다. 기존 클라이언트 라이브러리를 수정할 필요가 없습니다.