hectorzhao/lislgosms
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
18ecf8045f488af349812938d513753aa25ec237
lislgosms/docs/client-http-api-guide.md
T
hectorzhao 18ecf8045f
CSS quality / css-quality (push) Has been cancelled
Details
feat: simplify HTTP request signing and publish revised client guide
2026-09-15 14:58:31 +08:00

44 KiB
Raw Blame History

聆界短信 HTTP API 参考手册

接口版本：v1 · 文档日期：2026-09-15

1. API 概览

聆界短信 HTTP API 提供单条短信发送、发送结果查询和用户回复查询。平台还可将短信回执和用户回复主动推送到客户系统。

1.1 服务地址与数据格式

项目 约定
接口基础地址 https://api.lisglo.com/api/openapi/v1
OpenAPI 定义 https://api.lisglo.com/api/client-docs-json
数据格式 UTF-8 JSON
发送方式 POST
查询方式 GET，不携带请求体
授权方式 Access Key + HMAC-SHA256 请求签名
发送受理 HTTP 202
查询成功 HTTP 200

业务接口的成功响应直接返回结果对象；Webhook 正文包含事件信息和 data 业务对象。

1.2 接口目录

接口名称 方法 接口路径 成功响应
单条短信发送接口 POST /api/openapi/v1/sms/messages 202：请求已受理
单条短信回执查询接口 GET /api/openapi/v1/sms/messages/{messageId} 200：返回短信状态
上行短信列表查询接口 GET /api/openapi/v1/sms/uplinks 200：返回回复列表
上行短信详情查询接口 GET /api/openapi/v1/sms/uplinks/{uplinkId} 200：返回指定回复

上表路径应拼接在 https://api.lisglo.com 后。收到 202 表示平台受理，不代表手机已经收到短信。最终结果通过回执查询或回执回调获取。

1.3 接入准备

  1. 联系聆界平台客服创建企业账号和短信应用，开通 HTTP 及相应发送、查询、回调能力，配置调用服务器的 IP 白名单。
  2. 在客户端“接口对接”选择应用，确认接口地址、QPS 和白名单。
  3. 在“访问凭据”创建 Access Key 和 Secret。Secret 仅在创建或轮换时展示一次，请保存在后端安全配置中。
  4. 发送前完成短信签名和模板审核；提交的完整正文应符合本应用的审核与发送要求。
  5. 如需接收回调，在“回调配置”保存公网 HTTPS 地址和各自的回调签名密钥。

接口凭据只能用于所属应用，平台登录密码不能代替 Secret。回调验签密钥与接口 Secret 分开保存。轮换请求凭据时先建立新凭据并切换调用，再吊销旧凭据；回调密钥轮换需同步更新接收端。

建议先按第 2 节校对签名，再调用上行列表查询接口验证接入；没有回复时返回空列表。

1.4 怎样使用后面的 cURL 示例

HTTP 报文使用演示 Access Key、演示 Secret DEMO_SECRET_NOT_A_REAL_CREDENTIAL 和固定时间戳；签名已计算，POST 正文末尾不含换行，游标为格式示例。实际调用使用本应用凭据、当前时间、新 nonce 和上一页返回的游标。

示例中的变量按下表准备；它们表示你自己的调用参数，不是平台提供的固定凭据。

变量 准备方法
$ACCESS_KEY 填入本应用的 Access Key
$TIMESTAMP 生成当前 Unix 秒级时间戳
$NONCE 为本次调用生成新的 UUID v4
$SIGNATURE 按第 2 节规则，使用本次方法、路径、时间戳、nonce 和请求体计算
$CURSOR 仅在翻页时使用，完整取自上一响应的 nextCursor

先在本机 Bash 会话中设置相应变量，再执行 cURL。每次调用重新计算，不可直接沿用另一接口或上一次调用的签名。示例使用 Bash 续行语法；PowerShell 请使用 curl.exe 并调整变量及续行写法。

POST 示例使用 --data-binary 原样发送文件；保存 sms.json 时采用 UTF-8 无 BOM，签名也读取该文件的同一份字节。cURL 进程成功退出后仍需检查 HTTP 状态和响应。

2. 授权与请求签名

2.1 填写请求头

