Cómo evitar facturas duplicadas en integraciones (idempotencia explicada)

Es uno de los problemas más comunes en integraciones de facturación: tu sistema envía una factura, la conexión se corta antes de recibir la respuesta, tu código reintenta… y el cliente termina con dos facturas iguales.

Por qué pasa

Cuando una petición falla por la red, tu sistema no sabe si el servidor alcanzó a procesarla. Reintentar es lo correcto, pero sin protección puede crear el documento dos veces.

Qué es la idempotencia

Una operación es idempotente si repetirla tiene el mismo efecto que hacerla una sola vez. La forma estándar de lograrlo en una API es enviar una clave única por operación.

Cómo funciona en AZUR

Las escrituras de la API v2 aceptan la cabecera Idempotency-Key:

POST /plataforma/api/v2/factura
X-Api-Key: azur_live_...
Idempotency-Key: pedido-10482

Si repites la misma petición con la misma clave, AZUR devuelve el mismo resultado en lugar de crear otro comprobante. Mientras la primera se procesa, una segunda igual espera su turno.

Qué usar como clave

• El identificador de tu pedido o venta (por ejemplo, pedido-10482).
• Un UUID que generes y guardes junto a la operación.

Lo importante: la misma operación siempre con la misma clave, y operaciones distintas con claves distintas.

Los SDK lo hacen solos

El SDK de PHP (composer require azur/sdk) y el de JavaScript (npm install @azur.com.ec/sdk) agregan automáticamente una clave en cada escritura y la reutilizan en sus reintentos.

Otras defensas

• Guarda en tu sistema que el pedido ya fue facturado y con qué clave de acceso.
• Factura en una cola de trabajos, no dentro de la petición del usuario.
• Ante errores 429 (demasiadas peticiones), espera lo que indica Retry-After antes de reintentar.

Revisa qué operaciones aceptan la cabecera en la referencia de la API.

Integra sin duplicados: crea tu cuenta gratis.