Plantillas de recorrido

Una plantilla de recorrido es una guía para un momento habitual de su producto: cuándo su backend llama a POST /v1/assessments, qué referencias seudónimas enviar y qué mirar en la consola después. Las plantillas existen solo en esta documentación y en la guía de integración de la consola. No se almacena nada de ellas, y no tienen ningún efecto sobre la evaluación: toda solicitud v1.1 ejecuta el mismo comportamiento interno, por lo que la misma evidencia da la misma puntuación con cualquier etiqueta (recorridos y etiquetas).

La etiqueta sugerida es solo una sugerencia. Puede enviar en su lugar cualquier etiqueta válida, por ejemplo saque en lugar de withdrawal; la consola muestra la etiqueta que usted envía.

La solicitud v1.1

Las plantillas describen la solicitud v1.1, que producción acepta. Una integración que se queda en v1 conserva sus tres recorridos fijos, sin cambios.

Las diez plantillas

Plantilla	Etiqueta sugerida	Cuándo llama su backend	subject_ref	account_ref
Creación de cuenta	signup	Después de que su backend valida el formulario, antes de activar la cuenta	Recomendado (un seudónimo nuevo)	Recomendado (un seudónimo nuevo)
Inicio de sesión	login	Después de que su backend verifica la credencial, antes de emitir la sesión	Recomendado cuando el usuario está identificado	Recomendado con subject_ref
Recuperación de contraseña	password_recovery	Cuando la contraseña realmente se cambia, no cuando se solicita el enlace de restablecimiento	Recomendado solo si su backend ya resolvió quién es el usuario; nunca el correo electrónico	null
Verificación en dos pasos	mfa_challenge	Cuando su backend valida el código	Recomendado	Recomendado
Cambio de perfil	profile_change	Cuando su backend guarda un nuevo correo electrónico, número de teléfono o dirección	Recomendado	Recomendado
Depósito	deposit	Cuando su backend emite el cobro (código QR, boleto)	Obligatorio	Obligatorio
Retiro	withdrawal	Cuando el usuario confirma, antes de que su backend liquide	Obligatorio	Obligatorio
Transferencia o Pix	pix_transfer	Cuando el usuario confirma, antes de que su backend liquide	Obligatorio	Obligatorio
Orden	trade	Cuando su backend acepta la orden, antes de enrutarla	Obligatorio	Obligatorio
Checkout	checkout	Cuando el usuario confirma el pago, antes de que su backend lo capture	Recomendado	Opcional

account_ref requiere subject_ref: cuando una plantilla marca la referencia de cuenta como obligatoria, la referencia de persona también es obligatoria, y una plantilla que recomienda account_ref lo recomienda junto con subject_ref. Ambos son seudónimos que crea su backend; nunca envíe un correo electrónico, un identificador fiscal, un número de teléfono, un nombre ni un número de cuenta. Envíe el mismo account_ref con el mismo subject_ref en cada llamada: una cuenta queda vinculada a la persona con la que se envió por primera vez, y otro subject_ref devuelve 409 binding-conflict (referencias de persona y de cuenta).

Los ítems de la consola sobre una cuenta (un dispositivo nuevo para la cuenta, otras cuentas en los mismos dispositivos, eventos con la misma etiqueta en la misma cuenta) necesitan account_ref: sin él muestran Conta não informada pelo sistema da empresa. El historial de la cuenta empieza en su primer acceso: con una captura del navegador completada, ese acceso muestra Primeira vez: ainda sem histórico (primera vez: aún sin historial), y sin ella Sem coleta concluída do navegador (sin captura del navegador completada). Un acceso 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; tras más de 90 días sin un acceso así, vuelve a mostrar Primeira vez (referencias de persona y de cuenta).

Reglas que repite toda plantilla

• La etiqueta no lleva datos personales: ni correo electrónico, ni identificador fiscal, ni nombre, ni ID de usuario, ni clave Pix. Tiene como máximo diez dígitos en total.
• recommended_action es un consejo, no una acción realizada: su sistema decide y actúa.
• La misma evidencia da la misma puntuación con todas las plantillas y con todas las etiquetas.
• Un reintento repite el cuerpo completo, etiqueta incluida. Cambiar cualquier campo excepto deadline_ms con el mismo external_event_id o idempotency_key es 409 idempotency-conflict; un reintento que cambia solo deadline_ms es la misma operación y responde 200.

