Idempotencia

Reintenta peticiones de timbrado sin miedo a duplicar facturas.

El problema

Imagina: tu punto de venta manda a timbrar una factura, pero la conexion a internet se cae justo despues de enviar la peticion. No sabes si el timbrado fue exitoso o no. Si reintentas, podrias generar (y pagar) una factura duplicada.

La solucion

Incluye un header Idempotency-Key con un identificador unico por operacion. Si FiscaFacil recibe dos peticiones con la misma key, la segunda devuelve el resultado de la primera sin ejecutar la operacion de nuevo.

POST /v1/facturas
Authorization: Bearer ff_live_...
Idempotency-Key: venta-pos-42-2026-03-21
Content-Type: application/json

{
  "tipoComprobante": "I",
  "conceptos": [...]
}

# Primera vez → 201 Created (factura timbrada)
# Segunda vez → 200 OK (misma respuesta, sin timbrar de nuevo)
# Tercera vez → 200 OK (idem)

Reglas

• Las keys deben ser unicas por operacion logica (ej: venta-123, nomina-periodo-5)
• Las keys expiran despues de 24 horas
• Solo aplica a peticiones POST (GET, PATCH, DELETE son naturalmente idempotentes)
• Si el body cambia con la misma key, se retorna un error 409 Conflict

Ejemplo con SDK

// El SDK genera la key automaticamente si no la provees
const factura = await client.facturas.crear(data, {
  idempotencyKey: "venta-pos-42"
})

// Reintentar es seguro
const mismaFactura = await client.facturas.crear(data, {
  idempotencyKey: "venta-pos-42"
})

factura.uuid === mismaFactura.uuid // true

Recomendaciones

• Usa UUIDs v4 o identificadores de negocio significativos
• Almacena la key junto con el evento que la genero en tu sistema
• Implementa reintentos con backoff exponencial en tu cliente