v1REST · JSON

SNSOTP OTP API

SMS 인증을 위한 REST API예요. 182개의 서비스 중 하나와 154개 국가 중 하나에서 번호를 주문하고, 주문에서 일회용 코드를 읽어요. 그리고 20분 안에 코드가 도착하지 않으면 전체 금액을 돌려받을 수 있어요.

모든 엔드포인트는 쿼리 파라미터(GET) 또는 폼 필드 또는 JSON(POST)으로 파라미터를 받아요. 응답은 JSON 형식이고, 금액은 소수점 두 자리까지의 USD 문자열로, 시간은 ISO 8601 형식의 UTC로 표시돼요.

서버

https://snsotp.com/api/v1

인증Bearer 토큰

콘솔에서 가져온 API 키를 Authorization: Bearer sok_...로 보내세요.

인증

콘솔의 API 페이지에서 키를 생성해요. sok_로 시작하며 한 번만 표시되므로 환경 변수에 저장해 두세요. 키를 교체하면 이전 키는 즉시 중지돼요. /services, /countries, /prices 호출은 키 없이도 작동해요.

헤더
Authorization: Bearer sok_your_key_here

키는 key 쿼리 파라미터나 폼 필드로도 보낼 수 있어요. 헤더를 설정할 수 없는 도구에서 유용해요.

빠른 시작

번호를 주문해 앱에 입력한 뒤, 코드가 올 때까지 주문을 폴링하세요. 같은 흐름을 네 가지 언어로 보여 드려요:

# 1. Order a number for whatsapp in US
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us

# 2. Read the code (poll every 3 to 5 seconds)
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"

GET/services

모든 서비스의 코드와 최저 가격 · 키 없음

주문할 수 있는 모든 서비스와 코드(다른 호출에서 service로 사용하세요), 카테고리, 그리고 국가별 최저 가격을 확인할 수 있어요. API 키가 필요하지 않아요.

요청cURL
curl https://snsotp.com/api/v1/services
응답200
{
  "services": [
    { "code": "whatsapp", "name": "WhatsApp", "category": "social", "from": "0.09" },
    { "code": "telegram", "name": "Telegram", "category": "social", "from": "0.03" }
  ]
}

GET/countries

모든 국가의 코드와 국가 번호 · 키 없음

모든 국가의 코드(ISO 3166 alpha-2 소문자, country 값으로 사용)와 국가 번호예요. 키가 필요 없어요.

요청cURL
curl https://snsotp.com/api/v1/countries
응답200
{
  "countries": [
    { "code": "us", "name": "United States", "dial_code": "1" },
    { "code": "gb", "name": "United Kingdom", "dial_code": "44" }
  ]
}

GET/prices

서비스, 국가 또는 둘 다에 대한 가격 · 키 없음

한 서비스에 대해 모든 국가에서, 한 국가에 대해 모든 서비스에서, 또는 한 쌍에 대해 주문당 가격이에요. 최소 하나의 필터를 보내세요. API 키가 필요 없어요.

매개변수

  • servicestring

    서비스 코드, 예: whatsapp

  • countrystring

    국가 코드, 예: us

요청cURL
curl "https://snsotp.com/api/v1/prices?service=whatsapp&country=us"
응답200
{
  "prices": [
    { "service": "whatsapp", "country": "us", "price": "0.93" }
  ]
}

GET/balance

USD 기준 크레딧 · 키 필요

USD 크레딧 잔액이에요.

요청cURL
curl https://snsotp.com/api/v1/balance \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "balance": "42.50",
  "currency": "USD"
}

POST/orders

서비스와 국가를 골라 번호 주문 · 키 필요

번호를 주문하고 가격을 차감해요. 응답에는 전체 번호(phone)와 국가 코드를 제외한 번호(number)가 포함돼요. 주문은 20분 동안 열려 있어요; 이 시간 동안 코드가 도착하지 않으면 가격이 자동으로 크레딧으로 환불돼요. 응답 상태는 201이에요.

매개변수

  • servicestring필수

    GET /services에서 가져온 서비스 코드

  • countrystring필수

    GET /countries에서 가져온 국가 코드

요청cURL
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us
응답201
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "dial_code": "1",
    "price": "0.93",
    "status": "waiting",
    "code": null,
    "sms": null,
    "codes": [],
    "expires_at": "2026-11-03T12:20:00.000Z"
  },
  "window_minutes": 20
}

GET/orders/{id}

하나의 주문에 대한 상태, 코드 및 SMS 텍스트 · 키 필요

하나의 주문과 그 상태, 최신 코드, 최신 SMS 텍스트, 그리고 지금까지 받은 모든 코드를 확인할 수 있어요. 상태가 waiting인 동안 3~5초마다 폴링하세요.

매개변수

  • idpath필수

    POST /orders에서 가져온 주문 ID

요청cURL
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "price": "0.93",
    "status": "received",
    "code": "284913",
    "sms": "Your WhatsApp code is 284913",
    "expires_at": "2026-11-03T12:20:00.000Z"
  }
}

GET/orders

열린 주문 (또는 status=all로 모든 주문) · 키 필요

진행 중인 주문을 최신순으로 확인할 수 있어요. 모든 상태의 최근 주문을 보려면 status=all을 추가하세요.

