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 configurações próprias, como títulos, descrições, dimensões recomendadas para imagens em desktop e mobile e um tipo de entidade (type), garantindo consistência visual e organizacional entre os banners que pertencem ao mesmo conjunto.

Além disso, os grupos podem ser vinculados a localizações específicas da loja, permitindo que diferentes conjuntos de banners sejam exibidos em áreas distintas da interface, conforme a estratégia de comunicação.

Tipo do Grupo (`type`)

O campo type define a qual tipo de entidade os banners do grupo podem se relacionar. Os valores aceitos são:

Tipo	Descrição
`category`	Categoria de produto
`brand`	Marca
`page`	Pagina institucional
`product`	Produto
`showcase`	Vitrine

Quando o grupo possui um type, cada banner individual pode ser vinculado diretamente a uma entidade desse tipo atraves dos campos productCategoryId, productBrandId, productPageId, productId ou templateShowcaseId.

Entidades Relacionadas

Banners

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

Eles são vinculados a um grupo de banners, que determina o contexto em que serão exibidos na loja.

Cada banner pode possuir configurações 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), permitindo criar comunicacoes visuais adaptadas para diferentes campanhas, dispositivos e contextos.

Os relacionamentos sao gerenciados no nivel do banner individual (nao do grupo). Cada banner pode ser vinculado a entidades especificas da loja atraves do endpoint de vinculo ou diretamente pelos campos de entidade no cadastro/atualizacao do banner.

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 }}/).

Listagem de banners

GET /template/banner-groups/{bannerGroupId}/banners

Listagem os banners da loja por grupo de banners

Descrição

Consulta de Banners

Este endpoint é responsável por retornar todos os banners cadastrados, permitindo visualizar a lista completa com as informações registradas na API.

