API atual/Referência completa/Engajamento: extras

Páginas do app

Lista, cria, altera e apaga as páginas de conteúdo que o aplicativo mobile da loja exibe, como a página inicial do app.

O aplicativo mobile da loja não tem layout fixo: ele monta suas telas a partir de páginas do app. Cada página tem um slug (o nome na URL), um título, uma posição e a opção de aparecer na página inicial do app. Dentro da página ficam seções (listas de produtos, de categorias, carrossel de banners) que o app desenha de cima para baixo.

Estas quatro rotas administram a página em si. A leitura pública que o app faz fica na API da vitrine e devolve as seções já preenchidas com os produtos e categorias.

Todas as rotas exigem o módulo mobile-pages ligado (sem ele: 403 module_disabled). Ler exige view_content ou manage_content; criar, alterar e apagar exigem manage_content.

Listar páginas

GET/api/v1/admin/mobile-pagesAdmin

Listar as páginas ativas do app

Devolve as páginas com status A (ativas), ordenadas por position e depois por data de criação, com as seções de cada uma. Páginas desativadas não aparecem na lista, mas continuam acessíveis pelo id. Sem paginação, sem filtros.

bash

curl "$BASE_URL/api/v1/admin/mobile-pages" \
  -H "Authorization: Bearer $TOKEN"

200Páginas

json

{
  "pages": [
    {
      "id": "6d1b4a7e-3c0f-4a52-9e6b-1f6a2f0b9c11",
      "page_id": "6d1b4a7e-3c0f-4a52-9e6b-1f6a2f0b9c11",
      "slug": "home",
      "status": "A",
      "position": 0,
      "show_in_home": true,
      "storefront_id": "",
      "title": "Início",
      "description": "Página inicial do app",
      "sections": [
        {
          "id": "0f3c9d6a-2a2d-4f5c-8d5e-6d0a7c1b2e33",
          "section_id": "0f3c9d6a-2a2d-4f5c-8d5e-6d0a7c1b2e33",
          "type": "product_list",
          "position": 0,
          "status": "A",
          "settings": {},
          "content": { "source": "newest", "limit": 10, "items": [] }
        }
      ]
    }
  ]
}

Campos da resposta

pages[].iduuid

Id da página.

pages[].page_iduuid

Cópia de id, mantida por compatibilidade.

pages[].slugstring

Nome curto e único da página.

pages[].statusstring

Letra de status. A é ativa.

pages[].positioninteger

Ordem de exibição, do menor para o maior.

pages[].show_in_homeboolean

Se a página entra na lista da página inicial do app.

pages[].storefront_idstring

Vitrine à qual a página pertence. Vazio quando vale para a loja inteira.

pages[].titlestring

Título exibido.

pages[].descriptionstring

Descrição curta.

pages[].sectionsarray

Seções ativas, por position. Sempre um vetor, vazio quando não há.

pages[].sections[].typestring

Tipo da seção. product_list, category_list e banner_carousel recebem content.items preenchido pela plataforma na leitura.

pages[].sections[].contentobject

Configuração da seção. Em product_list: product_ids (lista), category_id ou source: "newest", e limit (1 a 50, padrão 10).

pages[].sections[].settingsobject

Reservado. Hoje sempre {}.

Criar uma página

POST/api/v1/admin/mobile-pagesAdmin

Criar uma página do app

Cria a página e devolve o registro criado, com sections vazio.

Corpo da requisição

slugstringobrigatório

Nome único da página, sem espaços (por exemplo ofertas).

statusstringpadrão: A

Letra de status. Vazio vira A.

positionintegerpadrão: 0

Ordem de exibição.

show_in_homebooleanpadrão: false

Se aparece na página inicial do app.

storefront_idstring

Vitrine da página. Só pode ser definida aqui; o PUT não a altera.

titlestring

Título.

descriptionstring

Descrição.

bash

curl -X POST "$BASE_URL/api/v1/admin/mobile-pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"ofertas","title":"Ofertas da semana","position":1,"show_in_home":true}'

201Página criada

json

