Estados e idempotencia

Estados de una operación

CREATED ─▶ DISPATCHED ─▶ CLAIMED ─▶ APPROVED
               │             │
               │             ├──▶ REJECTED
               │             ├──▶ FAILED
               │             ├──▶ REVERSED
               │             └──▶ CANCELLED
               └──▶ EXPIRED  (el POS no tomó la operación a tiempo)

Estado	Significado	¿Final?
`CREATED`	La operación quedó registrada, pero aún no se envía al POS.	No
`DISPATCHED`	La operación se envió al POS y espera que el equipo la tome.	No
`CLAIMED`	El POS tomó la operación y la está ejecutando.	No
`APPROVED`	La operación terminó con éxito. En `PRINT`, `SCAN_BARCODE` y `GET_SERIAL` indica que se imprimió, se leyó el código o se obtuvo el serial.	Sí
`REJECTED`	La operación terminó sin éxito, por ejemplo una tarjeta rechazada.	Sí
`REVERSED`	La transacción fue reversada.	Sí
`FAILED`	Error técnico: la operación no se pudo enviar al POS o el equipo no pudo ejecutarla.	Sí
`EXPIRED`	El POS no tomó la operación dentro de 10 segundos.	Sí
`CANCELLED`	La operación se canceló en el POS antes de completarse.	Sí

Recibirás un webhook cada vez que la operación cambie de estado, por ejemplo al pasar a CLAIMED y luego a APPROVED. Toma decisiones de negocio (entregar el producto, cerrar la venta) solo con un estado final.

Idempotencia con `externalPaymentId`

externalPaymentId es el identificador de la operación en tu sistema: el ID de tu orden, reserva, impresión o lectura. Virtualpos lo usa para que una misma operación no se ejecute dos veces aunque repitas la solicitud, por ejemplo tras un timeout de red.

Si envías un `externalPaymentId`…	Respuesta
Nuevo	`201 Created` con la operación recién creada
Ya usado en una operación `APPROVED`	`200 OK` con la operación existente. No se vuelve a cobrar.
Ya usado en una operación no aprobada	`200 OK`. Si el intento anterior sigue en curso, se mantiene; si terminó sin éxito, la operación se envía de nuevo al POS como un nuevo intento (`attemptNumber` aumenta).

La regla aplica por comercio: dos API keys de tu mismo comercio comparten los mismos externalPaymentId.