对接
海外号码 API
两种对接模式任选——卡密兑换(推荐,适合代理)或 API key + USD 余额(适合开发者)。 两种路径共享同一套 webhook / relay / 多次接码能力。
选择对接方式
不确定?两条路径并行不冲突,可同时使用。
用卡密自动化兑换
从拿到卡密到第一条短信回调,3 步搞定。无需 api_key、无需余额管理。
批量采购卡密
TG 联系 ,告诉对方需要的国家+服务+张数(如「印尼 + Telegram × 100 张」)。客户经理会按当时上游成本给阶梯价,付款后发卡密 CSV。
调 redeemCard 兑换号码
把卡密代码传给 ,可选附带一个 webhook URL 让我们短信到达时主动推给你。返回里的 activationId 就是卡密代码本身——后续所有操作都用它。
# 1. 用卡密兑换(无需 api_key) curl "https://eazysms.cc/api/v1/redeemCard?code=ABCD-EFGH-JKLM-NPQR&webhook=https://your.example.com/sms-hook" # → ACCESS_NUMBER:ABCD-EFGH-JKLM-NPQR:+628123456789 # 配 webhook 后服务端会主动推送,无需自己轮询。 # 不想配 webhook 的话,跳到下方第 3 步用 getStatus 轮询。
收码 → 完成或取消
轮询 (或等 webhook 推送)拿到验证码 → 业务用完 → 调 完成或取消。用卡密代码当 id 传,不需要 api_key。
# 1. 兑换拿到号码
RESP=$(curl -s "https://eazysms.cc/api/v1/redeemCard?code=ABCD-EFGH-JKLM-NPQR")
PHONE=$(echo $RESP | cut -d: -f3)
echo "phone=$PHONE"
# 2. 把 phone 提交给目标平台,然后轮询收码(用卡密代码当 id)
while true; do
R=$(curl -s "https://eazysms.cc/api/v1/getStatus?id=ABCD-EFGH-JKLM-NPQR")
case "$R" in
STATUS_OK:*) echo "✓ 验证码: ${R#STATUS_OK:}"; break ;;
STATUS_WAIT_CODE) sleep 5 ;;
STATUS_WAIT_RETRY*) sleep 5 ;;
*) echo "状态: $R"; break ;;
esac
done
# 3. 查完整信息(含多条短信历史 + relayUrl)
curl "https://eazysms.cc/api/v1/getActivationInfo?id=ABCD-EFGH-JKLM-NPQR"
# 4. 完成(确认无需更多短信)
curl "https://eazysms.cc/api/v1/setStatus?id=ABCD-EFGH-JKLM-NPQR&status=6"
# 4'. 或取消(未收到短信时可释放号码、可重兑同一张卡密)
curl "https://eazysms.cc/api/v1/setStatus?id=ABCD-EFGH-JKLM-NPQR&status=8"程序按次调用、灵活切换国家/服务
充值 USD 余额,每次调用按账户售价扣费。适合 SaaS 集成、风控测试、自动化注册。
联系开通 + 拿 API Key
添加 TG ,说明用途和月调用量,充值后获得独立 API Key(可在后台多次查看,丢失可重置)。
查可用价目 + 调用
推荐先用 看你账户有效的 (国家, 服务) 组合(含中英文名+国旗+价格),然后用 下单。
# 1. 查余额
curl "https://eazysms.cc/api/v1/getBalance?api_key=$KEY"
# → ACCESS_BALANCE:100.00
# 2. 查能买什么(含中英文名+国旗,推荐)
curl "https://eazysms.cc/api/v1/getCatalog?api_key=$KEY"
# → { "countries": { "6": {"name_zh":"印度尼西亚",...} },
# "services": { "tg": {"name_zh":"Telegram"} },
# "prices": { "6": { "tg": 0.40 } } }
# 3. 下单 — 拿到 activationId 和号码(service=tg 是 Telegram, country=6 是印尼)
ACT=$(curl -s "https://eazysms.cc/api/v1/getNumber?api_key=$KEY&service=tg&country=6")
echo $ACT
# → ACCESS_NUMBER:42:+628123456789
ID=$(echo $ACT | cut -d: -f2)
# 4. 把号码提交给目标平台,然后轮询拿短信
while true; do
R=$(curl -s "https://eazysms.cc/api/v1/getStatus?api_key=$KEY&id=$ID")
case "$R" in
STATUS_OK:*) echo "✓ 短信: ${R#STATUS_OK:}"; break ;;
STATUS_WAIT_CODE) sleep 5 ;;
*) echo "其他: $R"; break ;;
esac
done
# 5. 完成(结算)或取消(未收到短信自动退款)
curl "https://eazysms.cc/api/v1/setStatus?api_key=$KEY&id=$ID&status=6" # 完成
# curl "https://eazysms.cc/api/v1/setStatus?api_key=$KEY&id=$ID&status=8" # 取消6=印尼、187=美国,service tg=Telegram、dr=ChatGPT。完整列表见「代码速查」。完整接口参考
所有接口走 GET,URL 参数传 api_key,无需 header;返回纯文本(除 getPrices 返回 JSON)。
https://eazysms.cc/api/v1/redeemCard| 参数 | 说明 | 必填 |
|---|---|---|
code | 卡密代码(如 ABCD-EFGH-JKLM-NPQR) | 必填 |
webhook | 短信到达时 POST 到此 URL,不传则需轮询 | 可选 |
ACCESS_NUMBER:ABCD-EFGH-JKLM-NPQR:+628123456789
https://eazysms.cc/api/v1/getBalance| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
ACCESS_BALANCE:100.00
https://eazysms.cc/api/v1/getCatalog| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
{
"countries": {
"6": {"name_zh":"印度尼西亚","name_en":"Indonesia","flag":"🇮🇩"},
"187": {"name_zh":"美国","name_en":"United States","flag":"🇺🇸"}
},
"services": {
"dr": {"name_zh":"OpenAI (ChatGPT)"},
"ni": {"name_zh":"Gojek"}
},
"prices": {
"6": { "ni": 0.06 },
"187": { "dr": 0.40 }
}
}https://eazysms.cc/api/v1/getPrices| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
country | 国家代码(如 6=印尼) | 可选 |
service | 服务代码(如 tg=Telegram) | 可选 |
{"6":{"tg":{"cost":0.40},"wa":{"cost":0.55}},"0":{...}}https://eazysms.cc/api/v1/getNumber| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
service | 服务代码 | 必填 |
country | 国家代码 | 必填 |
operator | 运营商或 listing ID (numeric) | 可选 |
maxPrice | 上游最高单价上限 (USD),仅影响上游撮合,不影响你扣的售价 | 可选 |
webhook | 短信到达时 POST 到此 URL(http/https),不传则只能轮询 | 可选 |
ACCESS_NUMBER:42:+628123456789
https://eazysms.cc/api/v1/getActivationInfo| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
id | activationId | 必填 |
{
"activationId": 42,
"phone": "+628123456789",
"service": "tg",
"country": "6",
"status": "waiting",
"maxReceives": 3,
"receiptCount": 2,
"isComplete": false,
"receipts": [
{ "seq": 1, "code": "111222", "text": "...", "receivedAt": 1748227200000 },
{ "seq": 2, "code": "333444", "text": "...", "receivedAt": 1748227260000 }
],
"latestSmsCode": "333444",
"relayUrl": "https://eazysms.cc/api/relay/rly_xxxxxxxxx",
"webhookUrl": "https://your.example.com/sms-hook",
"price": 0.40
}https://eazysms.cc/api/v1/getStatus| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key | 必填 |
id | activationId(来自 getNumber 返回值) | 必填 |
STATUS_WAIT_CODE | STATUS_OK:123456 | STATUS_CANCEL | STATUS_WAIT_RETRY:123456
https://eazysms.cc/api/v1/setStatus| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key(API 模式) | 条件必填 |
id | activationId(数字)或卡密代码(4 段格式) | 必填 |
status | 1=已转发 / 3=再来一条 / 6=完成 / 8=取消 | 必填 |
ACCESS_READY | ACCESS_RETRY_GET | ACCESS_ACTIVATION | ACCESS_CANCEL
https://eazysms.cc/api/v1/reportCode| 参数 | 说明 | 必填 |
|---|---|---|
api_key | 你的 API key(API 模式必填) | 条件必填 |
id | activationId 数字 或 卡密代码 | 必填 |
seq | 针对第几条短信(默认最新) | 可选 |
result | success / invalid / used | 必填 |
ACCESS_REPORTED | ACCESS_REFUNDED
https://eazysms.cc/api/v1/health| 参数 | 说明 | 必填 |
|---|
{
"ok": true,
"uptime_seconds": 12345,
"upstream": {
"smsbower_reachable": true,
"smsbower_latency_ms": 234,
"smsbower_balance_usd": 67.42
},
"stats": {
"total_24h": 1234,
"successful_24h": 1102,
"success_rate_24h": 0.893,
"api_activations_24h": 980,
"card_redemptions_24h": 254
}
}代码速查
常用 country / service 代码(SMS-Activate 兼容编码)。你账户的完整可用代码请用 getCatalog 取——这里只列高频组合,方便上手。
常用国家代码(country)
| 代码 | 国家 |
|---|---|
0 | 🇷🇺 俄罗斯 |
6 | 🇮🇩 印度尼西亚 |
10 | 🇰🇿 哈萨克斯坦 |
16 | 🇬🇧 英国 |
22 | 🇮🇳 印度 |
37 | 🇲🇦 摩洛哥 |
38 | 🇬🇭 加纳 |
43 | 🇩🇪 德国 |
78 | 🇫🇷 法国 |
187 | 🇺🇸 美国 |
常用服务代码(service)
| 代码 | 服务 |
|---|---|
tg | Telegram |
wa | |
go | Google / YouTube / Gmail |
fb | |
ig | |
tw | X (Twitter) |
ds | Discord |
dr | OpenAI / ChatGPT |
ot | 其他 / 通用 |
getCatalog 看你账户实际能用什么——以上只是 SMS-Activate 通用编码示例。 你账户的有效代码、价格、可用国家完全由后台为你配置,跟其他客户可能不同。错误码速查
所有错误以纯文本响应(HTTP 200),便于脚本简单匹配。
计费规则
预付费
账户预存 USD 余额,每次 getNumber 成功立即按你的账户售价扣费。售价根据充值额度和拿货量阶梯式定价。
取消退款
setStatus=8 取消时,如果尚未收到任何短信,已扣款全额自动退回。收到短信后取消不退款。
价目变更
后台调价后立即生效。变价前会通过 TG 频道公告。大客户可申请价格锁定一段时间。
余额查询
用 getBalance 查看余额,建议每次调用前/后查一次或设置阈值告警。余额不足 NO_BALANCE。
代理纯静态兑换页
给做卡密分发的代理:一份纯 HTML + CSS + JS 的兑换页,改一行品牌名就能挂到自己域名。 兑换请求回调本平台 API(已加 CORS),无需任何服务器代码。
app.js 顶部的 brandName 即可上线 · 视觉与主站一致使用步骤:
1. 下载 zip → 解压 3 个文件 → 任意修改 app.js 第 1 行 APP_CONFIG.brandName
2. 上传到任意静态托管(Cloudflare Pages / Vercel / GitHub Pages / 你自己的服务器都行)
3. 把链接发给你的终端用户,他们输卡密 → 自动调用本平台 API → 拿号码、收码全在浏览器里完成
4. 你的客户看到的只有你自己的品牌;本平台 API 域名仅出现在网络请求里
验证码回馈(reportCode)
收到码后告诉我们码是否真的可用。会用于运营侧的质量统计,API 模式 + invalid + 10 分钟内可触发自动退款。
# 成功使用(仅记录,无业务动作) curl "https://eazysms.cc/api/v1/reportCode?api_key=$KEY&id=42&seq=1&result=success" # 收到但码无效(API 模式 10 分钟内自动退款 + 上游取消) curl "https://eazysms.cc/api/v1/reportCode?api_key=$KEY&id=42&seq=1&result=invalid" # → ACCESS_REFUNDED 或 ACCESS_REPORTED(超出窗口) # 卡密场景下不需要 api_key curl "https://eazysms.cc/api/v1/reportCode?id=ABCD-EFGH-JKLM-NPQR&result=success"
success——帮助我们持续优化你账户的服务质量分。一个号码接多次短信
部分平台需要同一个号码接收 2+ 条短信(如「先注册码 + 后操作码」)。我们后台为每个 (国家, 服务) 配了「接码次数」上限。
- 下单时按该组合后台配置的
maxReceives写入到 activation - 每收到一条新码:插入 receipts 表(带
seq自增)、触发 webhook、自动向上游setStatus=3请求下一条 - 收满
maxReceives后:自动setStatus=6完成、activation 状态变为done、webhook 携带isLast: true - 同一条码不会重复推送——基于 (activation, sms_code) 唯一约束去重,杜绝 STATUS_WAIT_RETRY 里携带的旧码被误判为新码
getActivationInfo,里面有完整的 receipts: [...] 数组。短信推送 / 拉取(两种 push 模式)
不想轮询 getStatus?两种方式可选——任选其一或组合使用:
webhook 参数,传你自己的 URL。短信到达后我们自动 POST JSON 过去,失败重试 3 次(10s/60s/300s)。# 下单时同时配置 webhook
curl "https://eazysms.cc/api/v1/getNumber?api_key=$KEY&service=tg&country=6&webhook=https://your.example.com/sms-hook"
# → ACCESS_NUMBER:42:+628123456789
# 每收到一条新短信,我们 POST 一次:
# {
# "activationId": 42,
# "seq": 1, # 该号码的第几条 SMS
# "maxReceives": 3, # 总共会推送几条
# "isLast": false, # 是不是最后一条
# "phone": "+628123456789",
# "service": "tg",
# "country": "6",
# "operator": null,
# "smsCode": "123456",
# "smsText": "Your code is 123456",
# "receivedAt": 1748227200000
# }getStatus 做兜底更稳。relayUrl。把这个 URL 粘到任何"输入验证码接收地址"的第三方平台,他们 GET 这个 URL 就能拿到纯文本验证码。典型场景:某些代填/代付平台要求填一个"验证码接口 URL"——直接把我们的 relayUrl 粘进去即可。
# 1. 下单拿到 activationId
ID=$(curl -s "https://eazysms.cc/api/v1/getNumber?api_key=$KEY&service=tg&country=6" | cut -d: -f2)
# 2. 拿到 relayUrl
curl "https://eazysms.cc/api/v1/getActivationInfo?api_key=$KEY&id=$ID"
# → { "relayUrl": "https://eazysms.cc/api/relay/rly_xxxxxxxxx", ... }
# 3. 把 relayUrl 粘到第三方平台的「验证码接口」字段
# 第三方 GET 这个 URL 时返回纯文本:
# WAITING -> 尚无短信,请重试
# <验证码> -> 当前最新一条码
# CANCELLED / DONE -> 终态
# 多次接码场景下可用 ?since=N 只取新码:
# curl "https://eazysms.cc/api/relay/rly_xxx?since=1"
# → 仅当存在 seq > 1 的码时返回,否则 WAITING
# 也支持 long-poll(?wait=25 最多挂 25 秒等新码 → 平均响应 < 1 秒):
# curl "https://eazysms.cc/api/relay/rly_xxx?wait=25"getStatus。开始接入
添加 TG 客户经理,5 分钟内回复。
联系 @younaotekan