---
title: 'Cancelamento no loyalty'
description: 'Como o serviço de loyalty reverte o resgate e o acúmulo quando um pedido ou uma reserva de resgate é cancelado.'
---

# Cancelamento no loyalty

Um cancelamento no serviço de loyalty faz duas coisas em direções opostas:

- O **resgate** que tinha sido debitado de um `rewardCard` é **creditado de volta** no mesmo card (o cliente recupera o cashback).
- O **acúmulo** que tinha sido creditado num `rewardCard` é **debitado** desse card (o cashback gerado pela compra cancelada é removido).

Todo movimento entra na `rewardCard_flow` com um dos quatro tipos — `reward`, `redemption`, `reward_cancel`, `redeem_cancel` — então o histórico sempre fica auditável.

## Quando usar cada endpoint

| Endpoint | Quando usar |
|---|---|
| `POST /api/loyalty/transaction/cancel/{TID}` | Cancela uma transação de loyalty, sem mexer no pedido. Reverte o resgate e o acúmulo. Também é o caminho para soltar uma reserva de resgate que nunca virou pedido (carrinho abandonado, falha no pagamento): não havendo acúmulo ainda, só a reserva é devolvida. |
| `POST /api/loyalty/cancelOrderByTransaction/{TID}` | A compra inteira está sendo revertida — a transação de loyalty e o pedido são cancelados juntos. |
| `POST /api/loyalty/cancelPartial/{TID}` | Só alguns itens do pedido estão sendo cancelados. O estorno e a reversão do acúmulo são calculados proporcionalmente aos itens cancelados. |
| `POST /api/loyalty/cards/{id}/cancel` | O alvo é um **card**, não uma compra: ele sai de circulação sem que nada seja debitado ou devolvido. Ver a seção "Cancelar um card específico" abaixo. |

Os caminhos de cancelamento total (`transaction/cancel`, `cancelOrderByTransaction`) revertem **todo** o resgate e o acúmulo da transação. O `cancelPartial` opera item a item — veja o endpoint de [Cancelamento parcial](/docs/{lang}/api-reference/loyalty/checkout/partial-cancellation) para as regras exatas de identificação dos itens.

## Cancelar um card específico

Os endpoints acima cancelam o que uma **transação** gerou. Quando o alvo é um card — um card de campanha concedido por engano, um card manual, um card que a operação precisa tirar de circulação —, o cancelamento é por card:

- [`POST /api/loyalty/cards/{id}/cancel`](/docs/{lang}/api-reference/loyalty/card/cancel) — o card sai de toda consulta de saldo e passa a ser lido como `canceled`
- [`POST /api/loyalty/cards/{id}/reactivate`](/docs/{lang}/api-reference/loyalty/card/reactivate) — desfaz o cancelamento, sem mexer na validade

Para mais de um card, existe a versão em lote — até 100 por chamada, com `dryRun` e um desfecho por item: [cancelar em lote](/docs/{lang}/api-reference/loyalty/card/cancel-batch) e [reativar em lote](/docs/{lang}/api-reference/loyalty/card/reactivate-batch). Num lote, card já cancelado, inexistente ou com reserva aberta **não** derruba os outros: cada id volta com o seu resultado.

A diferença em relação aos endpoints de transação é a **natureza** da operação:

- cancelar card é mudança de **estado**. O saldo não é debitado nem devolvido, o card inteiro sai de circulação com o `amount` intacto e **nenhuma linha entra na `rewardCard_flow`**. O card não tem coluna de status: `canceled` é derivado da data de cancelamento.
- cancelar transação é **movimento**. O acúmulo é debitado, o resgate é creditado de volta, e cada um deixa sua linha no ledger.

Consequência prática em relatório: o crédito original do card cancelado continua na `rewardCard_flow`, então número que soma pelo flow (crédito concedido) segue contando esse valor, enquanto o contador por card conta o card como `canceled`. Os dois não fecham entre si — é esperado, não é erro.

Para tirar valor de um card que **continua vivo**, o caminho é [Ajustar saldo do card](/docs/{lang}/api-reference/loyalty/card/adjust) com `manual_debit`, que passa pelo ledger.

Card com **reserva de resgate aberta** é recusado com `409`: o valor reservado já foi debitado e espera liquidação ou devolução, então cancelar o card deixaria esse valor preso. Resolva a reserva primeiro.

## Cancelamento automático pelo fluxo do pedido

Nem sempre é preciso chamar um endpoint de cancelamento explicitamente. Quando um pedido é cancelado pelo fluxo do pedido (por exemplo, a plataforma de origem cancela a compra), o lado do loyalty é revertido automaticamente, com a mesma lógica acima:

- Uma transação ainda retida em `waitSettlement` (confirmada com `waitSettlement: true`, ainda não liquidada) tem a **reserva liberada** — o resgate reservado é creditado de volta. Nenhum acúmulo foi creditado ainda, então não há o que debitar.
- Uma transação que já foi liquidada tem o **acúmulo revertido** e qualquer resgate creditado de volta, exatamente como o `cancelOrderByTransaction` faria.

Isso roda assim que o pedido chega ao estado `canceled`, então uma transação retida nunca fica com o saldo do cliente preso depois que a compra é revertida. Os movimentos entram na `rewardCard_flow` com os mesmos tipos `reward_cancel` / `redeem_cancel` e seguem a mesma regra de idempotência abaixo — sem reversão dupla se a transação já estava cancelada.

## Estorno em card expirado

Quando o resgate é creditado de volta num card que **já está expirado** no momento do cancelamento, o cliente receberia um crédito que não conseguiria mais usar. Para não prender o valor estornado, o loyalty estende automaticamente o `expiresAt` do card para **amanhã às 23:59:59**.

A extensão é aplicada **só** quando as duas condições são verdadeiras:

- O card está **ativo** (`canceledAt IS NULL`).
- O card está **realmente expirado** (`expiresAt < NOW()`) no momento do cancelamento.

Cards ainda dentro da validade mantêm o `expiresAt` original — a regra nunca encurta nem estende um card não-expirado. Cards cancelados manualmente ou inativos por outro motivo não são reativados.

A extensão é **por card e por cancelamento**: cada card que recebe estorno é avaliado de forma independente. Um cancelamento parcial que divide o estorno entre vários cards pode estender alguns e deixar outros intactos.

## Idempotência e status

Uma segunda chamada em qualquer endpoint de cancelamento depois que a transação já está cancelada retorna `409 Conflict` — a transação carrega um `canceledAt` que é verificado antes. Nenhum movimento é duplicado.

## Veja também

- [Cancelar uma transação](/docs/{lang}/api-reference/loyalty/transaction/cancel)
- [Cancelar transação e pedido](/docs/{lang}/api-reference/loyalty/checkout/cancel-transaction-and-order)
- [Cancelamento parcial](/docs/{lang}/api-reference/loyalty/checkout/partial-cancellation)
- [Cancelar card](/docs/{lang}/api-reference/loyalty/card/cancel)
- [Reativar card](/docs/{lang}/api-reference/loyalty/card/reactivate)
