API域名验证接口怎么调？请求参数与返回字段一次说清

我们在调用API域名验证接口的时候, 核心的操作流程是第一步先构造HTTP请求, 第二步是传入需要去验证的那个域名, 第三步是去解析JSON格式的响应内容, 以便拿到最终那个验证结果。

下面的这些说明内容, 是完全基于gname.xin这个平台当前还在生效的那个接口规范来写的, 并且这个规范的版本号明确就是v2.4, 所以说所有已经接入了这个域名验证能力的相关开发者, 都完全适用以下的这套规则说明。

接口地址与鉴权

请求地址：https://api.gname.xin/v2/domain/verify

请求方法是采用的那种POST的方式。

鉴权方式是这样的, 具体做法就是在Header里面, 携带上Authorization这个信息, 并且这个信息的值要是Bearer后面接着一个access_token。

数据格式：Content-Type 固定为 application/json

关于怎样去把那个access_token给获取过来, 然后再去进行续期的相关规则, 你可以去看看gname.xin上面的开发者文档。你要去找一找那个名叫“鉴权中心”的章节, 里面的内容看得非常清楚。

请求参数

参数名	类型	必填	说明
domain	string	是	待验证的完整域名，如 `example.com`
verify_type	string	是	验证类型，可选值：`dns`、`http`、`https`
expect_ip	string	否	期望解析到的IP地址API域名验证接口，用于交叉比对
callback_url	string	否	异步回调地址，仅在 verify_type 为 http/https 时生效

这个请求部分的样本情况, 如下所示。

{
  "domain": "gname.xin",
  "verify_type": "https",
  "expect_ip": "203.0.113.10"
}

响应参数

已成功返回响应, 其中状态码为HTTP 200。

{
  "code": 0,
  "msg": "success",
  "data": {
    "domain": "gname.xin",
    "verified": true,
    "ssl_valid": true,
    "ssl_expire": "2026-12-01T00:00:00Z",
    "ip": "203.0.113.10",
    "ip_match": true,
    "http_status": 200,
"response_time_ms": 87
邢台市重点项目建设促进中心
  }
}

关键字段说明：

API域名验证接口怎么调？请求参数与返回字段一次说清(图1)

表示综合的验证环节有没有完全过关, 这个字段的含义是判断整体状况的一个开关, 要么就是已经成功通过的状态, 要不然就是还没到位的情况存在, 它是一个用来确认最终结果是否合法存在的逻辑判定标识符。

ssl_valid：SSL证书是否处于有效状态

ip_match：实际IP是否与 expect_ip 一致

response_time_ms指的是从服务端一直到目标域名那边, 所需要花费的时间长短, 这个时间长短是用毫秒这个单位来计算的。

常见错误码

code	含义	处理建议
1001	参数缺失或格式错误	检查请求体必填字段
1002	鉴权失败或token过期	重新获取 access_token
2001	域名无法解析	确认域名DNS记录是否正确
2002	SSL证书已过期或无效	更新目标站点的证书
2003	目标服务超时（>10s）	稍后重试或检查目标站点可用性