Referencia del veredicto

Cada veredicto de Prevención de fraude — ya se entregue a tu callback onVerdict en el Web SDK o se extraiga de la API de datos — es el mismo objeto BotVerdict. Esta página documenta cada campo y cómo actuar sobre él.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Campos

Campo	Tipo	Descripción
is_bot	boolean	El veredicto principal. true = la visita se juzga como tráfico automatizado o inválido; false = parece una persona real. Es el campo sobre el que ramifican la mayoría de las integraciones.
score	number (0–100)	Cuán sospechosa es la visita. Más alto significa más sospechoso. Úsalo para definir tus propios umbrales — p. ej. excluir visitas por encima de un corte que elijas. El valor exacto lo produce nuestro modelo de riesgo y no está pensado para someterse a ingeniería inversa.
level	enum	Banda aproximada de score: low, medium, high, critical. Conveniente cuando prefieres categorías en lugar de un número en bruto.
action	enum	Nuestro manejo recomendado para la visita: record_only, challenge, flag o deny. Ver más abajo. Trata los valores desconocidos como flag, para que tu integración siga funcionando si se añaden valores nuevos.
reasons	string[]	Hasta tres categorías de motivo generales que explican un veredicto de riesgo. Vacío en visitas limpias.
consistency	object	Una conclusión de consistencia entre señales. Lee consistency.ok (boolean): true = las señales de la visita encajan como se espera; false = algo no cuadró y la visita merece un escrutinio adicional. El desglose interno tras esta conclusión no se expone.
degraded	boolean	true cuando el veredicto no pudo computarse por completo (servicio inalcanzable, error, etc.) y se devolvió un valor de reserva conservador. Trata los veredictos degradados como "desconocidos", no como "limpios".
verdict_id	string	Id único de este veredicto. Úsalo para consultar el veredicto más tarde con la API de datos.
verdict_token	string	Prueba firmada de este veredicto, para que la verifique tu servidor. Consulta Verificación del lado del servidor. Ausente en los veredictos de reserva.
verdict_token_exp	number	Hora Unix (segundos) en la que caduca verdict_token.

action — qué hacer

action es nuestra recomendación; tú conservas el control de la decisión final.

action	Significado	Qué hacer
record_only	La visita parece normal.	Procede como de costumbre. Solo registra el veredicto para informes y conciliación.
flag	La visita es sospechosa pero no concluyentemente mala.	Sigue sirviendo la página, pero marca la visita como de baja calidad — exclúyela de tus métricas, sepárala de los flujos posteriores y pondérala en tus propias decisiones (p. ej. atribución de conversiones o cuánto confías en la visita).
challenge	La visita alcanzó tu umbral de verificación (alto riesgo por defecto).	Pide una verificación adicional antes de tratar al visitante como humano. Cuando la acción de manejo de tu app está configurada como challenge, el Web SDK la ejecuta por ti (consulta Escalado); de lo contrario, aplica tu propio filtro.
deny	La visita coincidió con una regla de bloqueo — por ejemplo, una entrada de lista de bloqueo o una política que configuraste para bloquear.	No sirvas contenido protegido. No se ofrece ningún challenge. Las versiones antiguas del SDK pasan este valor sin cambios, así que gestiónalo en onVerdict.

Acción de manejo configurable

Lo que action reporta para una visita de alto riesgo es configuración por aplicación, definida en el panel bajo los detalles de tu aplicación. El veredicto es autoritativo en el servidor: action solo pasa a ser challenge o flag cuando la visita alcanza la banda de alto riesgo y tu aplicación está configurada con la acción correspondiente. Por debajo de esa banda el veredicto permanece como record_only.

Ajuste	action devuelto en alto riesgo	Significado
record_only (por defecto)	record_only	Solo registrar. El veredicto se registra para informes y conciliación; no se le pide nada al visitante.
challenge	challenge	Dispara un CAPTCHA de reverificación. El Web SDK muestra un challenge (el estilo lo controla el challengeConfig del SDK).
flag	flag	Marca la visita. El veredicto lleva flag; tu integración decide cómo actuar sobre él (bloquear / segmentar / gestionar).

Como la decisión se toma del lado del servidor, tu código permanece simple: lee verdict.action en onVerdict y actúa sobre él — procede, bloquea o deja que el SDK muestre un challenge. No necesitas volver a derivar el riesgo por tu cuenta.

Umbral y tipo de verificación