매개변수

  • statusstring

    open (기본값) 또는 all

  • limitnumber

    1~100, 기본값 50

요청cURL
curl "https://snsotp.com/api/v1/orders?status=open" \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "orders": [
    { "id": "OT-7K2M9QX4PB", "service": "whatsapp", "status": "received", "code": "284913" }
  ]
}

POST/orders/{id}/resend

같은 번호로 다른 코드 받기 · 키 필요

첫 코드 뒤, 코드 대기 시간 안에 같은 번호로 다른 코드를 추가 비용 없이 요청해요. 그다음 앱에서 새 SMS를 보내게 하세요. 도착할 때까지 waiting_for_resend가 true예요.

매개변수

  • idpath필수

    주문 ID

요청cURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/resend \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "received", "waiting_for_resend": true }
}

POST/orders/{id}/finish

코드를 사용한 후 주문 종료 · 키 필요

코드를 받아 사용한 주문을 닫아요. 완료는 선택이에요: 열린 주문은 코드 대기 시간이 끝나면 자동으로 닫혀요.

매개변수

  • idpath필수

    주문 ID

요청cURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/finish \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "finished" }
}

POST/orders/{id}/cancel

코드 전 취소 시 전액 환불 · 키 필요

코드가 도착하기 전에 주문을 취소하면 전체 금액이 즉시 크레딧으로 돌아가요. 코드가 도착한 후에는 취소 요청에 has_code 응답이 와요.

매개변수

  • idpath필수

    주문 ID

요청cURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/cancel \
  -H "Authorization: Bearer $SNSOTP_KEY"
응답200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "canceled", "refunded": "0.93" }
}

주문 상태

상태 값
  • waiting번호가 준비되었지만 아직 SMS가 도착하지 않았어요. 취소가 가능해요.
  • received최소 하나의 인증 코드가 도착했어요. code와 sms에는 가장 최근 코드가 저장되어 있어요.
  • finished코드 수신 후, 완료 시 또는 코드 대기 시간이 종료된 후에 닫혔어요.
  • refunded20분 안에 코드가 도착하지 않았어요. 전체 금액이 크레딧으로 돌아왔어요.
  • canceled코드가 도착하기 전에 취소했어요. 전체 금액이 크레딧으로 돌아왔어요.

오류

에러는 HTTP 상태와 함께 안정적인 코드와 읽기 쉬운 메시지가 포함된 본문을 사용해요.

HTTP 상태 및 코드
  • 400missing_filter, bad_json필수 값이 누락되었거나 본문을 읽을 수 없어요.
  • 401no_key, bad_key키가 누락되었거나, 잘못되었거나, 삭제되었어요.
  • 402no_balance이 주문을 하기에는 크레딧이 부족해요. 콘솔에서 크레딧을 충전하세요.
  • 404unknown_service, unknown_country, not_sold, not_found인증 코드나 주문이 존재하지 않거나, 해당 조합이 판매되지 않았어요.
  • 409too_many_open, has_code, not_ready, no_numbers해당 작업이 주문 상태와 맞지 않거나, 현재 사용 가능한 번호가 없어요(요금이 청구되지 않아요).
  • 429rate_limited한 키로 1분에 300회를 넘게 요청했어요.
오류 본문402
{
  "error": {
    "code": "no_balance",
    "message": "Not enough credit. Add credit in the console."
  }
}

요청 한도

  • 키당 분당 300회 요청이 가능해요. 이를 초과하면 API는 해당 분 동안 429 rate_limited로 응답해요.
  • 계정당 최대 20개의 주문을 열 수 있어요. 새로운 주문을 하려면 기존 주문을 완료하거나 취소하세요.
  • 주문을 3~5초마다 폴링하세요. 코드는 보통 1분 이내에 도착해요.

SMS 액티베이션 형식

널리 쓰이는 handler_api.php 형식으로 작성한 스크립트도 같은 API 키로 작동해요. 기본 주소만 https://snsotp.com/stubs/handler_api.php로 바꾸고 액션은 그대로 두세요. 서비스와 국가 코드는 REST API와 같아요.

액션

  • getBalance

    ACCESS_BALANCE:42.50

  • getServicesList

    서비스 JSON 목록

  • getCountries

    국가 JSON 맵

  • getPricesservice, country (선택 사항)

    JSON {country: {service: {cost, count}}}

  • getNumberservice, country

    ACCESS_NUMBER:<id>:<phone>

  • getStatusid

    STATUS_WAIT_CODE, STATUS_OK:<code>, STATUS_WAIT_RETRY:<code>, STATUS_CANCEL

  • setStatusid, status 1 / 3 / 6 / 8

    ACCESS_READY, ACCESS_RETRY_GET, ACCESS_ACTIVATION, ACCESS_CANCEL

요청cURL
curl "https://snsotp.com/stubs/handler_api.php\
?api_key=$SNSOTP_KEY&action=getNumber\
&service=telegram&country=gb"

ACCESS_NUMBER:OT-3QF8ZK2W7M:447700900182

setStatus 값: 1 준비, 3 다른 코드, 6 완료, 8 전체 환불로 취소.

OTP API 문서: SMS 인증 REST API | SNSOTP