开放平台文档
开放平台 API 文档,涵盖行为验证码、SDK 接入指南等接口说明。
# vastark-seo-spider 校验 API
校验访问来源是否为**可信搜索引擎爬虫**。
## 能力简介
- 三重校验,能保证站长平台和爬虫的准确识别,覆盖国内外 12 个主流搜索引擎。
- 明确**不支持** Yahoo、各类小众爬虫及已停运爬虫的识别;这类 UA 会返回 `ua_mismatch`。
## 鉴权与计费
| 项目 | 说明 |
|------|------|
| 请求头 | `X-API-Key: <你的 API Key>` |
| IP 白名单 | 客户开启白名单后,调用方 IP 必须命中 `open_ip_whitelist` 中的 IP 或 CIDR;未开启则放行所有 IP |
| 计费权益码 | `seo_spider` |
| 单条校验 | 扣 1 次 |
| 批量校验 | 按实际校验条数扣减(`items` 长度) |
| 引擎列表 | 免费,只做鉴权,不查询余额、不计费 |
计费流程:请求先查询权益余额,余额 `<= 0` 时直接返回 `40012 额度不足`;余额查询失败返回 `50001 额度校验失败`。
> API Key 认证中间件在缺失 `X-API-Key` 时会直接返回 `HTTP 401`,响应体为 `{"status":40101,"user_msg":"缺少API-KEY","data":{}}`。
## 端点总览
| 方法 | 路径 | 说明 | 计费 |
|------|------|------|------|
| POST | `/saas/api/v1/seo-spider/verify` | 单条校验 | 1 次/条 |
| POST | `/saas/api/v1/seo-spider/verify/batch` | 批量校验(1–100 条) | 按条数 |
| GET | `/saas/api/v1/seo-spider/engines` | 引擎能力清单 | 免费 |
统一响应结构:
```json
{
"code": 0,
"message": "ok",
"data": {}
}
```
- `code = 0` 表示成功,`message` 为 `ok`。
- 失败时 `code` 为业务错误码,`data` 为空对象(`额度不足` 例外,`data` 含 `is_threshold_reached`)。
### 请求体大小限制
除批量条数上限 100 外,服务端还会限制**整个请求体的字节数**,默认 `256KB`。
超过上限会直接返回 `HTTP 413`,且**不会触发额度查询与计费**:
```json
{"code": 40001, "message": "请求体过大", "data": {}}
```
## 单条校验
`POST /saas/api/v1/seo-spider/verify`
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `ip` | string | 是 | 待校验的 IPv4/IPv6 地址,服务端会去除首尾空白并做格式校验 |
| `user_agent` | string | 是 | 请求的 User-Agent,去除首尾空白后不能为空,长度不超过 1024;匹配规则见下方「UA 匹配规则」 |
### UA 匹配规则
`user_agent` 只需**原样透传调用方请求头**,不需要拼装或补全。服务端按**小写子串包含**匹配,不做完整字符串比对:
- 不区分大小写;
- 命中任一内置关键词即判定为该引擎,取引擎清单顺序中第一个命中的;
- 官方 UA 里的附加注释(如 `+http://www.google.com/bot.html`)**可以省略**,不影响识别。
Googlebot 为例,以下写法都能命中 `engine = googlebot`:
```
Googlebot/2.1
Mozilla/5.0 (compatible; Googlebot/2.1)
Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
```
各引擎的关键词见下文「支持的引擎」表。
### curl 示例
```bash
curl -X POST 'https://api.vastark.cn/saas/api/v1/seo-spider/verify' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ip": "66.249.66.1",
"user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
}'
```
### 响应示例
```json
{
"code": 0,
"message": "ok",
"data": {
"verified": true,
"engine": "googlebot",
"verdict": "ok",
"cached": false,
"elapsed_ms": 37
}
}
```
### data 字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `verified` | bool | 是否为可信爬虫(等价于 `verdict == "ok"`) |
| `engine` | string | 命中的内部引擎标识,如 `googlebot`;UA 未命中任何引擎时为空字符串 |
| `verdict` | string | 校验结论,取值见下文 |
| `cached` | bool | 本次请求是否命中进程内结果缓存 |
| `elapsed_ms` | int | 本次校验耗时(毫秒) |
## 批量校验
`POST /saas/api/v1/seo-spider/verify/batch`
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `items` | array | 是 | 校验项数组,长度 1–100 |
| `items[].ip` | string | 是 | 待校验的 IPv4/IPv6 地址 |
| `items[].user_agent` | string | 是 | 请求的 User-Agent,匹配规则与单条校验相同(见「UA 匹配规则」) |
任意一条参数非法都会导致整个请求返回 `40001 参数错误`,不会部分成功。
### curl 示例
```bash
curl -X POST 'https://api.vastark.cn/saas/api/v1/seo-spider/verify/batch' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"ip": "66.249.66.1",
"user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
},
{
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
}
]
}'
```
### 响应示例
```json
{
"code": 0,
"message": "ok",
"data": {
"results": [
{
"verified": true,
"engine": "googlebot",
"verdict": "ok",
"cached": false,
"elapsed_ms": 35
},
{
"verified": false,
"engine": "googlebot",
"verdict": "ptr_mismatch",
"cached": false,
"elapsed_ms": 12
}
],
"count": 2
}
}
```
- `results` 与请求 `items` 顺序一致,逐条独立判定。
- `count` 为返回结果条数,等于请求条数。
## 引擎列表
`GET /saas/api/v1/seo-spider/engines`
### curl 示例
```bash
curl -X GET 'https://api.vastark.cn/saas/api/v1/seo-spider/engines' \
-H 'X-API-Key: YOUR_API_KEY'
```
### 响应示例
```json
{
"code": 0,
"message": "ok",
"data": {
"engines": [
{ "engine": "bingbot", "label": "Bingbot" },
{ "engine": "360spider", "label": "360 搜索" }
]
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `engine` | string | 引擎标识 |
| `label` | string | 展示名 |
## 支持的引擎
| engine | label | UA 关键词(小写子串) |
|--------|-------|------------------------|
| `bingbot` | Bingbot | `bingbot`、`msnbot` |
| `googlebot` | Googlebot | `googlebot`、`google-inspectiontool`、`mediapartners-google` |
| `baiduspider` | 百度 | `baiduspider` | `.baidu.com`、`.baidu.jp` | 否 |
| `sogou` | 搜狗 | `sogou web spider`、`sogou inst spider`、`sogou news spider`、`sogou pic spider` |
| `yisouspider` | 神马 | `yisouspider` |
| `bytespider` | 字节跳动| `bytespider` |
| `yandexbot` | YandexBot | `yandexbot`、`yandex.com/bots` |
| `360spider` | 360 搜索 | `360spider`、`haosouspider` |
| `applebot` | Applebot | `applebot` |
| `amazonbot` | Amazonbot | `amazonbot` |
| `naverbot` | Naver Yeti | `yeti/`、`naverbot` |
| `duckduckbot` | DuckDuckBot | `duckduckbot` |
说明:
- UA 关键词按小写子串匹配(不区分大小写、不要求完整 UA),按上表顺序取第一个命中的引擎;详见「UA 匹配规则」。
- `360spider`、`duckduckbot` 官方未提供 PTR 约定,必须命中运维发布的网段才能判为可信;网段未加载时返回 `ranges_unavailable`。
- Yahoo、小众爬虫、已停运爬虫不在支持范围内,会返回 `ua_mismatch`。
## verdict 取值
| verdict | 含义 |
|---------|------|
| `ok` | 校验通过,`verified = true` |
| `ua_mismatch` | User-Agent 未匹配任何内置引擎(`engine` 为空字符串) |
| `ip_not_allowed` | IP 不在允许网段内,或 IP 无法解析 |
| `ranges_unavailable` | 该引擎需要网段校验,但当前没有可用网段数据 |
| `ptr_mismatch` | PTR 记录不匹配该引擎的后缀白名单 |
| `fcrdns_mismatch` | PTR 命中,但正向解析结果未回指原 IP |
| `forward_nxdomain` | PTR 命中,但该主机名没有正向解析记录(NXDOMAIN) |
| `dns_error` | DNS 查询失败(非超时) |
| `dns_timeout` | 单次 DNS 查询超时或被取消 |
## 错误码
| HTTP | code | message | 场景 |
|------|------|---------|------|
| 401 | 40101 | `API KEY 无效` | `X-API-Key` 缺失或无效 |
| 500 | 50001 | `系统错误` | 内部系统错误 |
| 403 | 40301 | `IP 不在白名单` | 客户开启 IP 白名单且调用方 IP 未命中 |
| 400 | 40001 | `参数错误` | 请求体不是合法 JSON,或 `ip` / `user_agent` 非法,或 `items` 不在 1–100 条 |
| 413 | 40001 | `请求体过大` | 请求体超过阈值,不查额度、不计费 |
| 502 | 50001 | `额度校验失败` | 内部系统错误 |
| 200 | 40012 | `额度不足` | 剩余额度 `<= 0`,`data.is_threshold_reached` 表示是否已达用量阈值,默认90%就reach |
| 200 | 0 | `ok` | 成功 |
`额度不足` 响应示例:
```json
{
"code": 40012,
"message": "额度不足",
"data": {
"is_threshold_reached": true
}
}
```
## 其它说明
- **DNS 超时**:单次 DNS 查询 2 秒, 极端情况下单条耗时可达约 4 秒, 境外搜索引擎检测场景会偶发。