SimpleSMS API 使用说明

下载 OpenAPI 和 Postman Collection，快速接入余额、价格、下单、查询和取消接口。

所有 /v1 接口都从 https://fenjueauto.com 调用，并需要调用密钥。请在请求头中加入：

Authorization: Bearer YOUR_ACCESS_KEY
Content-Type: application/json

查询账户可用余额和冻结余额。

curl -X GET https://fenjueauto.com/v1/balance \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

{
  "balance": 12.5000,
  "frozen": 0.2000
}

查询当前可用国家、客户价格、库存、价格档位和更新时间。客户价格是最终美元售价，已经包含后台设置的价格倍率。创建订单返回的 price 与冻结金额使用同一口径。

curl -X GET "https://fenjueauto.com/v1/catalog/prices?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

{
  "prices": [
    {
      "country": 52,
      "countryName": "泰国",
      "countryIso2": "TH",
      "availableCount": 184,
      "customerPrice": 0.0800,
      "tiers": [
        {
          "tierId": "sms:TH:0.080000",
          "price": 0.0800,
          "customerPrice": 0.0800,
          "availableCount": 120,
          "updatedAt": "2026-05-10T09:00:00.000Z"
        },
        {
          "tierId": "sms:TH:0.120000",
          "price": 0.1200,
          "customerPrice": 0.1200,
          "availableCount": 64,
          "updatedAt": "2026-05-10T09:00:00.000Z"
        }
      ],
      "syncedAt": "2026-05-10T09:00:00.000Z"
    }
  ]
}

查询当前邮箱验证码可用域名、库存和客户价格。客户价格是最终美元售价，已经包含后台设置的价格倍率。

curl -X GET "https://fenjueauto.com/v1/catalog/email-prices" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

{
  "prices": [
    {
      "domain": "gmail.com",
      "availableCount": 12,
      "customerPrice": 0.2000,
      "syncedAt": "2026-05-10T09:00:00.000Z"
    }
  ]
}

创建手机号订单或邮箱订单。maxPrice 表示你愿意支付的最终最高价，不会在此基础上再次加价。创建成功会先冻结 price 对应金额，每个订单默认有 10 分钟倒计时，验证码未到达前 code 为空。

手机号订单可以传 tierId 主动选择价格档位。价格档位里的 price / customerPrice 都已经按运营倍率计算好，是客户最终售价。

创建订单默认会最多等待 10 秒，尽量在响应里直接返回手机号或邮箱地址。分配较慢时仍会返回订单号，请继续查询订单。需要立即返回时可使用 waitAddress=false。

curl -X POST "https://fenjueauto.com/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "country": 52,
    "tierId": "sms:TH:0.120000",
    "maxPrice": 0.1200
  }'

curl -X POST "https://fenjueauto.com/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "domain": "gmail.com",
    "maxPrice": 0.1000
  }'

{
  "orderId": "AGW_2x7h9k...",
  "type": "sms",
  "country": 52,
  "domain": null,
  "status": "reserved",
  "address": null,
  "code": null,
  "price": 0.0800,
  "createdAt": "2026-05-10T09:10:00.000Z",
  "timeoutAt": "2026-05-10T09:20:00.000Z"
}

查询订单状态和验证码结果。创建订单后先等待 address 不为空，再将手机号或邮箱用于你已获授权的验证流程；提交后继续每 5-10 秒查询一次，code 不为空或状态为 completed 后停止轮询。

curl -X GET https://fenjueauto.com/v1/orders/AGW_2x7h9k... \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

{
  "orderId": "AGW_2x7h9k...",
  "status": "completed",
  "address": "+66812345678",
  "code": "123456",
  "price": 0.0800,
  "completedAt": "2026-05-10T09:12:18.000Z"
}

手机号已用于授权验证页面后调用一次。系统会发送“已使用号码，可以等待验证码”的状态信号，提高订单状态准确性；不支持该信号时会自动跳过。

curl -X POST https://fenjueauto.com/v1/orders/AGW_2x7h9k.../ready \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

{
  "orderId": "AGW_2x7h9k...",
  "status": "active",
  "message": "Order is ready to receive SMS code."
}

取消尚未完成的订单。取消成功后释放冻结余额；已完成、已超时或已失败的订单会返回当前最终状态。

curl -X POST https://fenjueauto.com/v1/orders/AGW_2x7h9k.../cancel \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

建议客户端对 429、5xx 和网络超时使用指数退避重试。创建订单接口不要盲目并发重试；如果收到订单号，请继续查询原订单。

retry delays: 1s, 2s, 5s, 10s
poll interval: 5-10s
stop polling: completed / cancelled / timeout / failed

可配置一个客户侧回调地址。订单完成时，SimpleSMS 会向该地址 POST order.completed 事件；轮询仍建议保留作为兜底。

PUT /v1/webhook
Authorization: Bearer YOUR_ACCESS_KEY
Content-Type: application/json

{
  "url": "https://example.com/simplesms-webhook",
  "secret": "optional-signing-secret",
  "enabled": true
}

{
  "event": "order.completed",
  "order": {
    "orderId": "AGW_2x7h9k...",
    "status": "completed",
    "address": "+66812345678",
    "code": "123456",
    "price": 0.0800
  },
  "deliveredAt": "2026-05-13T00:00:00.000Z"
}

如果设置了 secret，请求头会包含 X-SimpleSMS-Signature: sha256=...，签名内容为原始 JSON body。