Também é possível listar todos os banners cadastrados na conta, independentemente do grupo ao qual pertençam, através da rota GET /template/banner-groups/banners (mesmo endpoint, sem o parâmetro bannerGroupId na URL).

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {usertoken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Não	ID único do grupo de banner. Quando omitido (rota `/template/banner-groups/banners`), retorna os banners de todos os grupos

Campos de Condição Disponíveis

Campo	Tipo	Descrição
id	integer	Identificador do banner
name	string	Nome definido ao banner
active	boolean	status de ativação do banner
productCategoryId	integer	ID da categoria vinculada diretamente ao banner
productBrandId	integer	ID da marca vinculada diretamente ao banner
productPageId	integer	ID da página vinculada diretamente ao banner
productId	integer	ID do produto vinculado diretamente ao banner
templateShowcaseId	integer	ID da vitrine vinculada diretamente ao banner

Campos de Ordenação Disponíveis

Campo	Descrição
id	Identificador único do banner
order	Ordem de exibição do banner

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners \
3  --header "Authorization: Bearer userToken" \
curl --request GET \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners \
  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

1{
2  {
3    "id": 1,
4    "templateBannerGroupId": 1,
5    "slot": {
6      "id": 1,
7      "salesChannelId": 1,
8      "code": "main-banner",
9      "locationId": null,
10      "type": null,
11      "name": "Banner Principal",
12      "title": "Banner Principal",
13      "description": "",
14      "desktopWidth": "1920",
15      "desktopHeight": "600",
16      "mobileWidth": "375",
17      "mobileHeight": "667",
18      "createdAt": "2025-08-14 13:42:05",
19      "updatedAt": "",
20      "additionalParameter": [],
21      "banners": []
22    },
23    "productCategoryId": null,
24    "productBrandId": null,
25    "productPageId": null,
26    "productId": null,
27    "templateShowcaseId": null,
28    "name": "Banner Principal",
29    "alt": "Banner principal",
30    "desktopImage": "/upload/banner/image1.webp",
31    "desktopOriginalImage": "",
32    "mobileImage": "/upload/banner/image2.webp",
33    "mobileOriginalImage": "",
34    "desktopUrl": "",
35    "mobileUrl": "",
36    "desktopWidth": "",
37    "desktopHeight": "",
38    "mobileWidth": "",
39    "mobileHeight": "",
40    "active": false,
41    "order": 1,
42    "scheduling": null,
43    "createdAt": "2025-08-14 14:05:40",
44    "additionalParameter": [],
45    "relationships": []
46  },
47  {
48    "id": 2,
49    "templateBannerGroupId": 1,
50    "slot": {
51      "id": 1,
52      "salesChannelId": 1,
53      "code": "main-banner",
54      "locationId": null,
55      "type": null,
56      "name": "Banner Principal",
57      "title": "Banner Principal",
58      "description": "",
59      "desktopWidth": "1920",
60      "desktopHeight": "600",
61      "mobileWidth": "375",
62      "mobileHeight": "667",
63      "createdAt": "2025-08-14 13:42:05",
64      "updatedAt": "",
65      "additionalParameter": [],
66      "banners": []
67    },
68    "productCategoryId": null,
69    "productBrandId": null,
70    "productPageId": null,
71    "productId": null,
72    "templateShowcaseId": null,
73    "name": "Banner triplo home",
74    "alt": "Banner triplo home",
75    "desktopImage": "/upload/banner/image1.webp",
76    "desktopOriginalImage": "",
77    "mobileImage": "/upload/banner/image2.webp",
78    "mobileOriginalImage": "",
79    "desktopUrl": "",
80    "mobileUrl": "",
81    "desktopWidth": "",
82    "desktopHeight": "",
83    "mobileWidth": "",
84    "mobileHeight": "",
85    "active": false,
86    "order": 1,
87    "scheduling": null,
88    "createdAt": "2025-08-15 16:56:14",
89    "additionalParameter": [],
90    "relationships": []
91  }
92  
93}
{
  {
    "id": 1,
    "templateBannerGroupId": 1,
    "slot": {
      "id": 1,
      "salesChannelId": 1,
      "code": "main-banner",
      "locationId": null,
      "type": null,
      "name": "Banner Principal",
      "title": "Banner Principal",
      "description": "",
      "desktopWidth": "1920",
      "desktopHeight": "600",
      "mobileWidth": "375",
      "mobileHeight": "667",
      "createdAt": "2025-08-14 13:42:05",
      "updatedAt": "",
      "additionalParameter": [],
      "banners": []
    },
    "productCategoryId": null,
    "productBrandId": null,
    "productPageId": null,
    "productId": null,
    "templateShowcaseId": null,
    "name": "Banner Principal",
    "alt": "Banner principal",
    "desktopImage": "/upload/banner/image1.webp",
    "desktopOriginalImage": "",
    "mobileImage": "/upload/banner/image2.webp",
    "mobileOriginalImage": "",
    "desktopUrl": "",
    "mobileUrl": "",
    "desktopWidth": "",
    "desktopHeight": "",
    "mobileWidth": "",
    "mobileHeight": "",
    "active": false,
    "order": 1,
    "scheduling": null,
    "createdAt": "2025-08-14 14:05:40",
    "additionalParameter": [],
    "relationships": []
  },
  {
    "id": 2,
    "templateBannerGroupId": 1,
    "slot": {
      "id": 1,
      "salesChannelId": 1,
      "code": "main-banner",
      "locationId": null,
      "type": null,
      "name": "Banner Principal",
      "title": "Banner Principal",
      "description": "",
      "desktopWidth": "1920",
      "desktopHeight": "600",
      "mobileWidth": "375",
      "mobileHeight": "667",
      "createdAt": "2025-08-14 13:42:05",
      "updatedAt": "",
      "additionalParameter": [],
      "banners": []
    },
    "productCategoryId": null,
    "productBrandId": null,
    "productPageId": null,
    "productId": null,
    "templateShowcaseId": null,
    "name": "Banner triplo home",
    "alt": "Banner triplo home",
    "desktopImage": "/upload/banner/image1.webp",
    "desktopOriginalImage": "",
    "mobileImage": "/upload/banner/image2.webp",
    "mobileOriginalImage": "",
    "desktopUrl": "",
    "mobileUrl": "",
    "desktopWidth": "",
    "desktopHeight": "",
    "mobileWidth": "",
    "mobileHeight": "",
    "active": false,
    "order": 1,
    "scheduling": null,
    "createdAt": "2025-08-15 16:56:14",
    "additionalParameter": [],
    "relationships": []
  }
  
}

GET /template/banner-groups/{bannerGroupId}/banners/{bannerId}

Retorna o detalhe de um banner

Este endpoint é responsável por retornar o detalhe de um banner específico, identificado pelo seu ID e pelo ID do grupo ao qual pertence 🔎.

A resposta inclui, além dos dados do próprio banner, o grupo (slot) ao qual ele pertence e os seus relacionamentos com entidades (categoria, marca, produto, página ou vitrine).

Header	Valor	Descrição
`Authorization`	Bearer {usertoken}	Token de autenticação

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	ID do grupo de banner ao qual o banner pertence
bannerId	integer	Sim	ID do banner

1curl --request GET \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId} \
3  --header "Authorization: Bearer userToken"
curl --request GET \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId} \
  --header "Authorization: Bearer userToken"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "templateBannerGroupId": 1,