请求头 必填 填写方式
X-App-Key 是 该应用的 Access Key
X-Timestamp 是 当前 Unix 时间戳，单位为秒，例如 1789344000；不要传毫秒
X-Nonce 是 本次 HTTP 请求的唯一标识，推荐 UUID v4，例如 550e8400-e29b-41d4-a716-446655440000；同一次发送的网络重试时，需要重新生成 UUID v4
X-Signature 是 按下文计算的 HMAC-SHA256，小写十六进制字符串
Idempotency-Key 发送时必填 一次业务发送的稳定编号，8～128 字符，允许字母、数字、.、_、:、-
Content-Type POST 使用 application/json
User-Agent 否 可填写客户端名称和版本，便于排错

每次调用，包括网络重试，都使用当前秒级时间戳和新的请求唯一标识。默认允许服务器时间前后相差 300 秒，具体以应用配置为准。X-Nonce 推荐 UUID v4，也接受字母、数字、下划线、短横线组成的 8～128 字符。

2.2 POST 发送请求如何计算签名

将请求方法、路径、时间戳、nonce 和原始请求体按以下规则拼接，使用 Secret 计算一次 HMAC-SHA256：

签名原文 = 字节拼接(UTF8(请求方法 + LF + 请求路径 + LF + 时间戳 + LF + nonce + LF), 原始请求体字节)
X-Signature = HEX(HMAC_SHA256(UTF8(Secret), 签名原文))
内容 规则
请求方法 大写，例如 POST
请求路径 从 /api 开始，不含域名及问号后的查询参数；路径参数使用实际发送的 URL 编码形式
时间戳 与 X-Timestamp 完全一致的秒级时间戳
nonce 与 X-Nonce 完全一致
LF 一个换行字节（0x0A），不能替换成 CRLF
原始请求体 实际发送的 UTF-8 JSON 字节，不预先计算摘要
Secret 直接使用 UTF-8 字节作为密钥，不做 Base64 解码
HEX 转为 64 位小写十六进制字符串

前四项后各接一个 LF，再接完整请求体。请求体可以有多行，空格、换行和字段顺序必须与实际发送内容完全一致；不要在签名时额外增加换行。Idempotency-Key 和 URL 查询参数不参与签名。

POST 签名校对示例：

演示 Secret：DEMO_SECRET_NOT_A_REAL_CREDENTIAL。请求体为下面这一整行，开头没有 BOM，末尾没有换行：

{"mobile":"13800138000","content":"【示例签名】您的验证码是123456，5分钟内有效。","clientMessageId":"doc-example-20260914-0001"}

完整签名原文：

POST
/api/openapi/v1/sms/messages
1789355443
7921b5d1-3b99-48d4-a068-ea7cf0c998db
{"mobile":"13800138000","content":"【示例签名】您的验证码是123456，5分钟内有效。","clientMessageId":"doc-example-20260914-0001"}

计算方法（Node.js）：

将以下代码保存为 post-signature.cjs，运行 node post-signature.cjs。代码使用 Node.js 自带的加密库，只进行本地计算。

const { createHmac } = require('node:crypto');

const secret = 'DEMO_SECRET_NOT_A_REAL_CREDENTIAL';
const method = 'POST';
const path = '/api/openapi/v1/sms/messages';
const timestamp = '1789355443';
const nonce = '7921b5d1-3b99-48d4-a068-ea7cf0c998db';
const body = Buffer.from(
  '{"mobile":"13800138000","content":"【示例签名】您的验证码是123456，5分钟内有效。","clientMessageId":"doc-example-20260914-0001"}',
  'utf8'
);

// 前四项后各接一个 LF，再拼接实际发送的请求体字节。
const prefix = method + '\n'
  + path + '\n'
  + timestamp + '\n'
  + nonce + '\n';
const signingBytes = Buffer.concat([
  Buffer.from(prefix, 'utf8'),
  body,
]);

const signature = createHmac('sha256', Buffer.from(secret, 'utf8'))
  .update(signingBytes)
  .digest('hex');

console.log(signature);

实际从文件发送时，将 body 的赋值改为 const body = require('node:fs').readFileSync('sms.json');，签名和发送使用同一份文件字节，不要解析后重新生成 JSON。

输出结果，填入 X-Signature：

a951451624d37d3e9df24045dc65d94557551dcbeada26988e25b6d49e945124

2.3 GET 查询请求如何计算签名

GET 请求不携带正文。签名只拼接请求方法、请求路径、时间戳和 nonce 四项，相邻项之间用一个 LF 换行符分隔，nonce 后不加换行。

计算公式：

签名原文 = 请求方法 + LF + 请求路径 + LF + 时间戳 + LF + nonce
X-Signature = HEX(HMAC_SHA256(UTF8(Secret), UTF8(签名原文)))

