API 域名验证接口是用来校验指定的域名有没有通过 ICP 备案, 还有实名认证的。这个接口用在内容发布那里。还用在地广告投放里面。也用在域名归属确认这些场景里。这篇文章给出了完整的接口调用说明。说明里面包括了请求方式是什么。还说了参数定义是怎样的。还有返回字段代表什么。错误又是怎么处理的。

01接口概述

接口地址：POST https://api.gname.xin/v1/domain/verify

关于鉴权方式这个问题, 需要在请求头里面携带具体的信息, 这个信息的格式必须是Authorization后面跟着一个冒号以及空格, 然后接着是Bearer这个词, 之后再接着是你的那个由花括号括起来的your_token这样的token令牌, 而这个令牌是怎么来的呢, 它是需要你去开放平台的那个控制台下进行生成操作的。

频率这里有个限制的情况, 就是对于单个账号来说, 每一分钟最多只能去调用60次。如果超过了这个次数, 就会返回429状态码。

02请求参数

邢台市重点项目建设促进中心

参数名 类型 必填 说明
domain string 是 待验证域名，不含协议前缀，如 example.com
check_type string 否 验证类型API域名验证接口，可选值：icp（备案状态）、dns（解析记录）、all（默认API域名验证接口，全部检查）
ip_version int 否 DNS验证时指定IP版本，4或6，默认4

03返回字段

当结果返回的是 HTTP 200 的时候, 会返回一个 JSON 对象。

domain：请求的域名

icp_status指的是备案状态, 其中可选的枚举值包括filed, 该值的含义为已备案, 还包括not_filed, 该值的含义为未备案, 以及unknown。

dns_resolved这个字段是布尔值类型的, 它表示的是域名有没有被成功地进行解析。

对于ip_addresses, 它是被解析出来的IP地址构成的一个列表。

API域名验证接口怎么用？请求参数、返回值与错误码全解(图1)

timestamp: 指的是对执行的时间戳来进行验证, 这个时间值是以Unix秒为单位记录的。

04调用示例

以验证域名 gname.xin 为例：

POST /v1/domain/verify
Content-Type: application/json
{
  "domain": "gname.xin",
  "check_type": "all"
}

成功响应：

{
  "domain": "gname.xin",
  "icp_status": "filed",
  "dns_resolved": true,
  "ip_addresses": ["203.0.113.42", "2001:db8::1"],
  "timestamp": 1762387200
}

05常见错误码

状态码 错误标识 含义 处理建议
400 invalid_domain 域名格式不合法 检查是否包含非法字符或过长
401 token_expired 鉴权失败或Token过期 重新生成Token
404 domain_not_found 该域名无解析记录 确认DNS是否生效，TTL等待
429 rate_limited 触发频率限制 按响应头Retry-After字段等待后重试
500 service_unavailable 服务端异常 30秒后重试，连续失败则联系技术支撑

06注意事项

1. 关于域名的参数, 它不接受以 https://example.com 这种 URL 的形式传入系统。在传递数据的时候, 只允许传送那个纯的域名部分, 必须这么做。

2. ICP备案状态查询这事儿, 它是得依赖工信部那边数据同步的, 所以会存在最长48小时的延迟, 也就是说, 对于刚完成备案的域名进行查询操作时, 那个结果可能会返回unknown。

3. 批量验证的情况, 需要一条条地去调用接口, 这个接口目前暂时不支持一次性传入多个域名。如果用户的需求是高频次的批量场景的话, 那么可以去申请企业版的SDK, 因为企业版的SDK支持并发的10个线程。

4. 所有的请求, 必须得是通过https的方式来搞的, 而如果是http的请求的话, 就会被直接地就给拒了。