POSTCriar banner

Cria um banner gráfico ou de texto, com janela de datas e segmentação.

Cria um banner para o carrossel da vitrine. Um banner gráfico exige nome e imagem; um banner de texto (type T) dispensa a imagem. A janela de exibição (starts_at, ends_at) e os filtros de página, categoria, canal e dispositivo decidem onde e quando ele aparece.

POST/api/v1/admin/bannersAdmin

Cria um banner da vitrine

Rota ligada ao módulo banners: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_content.

Corpo da requisição

namestringobrigatório

Nome do banner (HTML é removido).

image_urlstring

Imagem. Obrigatória em banner gráfico. Aceita URL https:// pública ou um caminho /uploads/... da própria loja; outros esquemas e endereços de rede interna são recusados.

mobile_image_urlstring

Arte para celular, com as mesmas regras de image_url.

link_urlstring

Destino do clique, mesmas regras de URL.

alt_textstring

Texto alternativo.

statusstringpadrão: active

activeinactivescheduledhidden

Estado do banner. Omitido = active. Só active é exibido; scheduled fica guardado como rascunho e não liga sozinho.

starts_atstring

Início da exibição (RFC 3339).

ends_atstring

Fim da exibição (RFC 3339). Não pode ser anterior a starts_at.

usergroup_idsstring

Ids de grupos de clientes separados por vírgula. Vazio = todos.

target_pagesarray

Slugs de páginas onde exibir. Vazio = em todas.

target_categoriesarray

Ids de categorias onde exibir. Vazio = em todas.

channelsarray

sitevenddor_appclient_app

Canais permitidos. Se enviado, precisa ter ao menos um código válido (veja Canais de exibição). Omitido = todos os canais.

devicesarray

mobiletabletdesktop

Dispositivos permitidos. Omitido = todos.

positionintegerpadrão: 0

Ordem no carrossel.

typestringpadrão: G

GT

G gráfico (padrão) ou T texto. Banner de texto dispensa imagem.

targetstringpadrão: T

TB

T mesma janela (padrão) ou B nova janela.

descriptionstring

Corpo HTML do banner de texto (sanitizado).

overlay_titlestring

Título sobre a imagem.

overlay_subtitlestring

Subtítulo sobre a imagem.

overlay_button_textstring

Texto do botão.

overlay_button_urlstring

Destino do botão.

overlay_text_colorstring

Cor do texto (hexadecimal).

overlay_button_colorstring

Cor do botão (hexadecimal).

overlay_positionstring

leftcenterright

Posição horizontal do texto.

vendor_iduuid

Atribui o banner a um seller. Omita para banner da loja.

descriptionsobject

Nome e descrição por idioma, com chave no código do idioma. Idiomas omitidos herdam name.

created_atstring

Data de criação (RFC 3339). Omitida = momento da chamada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/banners" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Black Friday 2026",
  "image_url": "https://cdn.minhaloja.com.br/banners/bf-2026.png",
  "alt_text": "Ofertas de Black Friday",
  "status": "scheduled",
  "starts_at": "2026-11-27T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "channels": [
    "site"
  ],
  "devices": [
    "mobile",
    "desktop"
  ]
}'

Resposta

201Banner criado

json

{
  "id": "d76f2753-a934-44a7-881f-146aa7438c7b",
  "name": "Black Friday 2026",
  "image_url": "https://cdn.minhaloja.com.br/banners/bf-2026.png",
  "alt_text": "Ofertas de Black Friday",
  "position": 0,
  "status": "scheduled",
  "usergroup_ids": "",
  "starts_at": "2026-11-27T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "target_pages": [],
  "target_categories": [],
  "created_at": "2026-10-11T21:04:55.045564Z",
  "overlay_position": "left",
  "type": "G",
  "target": "T",
  "description": "",
  "channels": [
    "site"
  ],
  "devices": [
    "mobile",
    "desktop"
  ],
  "banner_id": "d76f2753-a934-44a7-881f-146aa7438c7b",
  "banner": "Black Friday 2026",
  "image_path": "https://cdn.minhaloja.com.br/banners/bf-2026.png"
}

Campos da resposta

iduuid

Identificador do banner.

