跳到主要内容

修改 DCV 接口

当用户想要更改域名验证方式或切换 DCV 作用域时,需要调用此接口

接口地址

POST /api/v1/certificate/update-dcv

Host:
...

完整地址

/api/v1/certificate/update-dcv

请求​

Content-Type: application/json
Content-Length: 165

{
"service_id": "o91bZ", // 证书编号,证书下单接口返回的 `service_id`
"domain_dcv": { // 域名+验证信息,选填(当仅切换作用域时可省略),一条域名对应一种验证类型
"*.example.com": "dns", //⚠️注意:通配符只支持dns或email验证
"example2.com": "http", //⚠️注意:http、https为子域名文件验证必须上传到子域名本身服务下,不支持传主域名或其他域名
"example3.com": "https",
"sub.example4.com": "admin@example4.com" // ⚠️注意:邮箱验证不支持whois邮箱,只支持admin@、administrator@、postmaster@、webmaster@、hostmaster@ + <子域名 或 主域名> 组合的邮箱
},
"dcv_scope": "base_domain" // DCV 验证作用域,选填,支持 base_domain (主域名) 或 apply_domain (子域/申请域名),仅部分产品支持,详见下方「DCV 验证作用域」
}
国际化域名(IDN)

domain_dcv 的域名键(以及单域名写法的 domain)punycode 与 Unicode 原文都接受,例如 xn--fiqs8s 与 中国 等价,任选一种即可。

请注意:接口响应里的域名一律返回 punycode,请按 punycode 做匹配。

DCV 验证作用域

dcv_scope 控制 DNS 验证的主机记录添加在主域名(根域)还是申请的子域(完整 FQDN)下。仅支持 AutoCert、Keymatic 品牌产品,其他品牌产品切换作用域将返回 400 错误。

  • 可选值:
    • base_domain:主域名作用域,验证记录添加在根域名下(例如申请 a.b.example.com,DNS 记录解析在 _dnsauth.example.com)。
    • apply_domain:子域作用域(申请域名作用域),验证记录直接添加在申请的具体子域名下(例如申请 a.b.example.com,DNS 记录解析在 _dnsauth.a.b.example.com)。同时兼容别名 fqdn。
  • 支持调用形态:
    • 同时修改验证方式与作用域:同时传递 domain_dcv 与 dcv_scope;
    • 仅切换作用域:仅传递 service_id 和 dcv_scope,无需重复传递 domain_dcv;
    • 单域名形式:传递 service_id、domain、type 与 dcv_scope。
  • 作用域切换行为:
    • 首次签发中:会自动向 CA 退款取消旧订单,然后使用新作用域和最新域名重新下单;
    • 重签审核中:会自动取消旧重签请求,然后使用新作用域和最新域名与 CSR 重新发起重签。
  • 切换条件约束:
    • 仅限域名验证方式为 DNS:若当前验证方式为 HTTP、HTTPS 或 Email,接口将直接报错(400)拒绝切换;
    • 仅限证书未签发时:仅在证书处于未签发状态(首次签发待验证、或重签待验证)时允许切换作用域;若证书已签发完成,接口将直接报错(400)拒绝切换。

响应​

HTTP/1.1 200 OK

Content-Type: application/json
Content-Length: 36

{
"success": true,
"message": "OK"
}
危险

用户解析、文件验证操作好之前,不要调用此接口;由于DNS存在缓存,当CA一次查询不到解析结果通常会被缓存数分钟,这会导致缓存期间您(或您客户)的证书一直不会得到签发。

正确的处理应该是用户解析完成后,您在您系统平台给用户一个点击按钮“检查解析结果” / “检查文件内容”的按钮。此按钮同步调用此接口。这样对接通常您API下的订单会在用户解析完成后1分钟内签发,从而达到的客户体验。