VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Banners

Listar e consultar banners

Lista os banners com filtros, consulta um banner e lê os canais de exibição disponíveis.

Listar banners

Devolve todos os banners, inclusive os inativos e os de sellers, sem paginação. Use os filtros para separar por canal, dispositivo ou dono.

GET/api/v1/admin/bannersAdmin

Lista os banners da loja

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 consulta

searchstring
Texto contido no nome, sem diferenciar maiúsculas.
channelstring
sitevenddor_appclient_app
Só banners que aparecem nesse canal (os sem restrição de canal também entram).
devicestring
mobiletabletdesktop
Só banners que aparecem nesse dispositivo (os sem restrição também entram).
vendor_iduuid
Só banners desse seller. Tem prioridade sobre marketplace_only.
marketplace_onlyboolean
Com true, 1 ou yes, só banners da loja.

Exemplo de requisição (Listar banners)

bash
curl "$BASE_URL/api/v1/admin/banners?channel=site&device=mobile" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar banners)

200Banners
json
{
  "banners": [
    {
      "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"
    }
  ],
  "total": 1
}

Campos da resposta

bannersarray

Banners que atendem ao filtro.

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.
totalinteger
Quantidade de banners devolvidos (não há paginação).

Erros (Listar banners)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}
500Falha ao consultar.{"error":"failed to list banners","detail":"..."}
Campos repetidos

A resposta traz também campos que repetem outros valores (banner_id, banner, image_path, timestamp). Em integrações novas use id, name e image_url.

Consultar banner

Devolve um banner completo. Com include_descriptions=1 a resposta vira um objeto com o banner e o nome/descrição em cada idioma, útil para montar um editor com abas de idioma.

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

Devolve um banner pelo id

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.

Parâmetros de consulta

include_descriptionsstring
1
Com 1, devolve {banner, descriptions} em vez do banner puro.

Exemplo de requisição (Consultar banner)

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

Resposta (Consultar banner)

200Banner
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"
}
200Com traduções (include_descriptions=1)
json
{
  "banner": {
    "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"
  },
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "name": "Black Friday 2026",
      "description": ""
    },
    "en": {
      "lang_code": "en",
      "name": "Black Friday 2026",
      "description": ""
    }
  }
}

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 (Consultar banner)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}
404O id não é um UUID ou não existe banner com ele.{"error":"banner not found","detail":"id inválido"}
500Falha de banco.{"error":"failed to get banner","detail":"..."}
Campos repetidos

A resposta traz também campos que repetem outros valores (banner_id, banner, image_path, timestamp). Em integrações novas use id, name e image_url.

Canais de exibição

Um canal é uma superfície digital da plataforma: o site, o app do vendedor, o app do cliente. O formulário de banner lê esta lista para montar as opções, e novos canais entram aqui sem mudar a tela. Use os códigos devolvidos no campo channels ao criar ou alterar um banner.

GET/api/v1/admin/banners/display-channelsAdmin

Lista os canais em que um banner pode aparecer

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.

Exemplo de requisição (Canais de exibição)

bash
curl "$BASE_URL/api/v1/admin/banners/display-channels" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Canais de exibição)

200Canais
json
{
  "channels": [
    {
      "code": "site",
      "name": "Site",
      "active": true
    },
    {
      "code": "venddor_app",
      "name": "Venddor App",
      "active": true
    },
    {
      "code": "client_app",
      "name": "Client App",
      "active": true
    }
  ]
}

Campos da resposta

channelsarray

Canais registrados.

codestring
Código a enviar em channels.
namestring
Nome para exibir.
activeboolean
Canal ativo. Um canal desativado ainda pode ficar selecionado em banners antigos.

Erros (Canais de exibição)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}

Veja também

  • Criar banner
  • Alterar e apagar
Anterior
Banners
Próxima
Criar banner
Nesta página
  • Listar banners
  • Exemplo de requisição (Listar banners)
  • Resposta (Listar banners)
  • Erros (Listar banners)
  • Consultar banner
  • Exemplo de requisição (Consultar banner)
  • Resposta (Consultar banner)
  • Erros (Consultar banner)
  • Canais de exibição
  • Exemplo de requisição (Canais de exibição)
  • Resposta (Canais de exibição)
  • Erros (Canais de exibição)
  • Veja também