v1REST · JSON

SNSOTP OTP API

Một REST API để xác minh SMS. Đặt một số cho một trong 182 dịch vụ tại một trong 154 quốc gia, đọc mã một lần từ đơn hàng và nhận lại toàn bộ giá tiền nếu không có mã nào đến trong 20 phút.

Mọi endpoint chấp nhận tham số dưới dạng tham số truy vấn (GET) hoặc dưới dạng trường biểu mẫu hoặc JSON (POST). Câu trả lời là JSON; tiền là chuỗi USD với hai chữ số thập phân và thời gian là ISO 8601 theo UTC.

Máy chủ

https://snsotp.com/api/v1

Xác thựcBearer token

Khóa API của bạn từ console, được gửi dưới dạng Authorization: Bearer sok_...

Xác thực

Tạo một khóa trên trang API của console. Nó bắt đầu với sok_ và chỉ hiển thị một lần, vì vậy hãy lưu trữ nó trong một biến môi trường. Thay thế khóa sẽ dừng khóa cũ ngay lập tức. Các cuộc gọi đến /services, /countries và /prices hoạt động mà không cần khóa.

Header
Authorization: Bearer sok_your_key_here

Khóa cũng có thể được gửi dưới dạng tham số truy vấn hoặc trường biểu mẫu key, điều này giúp các công cụ không thể thiết lập header.

Bắt đầu nhanh

Đặt một số, cung cấp nó cho ứng dụng, sau đó kiểm tra đơn hàng cho đến khi mã xuất hiện. Quy trình tương tự bằng bốn ngôn ngữ:

# 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

Mọi dịch vụ với mã và giá thấp nhất · không cần khóa

Mọi dịch vụ bạn có thể đặt, với mã của nó (sử dụng nó làm service trong các cuộc gọi khác), danh mục và giá thấp nhất trên các quốc gia. Không cần khóa.

Yêu cầucURL
curl https://snsotp.com/api/v1/services
Phản hồi200
{
  "services": [
    { "code": "whatsapp", "name": "WhatsApp", "category": "social", "from": "0.09" },
    { "code": "telegram", "name": "Telegram", "category": "social", "from": "0.03" }
  ]
}

GET/countries

Mọi quốc gia với mã và mã quay số · không cần khóa

Mọi quốc gia với mã của nó (ISO 3166 alpha-2 viết thường, sử dụng nó làm country) và mã quay số. Không cần khóa.

Yêu cầucURL
curl https://snsotp.com/api/v1/countries
Phản hồi200
{
  "countries": [
    { "code": "us", "name": "United States", "dial_code": "1" },
    { "code": "gb", "name": "United Kingdom", "dial_code": "44" }
  ]
}

GET/prices

Giá cho một dịch vụ, một quốc gia hoặc cả hai · không cần khóa

Giá mỗi đơn hàng cho một dịch vụ tại mọi quốc gia, một quốc gia cho mọi dịch vụ hoặc một cặp. Gửi ít nhất một bộ lọc. Không cần khóa.

Tham số

  • servicestring

    Mã dịch vụ, ví dụ whatsapp

  • countrystring

    Mã quốc gia, ví dụ us

Yêu cầucURL
curl "https://snsotp.com/api/v1/prices?service=whatsapp&country=us"
Phản hồi200
{
  "prices": [
    { "service": "whatsapp", "country": "us", "price": "0.93" }
  ]
}

GET/balance

Số dư của bạn bằng USD · cần khóa

Số dư của bạn bằng USD.

Yêu cầucURL
curl https://snsotp.com/api/v1/balance \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "balance": "42.50",
  "currency": "USD"
}

POST/orders

Đặt một số cho một dịch vụ và một quốc gia · cần khóa

Đặt một số và tính phí của nó. Câu trả lời có số đầy đủ (phone) và không có mã quay số (number). Đơn hàng vẫn mở trong 20 phút; nếu không có mã trong thời gian đó, giá tiền sẽ tự động trả lại vào số dư của bạn. Trạng thái phản hồi 201.

Tham số

  • servicestringbắt buộc

    Mã dịch vụ từ GET /services

  • countrystringbắt buộc

    Mã quốc gia từ GET /countries

Yêu cầucURL
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us
Phản hồi201
{
  "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}

Trạng thái, mã và văn bản SMS của một đơn hàng · cần khóa

Một đơn hàng với trạng thái của nó, mã mới nhất, tin nhắn SMS mới nhất và mọi mã đã nhận cho đến nay. Kiểm tra mỗi 3 đến 5 giây trong khi trạng thái là waiting.

Tham số

  • idpathbắt buộc

    ID đơn hàng từ POST /orders

Yêu cầucURL
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "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

Các đơn hàng mở của bạn (hoặc tất cả với status=all) · cần khóa

Các đơn hàng mở của bạn, mới nhất trước. Thêm status=all cho các đơn hàng gần đây trong mọi trạng thái.

Tham số

  • statusstring

    mở (mặc định) hoặc tất cả

  • limitnumber

    1 đến 100, mặc định 50

Yêu cầucURL
curl "https://snsotp.com/api/v1/orders?status=open" \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "orders": [
    { "id": "OT-7K2M9QX4PB", "service": "whatsapp", "status": "received", "code": "284913" }
  ]
}

