Consultar estado (polling)

Consulta el estado de una transacción de validación hasta obtener un estado terminal. Mientras la transacción no ha finalizado, la respuesta contiene únicamente el identificador y el estado. Al alcanzar un estado terminal con diagnóstico, incluye además la respuesta de resultado completa.

Endpoint

GET /document/validate/{transactionId}

Headers

Nombre	Tipo	Requerido	Descripción
Authorization	string	Sí	Token de consumer en formato Bearer <token> (ver Autenticación).
consumer-id	string	Sí	Identificador del consumer.
operation-id	string	Sí	Identificador de la operación de la validación, el mismo que se envió al iniciarla.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
transactionId	string	Sí	Identificador de transacción devuelto por POST /document/validate.

Respuestas

200 Éxito (transacción en curso)

{
  "transactionId": "1c7d...e9",
  "status": "IN_PROGRESS"
}

200 Éxito (transacción terminal)

Cuando la transacción alcanza un estado terminal con diagnóstico (COMPLETED), la respuesta incluye además el diagnóstico completo. Ver Respuesta de resultado.

Estados de la transacción

Estado	Significado	¿Terminal?
PROCESSED	La transacción fue creada y aceptada para procesamiento.	No
ERROR	No se pudo crear/iniciar la transacción (fallo en la solicitud inicial).	Sí
IN_PROGRESS	La validación está en curso.	No
COMPLETED	Hay un diagnóstico disponible (APPROVED, DECLINED o DOUBTFUL).	Sí
FAILED	Fallo irrecuperable durante el procesamiento. Incluye failureReason.	Sí

El estado terminal COMPLETED es único para cualquier resultado con diagnóstico. Ante ERROR o FAILED, no habrá diagnostic ni ocr en la respuesta. El estado FAILED sí incluye failureReason y timestamp.

failureReason

Cuando status = FAILED, el campo failureReason describe la causa del fallo con un mensaje genérico y estable. Estos son los valores posibles:

failureReason	Significado / acción recomendada
Validation could not be completed	Fallo transitorio del procesamiento. Es seguro reintentar iniciando una nueva transacción con los mismos assets; si persiste, contactar con soporte.
Internal processing error	Error inesperado durante el procesamiento. Reintentar más tarde; si persiste, contactar con soporte.
Asset not found in storage: <fileKey>	No se pudo resolver uno de los assets referenciados. Verificar que las fileKeys existen y se subieron correctamente antes de reintentar.
Invalid <front|back|face> asset token	El asset indicado no es un token de captura válido. Volver a capturar/subir ese asset y reiniciar el proceso.

failureReason es deliberadamente genérico: distintas causas internas (incluidos los timeouts del análisis) se agregan en Validation could not be completed. El detalle concreto queda en los registros internos del servicio; si necesitas diagnosticar un caso, compárte­lo con soporte junto al transactionId.

Otras respuestas

Código	Descripción
400	La cabecera operation-id está ausente o vacía.
401	Token ausente, inválido o caducado.
403	El consumer no está aprovisionado con el servicio DOCUMENT_ANTIFRAUD.
404	La transacción no existe o pertenece a otro consumer.
429	El consumer ha superado su límite de tasa de peticiones. La respuesta incluye Retry-After con los segundos de espera, y X-RateLimit-Limit y X-RateLimit-Burst con los umbrales vigentes.
503	La persistencia del servicio no está disponible temporalmente.

El cuerpo de una respuesta de error tiene la forma descrita en Middleware API v2.

El 429 de este endpoint es el del límite de tasa, y conviene tenerlo en cuenta al elegir la cadencia de sondeo: sondear cada pocos milisegundos lo provoca. La estrategia recomendada, por fases y con backoff, está en Buenas prácticas.