Ir al contenido
FingerTrackIDFingerTrackID Docs
En producción, en modo shadow: FingerTrackID recomienda, su sistema decide.Estado →

Entrega de la implementación para su desarrollador o su IA

Use esta página como las instrucciones de implementación para el equipo o la IA que integra su producto. Registre su empresa y su aplicación y, después, prepare el navegador y el backend juntos. Todas las empresas siguen este mismo flujo; no se requiere ningún cliente de demostración preconfigurado ni ninguna integración específica de un sitio. Cuando el trabajo lo haga un agente de programación con IA, entréguele también los archivos de documentación y las reglas de repositorio para agentes de IA.

Empiece en SHADOW: FingerTrackID evalúa y recomienda mientras su producto sigue autenticando a los usuarios y ejecutando sus propias decisiones.

Datos emitidos

Sección titulada «Datos emitidos»

Obtenga lo siguiente de la configuración real y de la entrega verificada del alta. Marque como bloqueante un dato que falte; no lo deduzca de un ejemplo, de la configuración de otra empresa ni de la URL de la documentación.

Dato Dónde va
IDs de la empresa/aplicación y entorno Configuración de la integración y referencias de soporte
Archivo privado aprobado del SDK, versión exacta, SHA-256 y SHA-512 Se descarga en la consola (Início › Configuração do SDK, o Integração e saúde › Pacote do SDK Web); verifique ambos hashes con los que muestra la consola antes de la instalación
Clave pública de la aplicación (pub_app_…) Configuración del SDK del navegador; un localizador público
Origen HTTPS exacto de captura y orígenes permitidos del sitio Configuración del navegador y CSP; se requiere el dominio first-party activo
Dos nombres/destinos CNAME exactos y un valor TXT reciente de titularidad Su proveedor de DNS; publique los registros emitidos y espere a la verificación
Origen de la API: https://api.fingertrackid.com (también se muestra en la consola como Endereço da API de risco, en el paso Credencial servidor a servidor) Configuración del backend; solo el origen, exactamente como está escrito, no el servidor de ejemplo de OpenAPI ni una ruta
key_id UUIDv7, capacidades habilitadas, límites de tasa y de ráfaga Configuración del backend; use el alcance de la credencial emitida
Secreto HMAC recibido una sola vez en la consola, codificación hex Gestor de secretos del backend, directamente desde la consola; nunca proporcione el valor a una IA
Política activa, release calificado y el perfil de solicitud en uso (v1.1, o v1 y sus recorridos) Interpretación esperada de la respuesta y el feature gate de producción
Acceso nominativo a la consola y confirmación de activación Acceso humano, verificación de correo/autenticador obligatoria y registro operativo

La entrega estándar del Web SDK es un archivo privado aprobado, que se descarga en la consola con el SHA-256 y el SHA-512 que FingerTrackID registró para él. Esos digests no implican una firma independiente. No hay instalación por script: la distribución por script no está habilitada (instalación).

El material HMAC nunca debe figurar en estas instrucciones ni en un archivo de configuración generado. FingerTrackID genera el secreto, y un administrador de la empresa o un gestor de integración lo recibe una sola vez en la consola y lo guarda directamente en el gestor de secretos del backend; nunca se vuelve a mostrar. Mientras la consola muestre la solicitud de la credencial como Aguardando você receber o segredo (esperando a que usted reciba el secreto), la firma real está bloqueada; prepare solo referencias y pruebas con vectores sintéticos.

Configuración gestionada antes de la implementación

