VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Registros da loja (1.0)

Páginas

Lista, lê, cria, altera e apaga as páginas institucionais da loja no formato da Venddor 1.0.

Uma página é um texto institucional da loja: "Sobre nós", "Política de trocas", "Como comprar". Cada página tem um título, um corpo em HTML, um tipo, uma situação e um endereço (slug). Estas rotas permitem a um CMS ou a um sistema de conteúdo manter as páginas sem abrir o painel.

A listagem traz só as páginas da loja (as páginas que um seller mantém na própria vitrine não aparecem). A leitura (GET) exige apenas um usuário autenticado; criar, alterar e apagar exigem administrador. A mesma rota existe sem /v1.0 (/api/pages).

GET/api/v1.0/pagesAutenticada

Listar páginas (API 1.0)

Devolve o resumo de cada página. O corpo vem em description.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 250. Fora disso volta a 10.
page_typestring
TLB
Tipo: T texto, L link, B blog.
statusstring
ADH
Situação: A ativa, D desativada, H escondida.
qstring
Texto procurado no título e no slug da página.
GET/api/v1.0/pages/{id}Autenticada

Ler uma página (API 1.0)

Devolve a página completa, com os campos de SEO.

Parâmetros de caminho

iduuidobrigatório
Id da página, em UUID. Na forma /api/pages/{id} também só o UUID é aceito.
POST/api/v1.0/pagesAdmin

Criar uma página (API 1.0)

Cria a página e devolve só o id. Se o slug já existe, a plataforma acrescenta -2, -3... em vez de recusar.

Corpo da requisição

pagestringobrigatório
Título da página (o nome do campo na 1.0 é page).
descriptionstring
Corpo da página, em HTML.
page_typestringpadrão: T
TLB
T texto, L link, B blog.
statusstringpadrão: A
ADH
A ativa, D desativada, H escondida.
slugstring
Endereço da página. Vazio gera a partir do título.
positionintegerpadrão: 0
Ordem entre as páginas.
meta_titlestring
Título para buscadores.
meta_descriptionstring
Descrição para buscadores.
PUT/api/v1.0/pages/{id}Admin

Alterar uma página (API 1.0)

Alteração parcial. Não altera meta_title nem meta_description: só a criação grava esses dois.

Parâmetros de caminho

iduuidobrigatório
Id da página.

Corpo da requisição

pagestring
Novo título.
descriptionstring
Novo corpo em HTML.
page_typestring
TLB
Novo tipo.
statusstring
ADH
Nova situação. Outro valor é recusado (500).
slugstring
Novo endereço. Se outra página já o usa, a alteração é recusada (500).
positioninteger
Nova ordem.
DELETE/api/v1.0/pages/{id}Admin

Apagar uma página (API 1.0)

Apaga a página. Responde 204 sem corpo.

Parâmetros de caminho

iduuidobrigatório
Id da página.
GET/api/pagesAutenticada

Listar páginas, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/pages. Os ids saem como decimais (veja o aviso abaixo).

GET/api/pages/{id}Autenticada

Ler uma página, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/pages/{id}.

POST/api/pagesAdmin

Criar uma página, sem o prefixo /v1.0

Idêntica a POST /api/v1.0/pages.

PUT/api/pages/{id}Admin

Alterar uma página, sem o prefixo /v1.0

Idêntica a PUT /api/v1.0/pages/{id}.

DELETE/api/pages/{id}Admin

Apagar uma página, sem o prefixo /v1.0

Idêntica a DELETE /api/v1.0/pages/{id}.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1.0/pages" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "page": "Política de trocas",
  "description": "<p>Você tem 7 dias para trocar.</p>",
  "page_type": "T",
  "status": "A",
  "slug": "politica-de-trocas",
  "position": 2,
  "meta_title": "Política de trocas"
}'

Listar as páginas ativas:

bash
curl "$BASE_URL/api/v1.0/pages?status=A&items_per_page=20" \
  -u "$EMAIL:$API_KEY"

Resposta

200Lista de páginas
json
{
  "pages": [
    {
      "page_id": "751d5a75-1165-4953-bd6c-09f9517ebc7a",
      "page": "Sobre nós",
      "page_type": "T",
      "description": "<p><strong>Quem somos.</strong> Na nossa loja ...</p>",
      "status": "A",
      "slug": "sobre-nos",
      "timestamp": 1788965088
    }
  ],
  "params": { "page": 1, "items_per_page": 20, "total_items": 32 }
}
200Página lida
json
{
  "page_id": "09ca5bc2-3419-4454-8461-d25b89c0653a",
  "page": "Política de trocas",
  "page_type": "T",
  "parent_id": 0,
  "description": "<p>Você tem 7 dias para trocar.</p>",
  "status": "H",
  "position": 3,
  "slug": "politica-de-trocas",
  "timestamp": 1791752926,
  "meta_title": "Política de trocas",
  "meta_description": "",
  "meta_keywords": "",
  "usergroup_ids": "",
  "company_id": ""
}
201Página criada
json
{ "page_id": "09ca5bc2-3419-4454-8461-d25b89c0653a" }

Campos da resposta

page_idstring
Id da página (UUID; decimal na forma /api/pages).
pagestring
Título.
page_typestring
TLBFPC
Tipo em letra. Páginas criadas por esta API são T, L ou B.
descriptionstring
Corpo em HTML.
statusstring
ADH
Situação em letra.
slugstring
Endereço da página.
timestampinteger
Criação em Unix timestamp (segundos, UTC).
parent_idinteger
Só na leitura de uma página. Id da página-mãe; 0 na raiz.
positioninteger
Só na leitura. Ordem entre as páginas.
meta_titlestring
Só na leitura. Título para buscadores.
meta_descriptionstring
Só na leitura. Descrição para buscadores.
meta_keywordsstring
Só na leitura. Sempre vazio.
usergroup_idsstring
Só na leitura. Sempre vazio.
company_idstring
Só na leitura. Sempre vazio.
paramsobject
Na lista: page, items_per_page e total_items.

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"message":"Invalid JSON","status":400}
400page (título) ausente na criação{"message":"Field 'page' (title) is required","status":400}
401Sem credencial{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403Escrita por quem não é administrador{"message":"Forbidden: admin scope required","status":403}
404Página inexistente (UUID válido){"message":"Page not found","status":404}
500Id que não é UUID{"message":"query page abc: ...","status":500}
500page_type fora de T, L, B na criação (por exemplo F){"message":"insert page: ...","status":500}
500Alteração ou remoção de página inexistente{"message":"page not found","status":500}
500status ou slug recusado na alteração{"message":"invalid page status ...","status":500}
Tipos F, P e C existem na leitura, mas não na criação

A 1.0 tinha páginas de formulário (F), de produto (P) e de categoria (C). Esta API as reconhece ao ler, mas criar uma página com esses tipos falha com 500. Crie sempre T (texto), L (link) ou B (blog).

Na forma /api/pages, o id da lista não volta

GET /api/pages devolve page_id como número decimal, mas GET /api/pages/{id} (e a alteração e a remoção) não aceitam esse número: respondem 500. Nessas rotas use o UUID. Guarde o UUID obtendo a lista pela forma /api/v1.0/pages.

Página criada como D ou H não aparece na loja

status: "A" publica a página. D e H a guardam sem exibir. A loja não tem um estado escondido separado para páginas: H é gravado como D, então uma página criada ou alterada com H volta como D na leitura, e filtrar por H devolve as mesmas páginas de D. O padrão, quando você não manda o campo, é A: a página é publicada na hora.

Veja também

  • Visão geral dos registros da loja
  • Autenticação
Anterior
Registros da loja (1.0)
Próxima
Pedidos de ligação
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também