Entrar
.md

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:

  1. Acúmulo — calcula o cashback e os descontos do pedido
  2. Confirmar — aplica os benefícios quando o pagamento é aprovado
  3. 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