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

Promoções, cupons e banners

Visão geral das rotas de promoção, cupom, banner promocional e cotação B2B em lote da API compatível com a Venddor 1.0.

Esta seção reúne o que um sistema escrito para a Venddor 1.0 usa para trabalhar com descontos. A promoção é a regra (condições e bônus). O cupom é o código que o cliente digita para ativá-la. O banner promocional é a imagem que divulga a campanha. E a cotação em lote devolve o preço efetivo de vários produtos para um cliente B2B.

Pontos-chave
  • Todas as rotas exigem autenticação (HTTP Basic e-mail:chave_de_api ou Bearer). Veja Autenticação. Criar, alterar e remover promoções exige um usuário administrador.
  • Os ids de promoção, banner e produto são UUID.
  • Dinheiro é decimal em texto ("10.00"). Datas são Unix timestamp em segundos.
  • Status em letra: A ativa, D desativada, H oculta, N pendente.
  • Os banners promocionais são só de leitura.
  • Erros têm o formato {"message":"...","status":4xx}.

Como funciona

  1. Crie a promoção

    POST /promotions com nome, tipo de bônus, desconto e, se quiser, um código de cupom em coupon_code.

  2. Valide o cupom no carrinho

    POST /coupons/{code}/validate recebe o total e os itens e diz se o cupom vale e quanto desconta.

  3. Acompanhe o uso

    GET /coupons/{code}/usage devolve quantas vezes o cupom foi usado, por quantos clientes e quanto descontou.

Conceitos

Zona

Toda promoção tem uma zone: cart (vale sobre o carrinho) ou catalog (vale sobre o preço do produto na vitrine).

Condições e bônus

conditions é uma árvore (set, set_value, conditions) com as regras de quando a promoção vale. bonuses é a lista do que a promoção entrega (order_discount, free_shipping...). Ambos são devolvidos como foram gravados.

Cupom

Uma promoção guarda no máximo um código de cupom, no campo auto_coupons. A comparação do código não diferencia maiúscula de minúscula.

Rotas

MétodoCaminhoPara que servePágina
GET/api/v1.0/promotionsListar promoçõesPromoções
POST/api/v1.0/promotionsCriar uma promoçãoPromoções
GET/api/v1.0/promotions/{id}Consultar uma promoçãoPromoções
PUT/api/v1.0/promotions/{id}Alterar uma promoçãoPromoções
DELETE/api/v1.0/promotions/{id}Remover uma promoçãoPromoções
GET/api/v1.0/promotions/{id}/couponsCupom de uma promoçãoPromoções
POST/api/v1.0/coupons/{code}/validateValidar um cupomCupons
GET/api/v1.0/coupons/{code}/usageUso de um cupomCupons
GET/api/v1.0/promotion_bannersListar bannersBanners promocionais
GET/api/v1.0/promotion_banners/{id}Consultar um bannerBanners promocionais
GET/api/v1.0/promotionbannerapiListar banners (nome do app)Banners promocionais
GET/api/v1.0/promotionbannerapi/{id}Consultar um banner (nome do app)Banners promocionais
POST/api/v1.0/quotation_batch_matchPreço efetivo de vários produtosCotação em lote

Erros comuns

  • Tratar cupom inválido como erro HTTP. POST /coupons/{code}/validate responde 200 com "valid": false e o motivo em message.
  • Mandar from_date e to_date na criação. A criação de promoção por esta API não grava datas de vigência.
  • Passar um id que não é UUID. Em GET /promotions/{id}, um id mal formado responde 500, não 404.
  • Esperar mais de um cupom por promoção. /promotions/{id}/coupons devolve no máximo um.

Próximos passos

Promoções
Criar e manter as regras de desconto.
Cupons
Validar no carrinho e acompanhar o uso.
Banners promocionais
Ler os banners das campanhas.
Anterior
Formas de envio para apps
Próxima
Rotas de promoções
Nesta página
  • Como funciona
  • Conceitos
  • Zona
  • Condições e bônus
  • Cupom
  • Rotas
  • Erros comuns
  • Próximos passos