Idempotencia
Cómo repetir una petición sin emitir dos veces el mismo documento.
Una red falla en el peor momento: tu sistema envía una factura, la conexión se corta y no sabes si Cetus la
recibió. Si la envías de nuevo, ¿quedan dos facturas? No, si usas la misma Idempotency-Key.
Toda creación de documentos (POST /v1/invoices, /v1/credit-notes y /v1/debit-notes) exige el
encabezado Idempotency-Key: un texto de hasta 100 caracteres que eliges tú y que identifica esa
emisión.
curl https://cetus-api.cantte.com/v1/invoices \
-H "Authorization: Bearer $CETUS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1001" \
-d @factura.jsonQué pasa al repetir
| Caso | Respuesta |
|---|---|
| Primera vez con esa llave | 202 con el documento nuevo. |
| Misma llave y mismo cuerpo | 202 con el mismo documento, y el encabezado Idempotent-Replayed: true. No se emite otro. |
| Misma llave y otro cuerpo | 422 idempotency_mismatch: esa llave ya se usó para otro documento. |
| Misma llave mientras la primera petición sigue en curso | 409 idempotency_in_progress: reintenta en unos segundos. |
Si una petición falla por validación (400 o 422), la llave no queda usada: corrige y reintenta con la
misma.
Cómo elegir la llave
- Usa algo que ya identifique la venta en tu sistema: el número del pedido, de la orden o de la transacción
(
pedido-1001). Así, un reintento después de reiniciar tu servidor usa la misma llave. - Si no tienes un identificador así, genera un UUID antes del primer intento y guárdalo con la venta.
- Una llave nueva en cada intento anula la protección: dos intentos serían dos facturas.
Cada llave vale por cuenta y por ambiente, y se recuerda al menos 24 horas. Una misma llave en simulación y en producción son dos llaves distintas.