Skip to content

Documentação de Banners

Visão Geral

O grupo de banners é responsável por organizar e estruturar a exibição de banners na loja 🖼️.

Ele funciona como um agrupador lógico que reúne múltiplos banners dentro de um mesmo contexto de exibição, permitindo que campanhas, destaques e comunicações visuais sejam gerenciados de forma mais organizada.

Cada grupo pode possuir configuracoes proprias, como titulos, descricoes, dimensoes recomendadas para imagens em desktop e mobile e um tipo de entidade (type), garantindo consistencia visual e organizacional entre os banners que pertencem ao mesmo conjunto.

Alem disso, os grupos podem ser vinculados a localizacoes especificas da loja, permitindo que diferentes conjuntos de banners sejam exibidos em areas distintas da interface, conforme a estrategia de comunicacao.

Filtragem por Entidade

Ao consultar grupos de banners, e possivel filtrar os banners retornados por tipo de entidade e ID da entidade, utilizando os parametros type e entityId. Isso permite exibir apenas os banners vinculados a uma categoria, marca, produto, pagina ou vitrine especifica.

Entidades Relacionadas

Banners

Os banners representam os elementos visuais exibidos ao cliente final, geralmente compostos por imagens promocionais ou institucionais.

Eles sao vinculados a um grupo de banners, que determina o contexto em que serao exibidos na loja.

Cada banner pode possuir configuracoes como imagem para desktop e mobile, titulo, link de destino e regras de exibicao, alem de vinculos diretos com entidades da loja (categorias, marcas, produtos, paginas e vitrines).

Localização

Os grupos de banners podem estar vinculados a uma localização específica.

As localizações são gerenciadas pelo frontend e permitem retornar um conjunto de entidades (incluindo grupos de banners) com base no local informado, determinando onde os banners devem ser exibidos na interface da loja.

Para mais informações sobre localizações, clique [aqui]({{ MAIN_URL }}/).

Listar Grupos de Banners

GET /api/v3/publics/template/banners

Obtém grupos de banners com seus banners ativos

Descrição

Endpoint responsável por retornar uma lista de grupos de banners filtrados por códigos, incluindo todos os banners ativos vinculados a cada grupo.

Ideal para renderização de carrosséis e áreas promocionais em páginas específicas do site.

Observações

  • Apenas banners ativos são retornados
  • Os banners são filtrados por agendamento, considerando a data atual dentro do período configurado
  • A ordenação segue o campo order
  • As imagens são disponibilizadas em três versões: desktop, tablet e mobile
  • O campo scheduling pode ser null caso não exista agendamento configurado

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
codesarraySimArray com codigos dos grupos de banners desejados
codes.*stringNaoCodigo individual de grupo de banner
typestringNaoTipo de entidade para filtrar os banners retornados (category, brand, page, product, showcase)
entityIdintegerObrigatorio quando type e informadoID da entidade para filtrar os banners

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/publics/template/banners' \
3  --header 'uappi-cookie-name: uappi-cookie' \
4  --data '{
5    "codes": ["banner-home-principal", "banner-categorias"],
6    "type": "category",
7    "entityId": 5
8  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "id": 1234,
6      "salesChannelId": 1,
7      "code": "banner-home-principal",
8      "locationId": "home",
9      "type": "category",
10      "name": "Banner Principal",
11      "title": "Banners da Home",
12      "description": "Carrossel principal da página inicial",
13      "desktopWidth": "1920",
14      "desktopHeight": "600",
15      "tabletWidth": "1024",
16      "tabletHeight": "400",
17      "mobileWidth": "768",
18      "mobileHeight": "300",
19      "createdAt": "2025-01-15 10:30:00",
20      "updatedAt": "2025-01-20 14:45:00",
21      "additionalParameter": {},
22      "banners": [
23        {
24          "id": 1234,
25          "templateBannerGroupId": 1,
26          "productCategoryId": 5,
27          "productBrandId": null,
28          "productPageId": null,
29          "productId": null,
30          "templateShowcaseId": null,
31          "name": "Banner Promoção Verão",
32          "alt": "Promoção de Verão - Até 50% OFF",
33          "desktopImage": "https://cdn.sua-loja.com.br/banners/verao-desktop.jpg",
34          "desktopOriginalImage": "https://cdn.sua-loja.com.br/banners/verao-desktop-original.jpg",
35          "tabletImage": "https://cdn.sua-loja.com.br/banners/verao-tablet.jpg",
36          "tabletOriginalImage": "https://cdn.sua-loja.com.br/banners/verao-tablet-original.jpg",
37          "mobileImage": "https://cdn.sua-loja.com.br/banners/verao-mobile.jpg",
38          "mobileOriginalImage": "https://cdn.sua-loja.com.br/banners/verao-mobile-original.jpg",
39          "desktopUrl": "/promocoes/verao",
40          "tabletUrl": "/promocoes/verao",
41          "mobileUrl": "/promocoes/verao",
42          "desktopWidth": "1920",
43          "desktopHeight": "600",
44          "tabletWidth": "1024",
45          "tabletHeight": "400",
46          "mobileWidth": "768",
47          "mobileHeight": "300",
48          "active": true,
49          "order": 1,
50          "scheduling": {
51            "startDate": "2025-01-15 00:00:00",
52            "endDate": "2025-03-31 23:59:59"
53          },
54          "createdAt": "2025-01-15 10:00:00",
55          "additionalParameter": {}
56        }
57      ]
58    }
59  ]
60}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_BANNER_GROUP_NOT_FOUND",
6    "message": "The requested banner group was not found."
7  }
8}

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;