POST/orders/{id}/resend

Mã khác trên cùng một số · cần khóa

Yêu cầu một mã khác trên cùng một số sau mã đầu tiên, trong cửa sổ, mà không tính thêm phí. Sau đó kích hoạt một SMS mới trong ứng dụng; waiting_for_resend là true cho đến khi nó đến.

Tham số

  • idpathbắt buộc

    ID đơn hàng

Yêu cầucURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/resend \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "received", "waiting_for_resend": true }
}

POST/orders/{id}/finish

Đóng đơn hàng sau khi bạn sử dụng mã · cần khóa

Đóng một đơn hàng đã nhận mã sau khi bạn đã sử dụng nó. Hoàn thành là tùy chọn: các đơn hàng mở sẽ tự động đóng khi cửa sổ kết thúc.

Tham số

  • idpathbắt buộc

    ID đơn hàng

Yêu cầucURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/finish \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "finished" }
}

POST/orders/{id}/cancel

Hủy trước khi nhận mã, hoàn tiền đầy đủ · cần khóa

Hủy một đơn hàng trước khi mã đến và trả lại toàn bộ giá tiền vào số dư của bạn ngay lập tức. Sau khi có mã, hủy trả lời has_code.

Tham số

  • idpathbắt buộc

    ID đơn hàng

Yêu cầucURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/cancel \
  -H "Authorization: Bearer $SNSOTP_KEY"
Phản hồi200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "canceled", "refunded": "0.93" }
}

Trạng thái đơn hàng

giá trị trạng thái
  • waitingSố đã sẵn sàng và chưa có SMS nào đến. Hủy là có thể.
  • receivedÍt nhất một mã đã đến. code và sms giữ mã mới nhất.
  • finishedĐóng sau khi có mã, bằng finish hoặc khi cửa sổ kết thúc.
  • refundedKhông có mã nào đến trong 20 phút. Toàn bộ giá tiền đã trả lại vào số dư của bạn.
  • canceledĐã hủy trước khi có mã. Toàn bộ giá tiền đã trả lại vào số dư của bạn.

Lỗi

Lỗi sử dụng trạng thái HTTP và một phần thân với mã ổn định và thông báo dễ đọc.

Trạng thái HTTP và mã
  • 400missing_filter, bad_jsonMột giá trị bắt buộc bị thiếu hoặc không thể đọc phần thân.
  • 401no_key, bad_keyKhóa bị thiếu, sai hoặc đã bị xóa.
  • 402no_balanceKhông đủ số dư cho đơn hàng này. Thêm số dư trong console.
  • 404unknown_service, unknown_country, not_sold, not_foundMã hoặc đơn hàng không tồn tại, hoặc cặp không được bán.
  • 409too_many_open, has_code, not_ready, no_numbersHành động không phù hợp với trạng thái đơn hàng, hoặc không có số nào miễn phí ngay bây giờ (không tính phí).
  • 429rate_limitedHơn 300 yêu cầu trong một phút với một khóa.
Phần thân lỗi402
{
  "error": {
    "code": "no_balance",
    "message": "Not enough credit. Add credit in the console."
  }
}

Giới hạn tốc độ

  • 300 yêu cầu mỗi phút mỗi khóa. Trên đó API trả lời 429 rate_limited trong phần còn lại của phút.
  • Tối đa 20 đơn hàng mở mỗi tài khoản. Hoàn thành hoặc hủy một đơn hàng để mở một đơn hàng khác.
  • Kiểm tra đơn hàng mỗi 3 đến 5 giây; mã thường đến trong vòng một phút.

Định dạng kích hoạt SMS

Các script viết cho định dạng handler_api.php phổ biến hoạt động với cùng API key: thay đổi địa chỉ cơ sở thành https://snsotp.com/stubs/handler_api.php và giữ nguyên các hành động. Mã dịch vụ và quốc gia giống như trong REST API.

Hành động

  • getBalance

    ACCESS_BALANCE:42.50

  • getServicesList

    Danh sách dịch vụ dạng JSON

  • getCountries

    Bản đồ quốc gia dạng JSON

  • getPricesservice, country (tùy chọn)

    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

Yêu cầucURL
curl "https://snsotp.com/stubs/handler_api.php\
?api_key=$SNSOTP_KEY&action=getNumber\
&service=telegram&country=gb"

ACCESS_NUMBER:OT-3QF8ZK2W7M:447700900182

Giá trị setStatus: 1 sẵn sàng, 3 mã khác, 6 hoàn thành, 8 hủy với hoàn tiền đầy đủ.

Tài liệu API OTP: API Xác minh SMS REST | SNSOTP