POST /v1/assessments — la solicitud

Su backend solicita una evaluación con una única llamada síncrona a POST https://api.fingertrackid.com/v1/assessments, firmada con HMAC.

El origen de la API de producción es https://api.fingertrackid.com; la consola también lo muestra, con un botón para copiar, como Endereço da API de risco en el paso Credencial servidor a servidor de Início. Configúrelo exactamente como está escrito, sin barra final ni ruta. La ruta es exactamente /v1/assessments: sin cadena de consulta, sin barra final y sin normalización. El cuerpo es un único objeto JSON en UTF-8.

Un intento

POST /v1/assessments HTTP/1.1
Host: api.fingertrackid.com
Content-Type: application/json
X-FTID-Timestamp: <second at which you sign this attempt>
X-FTID-Request-Id: <a new lowercase UUIDv7>
X-FTID-External-Event-Id: evt:tag-0001
X-FTID-Signature: v1=<key_id>:<mac>

{"schema_version":"event-assessment-request.v1.1","external_event_id":"evt:tag-0001","idempotency_key":"idem-tag-0001","occurred_at":"2026-10-11T12:00:00.000Z","subject_ref":null,"account_ref":null,"event_context_token":null,"tag":"login","deadline_ms":null}

Estado en producción

La API de evaluación firmada está en producción en modo shadow en https://api.fingertrackid.com/v1/assessments: las respuestas son recomendaciones y nunca imponen nada. Su aplicación necesita su credencial instalada y su admisión activa. Con el perfil de producción gestionado actual, una evaluación almacenada sin un event_context_token del navegador es INCONCLUSIVE con trust_score: null, nunca COMPLETED; sigue siendo posible un Problem operativo como 503. Consulte el estado en producción.

Descargue los archivos de contrato exactos de cada perfil. Para v1.1: el contrato OpenAPI v1.1, el esquema de la solicitud, el esquema de la respuesta y los ejemplos sintéticos. Para v1: el contrato OpenAPI v1, el esquema de la solicitud, el esquema de la respuesta y los ejemplos sintéticos. Ambos perfiles comparten el esquema de Problem, y el contrato v1.1 también hace referencia a los ejemplos v1 para dos Problems. Conserve la estructura relativa de directorios de estos archivos al usar las referencias de OpenAPI. Los archivos conservan su servidor de ejemplo original y su anotación de estado de implementación; ignore ese servidor de ejemplo y use https://api.fingertrackid.com. Producción acepta ambos perfiles: un cuerpo v1.1 correctamente firmado con su tag recibe como respuesta event-assessment.v1.1, y la solicitud v1 no cambia.

Encabezados

Encabezado	Valor	Regla
Content-Type	application/json	Exactamente este. application/json; charset=utf-8 se rechaza con 415
X-FTID-Timestamp	Epoch UTC en segundos, p. ej. 1788523200	Solo dígitos, sin cero a la izquierda, como máximo 253402300799; se acepta dentro de ±300 s del reloj del servidor
X-FTID-Request-Id	UUIDv7 canónico en minúsculas	Nuevo en cada intento de envío; es el nonce anti-replay
X-FTID-External-Event-Id	El external_event_id del cuerpo	Igual byte a byte al del cuerpo y al de la cadena firmada
X-FTID-Signature	v1=<key_id>:<mac>	Una sola firma; mac tiene 64 caracteres hexadecimales en minúsculas

No envíe estos encabezados:

Encabezado enviado	Respuesta
Content-Encoding, con cualquier valor, incluido identity	415 unsupported-media-type
Expect o Trailer; Host, Content-Length, Content-Type o Transfer-Encoding duplicados	400 validation-failed
X-Client-Id, X-Signature, X-Timestamp, X-Nonce	401 authentication-failed
X-FTID-Client-Id, X-FTID-Key-Id, X-FTID-Nonce, X-FTID-Event-Id, X-FTID-Business-Event-Id, X-FTID-Delivery-Id	401 authentication-failed
X-FTID-Assessment-Id en esta ruta	401 authentication-failed

Si su cliente HTTP agrega Expect: 100-continue o ; charset=... por su cuenta, desactívelo. No comprima la solicitud.

No existe X-Client-Id, ni client_id en el cuerpo, ni elección de empresa, aplicación o entorno por parte del cliente: todo eso se deriva del key_id una vez verificada la firma.

Cuerpo

El cuerpo tiene dos perfiles en esta ruta, elegidos por schema_version en cada llamada: v1.1, que nombra el momento con su propio tag, y v1, con tres recorridos fijos (recorridos y etiquetas). v1.1 es el perfil recomendado para integraciones nuevas y se acepta en producción; v1 se sigue admitiendo, sin cambios.

