Idempotency

Every AdapterDian POST that issues a tax document requires an Idempotency-Key, so a retry never consumes a second DIAN number.

A number from a DIAN-authorized range can’t be given back: once it’s used, the only correction is another tax document. A timeout followed by a naive retry would issue the same invoice twice. Idempotency-Key prevents that.

Which requests need it

It’s required on every POST that produces a document:

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

It must be at least 8 characters long. A UUID works well.

How it behaves

You send	You get
A new key	`202 Accepted`, `"deduplicated": false`. The document is queued.
The same key and the same body	`202 Accepted` with the original document and `"deduplicated": true`. Nothing is issued again.
The same key with a different body	`409` with `code: IDEMPOTENCY_CONFLICT`.

The guard lives in the database, not in memory, so it holds even when the retry reaches another instance.

Generate the key once, not per attempt

Create the key when the business operation is born (for example, when the order is closed) and store it next to it. If you generate a new key on each retry, the adapter can’t recognize the retry and will issue again.

Fixing a request that failed validation

If the document was rejected by validation (422), fix the body and send it with a new key: the old key is tied to the old body.