API legada/Referência completa/API de apps (token vat_)

Banners e páginas

Lista os banners da loja e cria ou altera páginas institucionais por token de app.

Um banner é uma imagem promocional da vitrine (carrossel da home, faixa de campanha). Uma página é um texto institucional ou de blog ("Sobre nós", "Trocas e devoluções"). Um app de conteúdo (um gerenciador de campanhas, um CMS externo) usa estas rotas para ler os banners e publicar páginas sem acessar o painel.

A leitura de banners exige o escopo read_content. Criar e alterar páginas exige write_content. Não há rota para criar banners nem para apagar páginas por token de app.

GET/api/admin/bannersAutenticada

Listar banners

Devolve os banners da loja inteira (os banners de seller não aparecem), em todas as situações: ativos, inativos e agendados, ordenados por position. Para mostrar só o que está no ar, filtre status igual a active no seu lado.

Parâmetros de consulta

searchstring

Texto contido no nome do banner, sem diferenciar maiúsculas.

channelstring

sitevenddor_appclient_app

Onde o banner será exibido. Se omitido, só voltam os banners sem restrição de canal.

devicestringpadrão: mobile

mobiletabletdesktop

Dispositivo. Omitido vale mobile.

POST/api/admin/pagesAutenticada

Criar uma página

Cria uma página. Se slug vier vazio, é gerado a partir do título; se já existir, a plataforma acrescenta -2, -3... A resposta é a página criada.

Corpo da requisição

titlestringobrigatório

Título da página. Obrigatório; HTML é removido.

bodystring

Conteúdo em HTML.

slugstring

Parte do endereço da página.

statusstringpadrão: active

activehidden

Se a página aparece (active) ou fica escondida (hidden). Qualquer outro valor, inclusive draft, vira active.

page_typestringpadrão: page

pagebloglink

Tipo da página. Outro valor vira page.

seo_titlestring

Título para buscadores.

seo_descriptionstring

Descrição para buscadores.

positionintegerpadrão: 0

Ordem entre as páginas.

PUT/api/admin/pages/{id}Autenticada

Alterar uma página

Alteração parcial: só os campos enviados mudam. Ao contrário da criação, aqui a situação é validada, não trocada.

Parâmetros de caminho

iduuidobrigatório

Id da página.

Corpo da requisição

titlestring

Novo título.

bodystring

Novo conteúdo em HTML.

slugstring

Novo slug. Se já estiver em uso por outra página, a alteração é recusada.

statusstring

activehiddendraftdisabled

Nova situação. Outro valor é recusado.

page_typestring

pagebloglink

Novo tipo.

seo_titlestring

Novo título para buscadores.

seo_descriptionstring

Nova descrição para buscadores.

positioninteger

Nova ordem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/admin/pages" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Trocas e devoluções",
  "body": "<p>Você tem 7 dias para devolver.</p>",
  "slug": "trocas-e-devolucoes",
  "status": "active",
  "page_type": "page",
  "seo_title": "Trocas e devoluções",
  "position": 2
}'

Listar banners:

bash

curl "$BASE_URL/api/admin/banners?channel=site&device=desktop" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Banners retornados

json

{
  "banners": [
    {
      "id": "a5e6b0e4-a17c-4d7f-b94a-020cc74f7965",
      "name": "Campanha de inverno",
      "image_url": "/uploads/banners/inverno.png",
      "alt_text": "Campanha de inverno com até 40% de desconto",
      "position": 0,
      "status": "active",
      "usergroup_ids": "",
      "target_pages": [],
      "target_categories": [],
      "created_at": "2026-07-11T21:22:52.255753Z",
      "overlay_title": "",
      "overlay_subtitle": "",
      "overlay_button_text": "",
      "overlay_button_url": "",
      "overlay_text_color": "#ffffff",
      "overlay_button_color": "#16a34a",
      "overlay_position": "left",
      "type": "G",
      "target": "T",
      "description": "",
      "channels": null,
      "devices": null
    }
  ],
  "total": 1
}

201Página criada

json

{
  "id": "378d3544-7918-4cb2-9b91-8a55bf2ea1cf",
  "title": "Trocas e devoluções",
  "slug": "trocas-e-devolucoes",
  "body": "<p>Você tem 7 dias para devolver.</p>",
  "status": "active",
  "page_type": "page",
  "seo_title": "Trocas e devoluções",
  "position": 2,
  "id_path": "",
  "created_at": "2026-10-11T21:15:49.847695Z",
  "updated_at": "2026-10-11T21:15:49.847695Z"
}

