Cancelación en loyalty
Una cancelación en el servicio de loyalty hace dos cosas en direcciones opuestas:
- El canje que se había debitado de un
rewardCardse acredita de vuelta en el mismo card (el cliente recupera su cashback). - La acumulación que se había acreditado en un
rewardCardse debita de ese card (el cashback generado por la compra cancelada se remueve).
Cada movimiento queda registrado en rewardCard_flow con uno de los cuatro tipos — reward, redemption, reward_cancel, redeem_cancel — de modo que el historial siempre es auditable.
Cuándo usar cada endpoint
| Endpoint | Cuándo usar |
|---|---|
POST /api/loyalty/transaction/cancel/{TID} |
Cancelar una transacción de loyalty, sin tocar el pedido. Revierte el canje y la acumulación. También es el camino para liberar una reserva de canje que nunca se convirtió en pedido (carrito abandonado, falla de pago): al no haber acumulación todavía, solo se devuelve la reserva. |
POST /api/loyalty/cancelOrderByTransaction/{TID} |
Toda la compra se está revirtiendo — la transacción de loyalty y el pedido se cancelan juntos. |
POST /api/loyalty/cancelPartial/{TID} |
Solo algunos ítems del pedido se están cancelando. El reembolso y la reversión de la acumulación se calculan proporcionalmente a los ítems cancelados. |
POST /api/loyalty/cards/{id}/cancel |
El objetivo es un card, no una compra: sale de circulación sin que nada se debite ni se devuelva. Vea la sección "Cancelar un card específico" más abajo. |
Las rutas de cancelación total (transaction/cancel, cancelOrderByTransaction) revierten toda la redención y acumulación de la transacción. cancelPartial opera por ítem — vea el endpoint de Cancelación parcial para las reglas exactas de identificación de ítems.
Cancelar un card específico
Los endpoints anteriores cancelan lo que generó una transacción. Cuando el objetivo es un card — un card de campaña otorgado por error, un card manual, un card que la operación necesita sacar de circulación —, la cancelación es por card:
POST /api/loyalty/cards/{id}/cancel— el card sale de toda consulta de saldo y se lee comocanceledPOST /api/loyalty/cards/{id}/reactivate— deshace la cancelación, sin tocar la vigencia
Para más de un card existe la versión en lote — hasta 100 por llamada, con dryRun y un desenlace por item: cancelar en lote y reactivar en lote. En un lote, un card ya cancelado, inexistente o con reserva abierta no tumba a los demás: cada id vuelve con su propio resultado.
La diferencia frente a los endpoints de transacción es la naturaleza de la operación:
- cancelar un card es un cambio de estado. El saldo no se debita ni se devuelve, el card completo sale de circulación con su
amountintacto y no entra ninguna línea enrewardCard_flow. El card no tiene columna de estado:canceledse deriva de la fecha de cancelación. - cancelar una transacción es un movimiento. La acumulación se debita, el canje se acredita de vuelta, y cada uno deja su línea en el ledger.
Consecuencia práctica en los reportes: el crédito original del card cancelado permanece en rewardCard_flow, así que una cifra sumada por el flow (crédito otorgado) sigue contando ese valor, mientras que el contador por card cuenta el card como canceled. Los dos no cuadran entre sí — es lo esperado, no un error.
Para sacar valor de un card que sigue vivo, use Ajustar saldo del card con manual_debit, que pasa por el ledger.
Un card con reserva de canje abierta se rechaza con 409: el valor reservado ya fue debitado y espera liquidación o devolución, así que cancelar el card lo dejaría atrapado. Resuelva la reserva primero.
Cancelación automática por el flujo del pedido
No siempre hay que llamar a un endpoint de cancelación explícitamente. Cuando un pedido se cancela por el flujo del pedido (por ejemplo, la plataforma de origen cancela la compra), el lado de loyalty se revierte automáticamente, con la misma lógica de arriba:
- Una transacción aún retenida en
waitSettlement(confirmada conwaitSettlement: true, todavía no liquidada) tiene su reserva liberada — el canje reservado se acredita de vuelta. Aún no se acreditó ninguna acumulación, así que no hay nada que debitar. - Una transacción que ya fue liquidada tiene su acumulación revertida y cualquier canje acreditado de vuelta, exactamente como lo haría
cancelOrderByTransaction.
Esto corre en cuanto el pedido llega al estado canceled, de modo que una transacción retenida nunca deja el saldo del cliente bloqueado después de revertir la compra. Los movimientos quedan en rewardCard_flow con los mismos tipos reward_cancel / redeem_cancel y siguen la misma regla de idempotencia de abajo — sin reversión doble si la transacción ya estaba cancelada.
Reembolso en card expirado
Cuando el canje se acredita de vuelta en un card que ya está expirado en el momento de la cancelación, el cliente recibiría un crédito que ya no podría usar. Para no atrapar el valor reembolsado, el loyalty extiende automáticamente el expiresAt del card para mañana a las 23:59:59.
La extensión se aplica solo cuando se cumplen las dos condiciones:
- El card está activo (
canceledAt IS NULL). - El card está efectivamente expirado (
expiresAt < NOW()) al momento de la cancelación.
Los cards aún dentro de la vigencia mantienen su expiresAt original — la regla nunca acorta ni extiende un card no expirado. Los cards cancelados manualmente o inactivos por otro motivo no se reactivan.
La extensión es por card y por cancelación: cada card que recibe reembolso se evalúa de forma independiente. Una cancelación parcial que divide el reembolso entre varios cards puede extender algunos y dejar otros intactos.
Idempotencia y estado
Una segunda llamada a cualquier endpoint de cancelación después de que la transacción ya está cancelada se rechaza con 409 Conflict — la transacción lleva un canceledAt que se verifica primero. Ningún movimiento se duplica.