v1REST · JSON

SNSOTP OTP API

一個用於 SMS 驗證的 REST API。為 182 個服務中的一個在 154 個國家中的一個訂購一個號碼，從訂單中讀取一次性代碼，並在 20 分鐘內未收到代碼時獲得全額退款。

每個端點接受查詢參數（GET）或表單字段或 JSON（POST）作為參數。回答是 JSON；金額是帶有兩位小數的美元字符串，時間是 UTC 的 ISO 8601 格式。

伺服器

https://snsotp.com/api/v1

認證Bearer token

來自控制台的 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}

一個訂單的狀態、驗證碼和 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在代碼到達後關閉，通過完成或窗口結束。
  • refunded在 20 分鐘內未收到代碼。全額已返還到您的餘額中。
  • 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 秒查詢一次訂單；驗證碼通常在一分鐘內到達。

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