namestring

Nome interno do banner (texto puro).

image_urlstring

Imagem principal. Vazia em banner de texto.

mobile_image_urlstring

Arte própria para celular. Ausente quando não há; a vitrine então recorta a imagem principal.

link_urlstring

Destino do clique. Ausente quando o banner não tem link.

alt_textstring

Texto alternativo da imagem.

positioninteger

Ordem no carrossel. Menor aparece primeiro.

statusstring

active, inactive, scheduled ou hidden.

usergroup_idsstring

Grupos de clientes que veem o banner (ids separados por vírgula). Vazio significa todos.

starts_atstring

Início da exibição, RFC 3339. Ausente = sem início.

ends_atstring

Fim da exibição, RFC 3339. Ausente = sem fim.

target_pagesarray

Slugs das páginas onde o banner aparece. Lista vazia = em todas.

target_categoriesarray

Ids de categorias onde o banner aparece. Lista vazia = em todas.

vendor_iduuid

Seller dono do banner. Ausente em banner da loja.

overlay_titlestring

Título sobreposto à imagem.

overlay_subtitlestring

Subtítulo sobreposto.

overlay_button_textstring

Texto do botão sobreposto.

overlay_button_urlstring

Destino do botão sobreposto.

overlay_text_colorstring

Cor do texto sobreposto (hexadecimal).

overlay_button_colorstring

Cor do botão sobreposto (hexadecimal).

overlay_positionstring

leftcenterright

Posição horizontal do texto.

typestring

G banner gráfico (imagem) ou T banner de texto.

targetstring

T abre no mesmo lugar, B abre em nova janela.

descriptionstring

Corpo HTML do banner de texto.

channelsarray

Canais em que o banner aparece. null = todos.

devicesarray

Dispositivos em que o banner aparece. null = todos.

created_atstring

Criação, RFC 3339.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_content"}`
400	Corpo inválido, ou falta `name`/`image_url` num banner gráfico.	`{"error":"name and image_url are required"}`
400	Dado inválido: status, canal ou dispositivo desconhecido, URL não http(s) ou apontando para rede interna, janela de datas invertida.	`{"error":"invalid input","detail":"invalid_channel: unknown channel \"tv\""}`

Veja também

POSTCriar banner

Cria um banner gráfico ou de texto, com janela de datas e segmentação.

POST/api/v1/admin/bannersAdmin

Cria um banner da vitrine

Rota ligada ao módulo banners: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_content.

Corpo da requisição

namestringobrigatório

Nome do banner (HTML é removido).

image_urlstring

Imagem. Obrigatória em banner gráfico. Aceita URL https:// pública ou um caminho /uploads/... da própria loja; outros esquemas e endereços de rede interna são recusados.

mobile_image_urlstring

Arte para celular, com as mesmas regras de image_url.

link_urlstring

Destino do clique, mesmas regras de URL.

alt_textstring

Texto alternativo.

statusstringpadrão: active

activeinactivescheduledhidden

Estado do banner. Omitido = active. Só active é exibido; scheduled fica guardado como rascunho e não liga sozinho.

starts_atstring

Início da exibição (RFC 3339).

ends_atstring

Fim da exibição (RFC 3339). Não pode ser anterior a starts_at.

usergroup_idsstring

Ids de grupos de clientes separados por vírgula. Vazio = todos.

target_pagesarray

Slugs de páginas onde exibir. Vazio = em todas.

target_categoriesarray

Ids de categorias onde exibir. Vazio = em todas.

channelsarray

sitevenddor_appclient_app

Canais permitidos. Se enviado, precisa ter ao menos um código válido (veja Canais de exibição). Omitido = todos os canais.

devicesarray

mobiletabletdesktop

Dispositivos permitidos. Omitido = todos.

positionintegerpadrão: 0

Ordem no carrossel.

typestringpadrão: G

GT

G gráfico (padrão) ou T texto. Banner de texto dispensa imagem.

targetstringpadrão: T

TB

T mesma janela (padrão) ou B nova janela.

descriptionstring

Corpo HTML do banner de texto (sanitizado).

overlay_titlestring

Título sobre a imagem.

overlay_subtitlestring

