Solución de problemas

Empiece por el síntoma que ve. Cada sección indica las causas probables, cómo distinguirlas y la corrección, con un enlace a la página que contiene la regla completa. FingerTrackID nunca bloquea su producto: mientras corrige cualquiera de estos casos, su inicio de sesión y cualquier otra acción de negocio siguen su camino normal (guía de integración).

Compruebe primero la salud de la integración

En la consola, abra Integração e saúde (integración y salud) para la aplicación (la pantalla). Cubre las últimas 24 horas registradas; sus cifras no son en tiempo real.

• Última coleta (última captura) muestra una hora reciente en lugar de nenhuma coleta na janela (ninguna captura en la ventana). La ausencia total de capturas apunta al lado del navegador: vea el Web SDK no captura nada.
• En Da coleta à avaliação (de la captura a la evaluación), Coletas aceitas (capturas aceptadas) crece con sus inicios de sesión y Correlacionadas (evaluaciones que encontraron su captura del navegador) se mantiene cerca de Avaliações (evaluaciones). Capturas sin evaluaciones correlacionadas apuntan al traspaso del navegador a su backend: vea las evaluaciones llegan sin evidencia del navegador.
• La salud Sem dados do SDK (sin datos del SDK) significa que llegaron evaluaciones en la ventana y ninguna trajo el contexto del SDK, así que ninguna recibió puntuación.
• Credenciais de servidor (credenciales de servidor) muestra el key_id y el estado de cada credencial, Origens das páginas (orígenes de las páginas) los orígenes del sitio desde los que el SDK puede capturar, y Limite de requisições (límite de solicitudes) la tasa vigente.

Para un acceso concreto, ábralo en Acessos (accesos): con evidencia del navegador, Cobertura de evidência (cobertura de evidencia) es mayor que cero, el indicador Automação (robô) muestra Detectado o Não detectado en lugar de Não avaliado, y las limitaciones no incluyen Coletor não carregado (capturador no cargado). La lista completa de comprobaciones está en compruebe que llega la evidencia del SDK.

El Web SDK no captura nada

Toda llamada del SDK que falla devuelve UNAVAILABLE con un reason (o, con el helper, un failure con su stage y su reason); initializeSdk() y createEvent() lanzan una excepción en su lugar. Regístrelos: el motivo distingue la mayoría de las causas (motivos de fallo).

Lo que ve	Causa probable	Corrección
Ninguna solicitud llega a su dominio de captura, y la configuración en Início no ha terminado	El dominio de captura aún no está activo. Sin un dominio de captura activo el SDK no se habilita para su aplicación, y publicar el DNS por sí solo no lo activa	Siga el paso Confirmar o domínio de coleta hasta que muestre Concluído, y Configurar a coleta web hasta Concluída (dominio de captura)
El paso espera en Depende de você, o un registro muestra Ainda não encontrado	Falta un registro DNS, tiene otro nombre, responde con más de un valor o está detrás de un proxy; o su política CAA no permite el certificado	Publique los tres registros exactamente como se muestran, solo DNS, sin nada delante; permita pki.goog y letsencrypt.org en la CAA; luego elija Verificar agora (los registros, cómo comprobarlo)
Un paso automático muestra Algo travou	Un paso de la plataforma no avanzó durante 30 minutos	Contacte con soporte indicando la referencia de la solicitud que se muestra en Início
TRANSPORT_ERROR en una página cuyo origen no figura en Origens das páginas	El origen de la página no es uno de los orígenes permitidos de la aplicación: el dominio de captura responde 403 origin-not-allowed sin aprobación de CORS, y el navegador oculta esa respuesta	Añada el origen HTTPS exacto en Integração e saúde › Origens das páginas (hasta 10, todos bajo el dominio de captura; el cambio surte efecto de inmediato)
TRANSPORT_ERROR, y la consola del navegador informa de una violación de CSP	Su connect-src no incluye el origen de captura exacto	Añádalo a connect-src; el SDK no necesita ninguna entrada en script-src (la CSP de su sitio)
TRANSPORT_ERROR, y la solicitud OPTIONS al dominio de captura responde 400	La instrumentación de la página añade encabezados de rastreo a las solicitudes del SDK	Deje el origen de captura fuera de la propagación de rastreo (encabezados de rastreo)
TRANSPORT_ERROR solo para algunos visitantes	Una extensión de bloqueo del navegador, o la red	Nada que cambiar en su configuración: continúe con un contexto null, y la evaluación de ese acceso queda inconclusa
AUTHENTICATION_FAILED en un origen permitido	El publicKey no es de esta aplicación (pub_app_…), o la versión del SDK no es aquella para la que está configurada la captura de su aplicación	Use la clave pública emitida en el dash; instale la versión que ofrece el dash, y contacte con soporte antes de cambiarla (actualización del SDK)
INVALID_RESPONSE	Un proxy, CDN o WAF delante del dominio de captura alteró la respuesta	Mantenga el CNAME de captura solo como DNS
TRANSPORT_ERROR o INVALID_RESPONSE justo al abrir la sesión, tras un cambio en el build	Una opción del minificador que rompe el SDK, como compress.unsafe_math (medido en el SDK 0.2.0)	Excluya el paquete del SDK de esa minificación o desactive la opción (instalación)
RATE_LIMITED	Por ejemplo, demasiadas sesiones nuevas, o más de 1000 sesiones vivas en la aplicación	Prepare solo en la primera intención de un formulario evaluado, nunca al cargar la página, y llame a close() al terminar (límites de sesión)
initializeSdk() lanza INVALID_CONFIGURATION	Su configuración no es exactamente publicKey y collectionOrigin, un origen HTTPS sin ruta	Corrija las dos claves (initializeSdk)
initializeSdk() lanza UNSUPPORTED_RUNTIME	La página no es HTTPS, o al navegador le falta Fetch, aleatoriedad criptográfica o un reloj monotónico	Continúe con un contexto null

