API atual/Referência completa/Engajamento: extras

Publicidade patrocinada

Liga a publicidade do marketplace, define o piso do leilão e as categorias bloqueadas, e consulta os totais de impressões, cliques e receita.

A publicidade patrocinada deixa os sellers (lojistas) pagarem para destacar produtos. Cada seller cria campanhas com um lance e um orçamento e abastece uma carteira de créditos. Quando a vitrine pede espaços patrocinados, a plataforma faz um leilão de segundo preço: o vencedor paga o lance do segundo colocado, e nunca menos que o piso da loja. A receita é da loja.

As três rotas desta página são do administrador da loja: ele liga o recurso, escolhe quantos espaços e que piso valem, bloqueia categorias e acompanha o resultado. As campanhas e a carteira pertencem à API do seller.

Ler a configuração

GET/api/v1/admin/ads/settingsAdmin

Ler a configuração de publicidade

Devolve a configuração atual. Se a loja nunca a salvou, devolve os valores padrão.

bash

curl "$BASE_URL/api/v1/admin/ads/settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{
  "enabled": false,
  "slots": 2,
  "floor_price_cents": 20,
  "blocked_category_ids": null
}

Campos da resposta

enabledboolean

Se a publicidade está ligada para a loja.

slotsinteger

Quantos espaços patrocinados, no máximo, um leilão pode preencher por pedido da vitrine. Padrão 2.

floor_price_centsinteger

Preço mínimo de um clique, em centavos (20 = R$ 0,20). Padrão 20.

blocked_category_idsarray

Ids (UUID) de categorias cujos produtos nunca aparecem como patrocinados. Pode vir null quando a lista nunca foi definida.

Alterar a configuração

PUT/api/v1/admin/ads/settingsAdmin

Salvar a configuração de publicidade

Substitui a configuração inteira. Envie sempre os quatro campos: o que faltar é gravado como false, 0 ou lista vazia. Na leitura, slots menor ou igual a 0 volta a valer 2 e floor_price_cents menor ou igual a 0 volta a valer 20, então esses dois não podem ser zerados.

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga a publicidade.

slotsintegerobrigatório

Máximo de espaços por leilão. Use 1 ou mais.

floor_price_centsintegerobrigatório

Piso do clique, em centavos. Use 1 ou mais.

blocked_category_idsarray

Ids de categorias bloqueadas. Lista vazia libera tudo.

bash

curl -X PUT "$BASE_URL/api/v1/admin/ads/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"slots":3,"floor_price_cents":50,"blocked_category_ids":[]}'

200Configuração salva

A resposta repete exatamente o corpo enviado.

json

{ "enabled": true, "slots": 3, "floor_price_cents": 50, "blocked_category_ids": [] }

Relatório

GET/api/v1/admin/ads/reportAdmin

Totais de publicidade da loja

Soma, desde sempre e para toda a loja, as impressões, os cliques, a receita cobrada e as campanhas ativas. Não tem filtro de período.

bash

curl "$BASE_URL/api/v1/admin/ads/report" \
  -H "Authorization: Bearer $TOKEN"

200Totais

json

{ "impressions": 12840, "clicks": 391, "revenue_cents": 18250, "active_campaigns": 6 }

Campos da resposta

impressionsinteger

Quantas vezes um anúncio foi exibido.

clicksinteger

Quantos cliques cobrados foram registrados.

revenue_centsinteger

Soma do que os sellers pagaram, em centavos.

active_campaignsinteger

Campanhas com status ativo e não apagadas, de todos os sellers.

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Token que não é de administrador.	`{"error":"admin access required"}`
500	Falha ao ler ou gravar.	`{"error":"failed to save ads settings","detail":"..."}`

Veja também

API atual/Referência completa/Engajamento: extras

Publicidade patrocinada

Liga a publicidade do marketplace, define o piso do leilão e as categorias bloqueadas, e consulta os totais de impressões, cliques e receita.

Ler a configuração

GET/api/v1/admin/ads/settingsAdmin

Ler a configuração de publicidade

Devolve a configuração atual. Se a loja nunca a salvou, devolve os valores padrão.

bash

curl "$BASE_URL/api/v1/admin/ads/settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{
  "enabled": false,
  "slots": 2,
  "floor_price_cents": 20,
  "blocked_category_ids": null
}

Campos da resposta

enabledboolean

Se a publicidade está ligada para a loja.

slotsinteger

Quantos espaços patrocinados, no máximo, um leilão pode preencher por pedido da vitrine. Padrão 2.

floor_price_centsinteger

Preço mínimo de um clique, em centavos (20 = R$ 0,20). Padrão 20.

blocked_category_idsarray

Ids (UUID) de categorias cujos produtos nunca aparecem como patrocinados. Pode vir null quando a lista nunca foi definida.

Alterar a configuração

PUT/api/v1/admin/ads/settingsAdmin

Salvar a configuração de publicidade

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga a publicidade.

slotsintegerobrigatório

Máximo de espaços por leilão. Use 1 ou mais.

floor_price_centsintegerobrigatório

Piso do clique, em centavos. Use 1 ou mais.

blocked_category_idsarray

Ids de categorias bloqueadas. Lista vazia libera tudo.

bash

curl -X PUT "$BASE_URL/api/v1/admin/ads/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"slots":3,"floor_price_cents":50,"blocked_category_ids":[]}'

200Configuração salva

A resposta repete exatamente o corpo enviado.

json

{ "enabled": true, "slots": 3, "floor_price_cents": 50, "blocked_category_ids": [] }

Relatório

GET/api/v1/admin/ads/reportAdmin

Totais de publicidade da loja

Soma, desde sempre e para toda a loja, as impressões, os cliques, a receita cobrada e as campanhas ativas. Não tem filtro de período.

bash

curl "$BASE_URL/api/v1/admin/ads/report" \
  -H "Authorization: Bearer $TOKEN"

200Totais

json

{ "impressions": 12840, "clicks": 391, "revenue_cents": 18250, "active_campaigns": 6 }

Campos da resposta

impressionsinteger

Quantas vezes um anúncio foi exibido.

clicksinteger

Quantos cliques cobrados foram registrados.

revenue_centsinteger

Soma do que os sellers pagaram, em centavos.

active_campaignsinteger

Campanhas com status ativo e não apagadas, de todos os sellers.

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Token que não é de administrador.	`{"error":"admin access required"}`
500	Falha ao ler ou gravar.	`{"error":"failed to save ads settings","detail":"..."}`