修改 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)拒绝切换。
响应
- response
- errors
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36
{
"success": true,
"message": "OK"
}
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 50
{
"success": false,
"message": "无法找到此订单"
}
危险
用户解析、文件验证操作好之前,不要调用此接口;由于DNS存在缓存,当CA一次查询不到解析结果通常会被缓存数分钟,这会导致缓存期间您(或您客户)的证书一直不会得到签发。
正确的处理应该是用户解析完成后,您在您系统平台给用户一个点击按钮“检查解析结果” / “检查文件内容”的按钮。此按钮同步调用此接口。这样对接通常您API下的订单会在用户解析完成后1分钟内签发,从而达到的客户体验。