开发者 API 快速入门
从你自己的软件中购买号码并读取验证码。按步骤创建密钥、查询价格、购买号码、等待短信并完成。
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 请求头中:
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here
密钥应该放在服务器上。切勿把它放进网站、浏览器扩展或你分发给他人的 App 中。
3. 查询余额和价格
export SMSGRAB_KEY="sgk_your_key_here"
curl -s https://smsgrab.com/api/dev/v1/balance \
-H "Authorization: Bearer $SMSGRAB_KEY"
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 中的标价。
{ "currency": "USD", "discount_percent": 5,
"items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
"retail_price_minor": 25, "available_numbers": 30412 } ] }
4. 购买号码
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,并附带激活信息:
{ "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 秒,直到有变化为止:
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
-H "Authorization: Bearer $SMSGRAB_KEY"
消息到达时,status 会变为 CODE_RECEIVED,sms 中包含目前为止的所有消息:
{ "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. 完成或取消
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 处理,并忽略你尚不认识的原因:
{ "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。
完整参考请见 开发者文档。
这篇文章对您有帮助吗?
谢谢!很高兴能帮到您。