Avoiding duplicate e-invoices: idempotency keys explained
A till sends an invoice and the connection drops before the answer arrives. Did it work? The safe reaction is to send it again, but without protection that can create two invoices for one sale. An idempotency key makes the retry safe.
The problem
Duplicate tax documents are hard to undo: an invoice reported to the NBR cannot simply be deleted. The cost of a duplicate is a credit note and an explanation.
How the key works
- The client generates a unique key for each sale, for example the till's own transaction number, and sends it in the Idempotency-Key header.
- The server stores the key with a fingerprint of the payload.
- A retry with the same key and the same payload returns the original result and creates nothing.
- The same key with a different payload is refused, because it signals a bug.
What makes a good key
- Stable: the same sale always produces the same key.
- Unique per sale, and not reused for another.
- Short enough to store (up to 190 characters here).
What about an unknown outcome
Sometimes the request reached the NBR but the answer was lost. Sending it blindly again could duplicate the report. Treat an uncertain outcome as a state in its own right: hold it, look it up with evidence, and only then decide.
Test it
Send the same payload twice with the same key and check that you get the same invoice back. Then send a changed payload with the same key and check that it is refused. A dry-run endpoint lets you rehearse without creating anything.