UTF8 表示将字符串转换为 UTF-8 字节；HMAC_SHA256 表示以 Secret 为密钥对签名原文进行运算；HEX 表示将运算结果转换为 64 位小写十六进制字符串。

本例输入：

项目 值
Secret doc-example-secret
请求方法 GET
请求路径 /api/openapi/v1/sms/uplinks
时间戳 1789344000
nonce 550e8400-e29b-41d4-a716-446655440000

请求路径不含域名和问号后的查询参数；包含路径参数时，使用实际发送的 URL 编码形式。时间戳和 nonce 必须分别与 X-Timestamp、X-Nonce 一致。Secret 直接作为 UTF-8 密钥使用，不做 Base64 解码；Access Key 和 Idempotency-Key 不参与本公式。

拼接签名原文：

GET\n/api/openapi/v1/sms/uplinks\n1789344000\n550e8400-e29b-41d4-a716-446655440000

上面每个 \n 表示一个 LF 换行字节（0x0A），不是反斜杠和字母 n，也不能替换为 CRLF。签名原文在 nonce 的最后一个字符处结束，不追加 LF、{} 或其他正文。

计算方法（Node.js）：

将以下代码保存为 get-signature.cjs，运行 node get-signature.cjs。代码使用 Node.js 自带的加密库，只进行本地计算。

const { createHmac } = require('node:crypto');

const secret = 'doc-example-secret';
const method = 'GET';
const path = '/api/openapi/v1/sms/uplinks';
const timestamp = '1789344000';
const nonce = '550e8400-e29b-41d4-a716-446655440000';

// 四项之间用 LF 分隔，nonce 后不加 LF。
const signingText = method + '\n'
  + path + '\n'
  + timestamp + '\n'
  + nonce;

const signature = createHmac('sha256', Buffer.from(secret, 'utf8'))
  .update(Buffer.from(signingText, 'utf8'))
  .digest('hex');

console.log(signature);

输出结果：

3db9c015c2b1c5365a0ef296a79b419653b0087daed2792cdb5717b0802eec51

将该结果填入 X-Signature 请求头。其他语言按相同输入字节调用标准库的 HMAC-SHA256，并输出小写十六进制，结果应一致。

本例的固定时间戳和演示密钥仅用于离线校对。实际调用使用本应用 Secret、当前秒级时间戳和新的 nonce，并重新计算签名。

3. API：单条短信发送

3.1 接口说明

向一个中国大陆手机号发送一条短信。正文填写完整短信签名及已替换变量的内容，平台据此匹配本应用的签名与模板。

项目 内容
URL https://api.lisglo.com/api/openapi/v1/sms/messages
HTTP 方法 POST
Content-Type application/json
是否鉴权 是，四个鉴权头见第 2 节
业务幂等头 Idempotency-Key，必填
所需能力 短信发送
成功状态 202 Accepted

3.2 请求参数

JSON 字段 类型 必填 说明
mobile string 是 单个中国大陆手机号，例如 13800138000；不能传数组或逗号分隔号码
content string 是 完整短信正文，包含签名和已填入的变量值；不能为空
clientMessageId string 否，建议提供 你的业务系统消息编号，应用内唯一；按不超过 128 字符使用

只传上述业务字段，不传企业、应用、签名、模板或通道选择字段。Idempotency-Key 为稳定的业务发送编号，8～128 字符，可使用字母、数字、点、下划线、冒号和短横线。

请求体示例：

{
  "mobile": "13800138000",
  "content": "【示例签名】您的验证码是123456，5分钟内有效。",
  "clientMessageId": "order-20260914-0001"
}

3.3 请求示例

将上面的 JSON 保存为 UTF-8 无 BOM 的 sms.json。按第 2 节对文件原始字节计算签名，并准备相应变量。发送命令：

curl --include --max-time 15 --request POST \
  "https://api.lisglo.com/api/openapi/v1/sms/messages" \
  --header "X-App-Key: $ACCESS_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: $SIGNATURE" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sms-order-20260914-0001" \
  --data-binary "@sms.json"

HTTP 请求报文：