Una plantilla nunca lleva un importe, una moneda, una orden, un beneficiario, un plazo propio, una contingencia, una política, un peso, un proveedor, una aplicabilidad de señales, una cuota, un precio ni una clase interna. El cuerpo v1.1 no tiene ningún campo para ninguno de ellos.

Plantilla por plantilla

Cada ejemplo es un cuerpo v1.1 sintético, formateado para su lectura. En la llamada real, envíe el JSON compacto que produce JSON.stringify(object) y sustituya el token por el que el Web SDK devolvió para esa acción, o por null cuando no haya ninguno.

Creación de cuenta

• Etiqueta sugerida: signup
• Llamada: después de que su backend valida el formulario, antes de activar la cuenta.
• Referencias: subject_ref recomendado (un seudónimo nuevo); account_ref recomendado (un seudónimo nuevo).
• Qué mirar en la consola: DEVICE_MULTI_USER, BOT_AUTOMATION y EMULATED_ENVIRONMENT; otras cuentas vistas en el mismo dispositivo (necesita account_ref); eventos con la misma etiqueta en el mismo dispositivo (muchos registros desde un solo dispositivo).

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_signup_0001",
  "idempotency_key": "idem_evt_signup_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_signup_0001",
  "tag": "signup",
  "deadline_ms": null
}

Inicio de sesión

• Etiqueta sugerida: login
• Llamada: después de que su backend verifica la credencial, antes de emitir la sesión.
• Referencias: subject_ref recomendado cuando el usuario está identificado; account_ref recomendado, siempre junto con subject_ref.
• Qué mirar en la consola: BOT_AUTOMATION y BROWSER_SPOOFING; NETWORK_TOR, NETWORK_VPN y NETWORK_HOSTING; un dispositivo nuevo para la cuenta (necesita account_ref).

{
  "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
}

Recuperación de contraseña

• Etiqueta sugerida: password_recovery
• Llamada: cuando la contraseña realmente se cambia, no cuando se solicita el enlace de restablecimiento.
• Referencias: subject_ref recomendado solo si su backend ya resolvió quién es el usuario; nunca el correo electrónico; account_ref null.
• Qué mirar en la consola: NETWORK_TOR, NETWORK_VPN y NETWORK_HOSTING; PRIVATE_BROWSING; dispositivos vistos para la persona.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_password_recovery_0001",
  "idempotency_key": "idem_evt_password_recovery_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": null,
  "event_context_token": "ect_password_recovery_0001",
  "tag": "password_recovery",
  "deadline_ms": null
}

Verificación en dos pasos

• Etiqueta sugerida: mfa_challenge
• Llamada: cuando su backend valida el código.
• Referencias: subject_ref recomendado; account_ref recomendado.
• Qué mirar en la consola: continuidad con el dispositivo del inicio de sesión: un dispositivo nuevo para la cuenta (necesita account_ref) o una cookie de dispositivo perdida.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_mfa_challenge_0001",
  "idempotency_key": "idem_evt_mfa_challenge_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_mfa_challenge_0001",
  "tag": "mfa_challenge",
  "deadline_ms": null
}

Cambio de perfil

• Etiqueta sugerida: profile_change
• Llamada: cuando su backend guarda un nuevo correo electrónico, número de teléfono o dirección.
• Referencias: subject_ref recomendado; account_ref recomendado.
• Qué mirar en la consola: un dispositivo nuevo para la cuenta (necesita account_ref); NETWORK_TOR, NETWORK_VPN y NETWORK_HOSTING.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_profile_change_0001",
  "idempotency_key": "idem_evt_profile_change_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_profile_change_0001",
  "tag": "profile_change",
  "deadline_ms": null
}

Depósito

