VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Conteúdo da loja

Banners do seller

Lista, consulta, cria, altera e apaga os banners do microsite do seller.

O banner é o destaque visual do microsite. Pode ser gráfico (type: G, uma imagem com link) ou de texto (type: T, um bloco de HTML), com texto e botão opcionais sobre a imagem, janela de exibição e segmentação por página, categoria, canal e dispositivo.

Listar banners

GET/api/v1/vendor/bannersSeller

Lista os banners do seller

Todos os banners do seller, ativos ou não, por position crescente. Sem paginação.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/banners" \
  -H "Authorization: Bearer $TOKEN"
200Banners
json
{
  "banners": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "name": "Promoção de verão",
      "image_url": "https://cdn.exemplo.com.br/banners/verao.jpg",
      "link_url": "https://exemplo.com.br/promocao-verao",
      "alt_text": "Até 30% de desconto em chinelos",
      "position": 0,
      "status": "active",
      "usergroup_ids": "",
      "starts_at": "2026-11-01T00:00:00Z",
      "ends_at": "2026-11-30T23:59:59Z",
      "target_pages": [],
      "target_categories": [],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T12:00:00Z",
      "overlay_title": "Verão",
      "overlay_subtitle": "",
      "overlay_button_text": "Ver ofertas",
      "overlay_button_url": "https://exemplo.com.br/promocao-verao",
      "overlay_text_color": "#ffffff",
      "overlay_button_color": "#16a34a",
      "overlay_position": "left",
      "type": "G",
      "target": "T",
      "description": "",
      "channels": null,
      "devices": null
    }
  ],
  "total": 1
}

Campos da resposta

bannersarray

Banners do seller.

iduuid
Id do banner.
namestring
Nome interno.
image_urlstring
Imagem do banner (desktop).
mobile_image_urlstring
Imagem para celular. Ausente se não houver.
link_urlstring
Destino do clique. Ausente se não houver.
alt_textstring
Texto alternativo da imagem.
positioninteger
Ordem de exibição, do menor para o maior.
statusstring
activeinactivescheduledhidden
active, inactive, scheduled ou hidden.
usergroup_idsstring
Grupos de clientes que veem o banner, texto separado por vírgula. Vazio = 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 de páginas onde aparece. Vazio = em todas.
target_categoriesarray
Ids de categorias onde aparece. Vazio = em todas.
vendor_iduuid
Seller dono. Sempre o do token.
created_atstring
Criação (RFC 3339, UTC).
overlay_titlestring
Título sobre a imagem.
overlay_subtitlestring
Subtítulo sobre a imagem.
overlay_button_textstring
Texto do botão sobre a imagem.
overlay_button_urlstring
Destino do botão.
overlay_text_colorstring
Cor do texto (hex). Padrão #ffffff.
overlay_button_colorstring
Cor do botão (hex). Padrão #16a34a.
overlay_positionstring
leftcenterright
Alinhamento do texto: left, center ou right.
typestring
GT
G banner gráfico (imagem) ou T banner de texto.
targetstring
TB
T abre na mesma janela, B em nova janela.
descriptionstring
HTML do banner de texto (tipo T).
channelsarray
Canais onde aparece: site, venddor_app, client_app. null = todos.
devicesarray
Dispositivos: mobile, tablet, desktop. null = todos.
banner_id, banner, image_path, timestampvarious
Campos de compatibilidade com a plataforma antiga (mesmos valores de id, name, image_url e criação em Unix). Ignore em integrações novas.
totalinteger
Quantidade de banners.

Consultar banner

GET/api/v1/vendor/banners/{id}Seller

Devolve um banner

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do banner.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/banners/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"
200Banner
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Promoção de verão",
  "image_url": "https://cdn.exemplo.com.br/banners/verao.jpg",
  "link_url": "https://exemplo.com.br/promocao-verao",
  "alt_text": "Até 30% de desconto em chinelos",
  "position": 0,
  "status": "active",
  "usergroup_ids": "",
  "starts_at": "2026-11-01T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "target_pages": [],
  "target_categories": [],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "overlay_title": "Verão",
  "overlay_subtitle": "",
  "overlay_button_text": "Ver ofertas",
  "overlay_button_url": "https://exemplo.com.br/promocao-verao",
  "overlay_text_color": "#ffffff",
  "overlay_button_color": "#16a34a",
  "overlay_position": "left",
  "type": "G",
  "target": "T",
  "description": "",
  "channels": null,
  "devices": null
}

Campos da resposta

...object
Os campos de cada banner da lista.

Criar banner

POST/api/v1/vendor/bannersSeller

Cria um banner

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Corpo da requisição

