Una cabecera que evita dos facturas por el mismo pedido

El problema, contado como pasa de verdad

Tu tienda recibe el pedido 1042. Tu código llama a Cairos para crear la factura y emitirla. Y entonces se cae la red.

Fíjate en lo que sabes y en lo que no. Sabes que mandaste la petición. No sabes si llegó. No sabes si se procesó. Lo único que tienes es un tiempo de espera agotado, que es exactamente la misma respuesta tanto si la factura se creó como si no.

Y aquí es donde empieza el problema de verdad, porque la reacción natural es reintentar. Si la primera llamada sí había llegado, ahora tienes dos facturas, con dos números correlativos, por el mismo pedido.

Por qué eso no se arregla borrando

En casi cualquier otra API, dos registros duplicados se borran y no ha pasado nada. En una serie de facturación, no.

Los números de una serie son correlativos y sin huecos: es lo que exige el reglamento de facturación y lo que comprueba cualquiera que mire tus libros. Si has emitido la F27/0042 y la F27/0043 por el mismo pedido y borras la segunda, no te queda una serie limpia: te queda una serie con un hueco, y un hueco en una numeración correlativa es exactamente la señal que busca una inspección.

Lo que hay que hacer entonces es lo correcto, y es trabajo: emitir una factura rectificativa que anule la duplicada, dejando constancia de por qué. Con VeriFactu hay además un registro de anulación encadenado, porque la norma no permite que una factura desaparezca sin dejar rastro.

Cómo se usa: una cabecera y nada más

En cualquier llamada que cree algo, añade Idempotency-Key con un valor tuyo:

curl -X POST https://erp.cairos.es/api/v1/facturas \
  -H "Authorization: Bearer $CAIROS_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{ "contacto_id": "con_7Qb3xK", "serie": "F27" }'

// La llave sale del pedido, no de un aleatorio: tiene que ser
// la misma en el intento y en el reintento.
const llave = "pedido-" + pedido.id;

const r = await fetch(BASE + "/facturas", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + CLAVE,
    "Content-Type": "application/json",
    "Idempotency-Key": llave,
  },
  body: JSON.stringify(cuerpo),
});

<?php
$llave = "pedido-" . $pedido->get_id();

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $clave,
    "Content-Type: application/json",
    "Idempotency-Key: " . $llave,
]);

Lo que hace el servidor con eso:

• Si es la primera vez que ve esa llave, hace el trabajo y guarda la respuesta.
• Si ya la había visto con el mismo cuerpo, no repite nada: devuelve la respuesta guardada, con el mismo identificador y el mismo número de factura.
• Si ya la había visto con un cuerpo distinto, devuelve 409 conflicto. Eso no es un fastidio: es la API avisándote de que estás reutilizando una llave para dos cosas diferentes, que es un fallo de tu lado.

Qué llave poner, que es lo único que hay que pensar

La regla es una sola y todo lo demás se deduce de ella: la llave tiene que ser la misma en el intento y en el reintento, y distinta para dos operaciones distintas.

Si tienes que guardar la llave en algún sitio para poder reintentar, elige otra: la buena es la que se calcula a partir de algo que ya tienes.

Un UUID aleatorio sí vale, pero sólo si lo generas una vez y lo guardas junto al pedido antes de llamar, y lo reutilizas en los reintentos. Que es más trabajo que usar el identificador del pedido y no da nada a cambio.

Cuánto dura una llave

Las llaves se recuerdan durante veinticuatro horas. Pasado ese plazo, la misma llave vuelve a considerarse nueva y crearía otra factura.

Es tiempo de sobra para lo que la cabecera resuelve —un corte de red, un reintento automático, un proceso que se reinicia—, y no es un mecanismo para no duplicar nunca. Si lo que necesitas es garantizar que un pedido de hace tres semanas no se vuelva a facturar, eso no lo arregla la idempotencia: lo arregla guardar en tu sistema el identificador de la factura que creaste y mirarlo antes de llamar. Las dos cosas se complementan y hacen falta las dos.

Dónde vale y dónde no hace falta

Mándala en todo lo que cree algo: POST /contactos, POST /productos, POST /facturas, POST /facturas/{id}/emitir, POST /gastos y POST /cobros. Emitir y registrar un cobro son las dos donde más duele el duplicado.

No hace falta en las lecturas. Un GET se puede repetir cien veces sin consecuencias; ésa es la definición de idempotente y por eso no lleva cabecera.

Y en un PATCH tampoco es necesaria, porque mandar dos veces el mismo cambio deja el recurso igual. Puedes mandarla si te simplifica el código, y no estorba.

La forma corta de acordarse: si la operación consume un número de serie o mueve dinero, lleva llave.