Ir al contenido

Idempotencia

Una red inestable puede cortar la respuesta de una emisión que sí se registró. Si tu POS reintenta sin protección, emite el mismo ticket dos veces y consume dos correlativos. La cabecera Idempotency-Key lo evita.

POST /v1/receipts HTTP/1.1
Authorization: Bearer sk_live_...
Idempotency-Key: pos-0042-20261113-000187
Content-Type: application/json
Situación Respuesta
Primera vez que usas la clave 201 Created: el comprobante nuevo.
Misma clave y mismo cuerpo 200 OK con cabecera Idempotent-Replayed: true: el mismo comprobante, sin emitir otro ni consumir otro número.
Misma clave y otro cuerpo 409 Conflict con {"reason":"IdempotencyKeyReused"}.
Dos peticiones simultáneas con la misma clave Solo una emite; la otra recibe el mismo comprobante.
  • De 1 a 100 caracteres: letras, números, _, -, . y :. Otro formato responde 422 InvalidIdempotencyKey.
  • La clave es única por emisor y por entorno; no caduca.
  • «Mismo cuerpo» significa el mismo JSON, sin importar el orden de las claves de los objetos.
  • La cabecera es opcional, pero muy recomendada en todo sistema que reintente.

Usa algo que identifique la venta en tu sistema y que no cambie entre reintentos:

<caja>-<fecha>-<número de venta interno> → pos-0042-20261113-000187
<id de pedido> → order_8f3a2c

No uses un valor aleatorio nuevo en cada reintento: eso anula la protección.