4  "slot": {
5    "id": 1,
6    "salesChannelId": 1,
7    "code": "main-banner",
8    "locationId": null,
9    "type": null,
10    "name": "Banner Principal",
11    "title": "Banner Principal",
12    "description": "",
13    "desktopWidth": "1920",
14    "desktopHeight": "600",
15    "mobileWidth": "375",
16    "mobileHeight": "667",
17    "createdAt": "2025-08-14 13:42:05",
18    "updatedAt": "",
19    "additionalParameter": [],
20    "banners": []
21  },
22  "productCategoryId": null,
23  "productBrandId": null,
24  "productPageId": null,
25  "productId": null,
26  "templateShowcaseId": null,
27  "name": "Banner Principal",
28  "alt": "Banner principal",
29  "desktopImage": "/upload/banner/image1.webp",
30  "desktopOriginalImage": "",
31  "mobileImage": "/upload/banner/image2.webp",
32  "mobileOriginalImage": "",
33  "desktopUrl": "",
34  "mobileUrl": "",
35  "desktopWidth": "",
36  "desktopHeight": "",
37  "mobileWidth": "",
38  "mobileHeight": "",
39  "active": true,
40  "order": 1,
41  "scheduling": null,
42  "createdAt": "2025-08-14 14:05:40",
43  "additionalParameter": [],
44  "relationships": []
45}
{
  "id": 1,
  "templateBannerGroupId": 1,
  "slot": {
    "id": 1,
    "salesChannelId": 1,
    "code": "main-banner",
    "locationId": null,
    "type": null,
    "name": "Banner Principal",
    "title": "Banner Principal",
    "description": "",
    "desktopWidth": "1920",
    "desktopHeight": "600",
    "mobileWidth": "375",
    "mobileHeight": "667",
    "createdAt": "2025-08-14 13:42:05",
    "updatedAt": "",
    "additionalParameter": [],
    "banners": []
  },
  "productCategoryId": null,
  "productBrandId": null,
  "productPageId": null,
  "productId": null,
  "templateShowcaseId": null,
  "name": "Banner Principal",
  "alt": "Banner principal",
  "desktopImage": "/upload/banner/image1.webp",
  "desktopOriginalImage": "",
  "mobileImage": "/upload/banner/image2.webp",
  "mobileOriginalImage": "",
  "desktopUrl": "",
  "mobileUrl": "",
  "desktopWidth": "",
  "desktopHeight": "",
  "mobileWidth": "",
  "mobileHeight": "",
  "active": true,
  "order": 1,
  "scheduling": null,
  "createdAt": "2025-08-14 14:05:40",
  "additionalParameter": [],
  "relationships": []
}

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.

Código Interno	Código Http	Descrição
UAPPI_STORE_BANNER_NOT_FOUND	404	O banner solicitado não foi encontrado (ou não pertence ao grupo informado).

Cadastro de banners

POST /template/banner-groups/{bannerGroupId}/banners

Cadastro de banners

Descrição

Endpoint responsável por permitir que o lojista crie banners para exibição na loja 🖼️.

Os banners podem ser configurados com imagens específicas para desktop e mobile, garantindo melhor adaptação aos diferentes dispositivos.

