API atual/Referência completa/Conteúdo da vitrine

Banners

Lista os banners ativos da vitrine, filtrados por página, categoria e grupo de usuário do cliente.

Um banner é uma peça de campanha: uma imagem (ou um texto) com título, botão e link, mostrada no carrossel da home ou no topo de uma categoria. O administrador cadastra os banners e decide onde cada um aparece; esta rota devolve os que valem agora para quem está olhando a loja.

GET/api/v1/storefront/bannersPública

Listar os banners ativos

Parâmetros de consulta

page_slugstring

Slug da página em que o banner vai aparecer (por exemplo home). Só traz banners sem alvo de página ou com esse slug em target_pages. Sem o parâmetro, não filtra por página.

category_idstring

Id da categoria que o cliente está vendo. Só traz banners sem alvo de categoria ou com esse id em target_categories. A comparação é por texto: um valor desconhecido apenas deixa de casar com os banners que têm alvo.

langstringpadrão: pt-BR

Idioma do texto dos banners do tipo texto (description). Também aceita o cabeçalho Accept-Language.

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional; libera os banners restritos aos grupos dele.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/banners?page_slug=home"

Resposta

200Banners

json

{
  "banners": [
    {
      "id": "a2170eb9-abd0-4398-9dbb-322c868e2fc5",
      "name": "Nova Coleção 2026",
      "image_url": "/uploads/banner/nova-colecao.png",
      "alt_text": "Nova Coleção 2026",
      "position": 0,
      "status": "active",
      "usergroup_ids": "",
      "target_pages": [],
      "target_categories": [],
      "created_at": "2026-09-06T03:43:55Z",
      "overlay_title": "Nova coleção",
      "overlay_subtitle": "Até 40% de desconto",
      "overlay_button_text": "Ver ofertas",
      "overlay_button_url": "/c/colecao-2026",
      "overlay_text_color": "#ffffff",
      "overlay_button_color": "#16a34a",
      "overlay_position": "left",
      "type": "G",
      "target": "T",
      "description": "",
      "channels": null,
      "devices": null
    }
  ],
  "total": 1
}

Campos da resposta

bannersarray

Banners válidos agora, em ordem de exibição (position). [] quando não há nenhum.

banners[].iduuid

Id do banner.

banners[].namestring

Nome interno do banner.

banners[].image_urlstring

Imagem principal. Caminho relativo à loja ou URL completa. Vazio em banner de texto.

banners[].mobile_image_urlstring

Arte própria para telas pequenas. Ausente quando o tema deve recortar image_url.

banners[].link_urlstring

Destino do clique na imagem. Ausente quando não há.

banners[].alt_textstring

Texto alternativo da imagem.

banners[].positioninteger

Ordem de exibição.

banners[].statusstring

Estado do banner. Aqui sempre active.

banners[].usergroup_idsstring

Grupos de usuários que enxergam o banner. Vazio quando é para todos.

banners[].starts_atstring

Início da exibição (RFC 3339). Ausente quando não há.

banners[].ends_atstring

Fim da exibição (RFC 3339). Ausente quando não há.

banners[].target_pagesarray

Slugs de página alvo. [] quer dizer "todas".

banners[].target_categoriesarray

Ids de categoria alvo. [] quer dizer "todas".

banners[].created_atstring

Criação (RFC 3339).

banners[].overlay_titlestring

Título sobre a imagem. Ausente quando não há.

banners[].overlay_subtitlestring

Subtítulo sobre a imagem. Ausente quando não há.

banners[].overlay_button_textstring

Texto do botão. Ausente quando não há.

banners[].overlay_button_urlstring

Destino do botão. Ausente quando não há.

banners[].overlay_text_colorstring

Cor do texto, em hexadecimal (#ffffff).

banners[].overlay_button_colorstring

Cor do botão, em hexadecimal.

banners[].overlay_positionstring

leftcenterright

Posição horizontal do texto sobre a imagem.

banners[].typestring

GT

G banner gráfico (imagem), T banner de texto (usa description).

banners[].targetstring

TB

T abre o link na mesma janela, B em nova janela. Só vale para G.

banners[].descriptionstring

Corpo HTML do banner de texto, no idioma pedido. Vazio em banner gráfico.

banners[].channelsarray

Canais em que o banner vale. null é "todos".

banners[].devicesarray

Dispositivos em que o banner vale. null é "todos".

totalinteger

Quantidade de banners na resposta.

A resposta ainda traz apelidos dos campos principais em cada banner: banner_id (igual a id), banner (igual a name), image_path (igual a image_url) e timestamp (criação em Unix timestamp). Não dependa deles em integrações novas.

Erros

Status	Quando	Corpo
403	O módulo `banners` está desligado.	`{"error":"module_disabled","module":"banners"}`
500	Falha ao consultar.	`{"error":"failed to list banners","detail":"..."}`

Veja também