请求与响应约定
本页内容
调用接口前,先确认请求地址、认证方式和数据格式。本页说明企业签名、应用分发与账号账单 API 共用的约定;具体业务字段以对应接口为准。
选择请求地址
业务 API 使用网站主域名 https://www.onesignios.com,具体路径见接口页。例如,当前身份查询的完整地址为 https://www.onesignios.com/api/v1/whoami。请求必须使用 HTTPS。
应用的公开下载页面供安装用户访问;存储地址用于传输安装包。这两类地址与业务 API 的用途不同。请勿把下载页短链、分发域名或存储地址填入 SDK 的网站地址。
下面约定适用于 /api/v1/。OAuth 授权和令牌端点使用自己的表单参数,详见OAuth 接入;沙箱的入口与凭据见沙箱指南。
选择认证请求头
一次请求只使用一种认证方式。先查看接口页的认证要求,再按下表准备请求头。使用服务端 SDK 时,由 SDK 完成 AccessKey 签名。
| 认证方式 | 发送哪些请求头 | 适用范围 |
|---|---|---|
| 长期 AccessKey(AKP) | Authorization: CS1-HMAC-SHA256 …,以及日期、nonce、正文摘要和环境这四个 X-Api- 签名头。 | 自己的服务端;动作、应用范围和功能许可均需符合授权。 |
| 临时 AccessKey(AKT) | 与长期 AccessKey 相同,另传 X-Api-Security-Token,令牌摘要也参与签名。 | 临时授权所指定应用的只读接口,不能用于上传、付款或签名。 |
| OAuth | Authorization: Bearer <access_token>。不发送 AccessKey 的日期、nonce、摘要、环境和安全令牌头。 | 用户同意范围内的读取;终端上传或签名还需独立许可。仅支持长期 AccessKey 的接口不能改用 OAuth。 |
所有 POST 管理请求还须传 JSON 类型和幂等键,OAuth 也一样。浏览器直连需要使用已批准的精确 Origin;在浏览器中内置长期 Secret 或放开存储 CORS,均不能代替 API 的用户授权。
签名头的精确定义见AccessKey 请求签名;临时凭据的签发与撤销见临时只读凭据。
构造 GET 或 POST 请求
- 按接口选择 GET 或 POST,保留资源 ID 的完整前缀。路径中的
{id}需替换为自己账号返回的应用 ID。 - GET 的业务筛选条件放在查询串中,不发送正文或幂等键。查询参数不可重复;按 RFC 3986 编码,空格使用
%20,不要使用+。 - POST 的业务字段放在 UTF-8 JSON 对象中,使用
Content-Type: application/json,或附加charset=utf-8。没有业务字段时也发送{}。 - POST 在首次提交前持久保存
X-Api-Idempotency-Key、路径及正文。键为 16–64 位字母、数字、下划线或连字符;同一次业务重试恢复原值。
GET /api/v1/apps?limit=10&module=distribution上面只展示请求方法和路径,实际发送时还需认证头。筛选普通分发应用须显式指定 module=distribution。POST 接口不接受额外查询参数,也不要把安装包字节或 multipart 表单发给业务 API;文件应按上传凭证发往存储服务。
处理 ID、时间与金额
| 数据 | 处理方式 |
|---|---|
| 资源 ID | 作为不透明字符串完整保存,不从长度或顺序推测业务含义。应用、上传任务、签名任务和订单 ID 不能互换。 |
| 签名时间 | X-Api-Date 使用 UTC 文本,例如 2026-11-16T00:00:00Z。此值仅示意格式;实际请求使用当前时间,允许偏差最多 300 秒。 |
| 结果中的时间 | created_at 等整数字段通常为 Unix 秒,传给接收毫秒的时间库前需转换。证书到期文本、统计日期等字段按各自定义解释;统计和预算还需使用返回的 timezone。 |
| 金额 | 按返回的十进制字符串与 currency 单位处理。避免用二进制浮点数计算或比较付款金额;确认付款时原样使用报价金额和修订号。 |
| 文件大小与摘要 | size_bytes 的单位为字节。SHA-256 使用小写十六进制;上传所用 MD5 是原始 16 字节摘要的 Base64,不能互换。 |
| 空值与缺省值 | null、空字符串、数字零和字段省略可能含义不同。不能把缺少统计数据直接显示为零,也不要把 JSON 布尔值 true 写成字符串 "true"。 |
请求字段表的“必填”表示需要提交;响应字段表的“必返”表示成功响应中应有该字段;数据模型的“必需”表示该对象存在时应满足的结构要求。可空字段仍可以为 null。类型、可选值与边界可展开查看,示例值不代表全部允许范围。
判断请求和业务结果
- 先读取 HTTP 状态和 JSON。成功的管理请求返回 HTTP 200,从
data取得结果;失败响应从error.code判断原因。 - 保存
request_id。API 同时通过X-Request-Id响应头提供请求标识;错误响应也有此值,不能仅凭它判断成功。 - 上传和签名被受理后仍需等待原任务。HTTP 200 或
accepted=true不代表安装包已可用;以任务成功状态及对应版本或产物为准。
{
"request_id": "11111111111111111111111111111111",
"error": {
"code": "RevisionConflict",
"message": "应用信息已变化,请重新读取"
}
}此示例对应 HTTP 409。异步任务查询本身则可能 HTTP 200 成功,但 data.state 或 data.status 表示任务失败;此时按任务返回的错误详情处理。具体读取路径见任务状态说明。
经过代理时也可能收到 HTML 或空响应。这不能作为平台业务结果解析;记录状态、时间和已有请求标识后排查网络。不要把完整 Secret、令牌、短期文件 URL 或设备数据写入日志。
处理限制与重试
管理请求正文最多 16 KiB,这个限制不代表安装包的上传大小。安装包限制以账号和当前站点配置为准。请求地址最长 2048 字节,查询参数最多 20 项;单个查询值解码后最多 512 字节,接口还会校验自己的字段范围。
收到 Retry-After 时,按返回的秒数等待,并设置最大次数及总时长。修订冲突先重新读取和确认差异;金额单位变化、预算未开启或账务复核须先解决业务原因。写入超时先核对原任务、报价或回执,不自动换幂等键重复执行。
继续阅读错误处理、幂等与重试,或回到产品接口目录。