聆界短信平台 · HTTP 接入文档

接入指南

接口版本：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：

将请求方法、路径、时间戳、nonce 和原始请求体按以下规则拼接，使用 Secret 计算一次 HMAC-SHA256 · text · 仅供阅读，不执行请求

签名原文 = 字节拼接(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，末尾没有换行：

POST 签名校对示例 · text · 仅供阅读，不执行请求

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

完整签名原文：

完整签名原文 · text · 仅供阅读，不执行请求

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 自带的加密库，只进行本地计算。

计算方法（Node.js） · javascript · 仅供阅读，不执行请求

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：

输出结果，填入 X-Signature · text · 仅供阅读，不执行请求

a951451624d37d3e9df24045dc65d94557551dcbeada26988e25b6d49e945124

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

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

计算公式：

计算公式 · text · 仅供阅读，不执行请求

签名原文 = 请求方法 + 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 不参与本公式。

拼接签名原文：

拼接签名原文 · text · 仅供阅读，不执行请求

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 自带的加密库，只进行本地计算。

计算方法（Node.js） · javascript · 仅供阅读，不执行请求

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);

输出结果：

输出结果 · text · 仅供阅读，不执行请求

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 字符，可使用字母、数字、点、下划线、冒号和短横线。

请求体示例：

请求体示例 · json · 仅供阅读，不执行请求

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

3.3 请求示例

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

将上面的 JSON 保存为 UTF-8 无 BOM 的 sms.json。按第 2 节对文件原始字节计算签名，并准备相应变量。发送命令 · bash · 仅供阅读，不执行请求

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 请求报文：

HTTP 请求报文 · 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 · 仅供阅读，不执行请求

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 · 仅供阅读，不执行请求

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 请求示例

4.3 请求示例 · bash · 仅供阅读，不执行请求

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 请求报文：

HTTP 请求报文 · 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 · 仅供阅读，不执行请求

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 · 仅供阅读，不执行请求

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	否	1 开头的 11 位手机号，精确匹配
accessNumber	string	否	1–21 位数字接入号，精确匹配 destId
keyword	string	否	筛选正文包含指定关键词的回复
limit	正整数	否	默认 50；按应用最大分页配置裁剪，系统默认上限 100
cursor	string	否	首次不传；下一页使用上一响应的 nextCursor

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

5.3 请求示例

5.3 请求示例 · bash · 仅供阅读，不执行请求

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 请求报文：

HTTP 请求报文 · 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 · 仅供阅读，不执行请求

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

没有回复：

没有回复 · json · 仅供阅读，不执行请求

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

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

分页参数错误：

分页参数错误 · http · 仅供阅读，不执行请求

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，下一页示例：

5.5 下一页查询 · bash · 仅供阅读，不执行请求

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 请求报文：

HTTP 请求报文 · 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 请求示例

6.3 请求示例 · bash · 仅供阅读，不执行请求

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 请求报文：

HTTP 请求报文 · 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 · 仅供阅读，不执行请求

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 · 仅供阅读，不执行请求

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 通知示例

7.4 通知示例 · http · 仅供阅读，不执行请求

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 换行、原始请求体”签名，使用该回调地址对应的签名密钥。

7.5 验证通知签名 · text · 仅供阅读，不执行请求

签名原文 = 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 · 仅供阅读，不执行请求

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

OK

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

暂时无法保存时的响应示例 · http · 仅供阅读，不执行请求

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 通知示例

8.3 通知示例 · http · 仅供阅读，不执行请求

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；失败重试规则相同。

8.4 验签与确认 · http · 仅供阅读，不执行请求

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

OK

9. HTTP 状态与错误码

错误响应示例：

错误响应示例 · json · 仅供阅读，不执行请求

{
  "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 或完整鉴权信息。