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.1Authorization: Bearer sk_live_...Idempotency-Key: pos-0042-20261113-000187Content-Type: application/jsonComportamiento
Sección titulada «Comportamiento»| 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 responde422 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.
Cómo construir la clave
Sección titulada «Cómo construir la clave»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_8f3a2cNo uses un valor aleatorio nuevo en cada reintento: eso anula la protección.