Alterar e apagar banners

Atualiza parcialmente um banner, apaga um ou apaga vários de uma vez.

Atualizar banner

Atualiza só os campos enviados. As regras de validação são as mesmas da criação (URLs, canais, dispositivos, janela de datas). Para trocar a lista de canais ou dispositivos, envie a lista completa nova: ela substitui a anterior.

PUT/api/v1/admin/banners/{id}Admin

Altera campos de um banner

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.

Parâmetros de caminho

iduuidobrigatório

Identificador do banner.

Corpo da requisição

namestring

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.

statusstring

activeinactivescheduledhidden

Estado do banner. 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.

Exemplo de requisição (Atualizar banner)

bash

curl -X PUT "$BASE_URL/api/v1/admin/banners/d76f2753-a934-44a7-881f-146aa7438c7b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

Resposta (Atualizar banner)

200Banner atualizado

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": "active",
  "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 (Atualizar banner)

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"}`
404	O `id` não é um UUID ou não existe banner com ele.	`{"error":"banner not found","detail":"id inválido"}`
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\""}`
500	Banner inexistente (a plataforma responde 500) ou falha de banco.	`{"error":"failed to update banner","detail":"banner not found"}`

Apagar banner

Remove o banner de vez: não há lixeira para banners. Para tirá-lo da vitrine sem perder o cadastro, mude o status para inactive com a rota de atualização.

DELETE/api/v1/admin/banners/{id}Admin

Apaga um banner definitivamente

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.

Parâmetros de caminho

iduuidobrigatório

Identificador do banner.

Exemplo de requisição (Apagar banner)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/banners/d76f2753-a934-44a7-881f-146aa7438c7b" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar banner)

200Banner apagado

json

{
  "message": "banner deleted"
}

Erros (Apagar banner)

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"}`
404	O `id` não é um UUID ou não existe banner com ele.	`{"error":"banner not found","detail":"id inválido"}`
500	O banner não existe (ou já foi apagado). A plataforma responde 500 em vez de 404.	`{"error":"failed to delete banner","detail":"banner not found"}`

Apagar vários banners

Apaga de uma vez os banners cujos ids você enviar. A operação é idempotente: ids que não existem são ignorados em silêncio, e a resposta diz quantos foram de fato apagados.

POST/api/v1/admin/banners/bulk-deleteAdmin

Apaga uma lista de banners de uma vez

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

idsarrayobrigatório

Ids dos banners a apagar. Pelo menos um.

simulateboolean

Com true, não apaga: devolve a contagem e uma amostra do que seria apagado, mais um confirm_token para confirmar depois. Recurso avançado de operação em lote.

confirm_tokenstring

Token devolvido pela simulação, para executar a mesma operação.

Exemplo de requisição (Apagar vários banners)

bash

curl -X POST "$BASE_URL/api/v1/admin/banners/bulk-delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "d76f2753-a934-44a7-881f-146aa7438c7b",
    "5b6c1f3e-0d5a-4b53-9a0e-8c1a3f7b2d10"
  ]
}'

Resposta (Apagar vários banners)

200Resultado

json

{
  "deleted": 1,
  "requested": 2
}

Campos da resposta

deletedinteger

Banners realmente apagados.

requestedinteger

Ids recebidos.

Erros (Apagar vários banners)

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	`ids` ausente ou vazio, ou corpo inválido.	`{"error":"ids array is required"}`
500	Algum id não é UUID válido, ou falha de banco.	`{"error":"failed to bulk delete banners","detail":"..."}`

Veja também

API atual/Referência completa/Banners

Alterar e apagar banners

Atualiza parcialmente um banner, apaga um ou apaga vários de uma vez.

Atualizar banner

PUT/api/v1/admin/banners/{id}Admin

Altera campos de um banner

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.

Parâmetros de caminho

iduuidobrigatório

Identificador do banner.

Corpo da requisição

namestring

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.

statusstring

activeinactivescheduledhidden

Estado do banner. 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.

Exemplo de requisição (Atualizar banner)

bash

curl -X PUT "$BASE_URL/api/v1/admin/banners/d76f2753-a934-44a7-881f-146aa7438c7b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

Resposta (Atualizar banner)

200Banner atualizado

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": "active",
  "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 (Atualizar banner)

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"}`
404	O `id` não é um UUID ou não existe banner com ele.	`{"error":"banner not found","detail":"id inválido"}`
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\""}`
500	Banner inexistente (a plataforma responde 500) ou falha de banco.	`{"error":"failed to update banner","detail":"banner not found"}`

Apagar banner

Remove o banner de vez: não há lixeira para banners. Para tirá-lo da vitrine sem perder o cadastro, mude o status para inactive com a rota de atualização.

DELETE/api/v1/admin/banners/{id}Admin

Apaga um banner definitivamente

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.

Parâmetros de caminho

iduuidobrigatório

Identificador do banner.

Exemplo de requisição (Apagar banner)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/banners/d76f2753-a934-44a7-881f-146aa7438c7b" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar banner)

200Banner apagado

json

{
  "message": "banner deleted"
}

Erros (Apagar banner)

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"}`
404	O `id` não é um UUID ou não existe banner com ele.	`{"error":"banner not found","detail":"id inválido"}`
500	O banner não existe (ou já foi apagado). A plataforma responde 500 em vez de 404.	`{"error":"failed to delete banner","detail":"banner not found"}`

Apagar vários banners

Apaga de uma vez os banners cujos ids você enviar. A operação é idempotente: ids que não existem são ignorados em silêncio, e a resposta diz quantos foram de fato apagados.

POST/api/v1/admin/banners/bulk-deleteAdmin

Apaga uma lista de banners de uma vez

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

idsarrayobrigatório

Ids dos banners a apagar. Pelo menos um.

simulateboolean

Com true, não apaga: devolve a contagem e uma amostra do que seria apagado, mais um confirm_token para confirmar depois. Recurso avançado de operação em lote.

confirm_tokenstring

Token devolvido pela simulação, para executar a mesma operação.

Exemplo de requisição (Apagar vários banners)

bash

curl -X POST "$BASE_URL/api/v1/admin/banners/bulk-delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "d76f2753-a934-44a7-881f-146aa7438c7b",
    "5b6c1f3e-0d5a-4b53-9a0e-8c1a3f7b2d10"
  ]
}'

Resposta (Apagar vários banners)

200Resultado

json

{
  "deleted": 1,
  "requested": 2
}

Campos da resposta

deletedinteger

Banners realmente apagados.

requestedinteger

Ids recebidos.

Erros (Apagar vários banners)

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	`ids` ausente ou vazio, ou corpo inválido.	`{"error":"ids array is required"}`
500	Algum id não é UUID válido, ou falha de banco.	`{"error":"failed to bulk delete banners","detail":"..."}`