Skip to content

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 /dte
  • POST /dte/{codigo}/retorno
  • POST /eventos/operaciones-especiales
Ventana de terminal
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, and evento_incierto are stored as the final response. Errors where nothing reached the MH release the key so you can retry.
  • The CLI generates a UUID for every dte emitir and 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, and operaciones_especiales_informar require the idempotencyKey argument.

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.