创建审核链接

POST

/openapi/v3/audit-links

创建一个审核链接（Audit Link），用于将组织信息、个人信息及审核材料的填写与验证流程托管给终端用户完成。创建后返回一个可访问的 access_url，可直接发送给终端用户。

终端用户通过该链接在线填写并提交信息，平台完成审核后可通过获取审核链接详情查询进度与结果。

可选审核方式由 product_id 对应的产品决定，终端用户在审核链接页面选择。本接口不接受 audit_method 参数；已选择的方式通过详情接口返回，取值见审核方式。

幂等

当当前 API 账户下的 business_id、end_user_id、product_id 完全一致时，系统会复用同一审核链接记录，但会撤销旧访问令牌并签发新的 token 与 access_url。命中已有链接时，初始的预填数据、字段配置、页面配置和有效期不会被本次请求覆盖。

电子签名认证证书的 private_key_custody 也参与幂等校验：不传与显式传 true 等价；若命中的审核链接与本次请求的生效值不同，请求会被拒绝，不会覆盖原选择。

请求包含 prefill_data.preauthorization 时，预授权开关、次数模式、期限模式及次数/期限值也属于首次创建配置。相同 business_id、end_user_id、product_id 的重试必须保持预授权配置一致；变更配置需要使用新的业务标识。

Body 参数 application/json

参数	类型	必填	说明
business_id	string	是	业务标识，接入方自定义的业务单号，用于幂等与回查
end_user_id	string	是	终端用户标识
product_id	string	是	产品 ID
private_key_custody	boolean	否	是否由 CA/云签托管私钥。仅电子签名认证证书生效；不传或传 `true` 表示托管，仅显式传 `false` 表示使用 UKey
validity_period	int	否	链接有效期（单位：分钟）。默认 60 分钟，最小 30 分钟，最大 7 天
prefill_data	object	否	预填充数据，终端用户打开链接时自动带入
∟ person_info	object	否	个人型为申请人信息，机构型为联系人信息；基础级法人本人认证时填写法人本人
∟∟ name	string	否	姓名原文（推荐）；与 `first_name/last_name` 互斥
∟∟ first_name	string	否	名（兼容字段；使用时必须与 `last_name` 同时提供）
∟∟ last_name	string	否	姓（兼容字段；使用时必须与 `first_name` 同时提供）
∟∟ job_title	string	否	职位
∟∟ telephone	string	否	电话
∟∟ id_type	string	否	证件类型
∟∟ id_number	string	否	证件号码
∟∟ email	string	否	联系人邮箱
∟∟ bank_card	string	否	银行卡号预填；需产品支持银行卡验证，不支持锁定，详情仅返回脱敏值
∟ organization	object	否	组织信息预填
∟∟ name	string	否	组织名称
∟∟ address_line1	string	否	组织地址
∟∟ address_line2	string	否	组织地址 2
∟∟ city	string	否	城市
∟∟ state	string	否	省份
∟∟ postal_code	string	否	邮编
∟∟ country	string	否	国家地区代码（如 `CN`）
∟∟ telephone	string	否	组织电话
∟∟ biz_email	string	否	企业邮箱
∟∟ uscc	string	否	统一社会信用代码
∟∟ legal_person	object	否	法人信息，仅 `legal_representative` 使用；基础级 `basic_legal` 使用 `person_info` 中的同一联系人资料
∟∟∟ name	string	否	法人姓名原文（推荐）；与 `first_name/last_name` 互斥
∟∟∟ first_name	string	否	法人名（兼容字段；使用时必须与 `last_name` 同时提供）
∟∟∟ last_name	string	否	法人姓（兼容字段；使用时必须与 `first_name` 同时提供）
∟∟∟ id_type	string	否	法人证件类型
∟∟∟ id_number	string	否	法人证件号码
∟∟∟ telephone	string	否	法人预留手机号
∟∟∟ bank_card	string	否	法人预留银行卡号；是否参与验证由产品配置决定，详情仅返回脱敏值
∟ preauthorization	object	否	电子签名预授权默认配置。省略表示不在审核链接中设置预授权
∟∟ enabled	boolean	是	是否开启预授权；对象存在时必填。该开关由创建方决定，审核页面始终只读
∟∟ usage_unlimited	boolean	否	次数模式（2026-09-04 新增）。缺省 `false` = 有限次数；`true` = 不限次数：签名不扣减次数、只受有效期约束，此时不得传 `usage_limit`。该模式由创建方决定，审核页面不可选择、只按模式展示（不限次数隐藏次数）。`enabled=false` 时不得为 `true`
∟∟ use_certificate_validity	boolean	否	期限模式，默认 `false`：使用自定义期限；`true`：授权持续至所绑定的本张证书实际到期，不受自定义期限上限限制，此时不得传 `validity`、`validity_unit`。`enabled=false` 时不得为 `true`
∟∟ usage_limit	integer	enabled=true 且 usage_unlimited 缺省/false 时是	默认授权次数，正整数且不得超过云签当前上限；`usage_unlimited=true` 时禁传
∟∟ validity	integer	enabled=true 且 use_certificate_validity 缺省/false 时是	自定义授权有效期数值，正整数；`use_certificate_validity=true` 时禁传
∟∟ validity_unit	string	enabled=true 且 use_certificate_validity 缺省/false 时是	自定义有效期单位：`MINUTE`、`HOUR`、`DAY`、`MONTH` 或 `YEAR`；组合有效期不得超过云签当前上限。`use_certificate_validity=true` 时禁传
field_config	object	否	字段配置
∟ immutable_paths	array[string]	否	不可修改字段路径列表（终端用户不可编辑，见下方说明）
ui_config	object	否	页面配置
∟ success_redirect_url	string	否	提交成功后的跳转地址
∟ end_redirect_url	string	否	流程结束后的跳转地址
∟ language	string	否	页面语言标识
∟ theme_color	string	否	主题色
∟ hide_header	boolean	否	是否隐藏页头
∟ hide_customer_service	boolean	否	是否隐藏审核页面的客服入口。默认 `false`（显示）；设为 `true` 时隐藏
∟ privacy_agreement_url	string	否	隐私协议地址

