文档中心

Appearance

变更日志 ​

记录 OpenAPI 文档站的重要变更。

2026-10-20 ​

ACME 接入指南 ​

新增业务流程二级页「ACME 接入指南」，串联完整对接流程：创建订单、获取 EAB 凭证、ACME 客户端签发、接收 ACME 回调事件，并说明 EAB 轮换与 ARI 续期窗口查询等运维操作。

配套文档：

  • 创建 ACME EAB：获取订单的 ACME Directory URL 与 EAB 凭证，eab_mac_key 仅在创建时下发一次。
  • 轮换 EAB、更新 EAB IP 白名单：按 kid 寻址的 EAB 运维接口。
  • 回调通知新增 ACME 事件：账户创建/停用、证书签发（载荷携带完整证书链 PEM）、证书吊销。

2026-10-15 ​

证书链选择与交付 ​

按 CertCloud v1.50.53 发布代码核对。

补充产品候选证书链、证书候选链、查询订单交付偏好与设置订单交付偏好四个接口文档，说明全量可选路径、链族偏好、材料身份（含 subject_ou）及失败后的结果回查。

同步更新创建、重颁发、续期的 certificate.chain_id、certificate.cross_chain，明确 ICA 选择范围、交叉链开关及默认继承规则。获取证书详情通过 Certificate.cross_chain 和 Certificate.chain_id 返回实际交付结果，零值字段省略；错误使用标准 code/error 响应。

补充获取根证书：传入 cert_id 和可选的 cross_chain，取得对应交付路径的最终根证书；同时保留按 cert_chain 获取根证书的方式。

2026-10-08 ​

SSL 审核链接支持关闭指定能力 ​

生成 SSL 审核链接新增 capabilities.disabled 参数，可关闭链接的证书下载和「企业认证材料」组织验证方式（含材料上传与提交）。

调整：每次调用生成的新链接，配置完全来自本次请求。未传入的 ui_config、prefill_data 不再沿用当前有效链接的配置，而是使用默认值，需要保留的配置请在每次调用时重新传入。

2026-09-23 ​

审核链接基础级认证方式 ​

补充 CertCloud v1.50.38 审核链接详情的四个新增 audit_method 返回值：基础级机构的 basic_legal、basic_contact，以及基础级个人的 name_idcard_mobile、name_idcard_bankcard_mobile。保留既有审核方式与历史链接的兼容说明。

创建审核链接补充基础级机构联系人即被验证人的预填规则，以及银行卡验证的产品支持条件。审核方式由终端用户在审核页面选择，创建接口没有新增 audit_method 请求参数。

回调通知明确 meeting_booked 由 CertCloud 面审预约成功触发，并补记 v1.50.38 对面审预约进度误触发的修复；事件名称和数据结构保持不变。

审核链接预授权期限 ​

补充 prefill_data.preauthorization.use_certificate_validity：设为 true 时授权持续至绑定证书实际到期，必须省略 validity、validity_unit。完善默认值、与次数模式的组合、独立期限模式锁、幂等规则和请求示例，并同步说明详情接口的返回边界。

2026-09-04 ​

云签电子签名 ​

精简完整调用时序与 esign 总览文案：各阶段步骤只留主干与陷阱提示，重复表述改为链接单一事实源（停轮公式、生效判据、Token 保管等），收敛警示密度——无接口契约变更。顺带修正：委托授权重叠的准确口径为「同一委托人在同一证书上的生效期不可重叠、首尾相接允许」；删除 Token 回调「穷尽记死信留痕」的超出实现表述。

销毁私钥 ​

更正撤销与销毁的分工：吊销证书时云签端自动同步销毁私钥材料（库内密文置空、与状态变更同一事务、不可恢复；证书保持「撤销」态）；销毁私钥接口定位为控制人意愿确认后的合规销毁通道（过期未吊销证书销毁私钥、吊销证书补留痕与清理签署口令）。销毁不再改动证书状态（2026-09-03 起云签证书状态机取消「已销毁」终态，查询证书状态不再返回 DESTROYED）。

审核链接完整姓名与预填字段 ​

创建审核链接支持通过 name 传入个人、机构联系人或法人姓名原文，并保留 first_name + last_name 兼容方式；两种方式互斥。详情接口优先返回姓名原文，兼容方式创建的数据和旧链接会由已有姓和名生成 name。

个人或机构联系人、法人可预填银行卡，法人可预填手机号；银行卡是否参与验证由产品配置决定，详情只返回脱敏值且不支持锁定。材料上传文档同步收敛为 OpenAPI 实际接受的材料类型，并补充文件格式和审核链接错误码说明。

预授权签署支持不限次数 ​