Sección titulada «Configuración gestionada antes de la implementación»
  1. En Início de la consola, complete Criar a aplicação con orígenes exactos del sitio, como https://app.yourcompany.com, en lugar de URL individuales de /login o /register.
  2. Complete Configurar a coleta web con uno de los orígenes de la aplicación y el dominio base de su propiedad yourcompany.com. El colector es collect.yourcompany.com, y el SDK captura a través de él desde todo origen permitido de la aplicación bajo ese dominio (por ejemplo, https://yourcompany.com y https://www.yourcompany.com); la lista se edita después en Integração e saúde › Origens das páginas. El perfil web cooperativo estándar (COOPERATIVE_WEB_SHADOW_V1) produce recomendaciones MONITOR solo de observación; su presencia no demuestra una detección de fraude calibrada.
  3. Publique los registros DNS emitidos una vez que la plataforma haya preparado la vinculación first-party exacta. Mantenga ambos CNAME en modo solo DNS. El valor TXT de titularidad no cambia: si la ventana de verificación de la plataforma ha vencido, Verificar agora (verificar ahora) la renueva con el mismo valor, sin ninguna solicitud a FingerTrackID y sin ningún cambio de DNS.
  4. Haga el seguimiento de la misma solicitud mientras la plataforma ejecuta sus pasos automáticos (release, política, admisión y dominio); el progreso de la configuración indica cuándo un paso depende de usted. Aguardando revisão (esperando revisión) no es una configuración completada; el paso está hecho solo cuando Início lo muestra como Concluída. Si se cancela un trabajo en espera, los artefactos ya creados permanecen; una solicitud cancelada no es una reversión ni una integración completada.
  5. Complete Credencial servidor a servidor, reciba el secreto una sola vez con Receber segredo y guárdelo en el gestor de secretos del backend; después, confirme el key_id público, los permisos y la admisión de producción activa. Los nuevos clientes gestionados empiezan con 5 solicitudes por segundo con una ráfaga de 10; la consola muestra el límite vigente y cómo aumentarlo (límites).
  6. Complete Configuração do SDK una vez que el dominio de captura esté activo, y obtenga el archivo privado exacto del SDK y los datos de integración. Prepare el código con los identificadores reales emitidos y vectores de firma sintéticos; habilite la captura y las llamadas reales solo después de la confirmación explícita de activación de la aplicación y de las pruebas técnicas aplicables.

La activación del SDK del navegador y la activación de la API firmada se confirman por separado. Un colector habilitado no exime de recibir el secreto de la credencial, ni de la admisión, ni de la verificación del aislamiento de la autenticación/del entorno de ejecución para las llamadas de su backend.

Limite estas instrucciones a IDs públicos, registros DNS, hashes, orígenes y referencias de activación. No incluya planes de infraestructura privada, archivos de credenciales de nube, localizadores de secretos ni bytes HMAC.

Contratos públicos legibles por máquina

Sección titulada «Contratos públicos legibles por máquina»

Descargue exactamente estos archivos y conserve sus directorios relativos:

El documento OpenAPI de evaluación conserva su servidor de ejemplo histórico, sus identificadores de esquema y su anotación de implementación planificada. No son valores de entorno emitidos ni prueba de despliegue; el origen de la API de producción es https://api.fingertrackid.com. Los esquemas/ejemplos públicos siguen siendo las fuentes exactas del contrato, no una aproximación. Lea en conjunto autenticación, solicitud, respuesta, errores y reglas de reintento.

Integración en el navegador

Sección titulada «Integración en el navegador»
  1. Verifique e instale el paquete privado del SDK. Inicialícelo solo en código del navegador, con una sola copia del SDK y un solo cliente para el ciclo de vida actual del documento/la cuenta.
  2. Después de cualquier consentimiento aplicable, prepare el contexto ante la primera intención en el formulario de la acción evaluada (foco o pointer-down, nunca al cargar la página) con createActionContextHelper; vuelve a capturar solo cuando la captura saldría de la ventana de evidencia (60 o 300 segundos) antes de su margen, cuando su sesión terminó, tras consultas rechazadas repetidas, o una vez por página tras una limitación transitoria; mientras los contextos de evento no están disponibles, añade como máximo una captura cada 300 segundos (etapas y motivos); siga el ciclo de vida del SDK. En un inicio de sesión con MFA, el contexto va con el envío del MFA. Si el inicio de sesión redirige a Google o a otro proveedor, siga inicio de sesión con Google, OAuth y otras redirecciones. Las páginas de inicio de sesión, registro y recuperación de contraseña pueden ser lugares de captura. En v1.1, cada momento que su backend evalúa recibe su propia etiqueta (signup, password_recovery…); en v1 no son recorridos adicionales. No lea ni envíe al SDK valores de formularios, contraseñas, códigos de recuperación ni referencias de identidad seleccionadas por el navegador.
  3. Para cada nueva acción de negocio que el backend vaya a evaluar, tome un contexto de acción retenido en su envío, esperando como máximo su propio tope y sin abortar nunca el SDK; con el SDK 0.3.0, el take() del helper hace esto y nunca rechaza. Un fallo del SDK, de la red o del contexto debe dejar funcionando su operación de negocio normal.
  4. Pase solo el token capturado y su expiresAt, o null, en su solicitud de negocio existente, autenticada y protegida contra CSRF; el backend envía null si el token está a punto de caducar. Reintente la misma acción con el mismo handle y el mismo resultado capturado, incluido null. No vuelva a capturar ni sustituya un token para cambiar una evaluación existente.
  5. Mantenga vivo el cliente del documento hasta que su backend haya respondido: cerrarlo antes de que se almacene la evaluación invalida el contexto. Manténgalo fuera de los componentes de página que se desmontan en el envío, y retenga la navegación de un formulario clásico hasta que el contexto esté resuelto o se agote su tope; conserve los plazos originales.
  6. Al cerrar sesión/cambiar de cuenta, cierre el cliente y descarte los handles antes de la reinicialización. Nunca retrase el cierre de sesión para terminar una captura opcional ni persista handles/tokens del SDK en el almacenamiento.
  7. Mantenga su origen de captura fuera de la propagación de trazas de la instrumentación de la página: un encabezado de solicitud adicional hace que falle cada solicitud del SDK (encabezados de rastreo).

El navegador nunca firma solicitudes S2S ni elige la identidad de confianza de la persona/cuenta. Use la interfaz aprobada del SDK en lugar de implementar usted mismo sus endpoints de transporte.

Integración en el backend

Sección titulada «Integración en el backend»

Las nuevas integraciones usan la solicitud v1.1 (event-assessment-request.v1.1): usted nombra cada momento evaluado con su propia etiqueta (login, saque, pix_transfer…), y todas las etiquetas se evalúan de la misma manera. Las plantillas de recorrido sugieren etiquetas y puntos de llamada para momentos habituales. Producción acepta la solicitud v1.1 con su tag.

La solicitud v1 sigue admitida, sin cambios. Tiene exactamente LOGIN, WITHDRAWAL y TRADE, con sus acciones y contextos cerrados; no invente REGISTER ni PASSWORD_RECOVERY, ni clasifique como LOGIN una operación no relacionada. Una integración que ya está en v1 migra llamada por llamada (pasar de v1 a v1.1).

Para una primera integración de inicio de sesión, use la etiqueta login (en v1: LOGIN con action: "LOGIN_ATTEMPT") después de que el backend haya completado su autenticación real y el MFA requerido, y de que derive el subject_ref de la persona y el account_ref de la cuenta como seudónimos con clave estables (referencias de persona y de cuenta). Envíe la evaluación de inmediato: el contexto del navegador de ese inicio de sesión debe almacenarse antes de su expiresAt. Una sesión provisional o una solicitud de OTP no es una autenticación completada. Conserve la respuesta de inicio de sesión existente aunque FingerTrackID no esté disponible.

Para cada evaluación lógica:

  1. Derive en el backend occurred_at, las referencias de identidad (el mismo par subject_ref y account_ref para la misma persona y la misma cuenta en cada llamada), external_event_id e idempotency_key. Nunca acepte valores del navegador como autoridad para esos campos.
  2. Valide la solicitud cerrada y serialícela una sola vez. Conserve los bytes originales exactos y el token, incluido null, con la operación lógica.
  3. En cada intento de transporte, genere un nuevo request_id UUIDv7, una marca de tiempo actual y una firma sobre esos mismos bytes. Decodifique la clave hexadecimal de 64 caracteres a sus 32 bytes antes del HMAC.
  4. Valide la evaluación o el Problem devuelto. Compruebe el evento esperado y su tag (v1.1) o journey (v1), y conserve los campos de política/release/recomendación devueltos.
  5. Siga la matriz de reintentos. Un resultado desconocido se concilia con el mismo POST y los bytes originales; un 410 definitivo nunca da lugar a IDs de operación regenerados.

Un contexto ausente significa evidencia del navegador ausente. No garantiza INCONCLUSIVE, 201, una puntuación ni el éxito. trust_score: null significa sin puntuación, nunca un valor predeterminado de 0 o 100. El cliente decide y ejecuta la acción; FingerTrackID nunca aplica un bloqueo en su producto.

Feedback y verificación en la consola

Sección titulada «Feedback y verificación en la consola»

Cuando su credencial tenga las capacidades activas requeridas, use los contratos de acción del cliente y de resultado para informar su decisión real y la evidencia posterior. Un bloqueo, una cancelación o una puntuación no es una confirmación de fraude. No declare una alineación que FingerTrackID debe derivar, ni sobrescriba la verdad histórica con la política más reciente.

Use la consola para consultar Acessos (accesos), Integração e saúde (integración y salud), Configuração de risco (configuración de riesgo), Auditoria (auditoría) y Uso según su rol. El uso es una estimación a partir de registros inmutables, no una factura ni una métrica de precisión en fraude.

Revisión y activación

Sección titulada «Revisión y activación»

Muestre el diff de su integración y las comprobaciones sintéticas del vector de firma, la validación de esquemas, el comportamiento ante duplicados/reintentos, los resultados desconocidos/caducados, el fallo de inicialización del SDK/del contexto síncrono, la red/el contexto no disponibles, el cierre de sesión/cambio de cuenta y la ubicación correcta de la autenticación de servidor. Demuestre que su producto sigue funcionando cuando la integración está deshabilitada o no disponible.

FingerTrackID confirma los datos de entrada reales, el dominio, la instalación de la credencial, la admisión activa, la política/el release y las pruebas aplicables antes de habilitar el tráfico real. Conserve los IDs de solicitud/operación, los IDs de correlación, las marcas de tiempo y los códigos de error públicos para el soporte. Nunca registre en logs tokens, secretos, cookies, datos personales ni payloads completos.

Antes de salir a producción, lea la guía de integración: envíe siempre la evaluación (con null cuando no haya contexto), aplique fail-open con errores visibles, valore el período en modo shadow con feedback y pruebe en producción sin sandbox. Para su política de privacidad, consulte datos recopilados y tratamiento.

Termine con la lista de verificación de integración.