开发者接入文档

概览

正式接口只接受 HTTPS。请求和响应中的金额均为人民币十进制字符串；产品列表按客户授权动态返回，当前默认美国短信验证产品价格为 ¥1.30。时间使用带时区的 ISO 8601 格式。客户端应保存自己的业务单号，并通过幂等键安全重试。

快速开始

1. 获取凭证

管理员为每个客户独立发放 API Key 和 API Secret。Secret 仅在创建或轮换时展示一次，请存放在服务端密钥管理系统中。

2. 查询产品

先调用产品列表获取当前账户被授权的国家和客户价；目录可能由管理员刷新，禁止把国家或产品 ID 写死在程序中。

GET /api/open/v1/products

X-API-Key: ak_live_xxx
X-Timestamp: 1785686400
X-Nonce: request_nonce_000001
X-Signature: 64位小写十六进制签名

3. 创建订单

POST /api/open/v1/orders
Content-Type: application/json
Idempotency-Key: order_20260803_customer_0001

{
  "client_order_id": "customer_order_0001",
  "product_id": "sms_verification_us",
  "quantity": 1
}

4. 查询结果

GET /api/open/v1/orders/order_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

按照响应中的 next_poll_after_seconds 等待后再查询。获得验证码或订单进入终态后停止轮询。

请求签名

正式接口使用 HMAC-SHA256。每次请求必须提供以下请求头：

待签名字符串按以下顺序拼接，每项之间使用一个换行符；GET 请求最后一行为空：

HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
SHA256_HEX(REQUEST_BODY)
X_TIMESTAMP
X_NONCE
IDEMPOTENCY_KEY

正式 v1 接口不接受查询参数，因此 CANONICAL_QUERY 当前为空字符串。请求体必须使用实际发送字节计算 SHA-256，签名后不得重新格式化 JSON。

Python 签名示例

import hashlib
import hmac
import json
import secrets
import time
import requests

API_KEY = "ak_live_xxx"
API_SECRET = "仅保存在服务端"
BASE_URL = "https://api.leadbee.cn"
path = "/api/open/v1/orders"
idempotency_key = "order_20260803_customer_0001"
payload = {
    "client_order_id": "customer_order_0001",
    "product_id": "sms_verification_us",
    "quantity": 1,
}
body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode()
timestamp = str(int(time.time()))
nonce = secrets.token_urlsafe(18)
canonical = "\n".join([
    "POST", path, "", hashlib.sha256(body).hexdigest(),
    timestamp, nonce, idempotency_key,
])
signature = hmac.new(
    API_SECRET.encode(), canonical.encode(), hashlib.sha256
).hexdigest()

response = requests.post(
    BASE_URL + path,
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
        "Idempotency-Key": idempotency_key,
    },
    timeout=30,
)
response.raise_for_status()

接口参考

成功响应

{
  "success": true,
  "request_id": "req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "order_id": "order_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "WAITING_CODE",
    "phone_number": "+56xxxxxxxxx",
    "verification_code": null,
    "next_poll_after_seconds": 3
  }
}

不同接口的 data 字段不同。客户端应忽略暂不认识的新增字段，并以 success、状态码和错误码作为处理依据。

订单状态

计费规则

1. 创建订单时，系统按照公开售价预留相应余额。
2. 订单完成后，预留余额转为正式扣费。
3. 取消确认成功后，系统释放对应预留余额。
4. 状态尚未确认时，客户端不得创建相同业务的重复订单。

请求限制

限制按客户凭证独立计算；公网入口同时提供单 IP 连接与突发流量保护。

超过限制时返回 HTTP 429。客户端应读取 Retry-After，并使用指数退避和少量随机抖动。

错误处理

{
  "success": false,
  "request_id": "req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

向管理员反馈问题时提供 request_id 和发生时间，不要发送完整密钥、签名或验证码。

轻量接入

面向已有纯文本协议客户端，接口地址为 https://api.leadbee.cn/api/handler_api.php。新项目建议优先使用正式 v1 接口。

Authorization: Bearer YOUR_COMPAT_API_KEY

轻量接口错误以固定文本返回，包括 BAD_KEY、NO_BALANCE、NO_NUMBERS、BAD_REQUEST_ID、ERROR_RATE_LIMIT 和 ERROR_ACTIVE_ORDER_LIMIT。同一业务发生超时或网络重试时必须复用原 request_id。

安全规范

• API Secret 和访问密钥只能保存在服务端，禁止进入网页、移动端安装包或公开仓库。
• 为不同系统发放独立凭证，并按照最小权限配置接口范围。
• 生产环境建议启用固定出口 IP 白名单。
• 不要记录完整请求头、签名、手机号、验证码或客户敏感数据。
• 发现凭证疑似泄露时立即停用并轮换，不要继续使用原凭证。
• 正式接口写操作必须使用幂等键；网络超时不能直接生成新的业务单号。

更新记录