Cuando la acción es challenge, aparecen dos ajustes más en la misma sección del panel:

• Umbral de verificación: a partir de qué nivel de riesgo se devuelve la acción configurada. El valor predeterminado es riesgo alto o superior. El modo estricto también la aplica a las visitas de riesgo medio: se detienen más scrapers y agentes de IA, pero más visitantes reales ven una verificación.
• Tipo de verificación: el tipo mínimo de CAPTCHA que se muestra al escalar: deslizador (predeterminado), rotar, clic o clic 3D. Los tipos más fuertes son más difíciles de resolver para herramientas automatizadas y de IA.

escalate_result

Presente después de que se ejecute una escalada de captcha gestionada — es decir, cuando action era challenge y el SDK ejecutó el captcha. null cuando no hubo escalada. También se entrega a onEscalateDone(passed, detail).

campo	descripción
passed	si el visitante superó el captcha
token	el token de aprobación del captcha — verifícalo en el servidor para confirmar la aprobación (no confíes solo en el passed del cliente)
challenge_id	el id del challenge del captcha
cid	el id de clic al que está vinculada esta escalada, si había un click token presente

reasons — categorías de motivo

reasons te indica, en términos generales, por qué una visita parecía de riesgo. Contiene como máximo tres categorías, de la más fuerte a la más débil. Nunca contiene señales individuales ni desgloses de la puntuación.

Categoría	Significado
automation	Indicios de herramientas automatizadas, como navegadores controlados por scripts o headless.
network	La red parece de riesgo o incoherente, como un proxy, una red de centro de datos o de anonimización, o una dirección bloqueada.
abnormal_requests	Patrones de solicitud inusuales, como demasiadas solicitudes, fallos repetidos o un historial de tráfico automatizado.
device	No se pudo confiar en el dispositivo o su entorno, o no se pudo reconocer.
behavior	La visita no se comportó como una persona, por ejemplo sin ninguna interacción o con un enlace reutilizado.
other	Cualquier otro motivo, incluidas tus propias reglas y los veredictos de reserva.

Trata la lista como una explicación para informes, no como una señal sobre la que construir reglas. Ramifica sobre is_bot, action o score en su lugar. Es posible que se añadan nuevas categorías.

Verificación del lado del servidor

Todo lo que recibe la página puede ser modificado por el visitante. Si proteges contenido (solo las personas reales pueden ver una página, una respuesta de API o una descarga), no confíes en el indicador is_bot del navegador. Envía verdict_token a tu propio servidor y verifícalo allí:

1. En onVerdict, envía verdict.verdict_token a tu backend, por ejemplo en una cabecera o una cookie.
2. Tu backend llama a POST /v1/bot/verdict/verify con el token y la dirección IP del visitante.
3. Sirve el contenido solo cuando la respuesta tenga valid: true y el veredicto te resulte aceptable (por ejemplo, verdict.is_bot es false).

El token está vinculado a tu app, a este veredicto y a la red del visitante, y caduca tras poco tiempo (10 minutos por defecto). Por defecto un token puede comprobarse muchas veces, así que un token puede cubrir las páginas vistas de una visita. Pasa consume: true cuando un token deba usarse una sola vez, como en el envío de un formulario.

Si el visitante supera después un challenge de escalado, el token sigue mostrando el veredicto original. Verifica también el token de aprobación del captcha de escalate_result con la API del captcha del lado del servidor.

level vs score

level es solo una agrupación de score en bandas, provista por conveniencia:

level	Úsalo cuando
low	Trátalo como tráfico limpio.
medium	En el límite — está bien registrarlo, considera excluirlo de embudos de alto valor.
high	Fuertemente sospechoso — márcalo y exclúyelo.
critical	Casi con certeza inválido — márcalo/exclúyelo e, idealmente, escálalo.

Elige el campo que encaje con tu pipeline

• Filtro simple sí/no → ramifica sobre is_bot.
• Guiado por recomendación → ramifica sobre action.
• Umbrales personalizados → ramifica sobre score (o level para categorías).

Manejo de veredictos degradados

Cuando degraded es true, el veredicto no se computó por completo. El valor de reserva es deliberadamente conservador (is_bot: false, action: record_only) para que los usuarios reales nunca se bloqueen. Para informes, trátalos como desconocidos en lugar de contarlos como tráfico confirmado-limpio.

Próximos pasos

• Web SDK — recibe veredictos en tu página
• API de datos — extrae veredictos y estadísticas del lado del servidor