{
  "id": "b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20",
  "page_id": "b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20",
  "slug": "ofertas",
  "status": "A",
  "position": 1,
  "show_in_home": true,
  "storefront_id": "",
  "title": "Ofertas da semana",
  "description": "",
  "sections": []
}

Alterar uma página

PUT/api/v1/admin/mobile-pages/{id}Admin

Alterar uma página do app

Grava de uma vez slug, status, position, show_in_home, title e description. Não é parcial: o que você omitir é gravado como vazio, zero ou falso. Envie sempre a página completa (leia, mude o que precisa, reenvie).

Parâmetros de caminho

iduuidobrigatório

Id da página.

Corpo da requisição

slugstringobrigatório

Slug da página. Se vier vazio, o slug é gravado vazio e a página deixa de ser encontrada por ele.

statusstringobrigatório

Letra de status (A ativa). Qualquer letra diferente de A (por exemplo D) tira a página da lista.

positionintegerobrigatório

Ordem de exibição.

show_in_homebooleanobrigatório

Se aparece na página inicial.

titlestringobrigatório

Título.

descriptionstring

Descrição.

bash

curl -X PUT "$BASE_URL/api/v1/admin/mobile-pages/b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"ofertas","status":"A","position":2,"show_in_home":false,"title":"Ofertas","description":""}'

200Página atualizada

A resposta é a página completa, no formato da criação, com as sections atuais. Se o id não existir, o corpo é null com status 200.

Apagar uma página

DELETE/api/v1/admin/mobile-pages/{id}Admin

Apagar uma página do app

Remove a página definitivamente. A operação é idempotente: apagar um id que não existe também responde 200.

Parâmetros de caminho

iduuidobrigatório

Id da página.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/mobile-pages/b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20" \
  -H "Authorization: Bearer $TOKEN"

200Página apagada

json