Subtítulo sobre a imagem.

overlay_button_textstring

Texto do botão.

overlay_button_urlstring

Destino do botão.

overlay_text_colorstring

Cor do texto (hexadecimal).

overlay_button_colorstring

Cor do botão (hexadecimal).

overlay_positionstring

leftcenterright

Posição horizontal do texto.

vendor_iduuid

Atribui o banner a um seller. Omita para banner da loja.

descriptionsobject

Nome e descrição por idioma, com chave no código do idioma. Idiomas omitidos herdam name.

created_atstring

Data de criação (RFC 3339). Omitida = momento da chamada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/banners" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Black Friday 2026",
  "image_url": "https://cdn.minhaloja.com.br/banners/bf-2026.png",
  "alt_text": "Ofertas de Black Friday",
  "status": "scheduled",
  "starts_at": "2026-11-27T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "channels": [
    "site"
  ],
  "devices": [
    "mobile",
    "desktop"
  ]
}'

Resposta

201Banner criado

json

{
  "id": "d76f2753-a934-44a7-881f-146aa7438c7b",
  "name": "Black Friday 2026",
  "image_url": "https://cdn.minhaloja.com.br/banners/bf-2026.png",
  "alt_text": "Ofertas de Black Friday",
  "position": 0,
  "status": "scheduled",
  "usergroup_ids": "",
  "starts_at": "2026-11-27T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "target_pages": [],
  "target_categories": [],
  "created_at": "2026-10-11T21:04:55.045564Z",
  "overlay_position": "left",
  "type": "G",
  "target": "T",
  "description": "",
  "channels": [
    "site"
  ],
  "devices": [
    "mobile",
    "desktop"
  ],
  "banner_id": "d76f2753-a934-44a7-881f-146aa7438c7b",
  "banner": "Black Friday 2026",
  "image_path": "https://cdn.minhaloja.com.br/banners/bf-2026.png"
}

Campos da resposta

iduuid

Identificador do banner.

namestring

Nome interno do banner (texto puro).

image_urlstring

Imagem principal. Vazia em banner de texto.

mobile_image_urlstring

Arte própria para celular. Ausente quando não há; a vitrine então recorta a imagem principal.

link_urlstring

Destino do clique. Ausente quando o banner não tem link.

alt_textstring

Texto alternativo da imagem.

positioninteger

Ordem no carrossel. Menor aparece primeiro.

statusstring

active, inactive, scheduled ou hidden.

usergroup_idsstring

Grupos de clientes que veem o banner (ids separados por vírgula). Vazio significa todos.

starts_atstring

Início da exibição, RFC 3339. Ausente = sem início.

ends_atstring

Fim da exibição, RFC 3339. Ausente = sem fim.

target_pagesarray

Slugs das páginas onde o banner aparece. Lista vazia = em todas.

target_categoriesarray

Ids de categorias onde o banner aparece. Lista vazia = em todas.

vendor_iduuid

Seller dono do banner. Ausente em banner da loja.

overlay_titlestring

Título sobreposto à imagem.

overlay_subtitlestring

Subtítulo sobreposto.

overlay_button_textstring

Texto do botão sobreposto.

overlay_button_urlstring

Destino do botão sobreposto.

overlay_text_colorstring

Cor do texto sobreposto (hexadecimal).

overlay_button_colorstring

Cor do botão sobreposto (hexadecimal).

overlay_positionstring

leftcenterright

Posição horizontal do texto.

typestring

G banner gráfico (imagem) ou T banner de texto.

targetstring

T abre no mesmo lugar, B abre em nova janela.

descriptionstring

Corpo HTML do banner de texto.

channelsarray

Canais em que o banner aparece. null = todos.

devicesarray

Dispositivos em que o banner aparece. null = todos.

created_atstring

Criação, RFC 3339.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_content"}`
400	Corpo inválido, ou falta `name`/`image_url` num banner gráfico.	`{"error":"name and image_url are required"}`
400	Dado inválido: status, canal ou dispositivo desconhecido, URL não http(s) ou apontando para rede interna, janela de datas invertida.	`{"error":"invalid input","detail":"invalid_channel: unknown channel \"tv\""}`