Idempotencia

Todo POST de AdapterDian que emite un documento fiscal exige Idempotency-Key, para que un reintento nunca consuma un segundo número DIAN.

Un número del rango autorizado por la DIAN no se puede devolver: una vez usado, la única corrección es otro documento fiscal. Un timeout seguido de un reintento ingenuo emitiría la misma factura dos veces. Idempotency-Key lo evita.

Qué peticiones la exigen

Es obligatoria en todo POST que produce un documento:

/invoices/v1/sales-invoices, /credit-notes, /debit-notes, /support-documents, /adjustment-notes
/payrolls/v1/payrolls, /adjustment-payrolls

Debe tener al menos 8 caracteres. Un UUID funciona bien.

Cómo se comporta

Envías	Recibes
Una clave nueva	`202 Accepted`, `"deduplicated": false`. El documento se encola.
La misma clave y el mismo cuerpo	`202 Accepted` con el documento original y `"deduplicated": true`. No se emite nada otra vez.
La misma clave con otro cuerpo	`409` con `code: IDEMPOTENCY_CONFLICT`.

La barrera vive en la base de datos, no en memoria, así que se sostiene aunque el reintento llegue a otra instancia.

Genera la clave una vez, no en cada intento

Crea la clave cuando nace la operación de negocio (por ejemplo, al cerrar el pedido) y guárdala junto a ella. Si generas una clave nueva en cada reintento, el adaptador no puede reconocerlo y volverá a emitir.

Corregir una petición que no pasó la validación

Si el documento se rechazó en la validación (422), corrige el cuerpo y envíalo con una clave nueva: la clave anterior quedó atada al cuerpo anterior.