Todos los campos son obligatorios, incluidos los que aceptan null: omitir un campo no es lo mismo que enviar null. Un campo desconocido es un error, y también lo es un campo del otro perfil.

Campo	Formato	Regla
schema_version	"event-assessment-request.v1.1" o "event-assessment-request.v1"	Selecciona el perfil
external_event_id	^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$	ID de su evento de negocio; nunca se reutiliza
idempotency_key	De 8 a 255 caracteres ASCII visibles (0x21–0x7E)	Identifica la operación lógica; nunca se reutiliza
occurred_at	RFC 3339 con segundos, desfase explícito y hasta 3 decimales	Cuándo ocurrió el evento en su backend; una operación nueva debe estar dentro de ±300 s del reloj del servidor
subject_ref	Referencia opaca (misma gramática que external_event_id, como máximo 128 caracteres) o null	Seudónimo estable de la persona en su sistema (referencias)
account_ref	Referencia opaca (misma gramática que external_event_id, como máximo 128 caracteres) o null. Requiere un subject_ref no nulo; de lo contrario, 400 validation-failed	Seudónimo estable de la cuenta. Queda vinculado al subject_ref con el que se envió por primera vez (referencias)
event_context_token	De 1 a 4096 caracteres ASCII visibles, o null	Token del Web SDK para esta acción; null = no se proporcionó contexto del navegador
tag	Solo v1.1. ^[a-z0-9][a-z0-9_]{0,63}$, con un máximo de 10 dígitos en total	Su nombre para el momento; nunca datos personales (la etiqueta)
journey	Solo v1. LOGIN, WITHDRAWAL o TRADE	El perfil v1
action	Solo v1. Fijo por recorrido	El perfil v1
journey_context	Solo v1. Objeto cerrado por recorrido	El perfil v1
deadline_ms	Entero dentro del rango, o null	v1.1: 250–5000 para todas las etiquetas; v1: el rango del recorrido. null usa el valor predeterminado

Sin datos personales

subject_ref, account_ref y beneficiary_ref son seudónimos creados por su backend, y tag nombra un momento de su producto, nunca a una persona. No envíe identificadores fiscales, correo electrónico, teléfono, nombre, número de cuenta, secretos ni ningún identificador reversible. El alfabeto restringido no detecta datos personales: esa garantía le corresponde a usted. A diferencia de la etiqueta, las referencias no tienen límite de dígitos, por lo que un identificador fiscal de 11 dígitos cumple su gramática y FingerTrackID no puede distinguirlo de un seudónimo.

Contexto del navegador

Prepare a la vez la captura en el navegador y el backend. Cada acción evaluada conserva su propio token o null en todos los reintentos. Envíe la evaluación incluso cuando no haya token: null es un valor válido. La ausencia de contexto no promete un estado ni un resultado HTTP en particular: valide la respuesta real según la política emitida. Consulte la guía de integración.

Referencias de persona y de cuenta

subject_ref nombra a la persona y account_ref nombra una cuenta de esa persona en su sistema. Una persona puede tener varias cuentas; una cuenta pertenece exactamente a una persona.