É possível informar a URL das imagens diretamente no cadastro ou realizar o envio da imagem por meio do endpoint de [Atualização de imagem do Banner]{docs/template/banner#atualização-de-imagem-do-banner}.

Essa flexibilidade permite maior controle sobre a comunicação visual da loja, facilitando campanhas, destaques promocionais e ações estratégicas 🚀.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Definição de cadastro de banner
`Authorization`	Bearer {usertoken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	Identificador do grupo de banner que deve ser vinculado

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	✅	Nome dado ao banner (max 255)
`alt`	string	✅	Propriedade CSS que descreve a imagem quando ela não é carregada (max 255)
`desktopUrl`	string	✅	url da imagem versão desktop
`mobileUrl`	string	✅	url da imagem versão mobile
`desktopWidth`	integer	❌	Tamanho da imagem horizontalmente em desktop
`desktopHeight`	integer	❌	Altura da imagem em desktop
`mobileWidth`	integer	❌	Tamanho da imagem horizontalmente em mobile
`mobileHeight`	integer	❌	Tamanho da imagem horizontalmente em mobile
`active`	boolean	✅	Status de ativação do banner
`order`	integer	✅	Ordem do banner para ordenação
`productCategoryId`	integer	❌	ID da categoria vinculada (quando o grupo for do tipo `category`)
`productBrandId`	integer	❌	ID da marca vinculada (quando o grupo for do tipo `brand`)
`productPageId`	integer	❌	ID da pagina vinculada (quando o grupo for do tipo `page`)
`productId`	integer	❌	ID do produto vinculado (quando o grupo for do tipo `product`)
`templateShowcaseId`	integer	❌	ID da vitrine vinculada (quando o grupo for do tipo `showcase`)
`additionalParameter`	array	❌	Lista de parâmetros adicionais, como textos e descrições extras para os banners (controlado pelo frontend)
`additionalParameter.*`	string	✅	Parâmetro adicional para o banner, controlado pelo frontend

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "name": "Periféricos Gamers",
6    "alt": "Mouse, teclado, headset e microfones em exibição",
7    "desktopUrl": "",
8    "mobileUrl": "",
9    "active": true,
10    "order": 1,
11  }'
curl --request POST \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners \
  --header "Authorization: Bearer userToken" \
  --data '{
    "name": "Periféricos Gamers",
    "alt": "Mouse, teclado, headset e microfones em exibição",
    "desktopUrl": "",
    "mobileUrl": "",
    "active": true,
    "order": 1,
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "templateBannerGroupId": 1,
4  "productCategoryId": null,
5  "productBrandId": null,
6  "productPageId": null,
7  "productId": null,
8  "templateShowcaseId": null,
9  "name": "Pré-treino",
10  "alt": "Pré-treino sendo segurado por um treinador de academia",
11  "desktopImage": "",
12  "desktopOriginalImage": "",
13  "mobileImage": "",
14  "mobileOriginalImage": "",
15  "desktopUrl": "https://www.sua-loja.com.br/upload/banner/image1.webp",
16  "mobileUrl": "https://www.sua-loja.com.br/upload/banner/image2.webp",
17  "desktopWidth": "",
18  "desktopHeight": "",
19  "mobileWidth": "",
20  "mobileHeight": "",
21  "active": true,
22  "order": 1,
23  "scheduling": null,
24  "createdAt": "2026-02-19 18:48:34",
25  "additionalParameter": [],
26  "relationships": []
27}
{
  "id": 1,
  "templateBannerGroupId": 1,
  "productCategoryId": null,
  "productBrandId": null,
  "productPageId": null,
  "productId": null,
  "templateShowcaseId": null,
  "name": "Pré-treino",
  "alt": "Pré-treino sendo segurado por um treinador de academia",
  "desktopImage": "",
  "desktopOriginalImage": "",
  "mobileImage": "",
  "mobileOriginalImage": "",
  "desktopUrl": "https://www.sua-loja.com.br/upload/banner/image1.webp",
  "mobileUrl": "https://www.sua-loja.com.br/upload/banner/image2.webp",
  "desktopWidth": "",
  "desktopHeight": "",
  "mobileWidth": "",
  "mobileHeight": "",
  "active": true,
  "order": 1,
  "scheduling": null,
  "createdAt": "2026-02-19 18:48:34",
  "additionalParameter": [],
  "relationships": []
}

⚠️ 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.

Código Interno	Código Http	Descrição
UAPPI_STORE_BANNER_GROUP_NOT_FOUND	404	O grupo de banner solicitado não foi encontrado.
UAPPI_STORE_BANNER_ADDITIONAL_PARAMETER	400	O corpo do parâmetro adicional informado não é válido.

PUT /template/banner-groups/{bannerGroupId}/banners/{bannerId}

Permite ao lojista atualizar banners da loja

Este endpoint é responsável por editar todas as informações de um banner. É possível alterar o nome, a situação (ativo ou inativo), a ordem de exibição, o agendamento de exibição com seu respectivo período, além de definir um texto alternativo para a imagem.

A atualização permite ajustar completamente as configurações do banner, garantindo que ele seja exibido conforme as regras e o planejamento definidos.