客服入口配置

ui_config.hide_customer_service 使用 JSON 布尔值 true 或 false，不接受字符串或数字。省略该字段时默认显示客服；页头显示由 hide_header 单独控制。

该配置在首次创建审核链接时保存。相同 business_id、end_user_id、product_id 再次调用创建接口，以及刷新访问令牌，都会保留原有客服显示设置。如需变更，请使用新的 business_id 创建链接；可通过获取审核链接详情中的 ui_config.hide_customer_service 查询已保存的值。

姓名字段互斥

个人、机构联系人或法人姓名推荐只传 name，由系统拆分为姓和名。兼容接入方仍可只传完整的 first_name + last_name。

name 与 first_name/last_name 同时传入，或兼容字段只传其中一个时，返回 HTTP 400 name_fields_conflict。
name 必须能拆分为姓和名；无法拆分或拆分后超出长度限制时，返回 HTTP 400 name_cannot_split。

immutable_paths 可选值

路径用于锁定终端用户不可修改的字段，格式为 section.field：

个人信息：person_info.name、person_info.first_name、person_info.last_name、person_info.job_title、person_info.telephone、person_info.id_type、person_info.id_number、person_info.email
组织信息：organization.name、organization.address_line1、organization.address_line2、organization.city、organization.state、organization.postal_code、organization.country、organization.telephone、organization.biz_email、organization.uscc
法人信息：organization.legal_person.name、organization.legal_person.first_name、organization.legal_person.last_name、organization.legal_person.id_type、organization.legal_person.id_number、organization.legal_person.telephone
预授权次数与有效期：preauthorization.usage_limit、preauthorization.validity、preauthorization.validity_unit
预授权期限模式：preauthorization.use_certificate_validity
材料：materials.id_person_img、materials.id_info_img、materials.business_license、materials.authorization_letter、materials.verification_form、materials.face_snapshot、materials.other

锁定个人、组织或法人资料字段时，必须在同次请求的 prefill_data 中提供对应的非空值；否则请求会被拒绝。材料与预授权字段按各自的锁定规则处理。个人型审核链接不能传入 prefill_data.organization。