El SDK se entrega solo como el paquete privado empaquetado en su frontend. FingerTrackID no sirve ningún script del SDK, así que una página que lo carga desde una URL o una CDN pública no captura nada.

Las evaluaciones llegan sin evidencia del navegador

La respuesta es INCONCLUSIVE con trust_score: null, recommendation_basis INSUFFICIENT_EVIDENCE y el MONITOR de respaldo; los 13 indicadores son NOT_EVALUATED con COLLECTOR_NOT_LOADED, y device_intelligence_snapshot_id y sdk_version son null. Con el perfil gestionado de producción actual, una evaluación almacenada sin event_context_token es siempre así (cuando el navegador no tiene contexto del evento).

• Su backend envía null. El navegador envía el token y su expiresAt en la solicitud de negocio que ya hace; su backend copia el token en event_context_token. Compruebe que el campo se reenvía, y que la mayoría de los inicios de sesión en los registros de su backend llevan un token. Un inicio de sesión sin token debe tener un motivo registrado, como WAIT_EXCEEDED en una red lenta, no un único código fijo en cada inicio de sesión.
• El navegador no tenía token. El SDK falló (vea arriba), o el contexto se tomó demasiado tarde: un envío sin nada preparado necesita al menos tres viajes de ida y vuelta antes de que exista un token. Llame a prefetch() en el primer foco o pointer-down del formulario (el ciclo de vida).
• Los inicios de sesión con redirección (proveedores sociales u OAuth) pierden el contexto, a menos que se tome antes de la redirección o se capture después del callback (redirecciones de inicio de sesión).
• El cliente se cerró demasiado pronto. Llamar a close() antes de que su backend responda termina la sesión que emitió el token, y un token cuya evaluación aún no se ha almacenado deja de funcionar.
• La API responde 400 event-context-invalid. El token caducó, ya se usó o es de otro ámbito (por ejemplo, capturado para otra aplicación). No se almacena nada. No repita el mismo cuerpo: evalúe el evento una vez más como una operación nueva con event_context_token: null (event-context-invalid).

Un token es de un solo uso, uno por evento de negocio, y la evaluación que lo lleva debe almacenarse antes de su expiresAt. La ventana de evidencia es de 60 o 300 segundos desde que la captura llega a FingerTrackID, según su aplicación; cada respuesta la muestra en data_freshness.maximum_required_age_ms (la ventana de evidencia). Si event-context-invalid es frecuente, capture más cerca de la acción.

401 en POST /v1/assessments

El type distingue tres casos. timestamp-out-of-window y request-replayed solo responden a una solicitud cuya firma se verificó para una credencial conocida: si los ve, su firma es correcta.

authentication-failed

El fallo uniforme, sin reintento: la respuesta nunca dice qué parte estaba mal. Trátelo como un error de configuración y compruebe, en este orden:

1. El secreto. La clave son los bytes decodificados del secreto, decodeSecret(text, 'hex'), nunca el texto hexadecimal. Use el secreto entregado con ese key_id: tras Trocar segredo la nueva credencial tiene un nuevo key_id, y la anterior se revoca al final de una superposición de como máximo 24 horas.
2. Los bytes. El hash del cuerpo cubre los bytes exactos que envía. Construya el cuerpo con una única llamada a JSON.stringify y envíe esos bytes; volver a serializar después de firmar da 401.
3. La cadena canónica. Exactamente diez líneas separadas por LF, sin LF final, la novena vacía; la ruta es literalmente /v1/assessments (la cadena canónica).
4. Los encabezados. X-FTID-Signature: v1=<key_id>:<mac>, una sola firma, con un MAC de 64 caracteres en minúsculas; key_id y request_id son UUIDv7 en minúsculas. X-Client-Id, X-Signature, X-Timestamp y X-Nonce se rechazan con 401.
5. El estado de la credencial. En Integração e saúde › Credenciais de servidor, la credencial debe estar activa, no revocada ni suspendida. Una credencial que aún espera su instalación segura no se puede usar. Un cliente que siguió reintentando 429 sin esperar queda bloqueado al menos 10 minutos, durante los cuales toda solicitud recibe 401.

