API 技术文档

对接
海外号码 API

两种对接模式任选——卡密兑换(推荐,适合代理)或 API key + USD 余额(适合开发者)。 两种路径共享同一套 webhook / relay / 多次接码能力。

CHOOSE A PATH

选择对接方式

不确定?两条路径并行不冲突,可同时使用。

PATH A · 卡密兑换

用卡密自动化兑换

从拿到卡密到第一条短信回调,3 步搞定。无需 api_key、无需余额管理。

1

批量采购卡密

TG 联系 ,告诉对方需要的国家+服务+张数(如「印尼 + Telegram × 100 张」)。客户经理会按当时上游成本给阶梯价,付款后发卡密 CSV。

每张卡密绑死了「国家+服务+接码次数」三要素,无法修改。如果你需要灵活切换组合,请走 Path B
2

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 轮询。
3

收码 → 完成或取消

轮询 (或等 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"
接码次数由卡密绑定的批次决定(如 1/3/5 次),多次接码请见「多次接码语义」
relayUrl 让第三方平台直接 GET 取码——见「推送 / 拉取」
PATH B · API KEY + 余额

程序按次调用、灵活切换国家/服务

充值 USD 余额,每次调用按账户售价扣费。适合 SaaS 集成、风控测试、自动化注册。

1

联系开通 + 拿 API Key

添加 TG ,说明用途和月调用量,充值后获得独立 API Key(可在后台多次查看,丢失可重置)。

2

查可用价目 + 调用

推荐先用 看你账户有效的 (国家, 服务) 组合(含中英文名+国旗+价格),然后用 下单。

# 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" # 取消
国家/服务编码跟 SMS-Activate 一致——country 6=印尼、187=美国,service tg=Telegram、dr=ChatGPT。完整列表见「代码速查」
API REFERENCE

完整接口参考

所有接口走 GET,URL 参数传 api_key,无需 header;返回纯文本(除 getPrices 返回 JSON)。

GEThttps://eazysms.cc/api/v1/redeemCard
用卡密兑换号码(无需 api_key 鉴权)。把零售卡密自动化分发的入口——卡密本身已付费,调用此接口零余额消耗
参数说明必填
code卡密代码(如 ABCD-EFGH-JKLM-NPQR)必填
webhook短信到达时 POST 到此 URL,不传则需轮询可选
ACCESS_NUMBER:ABCD-EFGH-JKLM-NPQR:+628123456789
返回格式中 activationId 用「卡密代码」原样填充——后续 getStatus / setStatus / relay / webhook 全部以卡密代码作为 id。max_receives 从卡密绑定的批次配置中读取。错误码:INVALID_CARD(卡密不存在)、CARD_EXHAUSTED:uses=N/M:status=<complete|partial|unknown>:age_sec=<秒>(已达接收上限;status=complete 即 N=M 自然用满,partial 即提前结束,age_sec 是距最后一次活动的秒数——若 age_sec 很小说明刚被别处用掉,可能渠道串号)、RATE_LIMITED:secs(被限频)、BAD_WEBHOOK_URL。
GEThttps://eazysms.cc/api/v1/getBalance
查询当前 API key 的余额
参数说明必填
api_key你的 API key必填
ACCESS_BALANCE:100.00
返回的数字单位是 USD
GEThttps://eazysms.cc/api/v1/getCatalog
一次拿到该 key 全部可用 (国家, 服务) 组合及中英文名、国旗、价格——推荐用于初始化 UI 或对照代码
参数说明必填
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 }
  }
}
非 SMS-Activate 标准。建议每小时缓存一次结果。
GEThttps://eazysms.cc/api/v1/getPrices
查询你账户下能买的 (国家, 服务) 组合及售价(SMS-Activate 兼容,无中文名)
参数说明必填
api_key你的 API key必填
country国家代码(如 6=印尼)可选
service服务代码(如 tg=Telegram)可选
{"6":{"tg":{"cost":0.40},"wa":{"cost":0.55}},"0":{...}}
不传 country/service 则返回全部已配价组合。价格反映你账户的有效价(专属价优先于全局价)。需要中文名请用 getCatalog。
GEThttps://eazysms.cc/api/v1/getNumber
下单获取一个手机号;成功后立即扣款,返回 activationId 和号码
参数说明必填
api_key你的 API key必填
service服务代码必填
country国家代码必填
operator运营商或 listing ID (numeric)可选
maxPrice上游最高单价上限 (USD),仅影响上游撮合,不影响你扣的售价可选
webhook短信到达时 POST 到此 URL(http/https),不传则只能轮询可选
ACCESS_NUMBER:42:+628123456789
格式:ACCESS_NUMBER:{activationId}:{phone}。activationId 用于后续 getStatus / setStatus。若需 relayUrl 请调 getActivationInfo。
GEThttps://eazysms.cc/api/v1/getActivationInfo
查询单个 activation 的完整信息(JSON),含 relayUrl、webhookUrl、所有已收短信
参数说明必填
api_key你的 API key必填
idactivationId必填
{
  "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
}
receipts 数组按 seq 升序。一次调用即可拿到全部已收码 + 总数 + 是否已收满。
GEThttps://eazysms.cc/api/v1/getStatus
查询 activation 状态(轮询用,建议间隔 5-10 秒)
参数说明必填
api_key你的 API key必填
idactivationId(来自 getNumber 返回值)必填
STATUS_WAIT_CODE | STATUS_OK:123456 | STATUS_CANCEL | STATUS_WAIT_RETRY:123456
短信到达后返回 STATUS_OK:CODE。如需第二条短信,调 setStatus=3 后继续轮询。
GEThttps://eazysms.cc/api/v1/setStatus
更新 activation 状态:发码 / 请求重发 / 完成 / 取消
参数说明必填
api_key你的 API key(API 模式)条件必填
idactivationId(数字)或卡密代码(4 段格式)必填
status1=已转发 / 3=再来一条 / 6=完成 / 8=取消必填
ACCESS_READY | ACCESS_RETRY_GET | ACCESS_ACTIVATION | ACCESS_CANCEL
status=8 取消时,如果尚未收到任何短信,已扣款会自动退回(API 模式)。
GEThttps://eazysms.cc/api/v1/reportCode
上报某条验证码是否成功被业务使用,触发质量统计;invalid + 10 分钟内 → 自动退款(API 模式)
参数说明必填
api_key你的 API key(API 模式必填)条件必填
idactivationId 数字 或 卡密代码必填
seq针对第几条短信(默认最新)可选
resultsuccess / invalid / used必填
ACCESS_REPORTED | ACCESS_REFUNDED
API 模式在 invalid + 收码后 10 分钟内可触发自动退款 + 取消上游。卡密模式仅记录用于运营统计,不退款。
GEThttps://eazysms.cc/api/v1/health
服务健康检查 + 24h 成功率统计(建议监控用)
参数说明必填
{
  "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
  }
}
响应缓存 30 秒。便于客户做监控告警 / SLA 校验。
CODE REFERENCE