姓名按组锁定：只要 name、first_name、last_name 中任一路径被锁定，系统都会将同一对象的三个姓名路径全部加入实际生效的 immutable_paths。银行卡只以脱敏值回显，不能加入 immutable_paths。

preauthorization.enabled 是系统固有只读项，调用方无需把 preauthorization.enabled 放入 immutable_paths。次数模式 usage_unlimited 由创建方决定，审核页面不可修改，也不是可选锁路径。

期限模式可单独锁定：将 preauthorization.use_certificate_validity 加入 immutable_paths 后，审核页面不能切换期限模式；不锁定时，终端用户可以在自定义期限和至本证书到期之间切换。false 也是有效预设值，省略该参数时可锁定默认的自定义期限模式。

次数与期限值须按下表全锁或全不锁；表中路径均带 preauthorization. 前缀。期限模式锁是独立选项，不属于表中的锁集合。

期限模式	次数模式	需要固定次数与期限值时的锁路径
自定义期限（默认）	有限次数（默认）	`usage_limit`、`validity`、`validity_unit` 三项须同时锁定
自定义期限（默认）	不限次数（`usage_unlimited=true`）	`validity`、`validity_unit` 两项须同时锁定
至本证书到期（`use_certificate_validity=true`）	有限次数（默认）	仅 `usage_limit`
至本证书到期（`use_certificate_validity=true`）	不限次数（`usage_unlimited=true`）	没有次数或期限值可锁定

至本证书到期模式不能锁定 preauthorization.validity 或 preauthorization.validity_unit；不限次数模式不能传入或锁定 usage_limit。若需固定期限模式本身，仍须单独锁定 preauthorization.use_certificate_validity。未提供预授权对象或 enabled=false 时不能设置期限模式锁及次数/期限值锁。

托管方式与银行卡验证

private_key_custody 由 OpenAPI 持有者在创建审核链接时选择，终端用户不能在审核链接页面修改。该选择同时决定后续订单的私钥交付方式，详见电子签名认证证书的 CSR 来源。

person_info.bank_card 和 organization.legal_person.bank_card 可以预填，银行卡验证需产品支持；基础级产品的具体规则见下方说明。银行卡不能锁定，且获取详情时只返回脱敏值。

基础级产品的预填规则

机构基础级产品的 basic_legal（法人本人认证）和 basic_contact（非法人联系人认证）都使用 prefill_data.person_info 预填被验证人的资料。选择 basic_legal 时，该联系人就是法人本人，无需再用 organization.legal_person 提供另一套身份信息。

基础级产品支持银行卡验证时，填写或预填银行卡用于姓名、证件、银行卡、手机号四要素认证；未填写时使用姓名、证件、手机号三要素认证。产品未启用银行卡验证时，请勿预填或提交银行卡，否则终端用户在审核页面提交验证时可能被拒绝。创建链接成功不代表后续验证提交一定成功。

银行卡不能锁定，详情接口只返回脱敏值。预填数据用于首次带入；终端用户后续编辑基础级个人或机构联系人资料时，未修改银行卡会保留当前已保存的值。

预填字段长度与格式

以下长度均按 Unicode 字符计。个人信息中，name 最长 128；个人型审核的姓和名拆分后各最长 64，机构联系人各最长 128。job_title 最长 128，telephone 最长 64，id_type 最长 8 且仅支持 1 或 2，id_number 最长 128，email 最长 254 且必须为合法邮箱，bank_card 最长 32。

组织信息中，name、address_line1、address_line2 最长 256，city、state 最长 128，postal_code 最长 32，country 必须为两位 ISO 国家或地区代码，telephone 最长 64，biz_email 最长 254 且必须为合法邮箱，uscc 最长 64。法人信息中，name、first_name、last_name 最长 128，id_type 最长 32，id_number 最长 128，telephone 最长 64，bank_card 最长 32。

预授权期限模式

开启预授权（enabled=true）后，prefill_data.preauthorization.use_certificate_validity 默认 false，此时必须成组提供 validity 和 validity_unit。设为 true 时，预授权截止取所绑定的本张证书实际到期时间，必须省略这两个字段，也不能通过它们指定额外时长。

