集成

表单 Gate

来自访客浏览器的令牌,由您的服务器使用站点 Secret 校验。

签发令牌

POST/v1/gate/token
无需密钥每位未缓存访客计 1 次请求

参数

  • sitekeystring必填

    表单 Gate 的站点 Key,可在控制台中找到。

  • signalsobject必填

    gate.js 收集的浏览器特征:headless_flags、user_agent 和 client。

响应字段

  • tokenstring

    表单使用的一次性令牌,五分钟后过期。

  • expiresAtstring

    令牌过期时间,ISO 8601 格式。

  • errorstring

    失败时:403 hostname_mismatch(页面的 Origin 不在该 Gate 的主机名中)、404 unknown_site、429 rate_limit_exceeded 或 quota_exhausted。此时 gate.js 会在没有令牌的情况下提交表单。

curl -X POST https://ipscanner.io/v1/gate/token \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "sitekey": "site_4fQ8nZ2kLm7xR1vT9cBw",
    "signals": {
      "headless_flags": {
        "webdriver": false,
        "headless_ua": false
      },
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Safari/605.1.15"
    }
  }'
响应
{
  "token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
  "expiresAt": "2026-10-09T09:35:00Z"
}

校验令牌

POST/v1/gate/verify
站点 Secret不计入用量

参数

  • secretstring必填

    表单 Gate 的 Secret。仅用于服务器端,切勿放入页面。

  • tokenstring必填

    表单提交的 ipscanner-token 值。

  • remote_ipstring

    您的服务器看到的访客 IP。可选,用于判断 ip_match。

响应字段

  • successboolean

    令牌有效且未使用时为 true。

  • classstring

    verified_bot、malicious_automation、ai_agent、tor、vpn、proxy、relay、hosting 或 human。

  • actionstring

    您的策略对该类别的动作:allow、flag 或 block。

  • modestring

    monitor 或 enforce。monitor 模式下由您决定如何处理 block。

  • confidencenumber

    置信度,范围 0 到 1。

  • networkobject

    classification、anonymized、provider 和 vpn_provider。provider 和 vpn_provider 仅 Starter 及以上方案提供,Free 方案为 null。

  • network.vpn_providerstring | null

    vpn 地址所属的 VPN 服务(NordVPN、Mullvad 等),已知时返回。Starter 及以上方案提供,Free 方案为 null。

  • signalsstring[]

    触发的自动化特征,例如 webdriver。正常访客为空。

  • hostnamestring

    签发令牌时所在页面的主机名。

  • issued_atstring

    令牌签发时间,ISO 8601 格式。

  • ip_matchboolean

    传入 remote_ip 且与签发令牌时的地址不同时为 false。

  • lockedstring[]

    在当前方案下以 null 返回的字段路径(以点分隔)。Starter 及以上方案不返回此字段。

  • planRequiredstring

    包含被锁定字段的方案。Starter 及以上方案不返回此字段。

  • errorstring

    success 为 false 时:400 missing_token、invalid_token、expired_token、already_used 或 hostname_mismatch;401 invalid_secret。

curl -X POST https://ipscanner.io/v1/gate/verify \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "gs_YOUR_GATE_SECRET",
    "token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
    "remote_ip": "203.0.113.7"
  }'
响应
{
  "success": true,
  "class": "human",
  "action": "allow",
  "mode": "enforce",
  "confidence": 0.6,
  "network": {
    "classification": "residential_clean",
    "anonymized": false,
    "provider": null,
    "vpn_provider": null
  },
  "signals": [],
  "hostname": "shop.example.com",
  "issued_at": "2026-10-09T09:30:00Z",
  "ip_match": true
}