POST /api/openapi/v1/sms/messages HTTP/1.1
Host: api.lisglo.com
Accept: */*
X-App-Key: DEMO_ACCESS_KEY_NOT_REGISTERED
X-Timestamp: 1789355443
X-Nonce: 4755e099-ba9a-4e6f-affa-3630261e7feb
X-Signature: e2a70fdd364cc865e251d475cec722bb949500d255649d215b0039de89f68125
Content-Type: application/json
Idempotency-Key: sms-order-20260914-0001
Content-Length: 154

{
  "mobile": "13800138000",
  "content": "【示例签名】您的验证码是123456，5分钟内有效。",
  "clientMessageId": "order-20260914-0001"
}

执行使用有效凭据的发送命令会提交短信请求；文档样例不自动执行。

3.4 返回结果

受理成功：

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
  "code": "ACCEPTED",
  "requestId": "req_11111111-1111-4111-8111-111111111111",
  "messageId": "MSG-22222222-2222-4222-8222-222222222222",
  "clientMessageId": "order-20260914-0001",
  "status": "queued",
  "acceptedAt": "2026-09-14T02:00:00.000Z"
}
字段 类型 说明
code string ACCEPTED 表示受理成功
requestId string 业务请求编号，用于排障
messageId string 平台短信编号，用于查询
clientMessageId string/null 调用方传入的业务短信编号
status string 当前业务状态，例如 queued 或 pending_review
acceptedAt string 受理时间，ISO 8601

保存 messageId 与客户业务编号的对应关系。202 不等于短信送达；若未取得明确结果，先查询已有记录。

幂等键与正文不一致：

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://cmpp-platform.local/problems/idempotency_conflict",
  "title": "CONFLICT",
  "status": 409,
  "code": "IDEMPOTENCY_CONFLICT",
  "detail": "同一Idempotency-Key对应的请求内容不一致"
}

3.5 超时、重试与重复请求

情况 建议处理
网络超时，无法确认受理结果 先按 clientMessageId 查询；必要时使用相同幂等键和相同原始正文重试
重试一次 HTTP 调用 重新生成时间戳、nonce 和签名；业务幂等键及正文保持不变
相同幂等键且正文一致 已完成时重放原受理响应或已保存的业务失败结果
相同幂等键但正文不同 返回 IDEMPOTENCY_CONFLICT
原请求仍处理中 返回 REQUEST_PROCESSING；稍后查询，长期不结束联系平台
换幂等键但客户短信编号已使用 返回 CLIENT_MESSAGE_ID_CONFLICT，核对已有业务

保存业务幂等键，不通过换键绕过冲突。JSON 空格或字段顺序变化也会被判定为不同正文。

4. API：单条短信回执查询

4.1 接口说明

查询一条短信的提交状态、回执结果和时间。

项目 内容
URL https://api.lisglo.com/api/openapi/v1/sms/messages/{messageId}
HTTP 方法 GET
请求体 无
是否鉴权 是，按第 2 节 GET 规则签名
所需能力 短信状态查询
成功状态 200 OK

4.2 路径参数

参数 类型 必填 说明
messageId string 是 平台短信编号，也支持发送时提交的 clientMessageId；仅限当前应用

路径参数需 URL 编码，签名使用编码后的实际路径。

4.3 请求示例

curl --include --max-time 15 --request GET \
  "https://api.lisglo.com/api/openapi/v1/sms/messages/MSG-22222222-2222-4222-8222-222222222222" \
  --header "X-App-Key: $ACCESS_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: $SIGNATURE"

HTTP 请求报文：

GET /api/openapi/v1/sms/messages/MSG-22222222-2222-4222-8222-222222222222 HTTP/1.1
Host: api.lisglo.com
Accept: */*
X-App-Key: DEMO_ACCESS_KEY_NOT_REGISTERED
X-Timestamp: 1789355443
X-Nonce: 3efb63ee-b99d-47c2-aa87-cbfeb7730a30
X-Signature: 8843aa140566a16a9fddd81339235a94abc218af125963ca2df365e5454f8212

4.4 返回结果

查询成功：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "messageId": "MSG-22222222-2222-4222-8222-222222222222",
  "clientMessageId": "order-20260914-0001",
  "phoneNumber": "13800138000",
  "status": "delivered",
  "submitStatus": "accepted",
  "receiptStatus": "delivered",
  "errorCode": null,
  "errorMessage": null,
  "queuedAt": "2026-09-14T02:00:00.000Z",
  "submittedAt": "2026-09-14T02:00:01.000Z",
  "deliveredAt": "2026-09-14T02:00:03.000Z",
  "updatedAt": "2026-09-14T02:00:03.100Z"
}
字段 类型 说明
messageId string 平台短信编号
clientMessageId string/null 客户消息编号
phoneNumber string 接收手机号；注意响应字段不是 mobile
status string 平台业务状态
submitStatus string/null 提交状态，如 queued、accepted、rejected、timeout
receiptStatus string/null 回执状态，如 delivered、undelivered、unknown；null 表示尚无结果
errorCode / errorMessage string/null 失败码与说明，未发生或暂无时可为空
queuedAt / updatedAt string 入队记录时间、最近更新时间
submittedAt / deliveredAt string/null 提交时间、结果时间，尚无数据时可为空

