Listar Grupos de Banners

Retorna uma lista de grupos de banners filtrados por códigos, incluindo todos os banners ativos vinculados a cada grupo. Ideal para renderizar carrosséis e banners em páginas específicas do site.

> 📌 Importante: A API Uappi é self-hosted em cada loja. Substitua sua-loja.com.br pelo domínio real da loja que você está integrando.

Endpoint

GET /api/v3/publics/template/banners

Obtém grupos de banners com seus banners ativos

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros de Query/Body

Parâmetro	Tipo	Obrigatório	Descrição
`codes`	array	Sim	Array com códigos dos grupos de banners desejados
`codes.*`	string	Não	Código individual de grupo de banner

Exemplo de Requisição

1curl --request GET \
2  --url 'https://sua-loja.com.br/api/v3/publics/template/banners' \
3  --header 'Content-Type: application/json' \
4  --header 'uappi-cookie-name: uappi-cookie' \
5  --data '{
6    "codes": ["banner-home-principal", "banner-categorias"]
7  }'
curl --request GET \
  --url 'https://sua-loja.com.br/api/v3/publics/template/banners' \
  --header 'Content-Type: application/json' \
  --header 'uappi-cookie-name: uappi-cookie' \
  --data '{
    "codes": ["banner-home-principal", "banner-categorias"]
  }'

Respostas

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

Possíveis Erros

#### Grupo de Banner Não Encontrado

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_BANNER_GROUP_NOT_FOUND",
6    "message": "Banner group not found with the provided codes."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_BANNER_GROUP_NOT_FOUND",
    "message": "Banner group not found with the provided codes."
  }
}

#### Validação de Parâmetros

1{
2  "status": false,
3  "data": {
4    "code": 422,
5    "errorCode": "VALIDATION_ERROR",
6    "message": "The codes field is required."
7  }
8}
{
  "status": false,
  "data": {
    "code": 422,
    "errorCode": "VALIDATION_ERROR",
    "message": "The codes field is required."
  }
}

Códigos de Status

Código	Descrição
200	Grupos de banners retornados com sucesso
404	Nenhum grupo de banner encontrado com os códigos fornecidos
422	Erro de validação nos parâmetros da requisição
500	Erro interno do servidor

Campos Retornados

Campo	Tipo	Descrição
`id`	integer	ID do grupo de banner
`salesChannelId`	integer	ID do canal de vendas
`code`	string	Código único do grupo
`locationId`	string\	null	Identificador da localização/página
`name`	string	Nome do grupo
`title`	string\	null	Título exibido do grupo
`description`	string\	null	Descrição do grupo
`desktopWidth`	string	Largura para desktop (px)
`desktopHeight`	string	Altura para desktop (px)
`tabletWidth`	string	Largura para tablet (px)
`tabletHeight`	string	Altura para tablet (px)
`mobileWidth`	string	Largura para mobile (px)
`mobileHeight`	string	Altura para mobile (px)
`createdAt`	string	Data de criação (ISO 8601)
`updatedAt`	string	Data de atualização (ISO 8601)
`additionalParameter`	object	Parâmetros adicionais personalizados
`banners`	array	Lista de banners ativos do grupo
`products`	array	Produtos vinculados ao grupo
`brands`	array	Marcas vinculadas ao grupo
`categories`	array	Categorias vinculadas ao grupo
`showcases`	array	Vitrines vinculadas ao grupo
`pages`	array	Páginas vinculadas ao grupo

Campo	Tipo	Descrição
`id`	integer	ID do banner
`templateBannerGroupId`	integer	ID do grupo ao qual pertence
`name`	string	Nome do banner
`alt`	string	Texto alternativo (SEO)
`desktopImage`	string	URL da imagem desktop
`desktopOriginalImage`	string	URL original desktop
`tabletImage`	string	URL da imagem tablet
`tabletOriginalImage`	string	URL original tablet
`mobileImage`	string	URL da imagem mobile
`mobileOriginalImage`	string	URL original mobile
`desktopUrl`	string	Link de destino desktop
`tabletUrl`	string	Link de destino tablet
`mobileUrl`	string	Link de destino mobile
`desktopWidth`	string	Largura desktop (px)
`desktopHeight`	string	Altura desktop (px)
`tabletWidth`	string	Largura tablet (px)
`tabletHeight`	string	Altura tablet (px)
`mobileWidth`	string	Largura mobile (px)
`mobileHeight`	string	Altura mobile (px)
`active`	boolean	Status de ativação
`order`	integer	Ordem de exibição
`scheduling`	object\	null	Agendamento do banner
`createdAt`	string	Data de criação (ISO 8601)
`additionalParameter`	object	Parâmetros personalizados

Observações

Apenas banners ativos são retornados
Banners são filtrados por agendamento (data atual dentro do período)
A ordem dos banners segue o campo order
Imagens são fornecidas em 3 versões: desktop, tablet e mobile
O campo scheduling pode ser null se não houver agendamento configurado

Prologue

Getting Started

Architecture Concepts

The Basics

Digging Deeper

Security

Database

Eloquent ORM

Testing

Packages