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

Posts do blog

Lista as categorias do blog, os posts publicados com filtros e lê um post pelo slug.

O blog da loja publica artigos (guias de compra, novidades, receitas) que atraem busca orgânica e ajudam a vender. Estas rotas servem a vitrine: as categorias para o filtro, a lista de posts para a página inicial do blog e o post completo para a leitura.

Pontos principais
  • Depende do módulo blog.
  • Só posts publicados e já no ar entram. Um post com published_at no futuro (agendado) fica escondido até a hora chegar.
  • O body do post é texto Markdown ou HTML cadastrado no painel. Renderize no cliente e sanitize.
  • Cada leitura de um post (GET .../posts/{slug}) soma 1 em view_count, inclusive leituras de robôs.
  • Só posts da loja aparecem. Posts de seller ficam na vitrine do seller.
  • Idioma: a lista só traz posts que têm texto no idioma pedido (?lang= ou Accept-Language). Um navegador em inglês que manda Accept-Language: en-US recebe a lista vazia se os posts só existem em pt-BR. A leitura por slug, ao contrário, cai em outro idioma e devolve o post.
GET/api/v1/storefront/blog/categoriesPública

Listar as categorias do blog

Parâmetros de consulta

langstringpadrão: pt-BR
Idioma do nome e da descrição. Também aceita Accept-Language.

Exemplo de requisição

Resposta

200Categorias

Campos da resposta

categoriesarray
Categorias ativas. [] quando não há nenhuma.
categories[].iduuid
Id da categoria. É o valor de category_id no filtro de posts.
categories[].namestring
Nome.
categories[].slugstring
Identificador na URL.
categories[].descriptionstring
Descrição. Ausente quando não há.
categories[].parent_iduuid
Categoria mãe. Ausente na raiz.
categories[].statusstring
Letra do estado. Aqui sempre A (ativa).
categories[].sort_orderinteger
Ordem de exibição.
categories[].created_atstring
Criação (RFC 3339).
categories[].updated_atstring
Última alteração (RFC 3339).
totalinteger
Quantidade de categorias.

Cada categoria traz também apelidos dos campos principais (category_id, category, seo_name, timestamp, updated_timestamp).

Erros

StatusQuandoCorpo
403Módulo blog desligado.{"error":"module_disabled","module":"blog"}
500Falha ao consultar.{"error":"failed to list blog categories","detail":"..."}
GET/api/v1/storefront/blog/postsPública

Listar os posts publicados

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora da faixa, vale 20.
category_iduuid
Só posts desta categoria. Um valor que não é UUID gera 500.
searchstring
Busca no título e no resumo (excerpt), sem diferenciar maiúsculas de minúsculas.
langstringpadrão: pt-BR
Idioma dos posts. Veja o aviso sobre idioma nos pontos principais.

Exemplo de requisição

Resposta

200Posts

Campos da resposta

postsarray
Posts da página, do mais recente para o mais antigo (por published_at). [] quando não há nenhum.
posts[].iduuid
Id do post. É o postId das rotas de comentários.
posts[].titlestring
Título no idioma pedido.
posts[].slugstring
Identificador na URL.
posts[].excerptstring
Resumo. Ausente quando não há.
posts[].bodystring
Texto completo. Ausente quando não há.
posts[].featured_imagestring
Imagem de destaque. Ausente quando não há.
posts[].author_iduuid
Id do autor. Ausente quando não há.
posts[].category_iduuid
Categoria do post. Ausente quando não há.
posts[].category_namestring
Nome da categoria. Ausente quando não há.
posts[].tagsarray
Etiquetas do post (lista de textos).
posts[].meta_titlestring
Título para buscadores.
posts[].meta_descriptionstring
Descrição para buscadores.
posts[].published_atstring
Quando foi ou será publicado (RFC 3339).
posts[].view_countinteger
Quantas vezes o post foi lido.
posts[].statusstring
Letra do estado. Aqui sempre A (publicado).
posts[].created_atstring
Criação (RFC 3339).
posts[].updated_atstring
Última alteração (RFC 3339).
totalinteger
Total de posts que combinam com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Total de páginas.

