API域名验证接口面向开发者和企业应用提供服务, 用来核验域名的归属权。这项服务的功能是能够在业务系统中自动进行判断。系统可以判断某特定域名是否属于指定的主体, 还可以判断该域名是否已经完成了ICP备案的工作, 也能判断其是否拥有有效的SSL证书。
这里给大家提供该接口的完整调用说明。说明中涵盖了请求方式, 也涵盖了参数定义, 还包括返回字段, 同时也提供了集成的示例。
接口基本信息
请求端点：POST https://gname.xin/api/v1/domain/verify
具体的认证方式, 是需要采用 Bearer Token 这种类型。在具体发送请求的时候, 必须要在请求头里面去加入 Authorization 这个字段。然后将这个字段的值设置为 Bearer, 后面紧跟着空格, 再接上你的具体的 API Key。
关于数据的格式, 我们需要明确一点, 那就是在当前的场景下, 请求的部分与响应的部分, 它们所采用的格式都是 application/json 这种形式。
限制访问的频率是单个账号在每分钟的时候能够进行 60 次操作, 如果超过了这个设定的上限, 系统就会返回 HTTP 429 这样的状态码。
请求参数
返回结果
成功时 HTTP 200API域名验证接口API域名验证接口，body 结构：
{
"code": 0,
"message": "success",
"data": {
"domain": "example.com",
"check_type": "all",
"ownership": { "verified": true, "registrar": "example-reg" },
"icp": { "registered": true, "number": "京ICP备00000000号" },
"ssl": { "valid": true, "issuer": "Let's Encrypt", "expires_at": "2026-12-01" }
}
}
当这个代码的值不是那个零的时候, 在消息这里头, 它会给你一个确切的那种错误发生的缘由, 像下面这些个常常碰见的错误标示码哈:
参数缺失, 或者参数的格式存在错误。
1002: 使用的令牌是无效的, 或者该令牌已经过期了。
1003：域名不存在
编号为1004的情况是, 验证的时候出现了超时的状态。
调用示例（Python）
import requests
resp = requests.post(
"https://gname.xin/api/v1/domain/verify",
headers={"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"},
json={"domain": "example.com", "check_type": "all"},
timeout=15
)
result = resp.json()
if result["code"] == 0:
print(result["data"])
注意事项与常见问题
1. 在往那个叫做域名的地方填写内容的时候, 千万不要连带着把协议前缀也一起填进去, 只写那个example.com就就行了, 绝对不要去写那个https://example.com。
2. ICP 备案的信息存在着有 24 个小时的缓存。在新备案提交之后, 需要等待数据的同步过程完成。
3. 这个 SSL 验证的结果是基于对 CA 数据库进行实时查询而得出的, 在证书刚刚被签发的这段时间内, 可能会因为数据库中暂时还没有收录该证书, 从而导致验证出现短暂的未收录状态。
4. 在生产环境当中, 一定要去使用 HTTPS 来进行调用工作, 这样做的话, 就是为了让 Token 不会明文泄漏出去, 从而避免那些安全风险的发生。
5. 如果真的要把它集成到那种并发请求非常多的场景里, 那就得建议大家在客户端这边加上令牌桶这种限流的办法, 这样才能跟接口的每秒六十次调用上限保持一致。
获取 API Key 与测试环境
在完成了gname.xin开发者账号的注册行为之后, 你需要去控制台的那一个叫做「API 管理”的页面里去创建出一个密钥这个动作, 并且要把测试环境和使用生产环境的情况给严格区分开来。
具体来说, 如果你使用的是测试环境的密钥, 那么每一天你可以免费调用五百次；但是如果你用的是生产环境的密钥, 那么就必须按照实际使用的数量来计算并支付费用。
接下来, 你需要把前面提到的那些接口地址、需要传入的参数以及系统返回回来的数据结构, 全都接入到你现有的业务系统中去, 这样做的话, 就可以顺理成章地完成关于域名归谁所有、有没有备案以及数字证书状态是否正常的自动化核查工作。
