跳转到主要内容
1签 (OneSign)

请求与响应约定

本页内容

调用接口前,先确认请求地址、认证方式和数据格式。本页说明企业签名、应用分发与账号账单 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,令牌摘要也参与签名。临时授权所指定应用的只读接口,不能用于上传、付款或签名。
OAuthAuthorization: Bearer <access_token>。不发送 AccessKey 的日期、nonce、摘要、环境和安全令牌头。用户同意范围内的读取;终端上传或签名还需独立许可。仅支持长期 AccessKey 的接口不能改用 OAuth。

所有 POST 管理请求还须传 JSON 类型和幂等键,OAuth 也一样。浏览器直连需要使用已批准的精确 Origin;在浏览器中内置长期 Secret 或放开存储 CORS,均不能代替 API 的用户授权。

签名头的精确定义见AccessKey 请求签名;临时凭据的签发与撤销见临时只读凭据。

构造 GET 或 POST 请求

  1. 按接口选择 GET 或 POST,保留资源 ID 的完整前缀。路径中的 {id} 需替换为自己账号返回的应用 ID。
  2. GET 的业务筛选条件放在查询串中,不发送正文或幂等键。查询参数不可重复;按 RFC 3986 编码,空格使用 %20,不要使用 +。
  3. POST 的业务字段放在 UTF-8 JSON 对象中,使用 Content-Type: application/json,或附加 charset=utf-8。没有业务字段时也发送 {}。
  4. POST 在首次提交前持久保存 X-Api-Idempotency-Key、路径及正文。键为 16–64 位字母、数字、下划线或连字符;同一次业务重试恢复原值。
GET 查询参数示例
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。类型、可选值与边界可展开查看,示例值不代表全部允许范围。

判断请求和业务结果

  1. 先读取 HTTP 状态和 JSON。成功的管理请求返回 HTTP 200,从 data 取得结果;失败响应从 error.code 判断原因。
  2. 保存 request_id。API 同时通过 X-Request-Id 响应头提供请求标识;错误响应也有此值,不能仅凭它判断成功。
  3. 上传和签名被受理后仍需等待原任务。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 时,按返回的秒数等待,并设置最大次数及总时长。修订冲突先重新读取和确认差异;金额单位变化、预算未开启或账务复核须先解决业务原因。写入超时先核对原任务、报价或回执,不自动换幂等键重复执行。

继续阅读错误处理、幂等与重试,或回到产品接口目录。