> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/midapi-v2/document-services/document-validation/buenas-practicas.md).

# Buenas prácticas

### Estrategia de polling

Consultar el estado mediante sondeo por fases, ya que el tiempo de resolución puede variar significativamente entre transacciones:

* **Fase 1 (sondeo rápido, primeros \~10 segundos)**: sondear cada 1 segundo. Cubre el caso habitual, en el que la transacción resuelve rápidamente.
* **Fase 2 (backoff exponencial, a partir de \~10 segundos si aún no hay estado terminal)**: aumentar el intervalo progresivamente (p. ej. 2s → 4s → 8s → 15s), con un tope de entre 15 y 20 segundos entre sondeos. Cubre los casos que requieren un análisis adicional y pueden tardar sustancialmente más.
* Definir un tiempo máximo de espera en el lado del consumer (p. ej. varios minutos). Si se supera, tratar el caso como indeterminado y reintentar más tarde o contactar con soporte.
* No asumir un tiempo de respuesta fijo: la duración puede variar sustancialmente entre transacciones, ya que algunas requieren un análisis adicional interno antes de resolver.

### Manejo de estados

* `COMPLETED`: leer `diagnostic` y, si es `DECLINED` o `DOUBTFUL`, `rejectionReason`/`diagnostics[]` para informar al usuario final. Un `DOUBTFUL` no es un rechazo: el análisis no fue concluyente y la decisión queda de tu lado (ver [Modalidades del servicio](/api-rest/midapi-v2/document-services/document-validation.md#modalidades-del-servicio)).
* `ERROR` / `FAILED`: tratar como error de integración o del servicio. Revisar los datos enviados y reintentar si procede.
* `FAILED` con `failureReason = Validation could not be completed`: fallo transitorio del procesamiento (incluye timeouts internos del análisis). Es seguro reintentar iniciando una nueva transacción con los mismos assets (ver [Consultar estado](/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md)). Para el resto de valores de `failureReason`, consultar su tabla en [Consultar estado](/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md#failurereason).

### Seguridad

* No almacenar el token OAuth2 en cliente. Renovarlo según su expiración (ver [Autenticación](/api-rest/midapi-v2/autenticacion.md)).
* Usar el mismo `operationId` en la subida de assets y en la cabecera `operation-id` del inicio de validación: todas las `fileKeys` de una petición deben pertenecer a esa misma operación.
* Crear la operación **cuando arranca la captura**, no antes: caduca a los 15 minutos por defecto, y una operación caducada obliga a crear otra y volver a subir los assets.
* Reenviar cada `fileKey` tal como la devolvió `POST /storage`, sin componerla ni interpretarla. Si necesitas recuperarlas, usa [Get File Keys](/api-rest/midapi-v2/operations/get-file-keys.md).
* Tratar `transactionId` como un identificador opaco. No inferir información de su formato.

### Trazabilidad para soporte

Para investigar un caso concreto con soporte, conserva y aporta los siguientes identificadores:

* **`transactionId`**: identificador principal de la transacción (devuelto por `POST /document/validate` y en cada consulta de estado). Es el dato clave para localizar un caso.
* **Cabecera de respuesta `X-Trace-Id`**: identificador de la petición que devuelve la API en cada respuesta; permite a soporte correlacionar la llamada exacta. Recomendado guardarlo junto al `transactionId`.
* **`timestamp`** de la transacción (formato ISO-8601) y los identificadores que tú aportas en las cabeceras: `operation-id` y `consumer-id`.

Al abrir una incidencia, incluye siempre el `transactionId` (y el `X-Trace-Id` si lo tienes registrado). Consulta con Facephi los plazos de retención aplicables a tu integración.