Campos da resposta

banners[].iduuid

Id do banner.

banners[].namestring

Nome interno.

banners[].image_urlstring

Imagem. Pode ser um caminho relativo (/uploads/...): junte com o endereço da loja.

banners[].mobile_image_urlstring

Imagem para celular, quando existe.

banners[].link_urlstring

Para onde o clique leva, quando existe.

banners[].alt_textstring

Texto alternativo da imagem.

banners[].positioninteger

Ordem no carrossel.

banners[].statusstring

activeinactivescheduled

Situação. scheduled depende de starts_at e ends_at.

banners[].starts_atstring

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

banners[].ends_atstring

Fim da exibição (RFC 3339), quando agendado.

banners[].target_pagesarray

Páginas (slugs) onde aparece. Vazio é em todas.

banners[].target_categoriesarray

Categorias (ids) onde aparece. Vazio é em todas.

banners[].channelsarray | null

Canais permitidos. null é todos.

banners[].devicesarray | null

Dispositivos permitidos. null é todos.

banners[].typestring

GT

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

banners[].targetstring

TB

T abre na mesma janela, B abre em nova janela.

banners[].overlay_*string

Título, subtítulo, botão (overlay_button_text, overlay_button_url) e cores/posição do texto sobre a imagem.

totalinteger

Quantidade de banners devolvidos. A lista não é paginada.

iduuid

(Página) Id da página criada ou alterada.

statusstring

activehiddendraftdisabled

(Página) Situação gravada.

id_pathstring

(Página) Caminho na hierarquia de páginas. Vazio quando a página está na raiz.

A página também pode trazer apelidos de compatibilidade (page_id, page_title, description, seo_name, timestamp). A alteração (PUT) responde 200 com a página no mesmo formato.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`title` ausente na criação	`{"error":"title is required"}`
401	Sem token de app	`{"error":"app_token_required"}`
403	Sem `read_content` ou `write_content`	`{"error":"missing_scope","required":"write_content"}`
500	`status` inválido na alteração	`{"error":"failed to update page","detail":"invalid page status \"x\": must be one of active, disabled, draft, hidden"}`
500	Página inexistente na alteração	`{"error":"failed to update page","detail":"page not found"}`
500	Slug já em uso na alteração	`{"error":"failed to update page","detail":"slug \"x\" already in use"}`

Veja também

Banners e páginas

Lista os banners da loja e cria ou altera páginas institucionais por token de app.

A leitura de banners exige o escopo read_content. Criar e alterar páginas exige write_content. Não há rota para criar banners nem para apagar páginas por token de app.

GET/api/admin/bannersAutenticada

Listar banners

Parâmetros de consulta

searchstring

Texto contido no nome do banner, sem diferenciar maiúsculas.

channelstring

sitevenddor_appclient_app

Onde o banner será exibido. Se omitido, só voltam os banners sem restrição de canal.

devicestringpadrão: mobile

mobiletabletdesktop

Dispositivo. Omitido vale mobile.

POST/api/admin/pagesAutenticada

Criar uma página

Cria uma página. Se slug vier vazio, é gerado a partir do título; se já existir, a plataforma acrescenta -2, -3... A resposta é a página criada.

Corpo da requisição

titlestringobrigatório

Título da página. Obrigatório; HTML é removido.

bodystring

Conteúdo em HTML.

slugstring

Parte do endereço da página.

statusstringpadrão: active

activehidden

Se a página aparece (active) ou fica escondida (hidden). Qualquer outro valor, inclusive draft, vira active.

page_typestringpadrão: page

pagebloglink

Tipo da página. Outro valor vira page.

seo_titlestring

Título para buscadores.

seo_descriptionstring

Descrição para buscadores.

positionintegerpadrão: 0

Ordem entre as páginas.

PUT/api/admin/pages/{id}Autenticada

Alterar uma página

Alteração parcial: só os campos enviados mudam. Ao contrário da criação, aqui a situação é validada, não trocada.

Parâmetros de caminho

iduuidobrigatório

Id da página.

Corpo da requisição

titlestring

Novo título.

bodystring

Novo conteúdo em HTML.

slugstring

Novo slug. Se já estiver em uso por outra página, a alteração é recusada.

statusstring

