莱特短信 莱特短信
登录 注册
DEVELOPER CENTER 全球短信 · 连接每一次业务

从第一条请求，
到完整的短信接入

从账号准备、接口认证到逐号码结果，按照清晰的接入步骤，把短信能力连接到你的业务服务。

开始接入 咨询技术问题
JSON 请求 AccessKey 认证 幂等重试
POST 发送你的第一条短信 
POST /sms-api/?action=sms.message.send&accessKeyId=ak_<40位十六进制>
X-Sms-Secret: <Secret>
Content-Type: application/json

{
  "to": ["+14155550123", "+442071838750"],
  "signature": "共享通道",
  "templateId": "notify_login",
  "templateData": { "CODE": "483920" },
  "requestId": "login_20261001_001"
}

01 / QUICK START

发送之前，先做好这四项准备

  1. 01

    创建客户账号

    注册并登录控制台，确认账号可正常使用。

  2. 02

    生成接口凭证

    在接口凭证中创建 AccessKey，并安全保存 Secret。

  3. 03

    准备短信模板

    使用已审核通过的模板，确认变量名称和类型。

  4. 04

    确认价格与余额

    检查目标国家价格、可用通道及账户余额。

建议为每个生产服务创建独立凭证，并配置 IP 白名单、发送频率和额度限制。

02 / AUTHENTICATION

把凭证留在服务端，把接入边界说明白

外部短信接口使用 AccessKey ID 和 Secret，不使用控制台登录会话。

统一接口入口

方法
POST
地址
/sms-api/
查询参数
action=sms.message.send
accessKeyId=<AccessKey ID>
请求格式
application/json

Secret 使用边界

  • 仅通过 X-Sms-Secret 请求头传入。
  • Secret 只在创建与轮换时显示一次。
  • 不要写入 URL、请求正文、浏览器代码或日志。
  • 泄露后及时轮换凭证，并核查调用记录。

认证请求头

字段 必填 说明
X-Sms-Secret 是 创建或轮换 AccessKey 时返回的 Secret，只在服务端保存并通过请求头发送

03 / SEND A MESSAGE

提交模板与变量，发起一次可追踪的请求

主动传入 requestId，为网络超时后的安全重试保留依据。

请求字段

字段 类型 必填 说明
to string | string[] 是 接收号码，支持单个号码或号码数组，使用国际号码格式
signature string 否 客户侧业务通道名称，例如“共享通道”；未传时使用默认通道，不是供应商短信签名
templateId string 是 已审核通过的短信模板编号
templateData object 是 模板变量对象，字段名和类型必须与模板声明一致；number 类型提交 JSON 安全整数，string 类型提交字符串，带前导零的验证码使用字符串类型模板变量
requestId string 否 业务幂等号，1 至 100 位字母、数字、点、下划线、冒号或连字符，区分大小写；未传时由服务端生成，建议主动传入；网络超时后使用原编号和相同请求内容重试，同号不同内容返回 40011
POST 请求示例 
POST /sms-api/?action=sms.message.send&accessKeyId=ak_<40位十六进制>
X-Sms-Secret: <Secret>
Content-Type: application/json

{
  "to": ["+14155550123", "+442071838750"],
  "signature": "共享通道",
  "templateId": "notify_login",
  "templateData": { "CODE": "483920" },
  "requestId": "login_20261001_001"
}

04 / RESULTS & ERRORS

HTTP 请求成功，只是结果处理的开始

请逐项记录号码状态、错误信息和计费结果，避免仅凭 HTTP 状态认定送达。

检查逐号码结果

读取 messages 中的 status、errorCode 与 errorMessage，按号码处理发送结果。

使用原编号重试

网络超时后使用相同 requestId 和相同内容重试；字段错误先修正，避免盲目重发。

按实际账务核对

以 amountUsd、billingStatus 和余额流水为准，不在客户端自行推算费用。

响应字段

字段 类型 说明
requestId string 本次请求的幂等号
jobId integer | null 发送任务编号，异步队列场景返回
queued boolean 是否已进入发送队列
messages array 逐号码结果，必须继续检查其中的 status 和 errorCode
messages[].status string 号码当前状态，如 submitting、unknown、sent、delivered、failed
messages[].billingStatus string 计费状态，如 frozen、consumed、refunded
messages[].errorCode string | null 号码级错误码，成功时为空
messages[].errorMessage string | null 号码级错误说明
messages[].amountUsd string 该号码实际计费金额，保留 6 位小数

常见错误码

错误码 含义 处理建议
40001 请求参数或号码格式错误 检查必填字段、字段类型、号码格式和批量数量
40002 发送凭证无效 检查客户登录凭证或接口 AccessKey 是否有效
40003 Secret 无效或缺失 确认 X-Sms-Secret 与 AccessKey ID 属于同一凭证
40004 客户账号不可用或无权限 检查账号状态、接口权限和来源 IP 白名单
40005 模板不存在或不可用 确认模板编号和审核状态
40006 通道或目的地不可用 确认客户通道已绑定，且目的地和业务场景已开放
40007 目的地或场景未开放 确认目标国家、地区和短信场景已配置并启用
40008 模板变量校验失败 按模板声明传入变量，确保名称、类型和长度正确
40009 余额不足 充值或等待余额到账后，再重新提交原请求
40010 发送频率或账号额度超限 降低发送频率，或检查客户额度和日限额配置
40011 请求编号冲突 相同 requestId 只能对应相同请求内容，换用新的业务编号
50001 没有可用的上游通道 检查平台通道和上游账号配置，稍后重试
50002 上游提交次数达到上限 等待系统处理或查看消息状态，不要重复创建新请求
50003 系统处理失败 保留 requestId 和请求时间，联系平台支持排查

LET’S CONNECT

准备好接入你的第一条短信了吗？

从你的业务场景出发，规划短信接入、发送与持续运营。

咨询接入方案