预授权的授权窗口新增次数模式：创建预授权意愿新增 usageLimitEnable（缺省 true 有限次数；false 不限次数，只固化有效期、禁传 grantCount）。查询预授权状态、查询意愿结果与预授权完成回调 esign:grant_ready 的响应恒返回 usageLimitEnable；凭预授权 Token 签名是签名接口，不返回该字段，仅有限次数返回 usageRemaining。不限次数不扣减次数、不返回 usageLimit / usageRemaining，EXHAUSTED 不可达。source 新增取值 CSR。

创建审核链接的 prefill_data.preauthorization 新增 usage_unlimited，由创建方预设不限次数（审核页面不可选择）；不限次数下 immutable_paths 只能锁 validity / validity_unit 两项。新增 33280 esign_preauthorization_mode_mismatch：云签建立的次数模式与预设不符时同步签发失败并作废该预授权。

2026-09-02 ​

审核链接预授权与同步订单 Token 交付 ​

创建审核链接新增可选 prefill_data.preauthorization，可预设签名授权次数和有效期，并通过既有 immutable_paths 决定次数与时长是否允许终端用户修改。preauthorization.enabled 由系统自动锁定，调用方无需显式传入。

同步签发证书支持使用审核链接返回的个人或组织 ID 完成预授权下单。命中预授权时必须提供稳定的 esign_sign_task_id；A1.1 成功后，HTTP 200 或 202 响应可携带仅通过创建响应交付的 esign_sign_grant_token。新增 33265–33279 预授权与 CSR 准备错误码说明。

云签电子签名 ​

  • 更正出证素材下载口径：downloadUrl 为云签公网一次性下载地址，补全云签域名后由浏览器直连下载，CertCloud 原样透传、不代理下载（此前「对内接口、需代理」的表述作废）。
  • 更正销毁私钥前置：云签受理已撤销（REVOKED）或已过期证书的销毁；reason 必填且非空白、最长 512 字符（缺失/空串/超长均被拒）。
  • 更正撤销语义：证书撤销即同步销毁私钥材料（库内密文置空、与状态变更同一事务、不可恢复）；销毁私钥接口为控制人确认后推进证书「已销毁」终态、解除密钥绑定并清理签署口令。
  • 更正调用时序页表述：终态预授权再次撤销将被拒绝（非幂等返回）；删除「凭据值不经过任何接口」的绝对化表述（唯一例外：首次 PIN 可在下单时经 esign_pin_digest 同步创建）；PIN 前置补充「证书须在有效期内」；修复委托代签至签名流程的锚点链接。
  • 预授权：创建预授权意愿在单次模式（multiGrant=false）下支持调用方成组指定 grantCount/grantValidity/grantValidityUnit（有效期单位含分钟/小时/天/日历月/日历年），不传取平台默认（1 次/3 天）；预授权 Token 由云签经回调与意愿查询双通道交付，调用方经「领取预授权 Token」按 grantId 拉取。
  • 补记：2026-08-03 起预授权相关接口的 orderNo 更名为 signTaskId（不兼容变更，旧名不再接受）；2026-08-26 起撤销/冻结/解冻不再提供 esign 独立接口，撤销改经吊销证书通用入口，吊销确认后 CertCloud 自动同步云签。

2026-08-31 ​

同步签发等待时间与重试规则 ​

同步签发新增可选请求参数 sync_timeout_seconds：省略或 0 保留默认等待配置，显式值允许 1～120 秒。同一备用订单 ID 重试时可调整本次等待时间，不会改变原订单。等待预算不代表签发时效承诺，也不保证请求在该时间内结束或必定返回 HTTP 202。

完善备用 ID 的原串匹配与订单访问权限说明、未支付订单返回 HTTP 422 且不自动补支付的处理方式，以及网络异常后保留同一备用 ID 的重试规则。同步更新多语言示例、FAQ、流程图、错误码和多张中间证书／交叉签名证书的响应说明。

2026-08-26 ​

TrustCenter ESign 同步签发 ​

新增 POST /openapi/v3/sync-orders/{product_id}。符合资格的 TrustCenter 托管型电子签名证书若在默认等待窗口内完成交付，可直接返回叶证书和中间证书链；处理中订单返回 HTTP 202 和 Retry-After: 3，调用方使用相同 alternative_order_id 重放原始请求恢复结果。

新增同步签发专用错误码。原 POST /openapi/v3/orders/{product_id} 继续保持异步行为。

2026-08-12 ​

电子签名认证证书 ​

将 TrustAsia 个人/机构普通版、专业版身份证书更新为个人/机构基础级、高等级电子签名认证证书。新建、重颁发和续期统一按审核链接中的私钥托管选择使用 esign 或 usb-token，不再支持自行导入证书。

审核链接 ​

创建审核链接新增 private_key_custody，不传默认为 CA/云签托管，只有显式传 false 时使用 UKey。审核链接详情新增生效托管方式、audit_method、脱敏 bank_card 与完整对公打款信息，并支持在验证完成前修改信息后重新提交。

2026-08-06 ​