activehiddendraftdisabled

Nova situação. Outro valor é recusado.

page_typestring

pagebloglink

Novo tipo.

seo_titlestring

Novo título para buscadores.

seo_descriptionstring

Nova descrição para buscadores.

positioninteger

Nova ordem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/admin/pages" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Trocas e devoluções",
  "body": "<p>Você tem 7 dias para devolver.</p>",
  "slug": "trocas-e-devolucoes",
  "status": "active",
  "page_type": "page",
  "seo_title": "Trocas e devoluções",
  "position": 2
}'

Listar banners:

bash

curl "$BASE_URL/api/admin/banners?channel=site&device=desktop" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Banners retornados

json

{
  "banners": [
    {
      "id": "a5e6b0e4-a17c-4d7f-b94a-020cc74f7965",
      "name": "Campanha de inverno",
      "image_url": "/uploads/banners/inverno.png",
      "alt_text": "Campanha de inverno com até 40% de desconto",
      "position": 0,
      "status": "active",
      "usergroup_ids": "",
      "target_pages": [],
      "target_categories": [],
      "created_at": "2026-07-11T21:22:52.255753Z",
      "overlay_title": "",
      "overlay_subtitle": "",
      "overlay_button_text": "",
      "overlay_button_url": "",
      "overlay_text_color": "#ffffff",
      "overlay_button_color": "#16a34a",
      "overlay_position": "left",
      "type": "G",
      "target": "T",
      "description": "",
      "channels": null,
      "devices": null
    }
  ],
  "total": 1
}

201Página criada

json

{
  "id": "378d3544-7918-4cb2-9b91-8a55bf2ea1cf",
  "title": "Trocas e devoluções",
  "slug": "trocas-e-devolucoes",
  "body": "<p>Você tem 7 dias para devolver.</p>",
  "status": "active",
  "page_type": "page",
  "seo_title": "Trocas e devoluções",
  "position": 2,
  "id_path": "",
  "created_at": "2026-10-11T21:15:49.847695Z",
  "updated_at": "2026-10-11T21:15:49.847695Z"
}

Campos da resposta

banners[].iduuid

Id do banner.

banners[].namestring

Nome interno.

banners[].image_urlstring

Imagem. Pode ser um caminho relativo (/uploads/...): junte com o endereço da loja.

banners[].mobile_image_urlstring

Imagem para celular, quando existe.

banners[].link_urlstring

Para onde o clique leva, quando existe.

banners[].alt_textstring

Texto alternativo da imagem.

banners[].positioninteger

Ordem no carrossel.

banners[].statusstring

activeinactivescheduled

Situação. scheduled depende de starts_at e ends_at.

banners[].starts_atstring

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

banners[].ends_atstring

Fim da exibição (RFC 3339), quando agendado.

banners[].target_pagesarray

Páginas (slugs) onde aparece. Vazio é em todas.

banners[].target_categoriesarray

Categorias (ids) onde aparece. Vazio é em todas.

banners[].channelsarray | null

Canais permitidos. null é todos.

banners[].devicesarray | null

Dispositivos permitidos. null é todos.

banners[].typestring

GT

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

banners[].targetstring

TB

T abre na mesma janela, B abre em nova janela.

banners[].overlay_*string

Título, subtítulo, botão (overlay_button_text, overlay_button_url) e cores/posição do texto sobre a imagem.

totalinteger

Quantidade de banners devolvidos. A lista não é paginada.

iduuid

(Página) Id da página criada ou alterada.

statusstring

activehiddendraftdisabled

(Página) Situação gravada.

id_pathstring

(Página) Caminho na hierarquia de páginas. Vazio quando a página está na raiz.

A página também pode trazer apelidos de compatibilidade (page_id, page_title, description, seo_name, timestamp). A alteração (PUT) responde 200 com a página no mesmo formato.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`title` ausente na criação	`{"error":"title is required"}`
401	Sem token de app	`{"error":"app_token_required"}`
403	Sem `read_content` ou `write_content`	`{"error":"missing_scope","required":"write_content"}`
500	`status` inválido na alteração	`{"error":"failed to update page","detail":"invalid page status \"x\": must be one of active, disabled, draft, hidden"}`
500	Página inexistente na alteração	`{"error":"failed to update page","detail":"page not found"}`
500	Slug já em uso na alteração	`{"error":"failed to update page","detail":"slug \"x\" already in use"}`