Tezora

Idempotencia

POST /sales, POST /sales/batches y POST /sales/{uuid}/adjustment-notes exigen la cabecera Idempotency-Key, que admite cualquier valor de 1 a 128 caracteres ASCII visibles. Un reintento con la misma llave nunca factura dos veces.

Cada operación de negocio usa su propia llave: un UUID generado al armar la petición, guardado con ella y repetido en cada reintento. El número de pedido no sirve como llave, porque un pedido que se factura de nuevo con el cuerpo corregido es otra operación y la misma llave respondería 409 idempotency_key_reused.

Situación Respuesta
Primera petición 201 con la venta.
Misma llave y mismo cuerpo, ya terminada 200 con la misma venta y Idempotent-Replayed: true.
Misma llave y otro cuerpo 409 idempotency_key_reused.
Misma llave con la primera en curso 409 idempotency_request_in_progress con Retry-After: 2.
Sin cabecera o llave mal formada 400 idempotency_key_required.
La primera falló sin crear nada La llave se libera y admite el cuerpo corregido.

Las llaves son por credencial. Una llave de nota queda atada a la venta de la ruta. Una venta creada cuyo documento falló no es un caso de idempotencia: la venta existe y el documento se reintenta con POST /sales/{uuid}/document. GET /sales/by-idempotency-key/{llave} informa qué creó una petición interrumpida.

Referencia del pedido

reference protege contra un pedido reenviado con una llave nueva. Mientras exista una venta vigente con esa reference, otro POST /sales responde 409 sale_reference_exists con la venta existente y no emite nada (si esa venta es de otra sucursal que la de la llave, data es nulo y el mensaje nombra su sucursal); en un lote, la venta queda already_invoiced, o failed con error_code sale_reference_exists y sin sale si es de otra sucursal. La unicidad es por empresa.

Una invalidación con reemplazo (tipo 1 o 3) no libera la referencia: el pedido sigue facturado en la venta que corrige el documento. Otro POST /sales con esa reference responde 409 sale_reference_exists con el reemplazo en data (el último, si el reemplazo también se corrigió), con las mismas reglas de sucursal; en un lote, la venta queda already_invoiced sobre el reemplazo. Si el reemplazo no se hizo por la API, data trae la venta invalidada, cuyo invalidation.replacement lo nombra.

Solo una venta retirada sin nada en su lugar libera la referencia: anulada, o con su documento invalidado por rescisión (tipo 2). Entonces queda libre solo para POST /sales, que es la forma de facturar de nuevo el pedido. Un lote nunca la reutiliza: la venta del lote queda invalidated_before, con la venta invalidada y su invalidation en sale, y no se crea nada. Así, un archivo de cierre que se reenvía después de una devolución o de una corrección no vuelve a facturar el ticket.

La venta con esa reference POST /sales En un lote
Vigente 409 sale_reference_exists con la venta already_invoiced
Vigente, con su documento rechazado 409 sale_reference_exists con la venta; se corrige con POST /sales/{uuid}/document rejected, con su rejection
Invalidada con reemplazo (tipo 1 o 3) 409 sale_reference_exists con el reemplazo already_invoiced sobre el reemplazo
Invalidada por rescisión (tipo 2) o anulada 201: se factura de nuevo invalidated_before