Idempotencia
Una factura emitida dos veces es un problema fiscal, no un bug menor. Por eso los endpoints que crean (
POST /invoices
,
POST /purchases
) aceptan
external_ref
: tu identificador de la operación, y la garantía de que se ejecuta una sola vez.
Cómo funciona#
-
La referencia se reclama antes de tocar el motor. La primera llamada emite y responde
201; cualquier repetición responde200con el mismo comprobante ya emitido. -
Si la repetición llega mientras la primera aún corre, la respuesta es
409 in_progress— nunca una segunda emisión. Reintenta en unos segundos. -
Si la operación falla, la referencia se libera: el mismo
external_refpuede reintentarse hasta lograrlo. -
Las referencias comparten un espacio por libro entre facturas y compras:
"orden-1042"nombra UNA operación, del tipo que sea. - Hasta 255 caracteres. Usa el id natural de tu sistema (orden, asiento, pedido).
Recomendación#
Envía
external_ref
en toda integración productiva y reintenta con la misma referencia ante timeouts o errores de red. Sin referencia, cada
POST
emite un comprobante nuevo.
POST /api/v1/invoices {"external_ref": "orden-1042", …}
→ 201 · se emite el comprobante
POST /api/v1/invoices {"external_ref": "orden-1042", …}
→ 200 · el MISMO comprobante, sin emitir de nuevo
POST /api/v1/invoices {"external_ref": "orden-1042", …} (aún en curso)
→ 409 · {"error": {"code": "in_progress"}}