整合

表單 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
}