Ejecute la autocomprobación de referencia en el Node.js que ejecuta su backend: node ftid-hmac-v1-self-check.mjs debe imprimir OK y el MAC del vector de prueba. Si lo hace, el firmador funciona, y la causa es el secreto, el key_id o los bytes que envía (firmador de referencia).

timestamp-out-of-window

Admite reintento. X-FTID-Timestamp es el segundo en que firma el intento, no el occurred_at del evento, y debe estar dentro de ±300 s del reloj del servidor. Sincronice el reloj de su backend (NTP) y envíe un nuevo intento. Un occurred_at fuera de ±300 s es otro error, 400 occurred-at-out-of-window.

request-replayed

Admite reintento. Se reutilizó un request_id. Es el nonce antirreproducción: genere uno nuevo en cada intento, incluso después de 401, 403, 429 o 503, con crypto.randomUUIDv7(), nunca crypto.randomUUID(), que genera la versión 4. Después corrija el generador que lo repitió.

403 forbidden

Está autenticado, pero la credencial no tiene la capability de la ruta. Las capabilities de una credencial quedan congeladas en su versión, así que no se le puede añadir una: cree en la consola una credencial de servidor con ese permiso. Las rutas de feedback necesitan action:write y outcome:write (forbidden).

429 rate-limited

Su cliente de servidor superó su tasa: 5 solicitudes por segundo con una ráfaga de 10 en el nivel estándar (límites). Espere el Retry-After (segundos enteros, hoy 1) y envíe un nuevo intento con el mismo cuerpo, un request_id nuevo, la marca de tiempo actual y una nueva firma. Reutilizar el request_id anterior da 401 request-replayed, y reintentar sin esperar agota el presupuesto de seguridad y bloquea la credencial al menos 10 minutos.

Para aumentar la tasa, abra Integração e saúde › Limite de requisições y elija Pedir aumento de limite, como Administrador da empresa o Gestor de integração; la consola ofrece hasta 10 por segundo, aprobado de inmediato. Para más, contacte con soporte en contato@fingertrackid.com. Una saturación momentánea del servicio es, en cambio, 503 assessment-unavailable, que se reintenta del mismo modo.

Muchos resultados inconclusos

INCONCLUSIVE es una afirmación sobre la evidencia, no sobre la persona: ningún código de limitación es un motivo contra el acceso.

• Sin contexto, toda evaluación es INCONCLUSIVE (arriba).
• Con contexto, la evaluación solo es COMPLETED cuando al menos el 30% de los 13 indicadores se evaluaron con evidencia fresca (evidence_coverage ≥ 30) y los dos indicadores que cuentan para la puntuación, BOT_AUTOMATION y BROWSER_SPOOFING, se evaluaron.
• Las reglas activas de su empresa hacen obligatorio cada indicador que active: un indicador activo sin evidencia fresca utilizable deja la evaluación sin puntuación (trust_score: null, MONITOR), incluso por encima del 30% de cobertura (reglas de riesgo).

Lea el not_evaluated_reason_code de cada indicador para ver qué faltó (códigos de limitación). Por ejemplo:

• STALE_DEVICE_PROFILE: la evidencia del navegador era más antigua que la ventana de evidencia de su aplicación (capture más cerca de la acción), o una fuente de evidencia del servidor era más antigua que su edad máxima, lo que volver a capturar no resuelve.
• UNSUPPORTED_RUNTIME en los indicadores de privacidad del navegador y de navegación privada: el SDK se ejecutó dentro de un iframe o de un navegador integrado en una app, o no se pudo identificar el motor del navegador de forma coherente.
• REQUIRED_EVIDENCE_MISSING en DEVICE_MULTI_USER: esperado en el primer inicio de sesión de una nueva instalación del navegador; los inicios de sesión siguientes lo evalúan.

Webhooks de salida

Los webhooks de salida de evaluaciones no están habilitados (estado en producción): no hay ningún webhook que configurar ni depurar. Su backend recibe cada evaluación solo en la respuesta a su POST /v1/assessments.

Qué enviar a soporte

Guarde y envíe los ID de operación, request_id, correlation_id (el encabezado X-Correlation-Id de cada respuesta), el assessment_id, los códigos de error públicos, las horas y las versiones. Nunca envíe tokens, secretos, cookies, encabezados sin procesar, datos personales ni payloads completos.