Unha cabeceira que evita dúas facturas polo mesmo pedido

O problema, contado como pasa de verdade

A túa tenda recibe o pedido 1042. O teu código chama a Cairos para crear a factura e emitila. E entón cae a rede.

Fíxate no que sabes e no que non. Sabes que mandaches a petición. Non sabes se chegou. Non sabes se se procesou. O único que tes é un tempo de espera esgotado, que é exactamente a mesma resposta tanto se a factura se creou coma se non.

E aquí é onde empeza o problema de verdade, porque a reacción natural é reintentar. Se a primeira chamada si chegara, agora tes dúas facturas, con dous números correlativos, polo mesmo pedido.

Por que iso non se arranxa borrando

En case calquera outra API, dous rexistros duplicados bórranse e non pasou nada. Nunha serie de facturación, non.

Os números dunha serie son correlativos e sen ocos: é o que esixe o regulamento de facturación e o que comproba calquera que mire os teus libros. Se emitiches a F27/0042 e a F27/0043 polo mesmo pedido e borras a segunda, non che queda unha serie limpa: quédache unha serie cun oco, e un oco nunha numeración correlativa é exactamente o sinal que busca unha inspección.

O que hai que facer entón é o correcto, e é traballo: emitir unha factura rectificativa que anule a duplicada, deixando constancia de por que. Con VeriFactu hai ademais un rexistro de anulación encadeado, porque a norma non permite que unha factura desapareza sen deixar rastro.

Como se usa: unha cabeceira e nada máis

En calquera chamada que cree algo, engade Idempotency-Key cun valor teu:

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": "clx3k2p9y0000qz8h1a2b3c4d",
    "serie": "F27",
    "lineas": [ { "descripcion": "Pedido 1042",
                  "cantidad": 1, "precio": 360.00,
                  "tipo_iva": 21 } ]
  }'

// 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,
]);

O que fai o servidor con iso:

• Se é a primeira vez que ve esa chave, fai o traballo e garda a resposta.
• Se xa a vira co mesmo corpo, non repite nada: devolve a resposta gardada, co mesmo identificador e o mesmo número de factura.
• Se xa a vira cun corpo distinto, devolve 409 conflicto. Iso non é unha molestia: é a API avisándote de que estás reutilizando unha chave para dúas cousas diferentes, que é un fallo do teu lado.

Que chave poñer, que é o único que hai que pensar

A regra é unha soa e todo o demais dedúcese dela: a chave ten que ser a mesma no intento e no reintento, e distinta para dúas operacións distintas.

Se tes que gardar a chave nalgún sitio para poder reintentar, escolle outra: a boa é a que se calcula a partir de algo que xa tes.

Un UUID aleatorio si vale, pero só se o xeras unha vez e o gardas xunto ao pedido antes de chamar, e o reutilizas nos reintentos. Que é máis traballo ca usar o identificador do pedido e non dá nada a cambio.

Canto dura unha chave

As chaves lémbranse durante vinte e catro horas. Pasado ese prazo, a mesma chave volve considerarse nova e crearía outra factura.

É tempo de sobra para o que a cabeceira resolve —un corte de rede, un reintento automático, un proceso que se reinicia—, e non é un mecanismo para non duplicar nunca. Se o que necesitas é garantir que un pedido de hai tres semanas non se volva facturar, iso non o arranxa a idempotencia: arránxao gardar no teu sistema o identificador da factura que creaches e miralo antes de chamar. As dúas cousas compleméntanse e fan falta as dúas.

Onde vale e onde non fai falta

Mándaa en todo o que cree algo: POST /contactos, POST /productos, POST /facturas, POST /facturas/{id}/emitir, POST /gastos e POST /cobros. Emitir e rexistrar un cobro son as dúas onde máis doe o duplicado.

Non fai falta nas lecturas. Un GET pódese repetir cen veces sen consecuencias; esa é a definición de idempotente e por iso non leva cabeceira.

E nun PATCH tampouco é necesaria, porque mandar dúas veces o mesmo cambio deixa o recurso igual. Podes mandala se che simplifica o código, e non estorba.

A forma curta de se lembrar: se a operación consome un número de serie ou move diñeiro, leva chave.