• Constrúyalas como seudónimos con clave, en su backend. Por ejemplo, HMAC-SHA-256 sobre su ID interno con una clave secreta que solo su backend posee, escrito en hexadecimal tras un prefijo corto propio (usr_…, acc_…). Un hash simple de un identificador fiscal o de un correo electrónico no es un seudónimo: cualquiera puede recalcularlo adivinando la entrada. El hexadecimal siempre cumple la gramática. base64url necesita un prefijo, porque puede empezar por - o _; el base64 estándar (+, /, =) se rechaza. La referencia completa, prefijo incluido, tiene como máximo 128 caracteres.
• Mantenga el par estable. Envíe el mismo par para la misma persona y la misma cuenta en cada llamada. Un account_ref queda vinculado al subject_ref con el que se envió por primera vez: el mismo account_ref con otro subject_ref devuelve 409 binding-conflict, y no se almacena ningún evento ni ninguna evaluación. Cambiar la clave HMAC o el prefijo crea personas nuevas y cuentas nuevas, por lo que su historial empieza de nuevo. Nunca cambie solo la clave de subject_ref manteniendo account_ref: en ese caso, todas las cuentas existentes devolverían 409. Una clave nueva para subject_ref también convierte a cada persona en una segunda persona nueva en los navegadores que ya usó: durante 30 días, DEVICE_MULTI_USER cuenta ambos seudónimos, por lo que cuenta de más a las personas de esos dispositivos (es DETECTED con más de tres personas) hasta que los seudónimos antiguos salgan de su ventana.
• Envíelas siempre que el usuario esté identificado. Envíe subject_ref en cada momento evaluado en el que su backend conozca al usuario; en un inicio de sesión, después de que su backend haya autenticado al usuario. Envíe account_ref junto con él cuando el momento se refiera a una de las cuentas de esa persona; siempre viaja con su subject_ref. Cada plantilla de recorrido indica qué referencias lleva su momento: una recuperación de contraseña, por ejemplo, envía account_ref: null.
• Qué cambian. En la consola, account_ref alimenta los ítems de cuenta de Contexto do acesso (contexto del acceso), las cuentas en Vínculos y la búsqueda por cuenta. Los 13 indicadores y evidence_coverage son los mismos con o sin él; trust_score y la recomendación cambian solo cuando su empresa ha activado una regla de contexto sobre un ítem de cuenta (reglas de riesgo de la empresa). DEVICE_MULTI_USER cuenta personas a través de subject_ref, por lo que subject_ref cambia las respuestas de las capturas posteriores (por qué un indicador no se evaluó).
• El historial empieza en el primer evento que lleva la referencia. Los eventos anteriores nunca se vinculan a ella después. El primer acceso de cada cuenta con una captura del navegador completada muestra Primeira vez: ainda sem histórico (primera vez: aún sin historial) en los ítems que se comparan con el pasado de la cuenta; sin una captura del navegador completada, muestran Sem coleta concluída do navegador (sin captura del navegador completada). Un inicio de sesión posterior evalúa Dispositivo novo para esta conta solo cuando un acceso anterior de la misma cuenta en los últimos 90 días también tuvo una captura del navegador cuya instalación del navegador quedó vinculada; una cuenta inactiva durante más de 90 días vuelve a mostrar Primeira vez.
• Una cuenta por persona. Si su producto tiene una sola cuenta por persona, envíe igualmente ambas, con un seudónimo distinto y estable para la cuenta.

Reglas de bytes del cuerpo

• Como máximo 16384 bytes, contados antes de cualquier análisis o verificación de firma. Por encima de eso: 413 payload-too-large.
• UTF-8 sin BOM, un único documento JSON, nada después de él y ninguna clave duplicada en ningún nivel (incluidas las claves que solo se vuelven iguales después de deshacer el escape).
• Solo objetos, cadenas, null y enteros; los arrays y los booleanos se rechazan.
• Los números deben tener un valor entero exacto y seguro (hasta 9007199254740991). Envíe enteros simples.
• La firma y el servidor leen los mismos bytes. Serialice una sola vez, con una única llamada a JSON.stringify, conserve los bytes, y firme y envíe exactamente esos bytes.

Ejemplos de solicitud

Un ejemplo sintético v1.1. Cada plantilla de recorrido tiene el suyo.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_login_0001",
  "idempotency_key": "idem_evt_login_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_login_0001",
  "tag": "login",
  "deadline_ms": null
}

Ejemplos sintéticos v1, uno por recorrido.

LOGIN

{
  "schema_version": "event-assessment-request.v1",
  "external_event_id": "login_20260904_000001",
  "idempotency_key": "idem_login_20260904_000001",
  "occurred_at": "2026-09-04T12:00:00Z",
  "subject_ref": "subject_123",
  "account_ref": "account_456",
  "event_context_token": "ect_login_20260904_000001",
  "journey": "LOGIN",
  "action": "LOGIN_ATTEMPT",
  "journey_context": {},
  "deadline_ms": null
}

WITHDRAWAL

{
  "schema_version": "event-assessment-request.v1",
  "external_event_id": "withdrawal_20260904_000001",
  "idempotency_key": "idem_withdrawal_20260904_000001",
  "occurred_at": "2026-09-04T12:00:00Z",
  "subject_ref": "subject_123",
  "account_ref": "account_456",
  "event_context_token": "ect_withdrawal_20260904_000001",
  "journey": "WITHDRAWAL",
  "action": "WITHDRAWAL_REQUEST",
  "journey_context": {
    "amount_minor": 150000,
    "currency": "BRL",
    "beneficiary_ref": "beneficiary_789"
  },
  "deadline_ms": 1000
}

TRADE

{
  "schema_version": "event-assessment-request.v1",
  "external_event_id": "trade_20260904_000001",
  "idempotency_key": "idem_trade_20260904_000001",
  "occurred_at": "2026-09-04T12:00:00Z",
  "subject_ref": "subject_123",
  "account_ref": "account_456",
  "event_context_token": "ect_trade_20260904_000001",
  "journey": "TRADE",
  "action": "TRADE_REQUEST",
  "journey_context": {},
  "deadline_ms": 750
}

Los ejemplos están formateados para facilitar la lectura. En la llamada real, envíe el JSON compacto que produce JSON.stringify(object).

Siguiente paso: autenticación HMAC.