Skip to main content
Una red inestable puede cortar la respuesta aunque el documento ya se haya creado. Para que puedas reintentar sin riesgo, POST /api/v1/integration/documents exige el header Idempotency-Key.
Los demás endpoints no lo usan.

​
Elige la clave

  • Usa un valor único por documento, como el folio o el identificador del documento en tu sistema.
  • Debe tener de 1 a 255 caracteres ASCII visibles.
  • La clave es única por API key: dos llaves distintas pueden usar el mismo valor sin chocar.
  • Genérala una vez y guárdala junto al documento antes de la primera llamada, para reenviar exactamente la misma en cada reintento.

​
Qué pasa al repetir una petición

La API compara la clave y el contenido de la petición: el PDF y el texto exacto del campo payload.
El payload se compara como texto. Si al reintentar lo serializas de nuevo con otro orden de campos u otros espacios, cuenta como otro contenido y la API responde INTEGRATION_IDEMPOTENCY_KEY_MISMATCH. Guarda el texto que enviaste y reenvía ese mismo.

​
Cuánto dura una clave

  • Una clave completada se conserva 24 horas. En ese plazo, cualquier reintento devuelve el documento original.
  • Pasadas las 24 horas, la clave se libera y una petición con ella crea un documento nuevo.
  • Si la creación falla (por ejemplo, por falta de créditos o un error de validación), la clave se libera de inmediato: corrige la causa y reintenta con la misma clave.

​
Estrategia de reintento recomendada

1

Reintenta los fallos de red y los 5xx

Repite la misma petición, con la misma clave y el mismo contenido, con espera creciente entre intentos.
2

Trata el 409 en curso como transitorio

INTEGRATION_IDEMPOTENCY_KEY_IN_PROGRESS significa que la primera petición sigue procesándose. Espera y repite.
3

No reintentes los 4xx de contenido

Un 400, 402 o 422 no se resuelve repitiendo. Corrige la petición o adquiere créditos; después puedes usar la misma clave.
Todos los códigos de error están en Errores.