代码速查

常用 country / service 代码(SMS-Activate 兼容编码)。你账户的完整可用代码请用 getCatalog——这里只列高频组合,方便上手。

常用国家代码(country)

代码国家
0🇷🇺 俄罗斯
6🇮🇩 印度尼西亚
10🇰🇿 哈萨克斯坦
16🇬🇧 英国
22🇮🇳 印度
37🇲🇦 摩洛哥
38🇬🇭 加纳
43🇩🇪 德国
78🇫🇷 法国
187🇺🇸 美国

常用服务代码(service)

代码服务
tgTelegram
waWhatsApp
goGoogle / YouTube / Gmail
fbFacebook
igInstagram
twX (Twitter)
dsDiscord
drOpenAI / ChatGPT
ot其他 / 通用
务必先调 getCatalog 看你账户实际能用什么——以上只是 SMS-Activate 通用编码示例。 你账户的有效代码、价格、可用国家完全由后台为你配置,跟其他客户可能不同。
ERROR CODES

错误码速查

所有错误以纯文本响应(HTTP 200),便于脚本简单匹配。

错误码含义建议动作
BAD_KEYapi_key 无效 / 已停用联系客户经理确认或重置
NO_BALANCE余额不足以支付当前组合的售价充值或换更便宜的国家/服务
NO_PRICE_CONFIG这个 (国家, 服务) 组合在你账户下未配价找客户经理补上价目
NO_NUMBERS上游暂无该国家+服务的号码稍后重试或换组合
WRONG_SERVICEservice 参数缺失或无效检查 service 代码
WRONG_COUNTRYcountry 参数缺失或无效检查 country 代码
NO_ACTIVATIONactivation id 不存在 / 不属于你确认 id 是 getNumber 返回的
BAD_STATUSstatus 必须是 1/3/6/81=已发码, 3=请求重试, 6=完成, 8=取消
BILLING

计费规则

预付费

账户预存 USD 余额,每次 getNumber 成功立即按你的账户售价扣费。售价根据充值额度和拿货量阶梯式定价。

取消退款

setStatus=8 取消时,如果尚未收到任何短信,已扣款全额自动退回。收到短信后取消不退款。

价目变更

后台调价后立即生效。变价前会通过 TG 频道公告。大客户可申请价格锁定一段时间。

余额查询

getBalance 查看余额,建议每次调用前/后查一次或设置阈值告警。余额不足 NO_BALANCE

RESELLER TOOLKIT

代理纯静态兑换页

给做卡密分发的代理:一份纯 HTML + CSS + JS 的兑换页,改一行品牌名就能挂到自己域名。 兑换请求回调本平台 API(已加 CORS),无需任何服务器代码。

下载 easysms-agent-pkg.zip · 22 KB
3 个文件(HTML / CSS / JS)· 解压后改 app.js 顶部的 brandName 即可上线 · 视觉与主站一致

使用步骤:
1. 下载 zip → 解压 3 个文件 → 任意修改 app.js 第 1 行 APP_CONFIG.brandName
2. 上传到任意静态托管(Cloudflare Pages / Vercel / GitHub Pages / 你自己的服务器都行)
3. 把链接发给你的终端用户,他们输卡密 → 自动调用本平台 API → 拿号码、收码全在浏览器里完成
4. 你的客户看到的只有你自己的品牌;本平台 API 域名仅出现在网络请求里

CODE FEEDBACK

验证码回馈(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——帮助我们持续优化你账户的服务质量分。
MULTI-SMS

一个号码接多次短信

部分平台需要同一个号码接收 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 MODES

短信推送 / 拉取(两种 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
# }
Webhook 失败会重试 3 次,全部失败后放弃。最佳实践:你的端点收到后立即 200 OK 接收,业务异步处理。配合轮询 getStatus 做兜底更稳。
下单成功后我们为每个 activation 生成一个唯一 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"
relayUrl 无需 api_key 鉴权(token 本身就是凭证),任何拿到该 URL 的服务都能取码。请仅分享给可信第三方。
每次 GET 都会主动向上游 smsbower 查询一次最新状态——你不需要再单独调 getStatus

开始接入

添加 TG 客户经理,5 分钟内回复。

联系 @younaotekan