Recorridos y etiquetas

Un recorrido es el momento en que su backend solicita una evaluación (POST /v1/assessments): un inicio de sesión, un retiro, una orden. No es una página; el Web SDK captura en cualquier página en la que ocurra la acción.

Hay dos perfiles de solicitud en la misma ruta, con la misma autenticación HMAC:

Perfil	schema_version	Cómo se nombra el momento
v1.1	event-assessment-request.v1.1	Un tag libre que usted elige (login, saque, pix_transfer, trade…)
v1	event-assessment-request.v1	Uno de tres recorridos fijos: LOGIN, WITHDRAWAL o TRADE

Cada llamada elige su perfil por su schema_version; no hay nada que configurar por aplicación. Las integraciones nuevas deberían usar v1.1. Si hoy usa v1, consulte cómo pasar de v1 a v1.1.

Ambos perfiles se aceptan en producción

Producción acepta la solicitud v1.1 con su tag. La solicitud v1 no cambia y se sigue aceptando, por lo que una integración en v1 sigue funcionando tal como está.

La etiqueta v1.1

El tag es un slug que nombra el punto de llamada en su sistema. No tiene registro, ni límite, ni activación, ni lista que mantener sincronizada con FingerTrackID: envíelo en cada llamada.

• Gramática: ^[a-z0-9][a-z0-9_]{0,63}$. Letras ASCII minúsculas, dígitos y guion bajo, de 1 a 64 caracteres, empezando por una letra o un dígito. No hay normalización: Login, pix-transfer o saque (con un espacio) se rechazan, no se corrigen.
• Como máximo diez dígitos en total. Once o más dígitos se rechazan, juntos o separados (tanto cpf_12345678901 como cpf_123_456_789_01), porque esa es la forma de un identificador fiscal o de un número de teléfono. Esta comprobación no demuestra que la etiqueta esté libre de datos personales: esa garantía le corresponde a usted.
• Sin datos personales. Nunca ponga en la etiqueta un correo electrónico, identificador fiscal, número de teléfono, nombre, ID de usuario, número de cuenta ni clave Pix. Una etiqueta nombra un momento de su producto, nunca a una persona.
• La etiqueta forma parte de la identidad de la operación. Un reintento debe repetir el cuerpo completo, etiqueta incluida; el mismo external_event_id o idempotency_key con otra etiqueta es 409 idempotency-conflict.

Qué cambia la etiqueta y qué no

La etiqueta organiza su lectura. En la consola, usted filtra los accesos por etiqueta, ve el volumen y el estado de cada etiqueta, lo exporta y lee cuántos eventos con la misma etiqueta llegaron a la misma cuenta (cuando envía account_ref) o al mismo dispositivo en el último minuto, en los últimos cinco minutos y en la última hora.

La etiqueta no cambia cómo evalúa FingerTrackID. Toda solicitud v1.1 ejecuta el mismo comportamiento interno, sea cual sea su etiqueta:

• la misma evidencia y la misma política dan el mismo estado, la misma puntuación y la misma recomendación con cualquier etiqueta;
• el rango de deadline_ms es el mismo para todas las etiquetas (250–5000 ms, 5000 ms por defecto cuando es null);
• la etiqueta nunca selecciona una política, un detector, un proveedor, una contingencia, una cuota ni un precio;
• la etiqueta nunca aparece en las métricas, los logs ni las trazas de FingerTrackID.

Elija etiquetas que le resulten útiles al leer. Las plantillas de recorrido sugieren cuándo llamar, qué enviar y qué observar en diez momentos comunes; son solo orientativas y no tienen ningún efecto en la evaluación.

Ejemplo

El cuerpo v1.1 no tiene campos de importe, moneda, orden ni beneficiario. FingerTrackID evalúa el dispositivo y el acceso; su sistema ya tiene la transacción. Los ítems de contexto que dependen de un importe o de un beneficiario vuelven como no evaluados en un evento v1.1, con un motivo que indica que la solicitud no los incluye.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_withdrawal_0001",
  "idempotency_key": "idem_evt_withdrawal_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_withdrawal_0001",
  "tag": "saque",
  "deadline_ms": null
}

El perfil v1

El perfil v1 tiene tres recorridos fijos. Cada uno define el action, qué referencias son obligatorias, la forma de journey_context y el presupuesto técnico deadline_ms. Se sigue aceptando, sin cambios, para las integraciones que lo usan.

Recorrido	action	subject_ref y account_ref	journey_context	deadline_ms cuando es null	Rango explícito
LOGIN	LOGIN_ATTEMPT	Pueden ser null; account_ref requiere subject_ref	{}	5000	250–5000
WITHDRAWAL	WITHDRAWAL_REQUEST	Ambos obligatorios	amount_minor, currency, beneficiary_ref	1000	500–1000
TRADE	TRADE_REQUEST	Ambos obligatorios	{}	750	250–750

WITHDRAWAL

• amount_minor es un entero positivo en la unidad menor de la moneda — centavos para BRL: 150000 = R$ 1.500,00. Nunca un decimal.
• currency es el código ISO 4217 en mayúsculas (^[A-Z]{3}$), y la moneda debe estar en la lista de permitidas de la política de su aplicación.
• beneficiary_ref es un seudónimo opaco del beneficiario, creado por su backend.

{ "amount_minor": 150000, "currency": "BRL", "beneficiary_ref": "beneficiary_789" }

TRADE

Una orden no desencadena una nueva captura ni una consulta externa por orden: reutiliza la evidencia reciente de la sesión. En el navegador, varias órdenes pueden provenir de la misma captura aceptada, cada una con su propio contexto del evento (consulte el SDK). En v1.1, el mismo flujo usa la etiqueta trade (órdenes de negociación, una evaluación por orden).

deadline_ms

• Es un presupuesto técnico interno, contado desde que la solicitud entra en el servicio. Un número solo puede reducir el valor predeterminado.
• Esto no es un SLA. No cambia la puntuación ni la evidencia y no forma parte de la identidad de la operación: cambiar solo deadline_ms en un reintento mantiene la misma operación.
• El tiempo de espera de su cliente HTTP debe sumar la latencia de red al presupuesto. Para un LOGIN (v1) o cualquier etiqueta v1.1 enviada con null, eso significa un tiempo de espera superior a unos 6 s (5000 ms más la red). Un cuerpo que firma deadline_ms explícitamente puede enviar cualquier valor hasta 5000, o null; un cuerpo ya firmado con 750 o 1000 sigue siendo válido y conserva exactamente ese presupuesto.

Acción cuando no hay puntuación

Cuando la evaluación no termina en COMPLETED (INCONCLUSIVE, UNSCORABLE o FAILED), la recomendación es MONITOR: para todos los recorridos v1 y para todas las etiquetas v1.1.

MONITOR es una contingencia neutral. No es una puntuación favorable, ni una autorización, ni una acción tomada; su sistema sigue decidiendo qué hacer. recommendation_basis le indica por qué no hay puntuación.

Las evaluaciones creadas antes de este cambio pueden traer STEP_UP (LOGIN) o REVIEW (WITHDRAWAL) sin puntuación, y el esquema v1 todavía las acepta. Escriba su código en función de los campos que recibe (recommended_action, recommendation_basis, fallback_policy_version), no de una tabla fija. Ningún estado sin puntuación recibe ALLOW.