基本概念与接入路线
本页内容
接入前先分清 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 也不能互换。
按步骤确认上传与签名结果
- 创建上传任务
- 传输并提交校验
- 取得原包版本
- 开通或核对权益
- 提交签名并取包
| 步骤 | 您已取得什么 | 还要确认什么 |
|---|---|---|
| 上传任务创建成功 | 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 的前缀相同,也要按取得它的接口和资源类型使用,不能互换。