Cada post traz também apelidos dos campos principais: post_id, page_id, page_title, seo_name, description (igual a body), short_description (igual a excerpt), timestamp, updated_timestamp, published_timestamp e company_id (igual a author_id).

Erros

StatusQuandoCorpo
403Módulo blog desligado.{"error":"module_disabled","module":"blog"}
500category_id que não é UUID, ou falha ao consultar.{"error":"failed to list blog posts","detail":"..."}
GET/api/v1/storefront/blog/posts/{slug}Pública

Ler um post pelo slug

Parâmetros de caminho

slugstringobrigatório
slug do post.

Parâmetros de consulta

langstringpadrão: pt-BR
Idioma preferido. Se o post não tiver texto nele, a plataforma devolve outro idioma disponível.
200Post encontrado

Campos da resposta

(campos do post)object
Os mesmos campos de posts[] da lista, com os mesmos apelidos.

Erros

StatusQuandoCorpo
403Módulo blog desligado.{"error":"module_disabled","module":"blog"}
404Não há post publicado da loja com esse slug.{"error":"blog post not found"}
500Falha ao consultar.{"error":"failed to get blog post","detail":"..."}
Deixe o idioma explícito

Se o seu site tem mais de um idioma, mande sempre ?lang= na lista de posts e use um idioma que a loja realmente traduziu. Sem isso, um visitante com o navegador em um idioma sem tradução vê um blog vazio, mesmo existindo posts.

Veja também

  • Comentários do blog
  • Páginas
  • Paginação
Anterior
Páginas
Próxima
Comentários do blog
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/blog/categories"
bash
curl "$BASE_URL/api/v1/storefront/blog/posts?per_page=10&search=mouse&lang=pt-BR"
bash
curl "$BASE_URL/api/v1/storefront/blog/posts/como-escolher-o-mouse-perfeito-para-o-seu-dia-a-dia"
json
{
  "categories": [
    {
      "id": "4e733a25-349a-4598-a916-a0984fc4aa76",
      "name": "Novidades",
      "slug": "novidades",
      "status": "A",
      "sort_order": 0,
      "created_at": "2026-07-31T23:57:31Z",
      "updated_at": "2026-07-31T23:57:31Z"
    }
  ],
  "total": 1
}
json
{
  "posts": [
    {
      "id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "title": "Como escolher o mouse perfeito para o seu dia a dia",
      "slug": "como-escolher-o-mouse-perfeito-para-o-seu-dia-a-dia",
      "excerpt": "Guia prático com 5 passos para escolher o mouse ideal.",
      "body": "## Por que o mouse importa mais do que parece\n\nPassamos horas com a mão sobre o mouse todos os dias...",
      "author_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "tags": [],
      "published_at": "2026-09-09T14:52:00Z",
      "view_count": 12,
      "created_at": "2026-09-09T14:52:13Z",
      "updated_at": "2026-09-09T14:56:05Z",
      "status": "A"
    }
  ],
  "total": 9,
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}
json
{
  "id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "title": "Como escolher o mouse perfeito para o seu dia a dia",
  "slug": "como-escolher-o-mouse-perfeito-para-o-seu-dia-a-dia",
  "excerpt": "Guia prático com 5 passos para escolher o mouse ideal.",
  "body": "## Por que o mouse importa mais do que parece\n\nPassamos horas com a mão sobre o mouse todos os dias...",
  "author_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "tags": [],
  "published_at": "2026-09-09T14:52:00Z",
  "view_count": 13,
  "created_at": "2026-09-09T14:52:13Z",
  "updated_at": "2026-09-09T14:56:05Z",
  "status": "A"
}