常见 status 的业务含义：

状态 你应如何理解
pending_review 等待审核，不代表已送出
queued / submit_queued 等待平台处理或向通道提交
submitted 已提交，等待明确回执
delivered 已获得送达结果
submit_failed / failed / rejected 提交失败、发送失败或业务拒绝，结合错误字段查看原因
unknown / timeout 结果未知或等待超时，不能当成送达

上述是常见值，不是服务端严格冻结的全部枚举。遇到其他值保留原值并展示“待确认”，不要默认成功。deliveredAt 在失败回执中也可能是结果发生时间，不能只看这个字段非空就认为送达。

不存在或不属于本应用时返回 404 MESSAGE_NOT_FOUND。查询刚超时的发送得到 404 也不能单独证明业务永远不会落库。

记录不存在或不属于当前应用：

HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://cmpp-platform.local/problems/message_not_found",
  "title": "NOT_FOUND",
  "status": 404,
  "code": "MESSAGE_NOT_FOUND",
  "detail": "短信记录不存在"
}

5. API：上行短信列表查询

5.1 接口说明

查询手机用户回复的短信。无需填写时间参数，默认读取最近 24 小时内已归属本应用的回复。

项目 内容
URL https://api.lisglo.com/api/openapi/v1/sms/uplinks
HTTP 方法 GET
请求体 无
是否鉴权 是，按第 2 节 GET 规则签名
所需能力 上行查询
成功状态 200 OK
排序 接收时间、记录编号倒序

5.2 查询参数

参数 类型 必填 默认值 / 说明
mobile string 否 精确匹配回复者手机号
accessNumber string 否 精确匹配短信接入号，对应返回字段 destId
keyword string 否 筛选正文包含指定关键词的回复
limit 正整数 否 默认 50；按应用最大分页配置裁剪，系统默认上限 100
cursor string 否 首次不传；下一页使用上一响应的 nextCursor

不使用的筛选项省略，所有 query 参数都不放入签名原文。

5.3 请求示例

curl --include --max-time 15 --get \
  "https://api.lisglo.com/api/openapi/v1/sms/uplinks" \
  --data-urlencode "limit=25" \
  --header "X-App-Key: $ACCESS_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: $SIGNATURE"

HTTP 请求报文：

GET /api/openapi/v1/sms/uplinks?limit=25 HTTP/1.1
Host: api.lisglo.com
Accept: */*
X-App-Key: DEMO_ACCESS_KEY_NOT_REGISTERED
X-Timestamp: 1789355443
X-Nonce: 567a9bdd-7d62-4097-9fa8-50586fa14c32
X-Signature: 7ca4cb9fe5fb455d9314797d00eeab797257e2671d0a547414122e971f534214

5.4 返回结果

查询成功：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "items": [
    {
      "id": "uplink-example-001",
      "messageId": null,
      "phoneNumber": "13800138000",
      "destId": "106900000000",
      "content": "收到，谢谢",
      "receivedAt": "2026-09-14T02:05:00.000Z"
    }
  ],
  "nextCursor": null
}
字段 类型 说明
items array 本页上行记录，没有记录时为空数组
nextCursor string/null 下一页凭据；null 表示本次查询结束

items 中每条记录的字段：

字段 类型 说明
id string 上行记录编号，用于查询详情
messageId string/null 关联的平台短信编号，未关联时为 null
phoneNumber string 回复短信的手机号
destId string 接收回复的短信接入号
content string 用户回复的正文
receivedAt string 接收时间，ISO 8601；Z 表示 UTC

没有回复：

{
  "items": [],
  "nextCursor": null
}

HTTP 状态为 200。无总条数或页码字段。

分页参数错误：

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://cmpp-platform.local/problems/limit_invalid",
  "title": "BAD_REQUEST",
  "status": 400,
  "code": "LIMIT_INVALID",
  "detail": "limit必须为正整数"
}

5.5 下一页查询

nextCursor 非 null 时，将完整值赋给 $CURSOR，保持首次使用的 limit 和其他筛选不变，重新生成鉴权头。假设第一页使用 limit=25，下一页示例：

curl --include --max-time 15 --get \
  "https://api.lisglo.com/api/openapi/v1/sms/uplinks" \
  --data-urlencode "limit=25" \
  --data-urlencode "cursor=$CURSOR" \
  --header "X-App-Key: $ACCESS_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: $SIGNATURE"

HTTP 请求报文：

GET /api/openapi/v1/sms/uplinks?limit=25&cursor=WyIyMDI2LTA5LTE0VDAyOjA1OjAwLjAwMFoiLCJ1cGxpbmstZXhhbXBsZS0wMDEiXQ HTTP/1.1
Host: api.lisglo.com
Accept: */*
X-App-Key: DEMO_ACCESS_KEY_NOT_REGISTERED
X-Timestamp: 1789355443
X-Nonce: 2232e6cf-144d-41c6-ac86-df7fb6184d78
X-Signature: 50869db4ff5a3b2d3ba5e6c1184020fc0ed50fbc594a56ccc6e2a16f7b617657

