🔗自定义取码 URL 与模板化返回

轮询订单接口能拿码，但要对接老系统、或想用一个固定地址实时取码，SimSmsBox 有更顺手的方式：自定义取码 URL + 模板化返回。下单后每个订单都带一个 apiBindingKey，凭它从一个固定 URL 实时取最新短信——对外只暴露我方地址，绝不泄露上游供应商。

拿到 apiBindingKey

下单（POST /api/sms/orders/purchase）的响应里带有该订单的 apiBindingKey。它就是这条取码 URL 的凭证：调用 record 端点时不需要再带 X-API-Key 请求头，key 本身即授权。

固定取码 URL

用 key 调 record 端点，实时取该订单最新短信：

# 默认 JSON：status=YES 表示已收到、NO 表示还没到；data 里有整条短信
curl "https://api.simsmsbox.com/api/sms/record?key=YOUR_API_BINDING_KEY"

# 极简文本：收到 -> YES|<整条短信内容>，未到 -> NO|
curl "https://api.simsmsbox.com/api/sms/record?key=YOUR_API_BINDING_KEY&format=txt"

默认 JSON 返回示例：

{
  "code": 200,
  "msg": "OK",
  "status": "YES",
  "data": {
    "orderNo": "S2606...",
    "phone": "+1xxxxxxxxxx",
    "content": "Your code is 123456",
    "codeValue": "123456",
    "sender": "Telegram",
    "receivedAt": "2026-06-02T08:00:00Z"
  }
}

format 取值：不传 = JSON（若你配了返回模板则按模板渲染）；format=json 强制 JSON；format=txt 极简文本。

模板化返回（对接老系统）

如果你的接收端只认固定格式（比如老系统期望某几个字段名），在后台「取码设置 → 返回模板」里建一个模板，把字段映射成你要的结构，再绑定到订单即可。模板用单花括号占位符（大小写不敏感）：

模板: { "otp": "{Code}", "order": "{OrderNo}", "from": "{Sender}" }
渲染: { "otp": "123456", "order": "S2606...", "from": "Telegram" }

可用占位符：

模板的返回 Content-Type 也能在「取码设置」里指定（如 text/plain 或 application/json），接收端拿到的就是你要的格式。

在脚本里直接用这个 URL 轮询

固定 URL 适合直接放进脚本轮询，format=txt 最省事：

# 先等 15 秒，再每 5 秒查一次，最多 2 分钟
sleep 15
for i in $(seq 1 24); do
  resp=$(curl -s "https://api.simsmsbox.com/api/sms/record?key=YOUR_API_BINDING_KEY&format=txt")
  case "$resp" in YES\|*) echo "$resp"; break;; esac
  sleep 5
done

安全建议

• 这条 URL 凭 key 授权、不含账号信息，但仍要当密钥保管，别公开到前端或日志。
• key 可在「取码设置 → 绑定」里轮换（rotate），疑似泄露及时换。
• 取码 URL 只读、且只暴露我方地址，不会泄露上游供应商。

固定取码 URL（实时拉）+ 订单轮询（兜底）配合最稳。延伸阅读：自动取号与轮询。