两种 API 风格
选择适合你项目的格式 — 两者由同一基础设施支持。
现代 REST API
基于 OpenAPI 规范的简洁 JSON API。适合新集成。
- JSON 请求与响应体
- /api/docs 提供 OpenAPI 3.0 规范
- Bearer token 或 x-api-key 鉴权
- 标准 HTTP 状态码
curl https://smsbulk.net/api/v1/wallet/balance \
-H "x-api-key: YOUR_KEY"传统 API 兼容
兼容业界标准的基于 query 的协议。现有 bot 脚本和库无需修改代码即可工作 — 仅需指向我们的基础 URL。
- 完全相同的基于 action 的协议
- 纯文本响应格式
- 兼容现有 bot 库
- 保留标准国家 ID 映射
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getBalance"快速开始
从零到第一条 SMS,5 分钟内完成。
1
2
测试鉴权
通过查询钱包余额验证密钥可用。
curl https://smsbulk.net/api/v1/wallet/balance \
-H "x-api-key: YOUR_KEY"
# Response:
# { "balance": "10.00", "currency": "USD" }3
购买号码
为 SMS 验证预留一个虚拟号码。费用从钱包扣除。
curl -X POST https://smsbulk.net/api/v1/activations \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "wa",
"countryIso": "TR"
}'
# Response:
# {
# "id": "cuid_xxx",
# "phoneNumber": "905551234567",
# "status": "WAITING",
# "userCost": "0.50"
# }4
等待短信
轮询激活端点直到状态变为 RECEIVED。SMS 代码会在响应中。
curl https://smsbulk.net/api/v1/activations/cuid_xxx \
-H "x-api-key: YOUR_KEY"
# Response (when SMS arrives):
# {
# "id": "cuid_xxx",
# "smsCode": "123456",
# "status": "RECEIVED",
# ...
# }身份验证
三种发送 API 密钥的方式。
选择适合你环境的方法
1. Header(推荐)
x-api-key: YOUR_API_KEY标准的基于 header 的鉴权。适用于 REST 和 SMS-Activate 端点。
2. Bearer token
Authorization: Bearer YOUR_API_KEY兼容默认使用 Authorization 头部的 HTTP 客户端库。
3. Query string
?api_key=YOUR_API_KEYSMS-Activate 兼容端点 /stubs/handler_api.php 必须使用。
保护好你的密钥
切勿将 API 密钥提交到公开仓库或暴露在客户端代码中。每个密钥有每日配额 — 一旦泄露立即轮换。