{ "ok": true }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido.	`{"error":"invalid json","detail":"..."}`
400	Criação sem `slug`.	`{"error":"failed to create mobile page","detail":"slug required"}`
400	Criação ou alteração rejeitada pelo banco (por exemplo `slug` repetido).	`{"error":"failed to update mobile page","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Módulo `mobile-pages` desligado.	`{"error":"module_disabled","module":"mobile-pages"}`
403	Sem o privilégio de conteúdo.	`{"error":"insufficient privileges","required":"manage_content"}`
500	Falha ao listar ou apagar.	`{"error":"failed to delete mobile page","detail":"..."}`
503	Serviço de páginas indisponível.	`{"error":"mobile pages unavailable"}`

Veja também

API atual/Referência completa/Engajamento: extras

Páginas do app

Lista, cria, altera e apaga as páginas de conteúdo que o aplicativo mobile da loja exibe, como a página inicial do app.

Estas quatro rotas administram a página em si. A leitura pública que o app faz fica na API da vitrine e devolve as seções já preenchidas com os produtos e categorias.

Todas as rotas exigem o módulo mobile-pages ligado (sem ele: 403 module_disabled). Ler exige view_content ou manage_content; criar, alterar e apagar exigem manage_content.

Listar páginas

GET/api/v1/admin/mobile-pagesAdmin

Listar as páginas ativas do app

bash

curl "$BASE_URL/api/v1/admin/mobile-pages" \
  -H "Authorization: Bearer $TOKEN"

200Páginas

json

{
  "pages": [
    {
      "id": "6d1b4a7e-3c0f-4a52-9e6b-1f6a2f0b9c11",
      "page_id": "6d1b4a7e-3c0f-4a52-9e6b-1f6a2f0b9c11",
      "slug": "home",
      "status": "A",
      "position": 0,
      "show_in_home": true,
      "storefront_id": "",
      "title": "Início",
      "description": "Página inicial do app",
      "sections": [
        {
          "id": "0f3c9d6a-2a2d-4f5c-8d5e-6d0a7c1b2e33",
          "section_id": "0f3c9d6a-2a2d-4f5c-8d5e-6d0a7c1b2e33",
          "type": "product_list",
          "position": 0,
          "status": "A",
          "settings": {},
          "content": { "source": "newest", "limit": 10, "items": [] }
        }
      ]
    }
  ]
}

Campos da resposta

pages[].iduuid

Id da página.

pages[].page_iduuid

Cópia de id, mantida por compatibilidade.

pages[].slugstring

Nome curto e único da página.

pages[].statusstring

Letra de status. A é ativa.

pages[].positioninteger

Ordem de exibição, do menor para o maior.

pages[].show_in_homeboolean

Se a página entra na lista da página inicial do app.

pages[].storefront_idstring

Vitrine à qual a página pertence. Vazio quando vale para a loja inteira.

pages[].titlestring

Título exibido.

pages[].descriptionstring

Descrição curta.

pages[].sectionsarray

Seções ativas, por position. Sempre um vetor, vazio quando não há.

pages[].sections[].typestring

Tipo da seção. product_list, category_list e banner_carousel recebem content.items preenchido pela plataforma na leitura.

pages[].sections[].contentobject

Configuração da seção. Em product_list: product_ids (lista), category_id ou source: "newest", e limit (1 a 50, padrão 10).

pages[].sections[].settingsobject

Reservado. Hoje sempre {}.

Criar uma página

POST/api/v1/admin/mobile-pagesAdmin

Criar uma página do app

Cria a página e devolve o registro criado, com sections vazio.

Corpo da requisição

slugstringobrigatório

Nome único da página, sem espaços (por exemplo ofertas).

statusstringpadrão: A

Letra de status. Vazio vira A.

positionintegerpadrão: 0

Ordem de exibição.

show_in_homebooleanpadrão: false

Se aparece na página inicial do app.

storefront_idstring

Vitrine da página. Só pode ser definida aqui; o PUT não a altera.

titlestring

Título.

descriptionstring

Descrição.

bash

curl -X POST "$BASE_URL/api/v1/admin/mobile-pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"ofertas","title":"Ofertas da semana","position":1,"show_in_home":true}'

201Página criada

json

{
  "id": "b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20",
  "page_id": "b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20",
  "slug": "ofertas",
  "status": "A",
  "position": 1,
  "show_in_home": true,
  "storefront_id": "",
  "title": "Ofertas da semana",
  "description": "",
  "sections": []
}

Alterar uma página

PUT/api/v1/admin/mobile-pages/{id}Admin

Alterar uma página do app

Parâmetros de caminho

iduuidobrigatório

Id da página.

Corpo da requisição

slugstringobrigatório

Slug da página. Se vier vazio, o slug é gravado vazio e a página deixa de ser encontrada por ele.

statusstringobrigatório

Letra de status (A ativa). Qualquer letra diferente de A (por exemplo D) tira a página da lista.

positionintegerobrigatório

Ordem de exibição.

show_in_homebooleanobrigatório

Se aparece na página inicial.

titlestringobrigatório

Título.

descriptionstring

Descrição.

bash

curl -X PUT "$BASE_URL/api/v1/admin/mobile-pages/b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"ofertas","status":"A","position":2,"show_in_home":false,"title":"Ofertas","description":""}'

200Página atualizada

A resposta é a página completa, no formato da criação, com as sections atuais. Se o id não existir, o corpo é null com status 200.

Apagar uma página

DELETE/api/v1/admin/mobile-pages/{id}Admin

Apagar uma página do app

Remove a página definitivamente. A operação é idempotente: apagar um id que não existe também responde 200.

Parâmetros de caminho

iduuidobrigatório

Id da página.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/mobile-pages/b2f0c8d4-71a9-4e61-8c35-0a9e5d7f4c20" \
  -H "Authorization: Bearer $TOKEN"

200Página apagada

json

{ "ok": true }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido.	`{"error":"invalid json","detail":"..."}`
400	Criação sem `slug`.	`{"error":"failed to create mobile page","detail":"slug required"}`
400	Criação ou alteração rejeitada pelo banco (por exemplo `slug` repetido).	`{"error":"failed to update mobile page","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Módulo `mobile-pages` desligado.	`{"error":"module_disabled","module":"mobile-pages"}`
403	Sem o privilégio de conteúdo.	`{"error":"insufficient privileges","required":"manage_content"}`
500	Falha ao listar ou apagar.	`{"error":"failed to delete mobile page","detail":"..."}`
503	Serviço de páginas indisponível.	`{"error":"mobile pages unavailable"}`