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

基本概念与接入路线

本页内容

接入前先分清 API 应用、业务应用、版本和任务,再选择认证与恢复方式。本页帮助您确定每一步要提交什么、保存什么,以及怎样判断操作成功。

先确定要完成的业务

开放 API 用于管理自己账号下的企业签名、普通应用分发和订单账务。本页把这些接口统称为“业务 API”。先选择要完成的任务,再准备对应权限和应用 ID。

您的目标使用哪类能力接下来阅读
上传 IPA 并生成企业签名包企业签名:上传原包、开通权益、提交签名、取得产物。企业签名快速入门
发布 IPA 或 APK 供用户下载应用分发:上传版本、确认发布、设置下载页。应用分发快速入门
查询余额、预算和交易结果账号账务:核对金额单位、订单与资金流水。余额、预算与订单对账

网站主域名用于调用业务 API,公开下载页面用于安装用户访问。SDK 的网站地址填写 https://www.onesignios.com,不要填写分发短链或文件传输地址。

区分两种应用

概念表示什么在接入中如何使用
API 应用您在开发者中心登记的接入程序。为它配置动作、资源范围、凭据和预算。不同程序可分别授权。
业务应用账号下要签名或分发的 IPA、APK 应用。通过业务应用 ID 指定操作目标;后续版本沿用同一个应用 ID。

接口路径中的应用 ID 通常是完整的 A 开头业务应用 ID,不是开发者中心的 API 应用 ID。SDK 不会因为您持有某个 ID 就获得访问权限;账号能力、授权动作和资源归属仍要同时满足。

首次创建业务应用时,平台先返回“应用预留”。请保存它的应用 ID,在有效期内上传首个安装包。预留还未完成时,使用创建状态接口核对;安装包保存成功后,再按正式应用查询。

区分原包、版本与签名包

应用 ID 表示要管理的应用,版本 ID 表示这次保存的具体安装包。上传新版本通常生成新的 V 开头版本 ID,应用 ID 保持不变。

概念产生方式适用操作
原包版本上传任务校验成功后保存。作为企业签名的输入,或作为普通分发的发布版本。
签名包版本企业签名任务成功后生成。按该任务的准确产物申请下载,不能用原包版本 ID 代替。
当前发布版本该包类型当前对外使用的版本,以 is_current 标记。原包与签名包可分别具有当前版本。核对下载页面当前展示和提供的版本。

企业签名取包时,先查询原签名任务的产物,以 signed_version.id 为准。版本列表第一项可能属于其他任务,不能据此认定为本次签名结果。两类文件的内容不同,预期 SHA-256 也不能互换。

按步骤确认上传与签名结果

  1. 创建上传任务
  2. 传输并提交校验
  3. 取得原包版本
  4. 开通或核对权益
  5. 提交签名并取包
步骤您已取得什么还要确认什么
上传任务创建成功U 开头上传任务 ID,即创建响应的 data.id。文件尚未保存为版本。使用 SDK 上传助手继续传输和确认。
文件传输达到 100%文件字节已发送。继续查询原上传任务,等待 state=succeeded 且取得 version_id。
企业签名服务已开通签名套餐或相应权益已生效。开通与签名分别处理,仍需按业务需要提交签名任务。
签名请求已受理J 开头签名任务 ID。等待任务结束,检查 status=succeeded,再查询准确产物。

HTTP 200 只表示本次请求成功。异步任务仍可能处理中、失败或取消;付款成功也不表示安装包已经签名。每一步保存原 ID,分别判断业务结果。

上传使用统一 SDK 流程,平台和 SDK 处理传输服务选择。您无需选择存储厂商或填写后台存储配置。

选择正确的凭据

凭据用途注意事项
AccessKey自己的服务端调用业务 API。Secret 由安全配置注入;临时凭据还需同组安全令牌。
OAuth 令牌第三方网页或终端在用户同意范围内调用。按授权流程取得和刷新,不在终端内置长期 AccessKey Secret。
企业签名开通密钥兑换指定的签名服务。它不是 API 认证凭据;核销也不会生成 AccessKey。
短期上传或下载凭证传输指定文件。由 SDK 按指令使用,不向文件传输地址发送平台 API 的认证头。
Webhook 回调密钥接收端验证平台事件通知。与 AccessKey 分别保存;普通通知持久保存成功后再返回回执。

需要选择认证方式时,阅读访问权限与OAuth 接入。需要接收通知时,阅读Webhook 指南。

保存哪些信息才能恢复

信息保存时间作用
业务幂等键、路径和正文每次独立写操作首次发送前。同一次业务重试恢复原请求,避免重复创建、扣款或核销。
上传任务、签名任务、报价或订单 ID接口返回后立即保存。查询原操作,不因等待超时再创建一次。
文件身份、原始摘要与上传检查点传输前及检查点更新时。确认仍是原文件,继续同一次上传。
request_id每次响应后。定位该次调用,不代替业务结果或幂等键。

请求时间、nonce 和认证签名每次尝试重新生成;业务幂等键按原操作保留。OAuth 一次性授权码和刷新令牌按自己的流程处理,不套用业务请求的重放方式。

字段为 null、未返回、空字符串或零,可能有不同含义。比如统计未提供不能显示为零,下载回执的 ticket=null 也不能作为可用链接。类型与空值约定见请求与响应约定。

开始接入

先按快速入门完成一次身份查询,再选择企业签名或应用分发教程。已有集成时,按任务查具体接口;需要恢复旧任务时,先阅读分页与等待和错误处理。

所有 ID 都作为不透明字符串完整保存。即使两类 ID 的前缀相同,也要按取得它的接口和资源类型使用,不能互换。