VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Blog

Listar e consultar posts

Lista os posts do blog com filtros e consulta um post pelo id.

Listar posts

Devolve os posts do blog, do mais recente para o mais antigo (pela data de publicação, ou de criação quando ainda é rascunho). Posts agendados e rascunhos aparecem aqui, mesmo que a vitrine os esconda.

GET/api/v1/admin/blog/postsAdmin

Lista os posts do blog

Rota ligada ao módulo blog: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_content.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, 1 a 100; fora disso vale 20.
statusstring
publisheddraftarchived
Filtra pelo estado. Aceita a palavra ou a letra.
category_iduuid
Só posts dessa categoria.
searchstring
Texto contido no título ou no resumo.
vendor_iduuid
Só posts desse seller.
marketplace_onlyboolean
Com true, 1 ou yes, só posts da loja.

Exemplo de requisição (Listar posts)

bash
curl "$BASE_URL/api/v1/admin/blog/posts?status=published&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar posts)

200Posts
json
{
  "posts": [
    {
      "id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "title": "Como escolher o mouse perfeito",
      "slug": "como-escolher-o-mouse-perfeito",
      "excerpt": "Guia prático com 5 passos.",
      "body": "<h2>Por que o mouse importa</h2><p>...</p>",
      "author_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "category_id": "4e733a25-349a-4598-a916-a0984fc4aa76",
      "category_name": "Guia de compras",
      "tags": [
        "mouse",
        "periféricos"
      ],
      "meta_title": "Como escolher o mouse perfeito",
      "meta_description": "Guia prático com 5 passos.",
      "published_at": "2026-09-09T14:52:00Z",
      "view_count": 0,
      "created_at": "2026-09-09T14:52:13.16253Z",
      "updated_at": "2026-09-09T14:56:05.04101Z",
      "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "page_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "page_title": "Como escolher o mouse perfeito",
      "seo_name": "como-escolher-o-mouse-perfeito",
      "description": "<h2>Por que o mouse importa</h2><p>...</p>",
      "short_description": "Guia prático com 5 passos.",
      "timestamp": 1788965533,
      "updated_timestamp": 1788965765,
      "published_timestamp": 1788965520,
      "company_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "status": "A"
    }
  ],
  "total": 9,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

postsarray

Posts da página.

iduuid
Identificador do post.
titlestring
Título.
slugstring
Trecho da URL pública do post. Único.
excerptstring
Resumo mostrado nas listas. Ausente quando vazio.
bodystring
Texto do post (HTML sanitizado ou Markdown, conforme foi enviado).
featured_imagestring
URL da imagem de destaque. Ausente quando não há.
author_iduuid
Usuário que criou o post.
category_iduuid
Categoria do post. Ausente quando não tem.
category_namestring
Nome da categoria, para exibir.
statusstring
Letra do estado: A publicado, R rascunho, D arquivado.
tagsarray
Etiquetas livres (strings).
meta_titlestring
Título para buscadores. Se você não enviar, copia o título.
meta_descriptionstring
Descrição para buscadores. Se você não enviar, usa os primeiros 160 caracteres do texto.
published_atstring
Quando o post vai ao ar (RFC 3339). Data futura = agendado. Ausente em rascunho.
view_countinteger
Visualizações na vitrine.
vendor_iduuid
Seller dono do post. Ausente em post da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total que atende ao filtro.
pageinteger
Página devolvida.
per_pageinteger
Itens por página usados.
total_pagesinteger
Total de páginas.

Erros (Listar posts)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}
500Falha de banco.{"error":"failed to list blog posts","detail":"..."}
Status entra como palavra e sai como letra

Ao gravar e ao filtrar você pode usar published, draft ou archived. A resposta do post devolve a letra: A, R ou D.

Consultar post

Devolve um post completo, em qualquer estado. Use para abrir o post no editor.

GET/api/v1/admin/blog/posts/{id}Admin

Devolve um post pelo id

Rota ligada ao módulo blog: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador do post.

Exemplo de requisição (Consultar post)

bash
curl "$BASE_URL/api/v1/admin/blog/posts/91af684b-cf41-4243-a37d-a133a39d6ed3" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar post)

200Post
json
{
  "id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "title": "Como escolher o mouse perfeito",
  "slug": "como-escolher-o-mouse-perfeito",
  "excerpt": "Guia prático com 5 passos.",
  "body": "<h2>Por que o mouse importa</h2><p>...</p>",
  "author_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "category_id": "4e733a25-349a-4598-a916-a0984fc4aa76",
  "category_name": "Guia de compras",
  "tags": [
    "mouse",
    "periféricos"
  ],
  "meta_title": "Como escolher o mouse perfeito",
  "meta_description": "Guia prático com 5 passos.",
  "published_at": "2026-09-09T14:52:00Z",
  "view_count": 0,
  "created_at": "2026-09-09T14:52:13.16253Z",
  "updated_at": "2026-09-09T14:56:05.04101Z",
  "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "page_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "page_title": "Como escolher o mouse perfeito",
  "seo_name": "como-escolher-o-mouse-perfeito",
  "description": "<h2>Por que o mouse importa</h2><p>...</p>",
  "short_description": "Guia prático com 5 passos.",
  "timestamp": 1788965533,
  "updated_timestamp": 1788965765,
  "published_timestamp": 1788965520,
  "company_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "status": "A"
}

Campos da resposta

iduuid
Identificador do post.
titlestring
Título.
slugstring
Trecho da URL pública do post. Único.
excerptstring
Resumo mostrado nas listas. Ausente quando vazio.
bodystring
Texto do post (HTML sanitizado ou Markdown, conforme foi enviado).
featured_imagestring
URL da imagem de destaque. Ausente quando não há.
author_iduuid
Usuário que criou o post.
category_iduuid
Categoria do post. Ausente quando não tem.
category_namestring
Nome da categoria, para exibir.
statusstring
Letra do estado: A publicado, R rascunho, D arquivado.
tagsarray
Etiquetas livres (strings).
meta_titlestring
Título para buscadores. Se você não enviar, copia o título.
meta_descriptionstring
Descrição para buscadores. Se você não enviar, usa os primeiros 160 caracteres do texto.
published_atstring
Quando o post vai ao ar (RFC 3339). Data futura = agendado. Ausente em rascunho.
view_countinteger
Visualizações na vitrine.
vendor_iduuid
Seller dono do post. Ausente em post da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Consultar post)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}
404Não existe post com esse id.{"error":"blog post not found"}
500O id não é um UUID válido (500, não 404).{"detail":"o valor \"zz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie.","error":"failed to get blog post"}
Campos repetidos

A resposta também traz campos que repetem outros valores (post_id, page_id, page_title, seo_name, description, short_description, timestamp, updated_timestamp, published_timestamp, company_id). Em integrações novas use os campos principais.

Veja também

  • Criar post
  • Atualizar e apagar post
Anterior
Blog
Próxima
Criar post
Nesta página
  • Listar posts
  • Exemplo de requisição (Listar posts)
  • Resposta (Listar posts)
  • Erros (Listar posts)
  • Consultar post
  • Exemplo de requisição (Consultar post)
  • Resposta (Consultar post)
  • Erros (Consultar post)
  • Veja também