v1REST · JSON

SNSOTP OTP API

用于短信验证的 REST API。为 182 个服务之一在 154 个国家之一订购一个号码，从订单中读取一次性验证码，如果 20 分钟内未收到验证码，则全额退款。

每个端点都接受查询参数（GET）或表单字段或 JSON（POST）作为参数。响应为 JSON；金额为带两位小数的美元字符串，时间为 UTC 的 ISO 8601 格式。

服务器

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

每个服务及其验证码和最低价格 · 无需密钥

您可以订购的每个服务，包括其代码（在其他调用中用作服务）、类别和各国的最低价格。无需密钥。

请求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 小写，用作国家）和拨号代码。无需密钥。

请求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

服务、国家或两者的价格 · 无需密钥

每个国家每个服务的订单价格，或每个服务每个国家的价格，或一对价格。至少发送一个过滤器。无需密钥。

参数

  • 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

您的余额（美元） · 需要密钥

您的余额（美元）。

请求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}

一个订单的状态、验证码和短信文本 · 需要密钥

一个订单及其状态、最新验证码、最新短信文本以及迄今为止收到的所有验证码。当状态为 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

在同一号码上获取另一个验证码 · 需要密钥

在收到第一个验证码后，在窗口期内免费请求同一号码的另一个验证码。然后在应用程序中触发新的短信；在收到之前，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号码已准备好，但尚未收到短信。可以取消。
  • 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一分钟内使用一个密钥发送超过 300 个请求。
错误响应体402
{
  "error": {
    "code": "no_balance",
    "message": "Not enough credit. Add credit in the console."
  }
}

速率限制

  • 每个密钥每分钟最多 300 个请求。超过此限制后，API 将在该分钟内返回 429 rate_limited。
  • 每个账户最多 20 个未完成订单。完成或取消一个订单以打开另一个。
  • 每3到5秒轮询一次订单；验证码通常在一分钟内到达。

短信激活格式

为常见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文档：短信验证REST API | SNSOTP