Promoções do seller

Um seller (lojista) é um vendedor que opera dentro do marketplace da loja, com catálogo e pedidos próprios. Esta seção reúne as ferramentas que ele tem para vender mais sem mexer nas regras da loja inteira: promoções com código de cupom, cupons automáticos entregues depois de uma compra, orçamentos que limitam quanto ele gasta em desconto e a leitura dos carrinhos abandonados que continham os produtos dele. Tudo vive sob /api/v1/vendor e só enxerga o que pertence ao próprio seller.

Como funciona

Quem pode o quê

Uma loja pode ter promoções de três donos. Esta seção trata só do terceiro.

Do cadastro ao desconto

1. Crie a promoção
   POST /api/v1/vendor/promotions com name, type, discount e, obrigatoriamente para ter efeito, code. Veja Criar, alterar e excluir promoção.
2. Proteja o caixa
   Crie um orçamento com teto em centavos ou em usos. Quando o teto estoura, a promoção para de aplicar.
3. Acompanhe
   Os usos aparecem em usage_count na promoção e em spent no orçamento.

Status e vigência

O status é gravado como letra: A ativa, D inativa (também usada ao excluir), E expirada. Uma promoção só desconta dentro de valid_from e valid_until, abaixo de usage_limit e de per_user_limit e enquanto nenhum orçamento ligado a ela estiver esgotado.

Conceitos importantes

Os dois tipos de cupom do seller

Ids

Promoções, orçamentos, grupos e carrinhos abandonados usam UUID. As regras de cupom automático usam número inteiro (/auto-coupons/3).

Seller em análise

Enquanto o cadastro de aprovação do seller não for aceito, todas as rotas desta seção respondem 403 com {"error":"vendor_pending_review"}. Só as rotas de cadastro ficam abertas.

Exclusão

Excluir uma promoção é lógico: ela some da lista e deixa de descontar. Excluir um orçamento ou um grupo remove o registro de verdade.

Endpoints

Erros comuns

• Cadastrar a promoção sem code e esperar que ela apareça sozinha na vitrine. Promoção de seller é excluída do cálculo automático: sem código ela nunca desconta.
• Mandar vendor_id no corpo. É ignorado; a promoção sempre nasce do seller do token.
• Usar o token de administrador. O prefixo /api/v1/vendor aceita só usuário seller; o administrador recebe 403 insufficient permissions.
• Trocar as unidades. discount é pontos-base em percentage e centavos em fixed. 1000 em fixed é R$ 10,00, não 10%.
• Esperar remover o código de uma promoção pelo PUT. "code": null não remove o código nesta rota; exclua e recrie a promoção.
• Passar um id de regra automática como UUID. Em /auto-coupons/{id} o id é inteiro, e um segmento numérico 0 ou negativo em qualquer caminho do seller leva 400 invalid id parameter.
• Criar orçamento com escopo marketplace. É exclusivo da loja e leva 403.

Próximos passos