Header	Valor	Descrição
`Content-Type`	application/json	Upload de imagem
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	Id do grupo de banners
bannerId	integer	Sim	Id do banner

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	✅	Nome dado ao banner (max 255)
`alt`	string	✅	Propriedade CSS que descreve a imagem quando ela não é carregada (max 255)
`desktopUrl`	string	✅	url da imagem versão desktop
`mobileUrl`	string	✅	url da imagem versão mobile
`desktopWidth`	integer	❌	Tamanho da imagem horizontalmente em desktop
`desktopHeight`	integer	❌	Altura da imagem em desktop
`mobileWidth`	integer	❌	Tamanho da imagem horizontalmente em mobile
`mobileHeight`	integer	❌	Tamanho da imagem horizontalmente em mobile
`active`	boolean	✅	Status de ativação do banner
`order`	integer	✅	Ordem do banner para ordenação
`productCategoryId`	integer	❌	ID da categoria vinculada (quando o grupo for do tipo `category`)
`productBrandId`	integer	❌	ID da marca vinculada (quando o grupo for do tipo `brand`)
`productPageId`	integer	❌	ID da pagina vinculada (quando o grupo for do tipo `page`)
`productId`	integer	❌	ID do produto vinculado (quando o grupo for do tipo `product`)
`templateShowcaseId`	integer	❌	ID da vitrine vinculada (quando o grupo for do tipo `showcase`)
`additionalParameter`	array	❌	Lista de parâmetros adicionais, como textos e descrições extras para os banners (controlado pelo frontend)
`additionalParameter.*`	string	✅	Parâmetro adicional para o banner, controlado pelo frontend

1curl --request PUT \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}\
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "name": "Periféricos Gamers",
6    "alt": "Mouse, teclado, headset e microfones em exibição",
7    "desktopUrl": "",
8    "mobileUrl": "",
9    "active": true,
10    "order": 1,
11  }'
curl --request PUT \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}\
  --header "Authorization: Bearer userToken" \
  --data '{
    "name": "Periféricos Gamers",
    "alt": "Mouse, teclado, headset e microfones em exibição",
    "desktopUrl": "",
    "mobileUrl": "",
    "active": true,
    "order": 1,
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "templateBannerGroupId": 1,
4  "productCategoryId": null,
5  "productBrandId": null,
6  "productPageId": null,
7  "productId": null,
8  "templateShowcaseId": null,
9  "name": "Creatina",
10  "alt": "",
11  "desktopImage": "/upload/banner/image1.webp",
12  "desktopOriginalImage": "",
13  "mobileImage": "/upload/banner/image1.webp",
14  "mobileOriginalImage": "",
15  "desktopUrl": "",
16  "mobileUrl": "",
17  "desktopWidth": "",
18  "desktopHeight": "",
19  "mobileWidth": "",
20  "mobileHeight": "",
21  "active": false,
22  "order": 1,
23  "scheduling": null,
24  "createdAt": "2026-02-19 18:48:34",
25  "additionalParameter": [],
26  "relationships": []
27}
{
  "id": 1,
  "templateBannerGroupId": 1,
  "productCategoryId": null,
  "productBrandId": null,
  "productPageId": null,
  "productId": null,
  "templateShowcaseId": null,
  "name": "Creatina",
  "alt": "",
  "desktopImage": "/upload/banner/image1.webp",
  "desktopOriginalImage": "",
  "mobileImage": "/upload/banner/image1.webp",
  "mobileOriginalImage": "",
  "desktopUrl": "",
  "mobileUrl": "",
  "desktopWidth": "",
  "desktopHeight": "",
  "mobileWidth": "",
  "mobileHeight": "",
  "active": false,
  "order": 1,
  "scheduling": null,
  "createdAt": "2026-02-19 18:48:34",
  "additionalParameter": [],
  "relationships": []
}

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.

Código Interno	Código Http	Descrição
UAPPI_STORE_BANNER_GROUP_NOT_FOUND	404	O grupo de banner solicitado não foi encontrado.
UAPPI_STORE_BANNER_NOT_FOUND	404	O banner solicitado não foi encontrado
UAPPI_STORE_BANNER_ADDITIONAL_PARAMETER	400	O corpo do parâmetro adicional informado não é válido.

POST /template/banner-groups/{bannerGroupId}/banners/{bannerId}/image

Atualização de imagem do banner

