Modelo de estados: solicitud e intento

Modelo de estados: solicitud e intento

Una verificación de identidad involucra dos objetos distintos, y confundirlos es la causa más común de dudas sobre "qué pasó con esta persona". La solicitud (disclosure request) lleva el estado real del flujo. El intento (validation attempt) es un intento concreto de validación biométrica dentro de esa solicitud.

Solicitud vs intento

	Solicitud	Intento
Qué representa	El flujo completo que abre el usuario: cargar el widget, autenticarse o validarse, y obtener un resultado	Un intento concreto de validación biométrica dentro de ese flujo
Prefijo del ID	dreq_...	va_...
Estados	pending, in_progress, authenticating, validating, granted, failed, timed_out	pending, in_progress, successful, failed, canceled
Resultado que importa	Sí: el status de la solicitud es el resultado del proceso	No por sí solo: describe cómo fue ese intento puntual

Relación 1 → N

Una solicitud tiene N intentos. Cada reintento del usuario crea un intento nuevo y cancela los anteriores que sigan activos.

El intento no es exclusivo del disclosure: también respalda otros flujos que necesitan validación biométrica. Reconoce a qué flujo pertenece por el prefijo del ID asociado.

Prefijo	Flujo
dreq_	Disclosure request
dsreq_	Solicitud de derechos del titular
govcheck_	Verificación gubernamental vía API
cfvreq_	Validación de un formulario de consentimiento

Cuando el usuario ya tiene una identidad Soyio, la solicitud se resuelve autenticándolo en vez de validarlo desde cero. Esa rama usa intentos de autenticación (aa_...), que son un objeto distinto del intento de validación y explican el estado authenticating de la solicitud.

Los 7 estados de la solicitud

Estado	Qué significa
pending	La solicitud existe y está lista, pero el usuario todavía no la inició
in_progress	El usuario inició el flujo y está avanzando
authenticating	El usuario ya tiene una identidad Soyio y está autenticándose en lugar de validarse desde cero
validating	La validación de identidad está en curso
granted	Terminal. El proceso se completó: hay identidad verificada y consentimiento registrado
failed	Terminal. El proceso terminó sin entregar datos
timed_out	Terminal. El usuario no completó el flujo dentro del tiempo permitido

La forma más simple de ubicar cada estado es seguir el flujo en orden y mirar en qué estado queda la solicitud después de cada paso:

Los pasos condicionales explican por qué no todas las solicitudes pasan por los mismos estados: una identidad nueva nunca pasa por authenticating, y una identidad reutilizada con datos suficientes puede llegar a granted sin pasar por validating.

Tres reglas cierran el modelo:

• granted y failed se alcanzan solo desde in_progress o validating
• timeout puede ocurrir desde cualquier estado en curso (pending, in_progress, authenticating o validating), no solo al final del flujo
• cuando la autenticación es exitosa, la solicitud vuelve a in_progress, no salta directo a granted. Desde ahí sigue a validating o se otorga

La solicitud no tiene canceled

Ese estado existe solo en el intento. Cuando una solicitud queda sin completarse por inactividad, el estado que verás es timed_out, no canceled.

Los 5 estados del intento

Estado	Qué significa
pending	El intento se creó, pero el usuario todavía no empezó a capturar su biometría
in_progress	El usuario está en la captura biométrica o esta se está procesando
successful	Terminal. El intento pasó todas las verificaciones configuradas
failed	Terminal. El intento no pasó las verificaciones. Aquí se escribe el error_reason
canceled	Terminal. El intento se descartó sin resultado

El intento no tiene timed_out

El timeout vive en la solicitud. Cuando una solicitud caduca, sus intentos activos pasan a canceled, no a timed_out.

Un intento tampoco puede volverse successful si su solicitud ya caducó: una captura que termina después del timeout no revive el flujo.

El campo error_reason se escribe solo cuando el intento falla. En un intento successful, canceled, pending o in_progress viene vacío. Sus valores posibles son expiration_error, unknown_error, camera_permission_error, matcher_error y timeout_error. Para interpretar el detalle completo del fallo, revisa los códigos de error de validación.

Los 3 caminos al canceled

Un intento llega a canceled por tres vías, y las tres se ven idénticas mirando solo el intento:

1. Reintento: al crearse un intento nuevo, se cancelan los intentos activos anteriores de la misma solicitud
2. Recarga del widget: al inicializar la validación se cancelan los intentos activos. En modo handoff no se cancelan, para no pisar el intento que corre en el otro dispositivo
3. Timeout de la solicitud: cuando la solicitud pasa a timed_out, sus intentos activos se cancelan

Si necesitas distinguir el motivo, mira el estado de la solicitud: si está timed_out, la cancelación viene del timeout; si sigue viva, viene de un reintento o de una recarga del widget.

El puente intento → solicitud

Aquí está el punto que más confunde: el éxito de un intento mueve la solicitud, pero su fallo no la mueve por sí solo.

Un intento fallido no falla la solicitud por sí solo

Que un intento pase a failed no mueve la solicitud: sigue en el estado en que estaba y el usuario puede reintentar. Por eso un intento failed o con una señal de riesgo puede convivir con una solicitud viva, o incluso granted si un intento posterior fue exitoso. Si cuentas fallos de identidad usando intentos, vas a contar reintentos, no personas rechazadas.

La solicitud pasa a failed por causas propias, que en algunos casos ocurren en el mismo momento en que el intento falla:

• Match de datos que no cuadra, cuando los datos verificados no coinciden con los que enviaste. Ocurre contra el documento recién escaneado o contra los datos ya almacenados si la identidad se reutiliza. Revisa el match de datos
• Rechazo por riesgo, cuando el control de riesgo de la plantilla decide terminar el flujo

En el match contra el documento recién escaneado y en el rechazo por riesgo, el intento también queda failed. En cambio, cuando no coinciden los datos de una identidad reutilizada, la solicitud falla directamente y no se genera un intento de validación fallido. La diferencia está en la dirección: es la solicitud la que falla por su propia regla, no el intento el que la arrastra.

Para medir resultados de negocio, usa el estado de la solicitud. Para diagnosticar por qué un usuario tuvo fricción, usa los intentos.

El chequeo gubernamental corre dentro del mismo intento

Cuando la plantilla tiene habilitada la verificación gubernamental, esta se encadena dentro del mismo intento, después de la verificación biométrica. No se crea una solicitud ni un intento aparte: el intento se mantiene en in_progress hasta que el registro civil responde, y solo entonces pasa a successful o failed.

No confundas esto con el government check request (govcheck_...), que sí es un flujo separado y API-only para consultar el registro civil sin widget ni biometría. Revisa la verificación gubernamental vía API.

Cómo consultar cada uno

Vía API:

• Obtén un disclosure request para el estado real del flujo
• Lista los validation attempts para ver los intentos de una solicitud

Vía webhooks:

• disclosure_request.granted, disclosure_request.failed y disclosure_request.timed_out para resultados del flujo
• validation_attempt.successful y validation_attempt.failed para el detalle de cada intento

Suscríbete con el wildcard disclosure_request.* si quieres todos los eventos del recurso y decidir en tu backend cuáles procesar.