VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Créditos e descontos

Como o cliente reduz o que paga: vale-presente, cupom e carteira.

Antes de cobrar, o cliente pode abater o pedido de três formas: com um vale-presente (crédito com código), com um cupom (desconto) ou com o saldo da carteira digital. Esta seção traz as rotas da vitrine para conferir cada uma e, em checkouts próprios, registrar o uso.

Pontos-chave
  • Todas as rotas exigem o token do cliente.
  • Valores em centavos; percentuais de cupom em pontos-base (1000 = 10%).
  • Validar não gasta nada. Usar/resgatar/aplicar gasta na hora e grava o uso.
  • As rotas de uso não conferem o pedido: o valor e a idempotência são responsabilidade de quem chama.
  • Módulos: gift-certificates, voucher-system e digital-wallet. Vale e cupom de um seller funcionam sem o módulo da loja.

Como funciona

Os três instrumentos lado a lado:

Vale-presenteCupomCarteira
O que éCrédito com códigoDesconto com códigoSaldo do cliente
ValorSaldo em centavosFixo, percentual ou frete grátisSaldo em centavos
VerificarvalidatevalidateGET /wallet
Gastarapplyredeemapply
Limite por clienteNãomax_per_userSaldo

Fluxo típico num checkout próprio:

  1. Validar

    Chame validate do vale ou do cupom para mostrar ao cliente quanto abate, e leia a carteira.

  2. Criar o pedido

    Crie o pedido pelo fluxo normal de pedidos.

  3. Registrar o uso

    Com o order_id em mãos, chame apply, redeem ou wallet/apply, uma vez cada.

Conceitos-chave

Da loja ou de um seller

Vale e cupom podem ser da loja inteira ou de um seller. O de um seller só abate os itens daquele seller no carrinho do cliente (o carrinho atual do token, ou o da sessão enviada em X-Session-ID). O da loja inteira abate o pedido todo.

Códigos de motivo

O cupom explica a recusa em reason (VOUCHER_EXPIRED, VOUCHER_MIN_ORDER_NOT_MET...). O vale-presente explica em error, em inglês. Traduza na sua tela.

Valores sempre inteiros

Sem decimais em lugar nenhum: R$ 50,00 é 5000. Percentual de cupom em pontos-base: 1 bps = 0,01%.

Endpoints

Método e caminhoPara quêAutenticaçãoPágina
POST /api/v1/storefront/gift-certificates/validateValida o vale-presente e mostra o saldo utilizávelToken do clienteVale-presente
POST /api/v1/storefront/gift-certificates/applyDebita o vale e registra o uso no pedidoToken do clienteVale-presente
POST /api/v1/storefront/vouchers/validateValida o cupom e calcula o descontoToken do clienteCupons de desconto
POST /api/v1/storefront/vouchers/redeemRegistra o uso do cupom em um pedidoToken do clienteCupons de desconto
GET /api/v1/storefront/vouchers/my-redemptionsLista os cupons que o cliente já resgatouToken do clienteCupons de desconto
GET /api/v1/storefront/walletSaldo e totais da carteiraToken do clienteCarteira digital
GET /api/v1/storefront/wallet/transactionsExtrato da carteiraToken do clienteCarteira digital
POST /api/v1/storefront/wallet/applyDebita a carteira para pagar um pedidoToken do clienteCarteira digital

Erros comuns

O que costuma dar errado
  1. Chamar apply/redeem para "testar". Eles gastam de verdade; teste com validate.
  2. Esperar 4xx para cupom inválido. O cupom volta 200 com valid: false; o vale-presente volta 400.
  3. Repetir apply/redeem/wallet/apply após um timeout sem reler o estado: o valor pode ser debitado duas vezes.
  4. Usar o balance de validate do vale como saldo total. Ele é o utilizável neste carrinho.
  5. Enviar o código do cupom em voucher_id. Lá vai o id numérico.
  6. Mostrar valores como decimais. Tudo vem em centavos.

Próximos passos

Vale-presente
Valide e use um vale-presente.
Cupons de desconto
Valide e resgate um cupom.
Carteira digital
Saldo, extrato e pagamento.
Anterior
Compras programadas
Próxima
Vale-presente
Nesta página
  • Como funciona
  • Conceitos-chave
  • Da loja ou de um seller
  • Códigos de motivo
  • Valores sempre inteiros
  • Endpoints
  • Erros comuns
  • Próximos passos