v1REST · JSON

SNSOTP OTP API

一個用於簡訊驗證的 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}

單一訂單的狀態、驗證碼和簡訊內容 · 需要金鑰

一個訂單及其狀態、最新驗證碼、最新簡訊文本以及迄今為止收到的所有驗證碼。在狀態為 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在收到驗證碼後關閉，通過完成或窗口結束。
  • 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