Checkout Genérico
Se sua loja não é VTEX nem Shopify (ou se você quer controle fino), esta é a integração no nível da API — a base sobre a qual todo o resto é construído. Os conectores prontos VTEX IO e Shopify conversam com os mesmos endpoints por baixo dos panos.
Pluga a Guper no seu checkout em três chamadas. Cada passo tem uma responsabilidade focada:
- Acúmulo — calcula o cashback e os descontos do pedido
- Confirmar — aplica os benefícios quando o pagamento é aprovado
- Atualizar — altera o pedido pendente antes da confirmação (mudança de quantidade, cancelamento, etc.)
Um quarto passo opcional permite exigir PIN para resgates de alto valor.
Passo 1 — Acúmulo por pedido
Envie os itens do carrinho e o identificador do cliente. A Guper retorna um confirmToken, o cashback que seria acumulado e os resgates disponíveis para o cliente.
POST /api/loyalty/rewardByOrder
Use a variante Público (sem x-guper-authorization) para uma prévia sem dados do cliente, ou Privado quando precisar da visão completa + token. Veja Acúmulo por pedido para o schema completo.
Passo 2 — Confirmar transação
Após o processador de pagamento retornar sucesso, devolva o confirmToken para a Guper. Os benefícios viram reais na conta do cliente e a transação é registrada.
POST /api/loyalty/confirmOrder/{confirmToken}
A partir desse momento o cashback está no saldo do cliente e o pedido aparece no Feed de dados para sistemas downstream.
Passo 3 — Atualizar transação (opcional)
Se o pedido mudar entre Acúmulo e Confirmar — itens adicionados/removidos, endereço alterado, cancelamento parcial — chame o Update antes do Confirm para recalcular o cashback.
POST /api/loyalty/updateTransaction/{confirmToken}
O mesmo confirmToken é mantido. A Guper recalcula e o próximo Confirm usa o novo valor.
Opcional — Validação por PIN
Para resgates de alto valor você pode exigir um PIN do cliente. Dois endpoints:
GET /api/register/customer/{person}/pin # gera / envia PIN ao cliente
POST /api/register/customer/{person}/pin/validate # valida o PIN digitado no POS
Valide o PIN entre Acúmulo e Confirm — só prossiga com o Confirm se a validação passar.
Fluxo completo
┌──────────────────────────────────────────────┐
│ │
┌─────────┐ │ ┌─────────┐ │
│ Acúmulo │ ─→│ │ Update │ ─→ (PIN, opcional) ──────→ │
└─────────┘ │ └─────────┘ │
│ ↑ │
│ │ ↓
│ │ ┌──────────────┐
│ └─────────────────────────────│ Confirm │
│ └──────────────┘
└──────────────────────────────────────────────┘
(loops de recálculo até o pagamento aprovar)
Cancelamento
Se precisar desfazer um pedido confirmado — total ou parcial:
- Total —
POST /api/loyalty/cancelOrderByTransaction/{TID}devolve o cashback acumulado e desfaz qualquer resgate. - Parcial —
POST /api/loyalty/cancelPartial/{TID}para cancelar itens específicos. Veja Cancelamento parcial para as regras por item.
Autenticação
Todos os endpoints de Confirm/Update/Cancel exigem um token x-guper-authorization válido. Apenas a variante Pública do Acúmulo dispensa autenticação. Veja Autenticação.
Veja também
- Acúmulo por pedido — referência completa com schema e Try-it
- Cancelar transação e pedido
- Sandbox — teste o fluxo completo end-to-end antes de virar pra produção