namestringobrigatório
Nome interno do banner.
image_urlstring
Imagem. Aceita URL https:// ou http:// pública, ou um caminho da própria loja que comece com uma barra (/uploads/...). Banners gráficos precisam dela para mostrar algo. Endereços locais ou de rede interna são recusados.
mobile_image_urlstring
Imagem para celular, mesmas regras de image_url.
link_urlstring
Destino do clique, mesmas regras de image_url.
alt_textstring
Texto alternativo. Tags HTML são removidas.
statusstringpadrão: active
activeinactivescheduledhidden
Estado. Aceita active, inactive, scheduled, hidden (também a letra A, D, R, H). Vazio vira active.
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.
positionintegerpadrão: 0
Ordem de exibição.
usergroup_idsstring
Grupos de clientes que veem o banner, texto separado por vírgulas. Omita para todos.
created_atstring
Data de criação (RFC 3339). Omita para usar o momento atual.
descriptionsobject
Nomes e textos por idioma, indexados pelo código do idioma. Cada valor tem lang_code, name e description opcional. Idiomas omitidos herdam o name.
typestring
GT
G (padrão) ou T.
targetstring
TB
T (padrão) ou B.
descriptionstring
HTML do banner de texto. Scripts e eventos são removidos.
target_pagesarray
Slugs de páginas onde mostrar.
target_categoriesarray
Ids de categorias onde mostrar.
channelsarray
Lista de canais. Lista vazia é recusada; omita para todos.
devicesarray
Lista de dispositivos. Lista vazia é recusada; omita para todos.
overlay_title / overlay_subtitle / overlay_button_text / overlay_button_url / overlay_text_color / overlay_button_color / overlay_positionstring
Texto e botão sobre a imagem. overlay_position aceita left, center, right; outro valor vira left.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/banners" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Promoção de verão",
  "image_url": "https://cdn.exemplo.com.br/banners/verao.jpg",
  "link_url": "https://exemplo.com.br/promocao-verao",
  "alt_text": "Até 30% de desconto em chinelos",
  "status": "active",
  "starts_at": "2026-11-01T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z"
}'
201Banner criado
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Promoção de verão",
  "image_url": "https://cdn.exemplo.com.br/banners/verao.jpg",
  "link_url": "https://exemplo.com.br/promocao-verao",
  "alt_text": "Até 30% de desconto em chinelos",
  "position": 0,
  "status": "active",
  "usergroup_ids": "",
  "starts_at": "2026-11-01T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "target_pages": [],
  "target_categories": [],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "overlay_title": "Verão",
  "overlay_subtitle": "",
  "overlay_button_text": "Ver ofertas",
  "overlay_button_url": "https://exemplo.com.br/promocao-verao",
  "overlay_text_color": "#ffffff",
  "overlay_button_color": "#16a34a",
  "overlay_position": "left",
  "type": "G",
  "target": "T",
  "description": "",
  "channels": null,
  "devices": null
}

Alterar banner

PUT/api/v1/vendor/banners/{id}Seller

Altera um banner

Parcial: só os campos enviados mudam. Os mesmos campos do corpo da criação. Não é possível trocar o dono.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do banner.

Corpo da requisição

...object
Qualquer campo do corpo da criação, todos opcionais.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/banners/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "inactive"
}'
200Banner atualizado
json
{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "name": "Promoção de verão",
  "image_url": "https://cdn.exemplo.com.br/banners/verao.jpg",
  "link_url": "https://exemplo.com.br/promocao-verao",
  "alt_text": "Até 30% de desconto em chinelos",
  "position": 0,
  "status": "inactive",
  "usergroup_ids": "",
  "starts_at": "2026-11-01T00:00:00Z",
  "ends_at": "2026-11-30T23:59:59Z",
  "target_pages": [],
  "target_categories": [],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T12:00:00Z",
  "overlay_title": "Verão",
  "overlay_subtitle": "",
  "overlay_button_text": "Ver ofertas",
  "overlay_button_url": "https://exemplo.com.br/promocao-verao",
  "overlay_text_color": "#ffffff",
  "overlay_button_color": "#16a34a",
  "overlay_position": "left",
  "type": "G",
  "target": "T",
  "description": "",
  "channels": null,
  "devices": null
}

Apagar banner

DELETE/api/v1/vendor/banners/{id}Seller

Apaga um banner

Remoção definitiva. Para só esconder, altere o status.

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório
Id do banner.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/banners/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"
200Banner apagado
json
{
  "message": "banner deleted"
}

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário do seller (equipe) não tem nenhum dos privilégios exigidos. O dono da loja nunca recebe este erro.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
403O usuário autenticado não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}
400JSON inválido.{"error":"invalid request body","detail":"..."}
400Status desconhecido.{"error":"invalid_status: unknown banner status"}
400ends_at anterior a starts_at.{"error":"invalid_date_range: ends_at must be on or after starts_at"}
400URL de imagem ou link que não é http(s) nem caminho da loja, ou que aponta para rede interna.{"error":"invalid_image_url: image_url must be http:// or https://"}
400type ou target inválido; channels/devices vazio ou desconhecido.{"error":"invalid_type: type must be G (Banner gráfico) or T (Banner de texto)"}
404O banner não existe ou é de outro seller.{"error":"banner not found"}
A palavra scheduled não agenda

No banner, scheduled é guardado como rascunho. A janela starts_at/ends_at só vale para banners active: para um banner aparecer só em novembro, deixe-o active e defina as duas datas. As mensagens de erro de banner voltam em inglês, com o código à frente (invalid_image_url: ...).

Veja também

  • Páginas
  • Blog
  • Visão geral do conteúdo
Anterior
Conteúdo da loja do seller
Próxima
Páginas do seller
Nesta página
  • Listar banners
  • Exemplo de requisição
  • Consultar banner
  • Exemplo de requisição
  • Criar banner
  • Exemplo de requisição
  • Alterar banner
  • Exemplo de requisição
  • Apagar banner
  • Exemplo de requisição
  • Erros
  • Veja também