Venddor Ads
Campanhas de produtos patrocinados do seller, pagas por clique, e a carteira de mídia que as financia.
Venddor Ads deixa o seller (lojista) pagar para que seus produtos apareçam em posições patrocinadas da loja (busca, listagem de categoria, página de produto e home). O modelo é custo por clique (CPC): você define o lance máximo que aceita pagar por clique e um orçamento diário; só o clique cobra, a exibição é grátis. O dinheiro vem de uma carteira de mídia do próprio seller. As rotas ficam em /api/v1/vendor/ads.
Como funciona
status | Significado |
|---|---|
draft | Rascunho, criada e ainda fora do ar. |
active | Veiculando, se houver saldo, orçamento do dia e produto à venda. |
paused | Pausada pelo seller; pode voltar a active. |
ended | Encerrada: pelo seller, ao apagar, ao passar ends_at ou ao esgotar o orçamento total. |
- Recarregar a carteira
Sem saldo nenhuma campanha veicula. Carteira aceita recargas de pelo menos R$ 50,00 (5000 centavos).
- Criar a campanha
Criar campanha com lance, orçamento diário e produtos.
- Ativar
Mudar status para
active. - Acompanhar o gasto
Consultar campanhas mostra
spent_today_centsespent_total_cents; a carteira mostra cada cobrança.
Conceitos-chave
Lance, preço do clique e orçamentos
O bid_cents é o máximo que você paga por clique. O preço efetivo vem de um leilão entre os anunciantes e nunca passa do seu lance nem fica abaixo do piso da loja (padrão R$ 0,20). O daily_budget_cents limita o gasto por dia; ao atingi-lo a campanha para até a virada do dia em São Paulo. O total_budget_cents, se existir, encerra a campanha ao ser esgotado. Cliques repetidos da mesma sessão em 10 minutos não são cobrados de novo.
Carteira de mídia
Cada seller tem um saldo. Cada clique cobrado desconta do saldo e gera uma linha click_charge negativa; cada recarga gera uma linha topup positiva. Saldo zero tira todas as campanhas do seller do leilão.
Privilégios
As rotas de campanha só exigem um token de seller. As rotas de carteira exigem um privilégio financeiro (vendor_financial e afins). O dono da loja tem todos.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/vendor/ads/campaigns | Lista as campanhas. | vendor |
| GET | /api/v1/vendor/ads/campaigns/{id} | Devolve uma campanha. | vendor |
| POST | /api/v1/vendor/ads/campaigns | Cria uma campanha em rascunho. | vendor |
| PUT | /api/v1/vendor/ads/campaigns/{id} | Altera lance, orçamento, nome e produtos. | vendor |
| DELETE | /api/v1/vendor/ads/campaigns/{id} | Apaga (encerra) a campanha. | vendor |
| POST | /api/v1/vendor/ads/campaigns/{id}/status | Ativa, pausa ou encerra. | vendor |
| GET | /api/v1/vendor/ads/wallet | Saldo e movimentos da carteira. | vendor |
| POST | /api/v1/vendor/ads/wallet/topup | Recarrega a carteira. | vendor |
Erros comuns
- Mandar reais em vez de centavos.
bid_cents: 0.8não é inteiro; mande80. - Ativar sem saldo. A API aceita, mas nada veicula. Recarregue antes.
- Esquecer o
total_budget_centsnoPUT. Ele é sempre regravado: omitir o campo remove o limite total. - Enviar
product_idsde outro seller. Os ids alheios são descartados sem erro. - Achar que a recarga é um pagamento. Ela vira dívida de mídia, descontada dos repasses.
- Esperar que a campanha apareça na vitrine padrão. O Ads precisa estar ligado pelo administrador e a vitrine precisa exibir os espaços.