Idempotency
Why invoice creation requires an idempotency key, and how to choose one.
Creating an invoice or a credit/debit note requires an idempotency-key header.
Without it the request is rejected with 400.
-H "idempotency-key: 9f8c1e40-3b7a-4a2f-8c1d-7e2b5a904f11"Why it is mandatory
An invoice registered with FIRS is a tax document. A retry that creates a second one — after a timeout, a dropped connection, or a queue redelivering a job — is not a harmless duplicate; it is a second filing that then has to be cancelled and explained. Requiring the key means we can tell a retry from a new invoice, and you cannot accidentally opt out.
Choosing a key
Use something derived from the invoice in your system — its primary key, or your own invoice number:
idempotency-key: order-88213-invoiceA UUID generated per invoice works too, as long as you generate it once and store it, so a retry sends the same one. A UUID generated per attempt defeats the purpose entirely.
Do not use a timestamp or a value generated per attempt — both change on retry, which defeats the whole mechanism.
What happens on a repeat
Sending the same key twice is not an error. The original invoice is returned with a
200, and no second one is created. So a safe retry loop is simply: send it again with
the same key.
The body is ignored on a replay. We match on the key alone and never compare what you sent. So if you correct a mistake and resend with the same key, the correction is silently discarded and the original, uncorrected invoice comes back.
To send a corrected invoice, use a new idempotency key — or amend the invoice you already created.
Keys are scoped to your business, so there is no chance of colliding with another customer's.