• Etiqueta sugerida: deposit
• Llamada: cuando su backend emite el cobro (código QR, boleto).
• Referencias: subject_ref obligatorio; account_ref obligatorio.
• Qué mirar en la consola: un dispositivo nuevo para la cuenta; NETWORK_TOR, NETWORK_VPN y NETWORK_HOSTING; eventos con la misma etiqueta en la misma cuenta. Los ítems de cuenta necesitan account_ref, que esta plantilla exige.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_deposit_0001",
  "idempotency_key": "idem_evt_deposit_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_deposit_0001",
  "tag": "deposit",
  "deadline_ms": null
}

Retiro

• Etiqueta sugerida: withdrawal
• Llamada: cuando el usuario confirma, antes de que su backend liquide.
• Referencias: subject_ref obligatorio; account_ref obligatorio.
• Qué mirar en la consola: un dispositivo nuevo para la cuenta; NETWORK_TOR, NETWORK_VPN y NETWORK_HOSTING; eventos con la misma etiqueta en la misma cuenta y en el mismo dispositivo.

Lo que un retiro v1.1 no muestra

La solicitud v1.1 no lleva importe ni beneficiario, por lo que los ítems de contexto que dependen de ellos (beneficiarios compartidos, beneficiarios por dispositivo, cuentas por beneficiario y el importe retirado en 24 horas) vuelven como no evaluados, con un motivo que indica que la solicitud no los lleva. Si los necesita hoy, integre el retiro con el recorrido v1 WITHDRAWAL, que conserva journey_context sin cambios.

{
  "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": "withdrawal",
  "deadline_ms": null
}

Transferencia o Pix

• Etiqueta sugerida: pix_transfer
• Llamada: cuando el usuario confirma, antes de que su backend liquide.
• Referencias: subject_ref obligatorio; account_ref obligatorio.
• Qué mirar en la consola: lo mismo que para un retiro.

Lo que un retiro v1.1 no muestra

La solicitud v1.1 no lleva importe ni beneficiario, por lo que los ítems de contexto que dependen de ellos (beneficiarios compartidos, beneficiarios por dispositivo, cuentas por beneficiario y el importe retirado en 24 horas) vuelven como no evaluados, con un motivo que indica que la solicitud no los lleva. Si los necesita hoy, integre el retiro con el recorrido v1 WITHDRAWAL, que conserva journey_context sin cambios.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_pix_transfer_0001",
  "idempotency_key": "idem_evt_pix_transfer_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_pix_transfer_0001",
  "tag": "pix_transfer",
  "deadline_ms": null
}

Orden

• Etiqueta sugerida: trade
• Llamada: cuando su backend acepta la orden, antes de enrutarla.
• Referencias: subject_ref obligatorio; account_ref obligatorio.
• Qué mirar en la consola: consulte órdenes de negociación, una evaluación por orden.

Una evaluación por orden, sin datos de la orden. El flujo completo y las notas de costo y capacidad están en órdenes de negociación, una evaluación por orden.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_trade_0001",
  "idempotency_key": "idem_evt_trade_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": "acc_77d2",
  "event_context_token": "ect_trade_0001",
  "tag": "trade",
  "deadline_ms": null
}

Checkout

• Etiqueta sugerida: checkout
• Llamada: cuando el usuario confirma el pago, antes de que su backend lo capture.
• Referencias: subject_ref recomendado; account_ref opcional.
• Qué mirar en la consola: BOT_AUTOMATION, BROWSER_SPOOFING y EMULATED_ENVIRONMENT; eventos con la misma etiqueta en el mismo dispositivo.

{
  "schema_version": "event-assessment-request.v1.1",
  "external_event_id": "evt_checkout_0001",
  "idempotency_key": "idem_evt_checkout_0001",
  "occurred_at": "2026-11-03T14:05:22.481Z",
  "subject_ref": "usr_5c0e",
  "account_ref": null,
  "event_context_token": "ect_checkout_0001",
  "tag": "checkout",
  "deadline_ms": null
}

Cómo elegir sus propias etiquetas

• Nombre el momento, no el resultado: withdrawal, no withdrawal_blocked.
• Mantenga una etiqueta por momento. La consola nunca fusiona dos etiquetas, por lo que saque y withdrawal son dos líneas en todos los informes.
• Mantenga la etiqueta estable entre versiones de su producto: una etiqueta renombrada inicia una línea nueva en la consola.