Entrar
.md

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 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:

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 e reativar em lote. 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 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