> 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/daf/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`, `rejectionReason`/`diagnostics[]` para informar al usuario final.
* `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/daf/consultar-estado.md)). Para el resto de valores de `failureReason`, consultar su tabla en [Consultar estado](/api-rest/midapi-v2/daf/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 un `operation-id` consistente entre la subida de assets y el inicio de validación, de forma que las `fileKeys` sean resolubles.
* 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 /v2/daf/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.