Integraciones

Gate de formulario

Un token desde el navegador del visitante, comprobado por tu servidor con el secreto del sitio.

Emitir un token

POST/v1/gate/token

Sin clave1 solicitud por visitante sin caché

Parámetros

sitekeystringObligatorio
La clave del sitio del gate de formulario, desde el panel.
signalsobjectObligatorio
Señales del navegador que envía gate.js: headless_flags, user_agent y client.

Campos de la respuesta

tokenstring
Token de un solo uso para el formulario. Caduca a los cinco minutos.
expiresAtstring
Cuándo caduca el token, ISO 8601.
errorstring
Si falla: 403 hostname_mismatch (el Origin de la página no está entre los nombres de host del gate), 404 unknown_site, 429 rate_limit_exceeded o quota_exhausted. gate.js envía entonces el formulario sin token.

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"
    }
  }'

Respuesta

{
  "token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
  "expiresAt": "2026-10-09T09:35:00Z"
}

Verificar un token

POST/v1/gate/verify

Secreto del sitioNo consume cupo

Parámetros

secretstringObligatorio
El secreto del gate de formulario. Solo en el servidor, nunca en una página.
tokenstringObligatorio
El valor ipscanner-token que envió el formulario.
remote_ipstring
La IP del visitante tal como la ve tu servidor. Opcional, fija ip_match.

Campos de la respuesta

successboolean
True cuando el token es válido y no se ha usado.
classstring
verified_bot, malicious_automation, ai_agent, tor, vpn, proxy, relay, hosting o human.
actionstring
La acción de tu política para la clase: allow, flag o block.
modestring
monitor o enforce. En modo monitor, tú decides qué hacer con un block.
confidencenumber
Confianza de 0 a 1.
networkobject
classification, anonymized, provider y vpn_provider. provider y vpn_provider desde Starter, null en Free.
network.vpn_providerstring | null
Servicio VPN de una dirección vpn (NordVPN, Mullvad...), si se conoce. Desde Starter, null en Free.
signalsstring[]
Las señales de automatización que saltaron, como webdriver. Vacío para un visitante normal.
hostnamestring
El nombre de host de la página para la que se emitió el token.
issued_atstring
Cuándo se emitió el token, ISO 8601.
ip_matchboolean
False cuando se envía remote_ip y no coincide con la dirección para la que se emitió el token.
lockedstring[]
Rutas con puntos de los campos enviados como null en este plan. Ausente desde Starter.
planRequiredstring
Plan que incluye los campos bloqueados. Ausente desde Starter.
errorstring
Con success en false: 400 missing_token, invalid_token, expired_token, already_used o 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"
  }'

Respuesta

{
  "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
}