Ejecución de flujos

Valida el token de invitación incluido en el enlace enviado al destinatario y devuelve toda la información necesaria para iniciar o continuar el flujo de verificación.

Este endpoint no requiere autenticación; el propio token JWT actúa como credencial de acceso.

Lógica de validación

El servidor realiza las siguientes comprobaciones en orden:

1. Firma del JWT — verifica que el token no haya sido alterado.
2. Expiración del JWT — el token tiene una fecha de expiración embebida.
3. Existencia de la invitación — busca la invitación en base de datos por token.
4. Estado de la invitación — las invitaciones en estado failed son rechazadas. Las invitaciones used se permiten si el flujo aún no está en un estado final (completed, pending_review, approved, rejected), permitiendo así que el usuario continúe una sesión interrumpida.
5. Estado del flujo — el flujo asociado debe estar published.
6. Tiempo de ejecución — si el usuario ya inició el flujo (expiresAt está establecido), se verifica que no haya expirado el tiempo permitido para completarlo.

flowRunStatus

El campo flowRunStatus en la respuesta indica en qué punto se encuentra el usuario dentro del flujo:

status	Descripción	canContinue	requiresOtp
not_started	El usuario nunca abrió el flujo	true	false
in_progress	El usuario inició pero no terminó	true	false
saved_for_later	El usuario guardó el progreso para continuar después	true	true
completed	El flujo fue completado y está en revisión	false	false
pending_review	Enviado para revisión manual	false	false
approved	Verificación aprobada	false	false
rejected	Verificación rechazada	false	false
expired	Tiempo de ejecución agotado	false	false
abandoned	El flujo fue abandonado	false	false

Inicia la ejecución del flujo de verificación asociado a una invitación. Debe llamarse justo después de validar el token con GET /flow-runs/verify/{invitationToken}.

Este endpoint no requiere autenticación; el invitationToken actúa como credencial.

deviceInfo

Se recomienda enviar información del dispositivo para fines de auditoría y detección de fraude. Todos los campos son opcionales.

Obtiene los datos de geolocalización y seguridad de la IP desde la que se realiza la solicitud. El servidor detecta la IP automáticamente a partir de las cabeceras del request (x-forwarded-for, x-real-ip) — el cliente no envía la IP en el body.

Requiere el invitationToken del flujo activo.

Respuesta

Devuelve la IP detectada junto con:

• Seguridad: indicadores de VPN, proxy, Tor y relay
• Ubicación: ciudad, región, país, coordenadas y zona horaria
• Red: número de sistema autónomo (ASN) y organización

Los datos de respuesta completos deben enviarse al Queue Service en POST /ip/verify-ip para registrar el resultado.

Genera un OTP de 6 caracteres alfanuméricos, lo almacena hasheado (SHA-256) con una vigencia de 10 minutos y lo envía al correo indicado.

No requiere autenticación Bearer — se autentica mediante el invitationToken.

Notas

• Si ya existe un OTP activo para ese correo, se elimina y se genera uno nuevo.
• El OTP tiene un máximo de 5 intentos de validación.
• La respuesta devuelve expiresAt pero no el OTP en sí.

Genera un OTP de 6 caracteres alfanuméricos y lo envía al número de teléfono indicado via SMS.

No requiere autenticación Bearer — se autentica mediante el invitationToken.

Notas

• El OTP tiene una vigencia de 10 minutos.
• Si ya existe un OTP activo para ese número, se elimina y se genera uno nuevo.
• La respuesta incluye el número enmascarado y expiresAt, pero no el OTP.
• Para enviar el código por llamada telefónica en lugar de SMS, usar POST /phone/send-code-to-verify-by-call en el Queue Service.

Sube el archivo de comprobante de domicilio (factura de servicios, extracto bancario, etc.) y lo almacena en S3. Devuelve el fileId y la URL del archivo, necesarios para los pasos siguientes.

No requiere autenticación Bearer — se autentica mediante el invitationToken.

Formatos aceptados

• JPEG, PNG, PDF
• Tamaño máximo: 5 MB

Tipos de documento (documentKey)

El valor de documentKey identifica el tipo de comprobante. Valores comunes:

• utility_bill_electricity
• utility_bill_water
• utility_bill_gas
• bank_statement