接口概述
API域名的这个验证的接口, 是用来用编程的方式去检查特定的域名, 看看它是不是已经把归属权确认好了, 或者是DNS解析也做完了验证, 这个功能是适合用在SSL证书的签发上面, 还有邮箱域名的绑定上面, 又或者是Saas应用的域名关联上面这些场景里的, 开发者是完全不用亲自登上去控制台的, 只要能够通过调用一次, 或者批量地去调用一下, 就可以拿到对应的域名的那个验证状态的。
接口基本信息
请求参数
请求内容里面的格式是JSON类型的, 关于各个参数具体代表的意义情况, 说明如下所示:
请求示例:
{
"domain": "www.example.com",
"verify_type": "dns",
"timeout": 60
}
返回结果
这是一个成功的例子。
{
"code": 0,
"message": "success",
"verified": true,
"verify_time": "2026-11-18T10:30:00Z"
}
调用流程
1. 使用账户密钥生成了Bearer Token, 并且借助这种方式完成了身份认证操作。
2. 要结合实际的业务需求来选择具体的验证方式, 可以选择dns / http / email这种类型的验证办法。
3. 我们来构造那个POST请求, 然后以JSON体的形式把参数提交上去。
4. 需要对返回来的 verified 这个字段进行解析;如果发现它的值是 false;那么就要去读取 failure_reason;目的是为了找准出现问题的具体地方。
5. 完成对应设置之后重新调用, 建议间隔大于等于六十秒。
常见错误码
因为DNS记录在网路上面会进行全球范围的传播, 所以新的配置情况通常需要等待5分钟之后, 一直到48个小时才能够真正完成生效, 于是我们在第一次执行调用动作之后的那个瞬间, 建议用户先去耐心等待2分钟的时间, 然后再去尝试执行一次重试操作。
这个接口, 它只是会返回一个验证的结果, 至于说域名注册这样的操作, 或者解析的变更操作, 该接口都不会去执行的。
我们建议在生产环境之中, 对那些 verified=false 的情况, 来设置为自动重试队列, 这样可以避免人工去一条一条地进行排查。
