文档·激活
⚡

激活

单次 SMS 验证——从请求到计费的一次性验证码生命周期。

什么是激活

激活是为一次 SMS-OTP 短期租用号码。你发起请求，平台保留号码，你读取入站 SMS 中的验证码，激活随后关闭——成功（计费）或过期（免费）。

仅需一个验证码时使用激活（注册、密码重置、KYC）。如需在更长窗口内接收多条 SMS，请参见 Rentals。

生命周期

waiting ─► sms_received ─► finished       （你确认；计费）
   │                  └──► refunded       （无验证码；免费）
   └─► expired                            （超时；免费）
  • waiting — 号码已保留，尚无 SMS。
  • sms_received — 已捕获至少一条入站 SMS。
  • finished — 你已调用 finish；计费。
  • expired — 期限届满且无 SMS；不计费。
  • refunded — 你在确认前取消；不计费。

创建

curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "country": "ua",
    "service": "telegram",
    "duration_minutes": 15,
    "max_price_cents": 12
  }'
字段 必填 说明
country 是 ISO-2 国家代码
service 是 服务目录中的 slug 或 any
duration_minutes 否 5 到 60。默认 20
max_price_cents 否 将故障转移提供商池扩展到不超过该上限

轮询

curl https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e \
  -H "Authorization: Bearer $EVESES_API_KEY"

每 1.5–2 秒轮询一次没问题；亚秒级轮询会限流。生产环境强烈建议使用 webhook。

Finish

确认激活并触发计费。幂等——多次调用安全。

curl -X POST https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e/finish \
  -H "Authorization: Bearer $EVESES_API_KEY"

Cancel

在任何 SMS 之前取消。如果已收到 SMS 则返回 409（应调用 finish）。

curl -X POST https://api.eveses.com/v1/activations/9a1f2c3d-4e5b-6a7c-8d9e-0f1a2b3c4d5e/cancel \
  -H "Authorization: Bearer $EVESES_API_KEY"
← 上一篇快速开始下一篇 →Authentication