直到 nextCursor 为 null 后停止。游标由平台返回，不自行生成或解码；格式错误返回 400 CURSOR_INVALID。每次默认查询范围随当前时间滚动，同一轮翻页应尽快完成，定期采集按 id 去重。历史补查或完整历史同步请联系平台。

6. API：上行短信详情查询

6.1 接口说明

查看一条用户回复的完整业务信息。

项目 内容
URL https://api.lisglo.com/api/openapi/v1/sms/uplinks/{uplinkId}
HTTP 方法 GET
请求体 无
是否鉴权 是，按第 2 节 GET 规则签名
所需能力 上行查询
成功状态 200 OK

6.2 路径参数

参数 类型 必填 说明
uplinkId string 是 列表中的 id 或回调中的 uplinkMessageId，按 URL 路径编码

6.3 请求示例

curl --include --max-time 15 --get \
  "https://api.lisglo.com/api/openapi/v1/sms/uplinks/uplink-example-001" \
  --header "X-App-Key: $ACCESS_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: $SIGNATURE"

HTTP 请求报文：

GET /api/openapi/v1/sms/uplinks/uplink-example-001 HTTP/1.1
Host: api.lisglo.com
Accept: */*
X-App-Key: DEMO_ACCESS_KEY_NOT_REGISTERED
X-Timestamp: 1789355443
X-Nonce: 7229fc46-7526-4726-a42b-a8edfe68fbdf
X-Signature: 869e57abbd91ceaadb73dbca1a091d0deba083e93acccc58cc4a941d9c18a1c8

6.4 返回结果

查询成功：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "uplink-example-001",
  "messageId": null,
  "phoneNumber": "13800138000",
  "destId": "106900000000",
  "content": "收到，谢谢",
  "receivedAt": "2026-09-14T02:05:00.000Z",
  "tenantId": "tenant-example",
  "applicationId": "application-example"
}

字段与第 5 节单条记录相同，增加 tenantId（本企业 ID）、applicationId（本应用 ID）；只返回客户自己的业务信息，不提供通道字段。

查询失败：

HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://cmpp-platform.local/problems/uplink_not_found",
  "title": "NOT_FOUND",
  "status": 404,
  "code": "UPLINK_NOT_FOUND",
  "detail": "上行记录不存在"
}

7. Webhook：短信回执通知

7.1 通知说明

短信产生回执结果时，平台向客户配置的回执地址发送 receipt 事件。

项目 内容
URL 客户在回调配置中保存的公网 HTTPS 地址
HTTP 方法 POST
Content-Type application/json
事件类型 receipt
签名密钥 回执回调地址对应的密钥
成功确认 客户返回任意 HTTP 2xx

参数错误或未受理的同步请求不保证生成回调；长短信按业务消息通知。保存发送响应中的编号映射，按 data.messageId 关联业务，回调不保证携带 clientMessageId。

7.2 请求头

请求头 说明
Content-Type application/json
X-Event-Id 事件编号，用于去重
X-Event-Type receipt（回执）或 uplink（用户回复）
X-Timestamp 本次投递的 Unix 秒级时间戳
X-Signature sha256= 前缀加 HMAC-SHA256 十六进制签名

7.3 请求字段

字段 类型 说明
eventId string 同一事件的唯一编号，重复投递时不变
eventType string 事件类型
occurredAt string 事件生成时间，ISO 8601
data object 对应事件的业务数据

receipt 事件的 data 字段：

data 字段 类型 说明
messageId string 平台短信编号，与发送响应关联
gatewayMessageId string/null 短信传输编号，可缺省；关联业务使用 messageId
phoneNumber string 接收短信的手机号
receiptStatus string 回执结果，delivered 表示送达
rawStatus string/null 原始回执状态，如 DELIVRD；可缺省
errorCode string/null 错误码，可缺省
errorMessage string/null 错误说明，部分失败事件提供
deliveredAt string/null 结果时间，可缺省；时间存在不等于发送成功

7.4 通知示例

POST /webhooks/sms/receipt HTTP/1.1
Host: customer.example.com
Content-Type: application/json
X-Event-Id: evt_receipt_example001
X-Event-Type: receipt
X-Timestamp: 1789344000
X-Signature: sha256=<本次投递的签名>

{
  "eventId": "evt_receipt_example001",
  "eventType": "receipt",
  "occurredAt": "2026-09-14T02:00:03.100Z",
  "data": {
    "messageId": "MSG-22222222-2222-4222-8222-222222222222",
    "gatewayMessageId": "example-gateway-id",
    "phoneNumber": "13800138000",
    "receiptStatus": "delivered",
    "rawStatus": "DELIVRD",
    "errorCode": null,
    "deliveredAt": "2026-09-14T02:00:03.000Z"
  }
}

地址和签名为说明用途，实际平台使用客户配置的地址并生成本次签名。

7.5 验证通知签名

回调验签与接口请求签名不同。回调只对“时间戳、一个 LF 换行、原始请求体”签名，使用该回调地址对应的签名密钥。

签名原文 = UTF8(X-Timestamp) + LF + 原始请求体字节
期望签名 = "sha256=" + HEX(HMAC_SHA256(回调签名密钥, 签名原文))

接收端按以下顺序处理：

  1. 保留原始请求体字节，不要解析后重新生成 JSON 再验签。
  2. 检查时间戳为秒级时间戳并校验时间偏差；接收端可采用前后 300 秒的策略。
  3. 计算期望签名，使用常量时间比较方法与 X-Signature 比较。
  4. 验签通过后解析 JSON，核对请求头与正文中的事件编号、事件类型一致。
  5. 以 eventId 做持久化唯一约束或原子去重，再保存事件。

同一事件重试时，eventId 和事件正文不变，投递时间戳和签名重新生成。已成功保存的重复事件正常确认，不重复执行后续业务。occurredAt 是事件生成时间，短信实际结果或回复时间分别取 data.deliveredAt、data.receivedAt。

7.6 接收确认与失败重试

平台将任意 HTTP 2xx 视为接收成功，不要求固定响应正文。建议验签并可靠保存后及时确认，后续业务异步处理。

接收成功响应示例：

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

OK

暂时无法保存时的响应示例：

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain; charset=utf-8

temporarily unavailable
接收端结果 平台处理
任意 2xx 视为成功，不再自动重试；即使正文写“失败”也按成功处理
网络错误、408、429、5xx 在应用开启重试且未达到次数上限时安排重试
其他 4xx 视为失败，通常不自动重试
3xx 不跟随重定向

默认最多尝试 7 次，包含第一次投递。第一次失败后依次等待 1 分钟、5 分钟、15 分钟、1 小时、6 小时、24 小时；这些是相邻尝试之间的等待时间，具体受应用重试配置限制。默认回调超时配置为 10 秒，请尽快完成可靠保存和确认。

回调未收到不等于短信发送失败，可使用短信回执查询接口核对结果。回调可能重复或延迟到达，业务系统应按事件编号去重。

8. Webhook：上行短信通知

8.1 通知说明

收到并确认归属本应用的用户回复后，平台向上行回调地址发送 uplink 事件。

项目 内容
URL 客户在回调配置中保存的上行公网 HTTPS 地址
HTTP 方法 POST
Content-Type application/json
事件类型 uplink
签名密钥 上行回调地址对应的密钥
成功确认 客户返回任意 HTTP 2xx

8.2 请求字段

公共请求头和事件外层字段与第 7 节相同，事件类型为 uplink。data 包含：

data 字段 类型 说明
applicationId string 本应用 ID
phoneNumber string 回复者手机号
destId string 接收回复的短信接入号
content string 回复正文
receivedAt string 接收时间，ISO 8601
uplinkMessageId string 上行记录编号，可用于详情查询
messageId string/null 可能提供的关联短信编号；缺省时不强行关联
manualClaim boolean 可选；true 表示该回复经人工确认归属

8.3 通知示例

POST /webhooks/sms/uplink HTTP/1.1
Host: customer.example.com
Content-Type: application/json
X-Event-Id: evt_uplink_example001
X-Event-Type: uplink
X-Timestamp: 1789344000
X-Signature: sha256=<本次投递的签名>

{
  "eventId": "evt_uplink_example001",
  "eventType": "uplink",
  "occurredAt": "2026-09-14T02:05:00.100Z",
  "data": {
    "applicationId": "application-example",
    "phoneNumber": "13800138000",
    "destId": "106900000000",
    "content": "收到，谢谢",
    "receivedAt": "2026-09-14T02:05:00.000Z",
    "uplinkMessageId": "uplink-example-001"
  }
}

没有 messageId 时，按 uplinkMessageId 保存用户回复，不强行关联发送记录。

8.4 验签与确认

按第 7.5 节规则验签，但使用上行回调密钥。以 eventId 原子去重并可靠保存后，按第 7.6 节返回 2xx；失败重试规则相同。

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

OK

9. HTTP 状态与错误码

错误响应示例：

{
  "type": "https://cmpp-platform.local/problems/signature_invalid",
  "title": "UNAUTHORIZED",
  "status": 401,
  "code": "SIGNATURE_INVALID",
  "detail": "请求签名校验失败"
}
HTTP code 处理方法
400 PARAMETER_INVALID / LIMIT_INVALID 检查字段类型、长度和正整数分页
409 REQUEST_REQUIRES_REVIEW 提供 requestId 核对，不更换幂等键重发
400 MOBILE_INVALID / CONTENT_REQUIRED 检查单个手机号和正文
400 IDEMPOTENCY_KEY_INVALID 补齐有效幂等键，检查长度与字符
413 PAYLOAD_TOO_LARGE JSON 请求体超过 2 MiB 限制，减少内容后再提交
415 UNSUPPORTED_MEDIA_TYPE 检查请求体编码及字符集，使用 UTF-8 JSON
400 CURSOR_INVALID 使用平台返回的 cursor，保持筛选条件一致
401 AUTH_HEADERS_MISSING 补齐四个鉴权头
401 CREDENTIAL_INVALID 核对应用、Access Key、有效期和吊销状态
401 NONCE_INVALID / NONCE_REPLAYED 检查格式，每次调用生成新的 nonce
401 TIMESTAMP_EXPIRED 使用秒级时间戳并同步时钟
401 SIGNATURE_INVALID 核对 Secret、签名原文、路径、原始请求体及 GET 末尾无换行
403 HTTP_API_DISABLED 应用未启用或未开通 HTTP，联系平台
403 IP_NOT_ALLOWED 核对调用机器公网出口 IP 和 HTTP 白名单
403 SEND_NOT_ENABLED / MESSAGE_QUERY_NOT_ENABLED / UPLINK_QUERY_NOT_ENABLED 联系平台开通对应子能力
404 MESSAGE_NOT_FOUND / UPLINK_NOT_FOUND 核对编号及凭据所属应用
409 IDEMPOTENCY_CONFLICT 同键 body 不一致，停止盲重试并核对原请求
409 REQUEST_PROCESSING 查询既有业务结果；长期停留联系平台
409 CLIENT_MESSAGE_ID_CONFLICT 查询已有客户编号对应记录，避免重复业务发送
422 SEND_REJECTED 正文、审核或其他业务条件不满足，按说明处理，不盲重试
429 QPS_LIMIT_EXCEEDED 应用共享限流，降低并发、延后并加随机退避；新凭据不能扩大应用额度
5xx REQUEST_FAILED / INTERNAL_ERROR 等 保留请求标识和时间联系平台；发送场景先查询，避免重新创建业务

遇到未知状态或错误码时，保留原始响应并联系平台；不要默认成功。网络中断也可能没有 HTTP 响应。发送结果不确定时先核对已有记录，避免创建重复业务。

联系平台排查时，请提供应用名称、请求时间及时区、接口路径、HTTP 状态、业务 code，以及相关 requestId、messageId、clientMessageId 或 eventId。响应头 X-Request-Id 用于定位本次 HTTP 调用；发送正文 requestId 用于定位该次业务受理。不要提供 Secret 或完整鉴权信息。

Reference in New Issue View Git Blame Copy Permalink