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

Vales-presente

Crédito pré-pago por código: como o vale é emitido, usado no checkout e acompanhado pelo administrador.

Um vale-presente é um valor em dinheiro guardado sob um código. Quem o recebe digita o código no checkout e o valor abate o pedido. A loja usa vales para presentes, compensações e campanhas.

São as rotas do administrador da loja. A validação e o uso do código acontecem no checkout, fora desta seção.

Pontos principais
  • Valores em centavos: 5000 é R$ 50,00.
  • O valor e o código de um vale emitido não mudam. Para corrigir, desative e emita outro.
  • Um vale pode ser da loja inteira ou de um seller (vendor_id); o de seller só abate itens daquele seller.
  • O estado vem como letra: A ativo, D desativado, F esgotado.
  • Exige os módulos promotions e gift-certificates ativos.

Como funciona

Emitido (A)→Usado em pedidos→Esgotado (F)
LetraEstadoSignificado
AativoAceito no checkout, com saldo.
DdesativadoRecusado no checkout. O saldo e o histórico ficam.
FesgotadoO saldo chegou a zero.

Cada uso grava um registro com o pedido e o valor. Se o pedido é cancelado ou estornado, o uso é revertido (refunded_at) e o valor volta ao saldo.

Conceitos-chave

Código

É o que o cliente digita. A plataforma gera um no formato GC-XXXX-XXXX-XXXX (sem as letras I e O e os números 0 e 1, para não confundir) ou aceita o que você mandar, sempre em maiúsculas. O código é único.

Validade

expires_at é opcional. Depois dela o vale deixa de ser aceito.

Endpoints

MétodoCaminhoPara que servePágina
GET/api/v1/admin/gift-certificatesListar valesVales
POST/api/v1/admin/gift-certificatesEmitir um valeVales
GET/api/v1/admin/gift-certificates/{id}Consultar um valeVales
PUT/api/v1/admin/gift-certificates/{id}Alterar um valeVales
PUT/api/v1/admin/gift-certificates/{id}/disableDesativarVales
GET/api/v1/admin/gift-certificates/{id}/usageHistórico de usoVales

Erros comuns

  • Tentar corrigir o valor com PUT. Responde 400 immutable_field. Desative e emita outro.
  • Achar que amount: 50 é R$ 50,00. É R$ 0,50. O valor é em centavos.
  • Esperar que o servidor envie o vale por e-mail. A entrega ao destinatário é sua.
  • Usar status: used para encerrar um vale. Use disable; used não zera o saldo.
  • Esperar 404 em UUID malformado ou usos de um vale inexistente. Respondem 500 e 200 com lista vazia.

Próximos passos

Emitir e consultar vales
Liste, consulte e emita vales.
Alterar e desativar
Altere, desative e veja o histórico de uso.
Anterior
Negociações (RFQ)
Próxima
Emitir e consultar vales
Nesta página
  • Como funciona
  • Conceitos-chave
  • Código
  • Validade
  • Endpoints
  • Erros comuns
  • Próximos passos