选择语言

开发者 API 快速入门

从你自己的软件中购买号码并读取验证码。按步骤创建密钥、查询价格、购买号码、等待短信并完成。

本页内容
  1. 谁可以使用
  2. 1. 创建 API 密钥
  3. 2. 身份验证
  4. 3. 查询余额和价格
  5. 4. 购买号码
  6. 5. 等待短信
  7. 6. 完成或取消
  8. 状态值
  9. 错误

SmsGrab 开发者 API 通过基于 JSON 的 REST API,为你的软件提供与 App 中相同的号码。你支付与 App 相同的价格,再扣除你的 批发折扣,从你普通的 SmsGrab 余额中支付,并享有同样的自动退款保障。

谁可以使用

  • 邮箱地址 已验证 的邮箱账号。访客账号无法创建密钥。
  • 未受限制的账号。

1. 创建 API 密钥

在网站上打开 账号 > 开发者,或在 App 中打开 设置 > 开发者 API,然后创建密钥。为了安全,你需要用密码确认;如果开启了两步验证,还需要输入验证码。只读工具请选择 read 权限范围,需要购买号码请选择 read 和 purchase。

密钥以 sgk_ 开头,且只显示 一次。请把它保存在服务器的密钥存储中。请参阅 API 密钥与安全。

2. 身份验证

基础 URL 为 https://smsgrab.com/api/dev/v1。将密钥作为 Bearer 令牌发送,或放在 X-Api-Key 请求头中:

HTTP
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

密钥应该放在服务器上。切勿把它放进网站、浏览器扩展或你分发给他人的 App 中。

3. 查询余额和价格

Bash
export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"
Bash
curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

金额始终以 USD 的 最小单位 表示,因此 24 表示 0.24 USD。price_minor 是含批发折扣的你的价格,retail_price_minor 是 App 中的标价。

JSON
{ "currency": "USD", "discount_percent": 5,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. 购买号码

Bash
curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":24}'
  • service 和 country 接受我们的 ID,例如 whatsapp 和 indonesia。国家也接受 ID 这样的 ISO 代码。
  • max_price_minor 可以保护你:如果价格上涨,不会扣除任何费用,你会收到 409 PRICE_CHANGED。
  • Idempotency-Key 让重试变得安全。用同一个键重复请求会返回第一次的结果,而不会重复购买。

响应为 201 Created,并附带激活信息:

JSON
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 24, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. 等待短信

不要在紧凑的循环中反复查询,而是让 API 将请求保持最多 30 秒,直到有变化为止:

Bash
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

消息到达时,status 会变为 CODE_RECEIVED,sms 中包含目前为止的所有消息:

JSON
{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

比起轮询更喜欢推送?请设置 Webhook。

6. 完成或取消

Bash
curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"
  • 用完验证码后调用 finish。只有在验证码到达后才会被接受。
  • 仍在等待第一条验证码时调用 cancel。全部费用都会退回。
  • 如果你什么都不做,没有验证码的号码会在 expires_at 指定的时间到期并自动退款。有效时长因服务和国家而异,请始终读取 expires_at,不要假定固定时长。

状态值

状态 含义
WAITING_SMS 已购买,等待第一条消息
CODE_RECEIVED 已收到至少一条消息
COMPLETED 由你完成,或收到验证码后时间结束
CANCELLED 在任何验证码前取消,已退款
EXPIRED 到 expires_at 仍没有验证码,已退款

错误

所有错误的格式都相同。请根据 code 和 reason 处理,并忽略你尚不认识的原因:

JSON
{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

常见情况包括 402 INSUFFICIENT_BALANCE、409 NO_NUMBERS_AVAILABLE、409 PRICE_CHANGED、带 ACTIVATION_LIMIT_REACHED 的 422(每个账号最多可同时有 100 个号码在等待),以及带 Retry-After 请求头的 429 RATE_LIMITED。

完整参考请见 开发者文档。

这篇文章对您有帮助吗?

仍需要帮助?

给我们留言。我们会回复每一条消息,通常在几小时内。

或发送邮件至 support@smsgrab.com