Banners

Banners do carrossel da vitrine, com janela de datas, segmentação por página, categoria, canal e dispositivo.

Banners são as imagens (ou textos) promocionais que aparecem no topo da vitrine e em outras áreas, normalmente num carrossel. Cada banner pode ter um link, um texto sobreposto, um período de exibição e uma segmentação: em quais páginas e categorias aparece, em qual canal (site ou aplicativos) e em qual dispositivo.

Como funciona

O fluxo comum é criar o banner como scheduled (rascunho), conferir, e mudar para active quando a campanha começar. A vitrine só devolve banners active cujo período inclui o momento atual. Fora do período o banner continua cadastrado, apenas deixa de ser exibido.

Criar→Conferir→Ativar→Desativar ou apagar

Status	Significado	Exibido
`active`	Ativo.	Sim, dentro da janela de datas
`inactive`	Desativado pelo administrador.	Não
`scheduled`	Rascunho/agendado. É guardado como rascunho e não ativa sozinho.	Não
`hidden`	Oculto.	Não

Conceitos importantes

Canal e dispositivo

Um canal é a superfície que mostra o banner: site, venddor_app ou client_app. Um dispositivo é mobile, tablet ou desktop. Um banner sem lista de canais ou dispositivos aparece em todos. Se você envia uma lista, ela precisa ter ao menos um código válido e substitui a anterior. Os canais disponíveis vêm de Canais de exibição.

Banner gráfico e banner de texto

O tipo G (padrão) usa imagem. O tipo T mostra só o texto de description (HTML sanitizado) e dispensa imagem e link.

Texto sobreposto

Os campos overlay_* desenham título, subtítulo e botão em cima da imagem, com cores e posição (left, center, right).

Banner da loja e de seller

Banners sem vendor_id são da loja inteira. Banners de seller aparecem só na vitrine daquele seller. A lista mistura os dois por padrão.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/api/v1/admin/banners`	Lista os banners da loja	admin
GET	`/api/v1/admin/banners/{id}`	Devolve um banner pelo id	admin
GET	`/api/v1/admin/banners/display-channels`	Lista os canais em que um banner pode aparecer	admin
POST	`/api/v1/admin/banners`	Cria um banner da vitrine	admin
PUT	`/api/v1/admin/banners/{id}`	Altera campos de um banner	admin
DELETE	`/api/v1/admin/banners/{id}`	Apaga um banner definitivamente	admin
POST	`/api/v1/admin/banners/bulk-delete`	Apaga uma lista de banners de uma vez	admin

Erros comuns

Criar um banner com status scheduled e esperar que ele ligue sozinho na data de início: ele não liga.
Enviar channels: [] ou um código que não existe: a criação é recusada com invalid_channel.
Usar http://localhost/... ou um IP interno como imagem: é recusado por segurança (ssrf_forbidden).
Esperar 404 ao apagar ou atualizar um banner que não existe: a resposta é 500 com banner not found no detail.
Paginar a lista: ela devolve todos os banners de uma vez.
Enviar ends_at antes de starts_at: recusado com invalid_date_range.

Próximos passos

Criar banner

Todos os campos e regras.

Listar e consultar

Filtros por canal e dispositivo.

Alterar e apagar

Atualizar, apagar e apagar em lote.