Idempotency
An issuance has fiscal effect. If the network fails right after you send it, you don’t know whether
the document was issued. That’s why these routes accept the Idempotency-Key header:
POST /dtePOST /dte/{codigo}/retornoPOST /eventos/operaciones-especiales
curl https://app.openfactura.co/api/v1/dte \ -H "Authorization: Bearer $OPENFACTURA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-1042" \ -d @factura.json- The key is yours: a UUID or an identifier from your system (
pedido-1042), up to 200 characters. - Same key and same body → the original response, with the header
Idempotent-Replayed: true. Nothing is issued twice. - Same key and a different body →
409 idempotencia_distinta. - The first attempt is still in progress →
409 idempotencia_en_curso: wait a few seconds and retry. If it persists, the first attempt’s result couldn’t be confirmed (it may have been issued): check your documents before using another key. - Keys are kept for 24 hours and are independent per environment: a key used in test returns nothing in production.
- Successes,
dte_rechazado,emision_incierta, andevento_inciertoare stored as the final response. Errors where nothing reached the MH release the key so you can retry.
In the CLI and MCP
Section titled “In the CLI and MCP”- The CLI generates a UUID for every
dte emitirand prints it to stderr before sending. To retry:openfactura dte emitir factura.json --idempotency-key <the same one>. - The MCP tools
dte_emitir,dte_retorno, andoperaciones_especiales_informarrequire theidempotencyKeyargument.
For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.