Este endpoint é responsável por realizar o upload de uma imagem em um banner. A imagem deve ser enviada no corpo da requisição, juntamente com a informação do tipo de imagem, que deve ser definido como mobile ou desktop.

A definição correta do tipo garante que a imagem seja associada à versão correspondente do banner.

Header	Valor	Descrição
`Content-Type`	multipart/form-data	Tipo do conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	Id do grupo de banners
bannerId	integer	Sim	Id do banner

Parâmetro	Tipo	Obrigatório	Descrição
`image`	file	✅	Imagem a ser enviada para o banner
`type`	string	✅	Tipo de imagem (mobile ou desktop)

1curl --request POST \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}/image \
3  --header "Authorization: Bearer userToken" \
4  --form 'image=@imagem.png' \
5  --form 'type=mobile' \
curl --request POST \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}/image \
  --header "Authorization: Bearer userToken" \
  --form 'image=@imagem.png' \
  --form 'type=mobile' \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "image": "/upload/stores/upload/banner/image1.webp",
3  "originalImage": "/upload/stores/upload/banner/image1.png"
4}
{
  "image": "/upload/stores/upload/banner/image1.webp",
  "originalImage": "/upload/stores/upload/banner/image1.png"
}

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.

Código Interno	Código Http	Descrição
UAPPI_STORE_BANNER_NOT_FOUND	404	O banner solicitado não foi encontrado.
UAPPI_STORE_BANNER_GROUP_NOT_FOUND	404	O grupo de banner solicitado não foi encontrado.
UAPPI_STORE_BANNER_NOT_VALID_IMAGE_TYPE	400	O tipo de payload solicitado não é válido!

DELETE /template/banner-groups/{bannerGroupId}/banners/{bannerId}/image

Rota para excluir uma imagem do banner.

Este endpoint é responsável por excluir a imagem de um banner cadastrado, ação que deve ser realizada por um usuário autorizado. Após a exclusão, a imagem poderá ser enviada novamente, caso necessário.

Para identificar corretamente o registro, devem ser informados na URL do endpoint os IDs do grupo do banner e do banner. Também é obrigatório indicar o tipo de imagem no corpo da requisição que será removida, sendo possível excluir uma imagem por vez, garantindo que a operação seja aplicada ao item correto.

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	ID único do grupo de banner
bannerId	integer	Sim	ID único do banner

Campo	Tipo	Descrição
type	string	Definição do tipo de imagem (desktop ou mobile)

1curl --request DELETE \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}/image\
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "type":"desktop"
6  }'
curl --request DELETE \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}/image\
  --header "Authorization: Bearer userToken" \
  --data '{
    "type":"desktop"
  }'

Respostas

Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3	"data": true
4}
{
  "status": true,
	"data": true
}

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.

Código Interno	Código Http	Descrição
UAPPI_STORE_BANNER_NOT_FOUND	404	O banner solicitado não foi encontrado.
UAPPI_STORE_BANNER_GROUP_NOT_FOUND	404	O grupo de banner solicitado não foi encontrado.

DELETE /template/banner-groups/{bannerGroupId}/banners/{bannerId}

Permite excluir um banner da loja.

Este endpoint é responsável por excluir um banner cadastrado, ação que deve ser realizada por um usuário autorizado. Após a exclusão, o banner não ficará mais disponível para consultas ou utilização na plataforma.

Tanto o grupo do banner quanto o banner que será removido devem ser identificados pelos respectivos IDs informados na URL do endpoint, garantindo que a exclusão seja aplicada ao registro correto.

Header	Valor	Descrição
`Authorization`	Bearer {usertoken}	Token de autenticação

Parâmetro	Tipo	Obrigatório	Descrição
bannerGroupId	integer	Sim	ID único do grupo de banner
bannerId	integer	Sim	ID único do banner

1curl --request DELETE \
2  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}\
3  --header "Authorization: Bearer userToken" \
curl --request DELETE \
  --url {{MAIN_URL}}/template/banner-groups/{bannerGroupId}/banners/{bannerId}\
  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3	"data": true
4}
{
  "status": true,
	"data": true
}

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

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Banners

Visão Geral

Tipo do Grupo (type)

Entidades Relacionadas

Banners

Relacionamentos de Banner

Localização

Listagem de banners

Descrição

Consulta de Banners

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

Detalhe de banner

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cadastro de banners

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Tipo do Grupo (`type`)