期限模式与次数模式独立：至本证书到期且有限次数时，仍须提供 usage_limit；同时设 usage_unlimited=true 时，应省略 usage_limit、validity 和 validity_unit。关闭预授权（enabled=false）时省略次数和期限配置。

以下示例预设最多签署 20 次、期限至本证书到期，并分别锁定次数和期限模式：

json

{
  "business_id": "biz-cert-validity-001",
  "end_user_id": "000000001",
  "product_id": "trustasia_ide_pic",
  "prefill_data": {
    "preauthorization": {
      "enabled": true,
      "use_certificate_validity": true,
      "usage_limit": 20
    }
  },
  "field_config": {
    "immutable_paths": [
      "preauthorization.use_certificate_validity",
      "preauthorization.usage_limit"
    ]
  }
}

如需不限次数，将示例中的 usage_limit 替换为 usage_unlimited: true，并删除 preauthorization.usage_limit 锁路径。保留期限模式锁时，终端用户只能使用至本证书到期模式。

同一 business_id、end_user_id、product_id 重试时，use_certificate_validity 与预授权开关、次数模式及次数/期限值都必须和首次创建一致；省略该参数与显式传 false 等价。

电子签名预授权

预授权开启后，终端用户在审核页面阅读当前生效协议，确认最终次数和有效期，并可选择设置签署 PIN。审核通过后，使用返回的个人或组织 ID 创建电子签名订单，详见同步签发证书。

创建接口不接收 PIN

创建审核链接阶段禁止传 PIN 明文、pin 或 pin_digest。PIN 只能由终端用户本人在审核页面选择设置；CertCloud 仅保存 SHA-256 摘要，不在 OpenAPI 创建请求中接收任何 PIN 值。

自定义期限：次数与时长允许终端用户修改

本例只锁定证件字段。预授权开关由系统自动锁定，usage_limit、validity 和 validity_unit 未进入 immutable_paths，因此是页面默认值，终端用户可在云签上限内修改。

json

{
  "business_id": "audit-person-20260902-001",
  "end_user_id": "customer-person-001",
  "product_id": "trustasia_ide_pipc",
  "private_key_custody": true,
  "prefill_data": {
    "person_info": {
      "name": "张三",
      "id_type": "1",
      "id_number": "110101********1234"
    },
    "preauthorization": {
      "enabled": true,
      "usage_limit": 10,
      "validity": 24,
      "validity_unit": "HOUR"
    }
  },
  "field_config": {
    "immutable_paths": [
      "person_info.id_type",
      "person_info.id_number"
    ]
  }
}

次数与时长全部锁定

需要固定自定义期限下的次数与时长时，增加以下三个路径，不需要增加 preauthorization.enabled。若还需固定自定义期限模式，可额外锁定 preauthorization.use_certificate_validity：

json

{
  "prefill_data": {
    "preauthorization": {
      "enabled": true,
      "usage_limit": 10,
      "validity": 24,
      "validity_unit": "HOUR"
    }
  },
  "field_config": {
    "immutable_paths": [
      "preauthorization.usage_limit",
      "preauthorization.validity",
      "preauthorization.validity_unit"
    ]
  }
}

不限次数并锁定有效期

不限次数（usage_unlimited=true）不传 usage_limit；需要固定有效期时只锁 validity、validity_unit 两项。审核页面隐藏次数、只展示有效期，终端用户不能改成有限次数：

json

{
  "prefill_data": {
    "preauthorization": {
      "enabled": true,
      "usage_unlimited": true,
      "validity": 1,
      "validity_unit": "YEAR"
    }
  },
  "field_config": {
    "immutable_paths": [
      "preauthorization.validity",
      "preauthorization.validity_unit"
    ]
  }
}

同步签发命中不限次数预授权时，后续凭预授权 Token 签名不扣减次数、响应不含 usageRemaining，查询预授权状态返回 usageLimitEnable=false。若云签实际建立的次数模式与本配置不符，同步签发会以 33280 esign_preauthorization_mode_mismatch 失败并作废该预授权，不会交付 Token。

云签公共配置不可用、预授权能力关闭或次数/有效期超过上限时，创建请求会失败（不限次数只受有效期上限约束，不受最大次数限制）。错误码见预授权与 CSR 准备错误码。

返回数据

参数	类型	说明
id	string	审核链接 ID
token	string	访问令牌
access_url	string	审核链接访问地址
expires_at	string	链接过期时间
is_existing	boolean	此前是否存在活动访问令牌；不表示返回的 `access_url` 可复用，接口始终返回新令牌

示例中的姓名、企业名称、地址和联系方式等敏感信息已脱敏，使用前请替换为实际业务数据。

bash

curl -X POST 'https://api.certcloud.cn/openapi/v3/audit-links' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "business_id": "biz-20260601-001",
    "end_user_id": "000000001",
    "product_id": "trustasia_ide_bipro",
    "private_key_custody": false,
    "validity_period": 1440,
    "prefill_data": {
      "organization": {
        "name": "亚数****有限公司",
        "country": "CN"
      }
    },
    "field_config": {
      "immutable_paths": ["organization.name"]
    },
    "ui_config": {
      "language": "zh-CN",
      "hide_header": false,
      "hide_customer_service": true
    }
  }'

javascript

const response = await fetch('https://api.certcloud.cn/openapi/v3/audit-links', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
  body: JSON.stringify({
    business_id: 'biz-20260601-001',
    end_user_id: '000000001',
    product_id: 'trustasia_ide_bipro',
    private_key_custody: false,
    validity_period: 1440,
    prefill_data: {
      organization: { name: '亚数****有限公司', country: 'CN' }
    },
    field_config: { immutable_paths: ['organization.name'] },
    ui_config: { language: 'zh-CN', hide_header: false, hide_customer_service: true }
  })
})
const data = await response.json()

body := map[string]interface{}{
  "business_id":     "biz-20260601-001",
  "end_user_id":     "000000001",
  "product_id":      "trustasia_ide_bipro",
  "private_key_custody": false,
  "validity_period": 1440,
  "prefill_data": map[string]interface{}{
    "organization": map[string]string{"name": "亚数****有限公司", "country": "CN"},
  },
  "field_config": map[string]interface{}{"immutable_paths": []string{"organization.name"}},
  "ui_config": map[string]interface{}{
    "language": "zh-CN",
    "hide_header": false,
    "hide_customer_service": true,
  },
}
jsonBody, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/audit-links", bytes.NewBuffer(jsonBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
resp, err := http.DefaultClient.Do(req)

python

import requests

response = requests.post(
    'https://api.certcloud.cn/openapi/v3/audit-links',
    headers={
        'Content-Type': 'application/json',
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    json={
        'business_id': 'biz-20260601-001',
        'end_user_id': '000000001',
        'product_id': 'trustasia_ide_bipro',
        'private_key_custody': False,
        'validity_period': 1440,
        'prefill_data': {
            'organization': {'name': '亚数****有限公司', 'country': 'CN'}
        },
        'field_config': {'immutable_paths': ['organization.name']},
        'ui_config': {'language': 'zh-CN', 'hide_header': False, 'hide_customer_service': True}
    }
)
data = response.json()

200成功

json

{
  "data": {
    "id": "al_7Kd9Qm2x",
    "token": "eyJhbGciOi...",
    "access_url": "https://certcloud.cn/audit-links/al_7Kd9Qm2x?token=eyJhbGciOi...",
    "expires_at": "2026-06-02 12:00:00",
    "is_existing": false
  },
  "code": "success"
}

业务流程

订单管理

ACME

证书管理

电子签名服务

审核链接

签名意愿

预授权签署（两步调用）

凭据管理（签署 PIN / TOTP）

证书标识与状态

密钥管理

人员信息变更

委托授权（仅企业证书）

组织管理

域名管理

账户设置

创建审核链接

预授权期限模式

电子签名预授权

自定义期限：次数与时长允许终端用户修改

次数与时长全部锁定

不限次数并锁定有效期

订单管理

ACME

证书管理

组织管理

域名管理

创建审核链接 ​

预授权期限模式 ​

电子签名预授权 ​

自定义期限：次数与时长允许终端用户修改 ​

次数与时长全部锁定 ​

不限次数并锁定有效期 ​

创建审核链接

预授权期限模式

电子签名预授权

自定义期限：次数与时长允许终端用户修改

次数与时长全部锁定

不限次数并锁定有效期