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

Blog

Posts, categorias e comentários do blog da loja, com agendamento, tradução e imagem de destaque gerada por IA.

O blog é o espaço de conteúdo editorial da loja: guias de compra, novidades, bastidores. Esta seção é a API de administração: criar e editar posts, organizá-los em categorias, traduzi-los, moderar os comentários dos leitores e gerar a imagem de destaque com IA. A leitura pública do blog fica na vitrine e não está aqui.

Pontos principais
  • Todas as rotas dependem do módulo blog; com o módulo desligado a resposta é 403.
  • O estado do post entra como palavra (published, draft, archived) e sai como letra (A, R, D).
  • Uma data de publicação no futuro agenda o post: a vitrine o esconde até lá.
  • Comentários novos chegam como pending e precisam de aprovação.
  • Apagar post, categoria ou comentário é definitivo.

Como funciona

O caminho normal de um post: criar como draft, escrever e traduzir, definir categoria e imagem de destaque e, quando estiver pronto, mudar para published (agora ou com uma data futura). Depois de publicado, leitores podem comentar na vitrine; os comentários caem na fila de moderação.

Rascunho→Agendado→Publicado→Arquivado
Estado do postLetraSignificado
draftRRascunho, só no painel.
publishedAPublicado. Se published_at está no futuro, está agendado e a vitrine ainda não o mostra.
archivedDArquivado, fora da vitrine.
Estado do comentárioSignificado
pendingAguardando moderação. Não aparece.
approvedAprovado, aparece abaixo do post.
rejectedRejeitado, escondido mas guardado.

Conceitos importantes

Slug

O slug é o trecho da URL pública do post. Na criação, um slug repetido recebe sufixo (-2, -3). Na atualização, um slug repetido é recusado.

Texto do post

O texto é sanitizado ao gravar: scripts e atributos de evento saem. O meta_title e a meta_description vazios são preenchidos a partir do título e dos primeiros 160 caracteres do texto.

Tradução

Cada post e cada categoria pode ter conteúdo por idioma. As rotas de descriptions leem e gravam esse conteúdo; title (ou name) é obrigatório em cada idioma enviado.

Post da loja e de seller

Posts e categorias sem vendor_id são da loja inteira. Posts de seller aparecem só na vitrine do seller. A lista mistura os dois por padrão.

Identificadores inválidos

Um id que não é UUID faz várias rotas responderem 500 em vez de 404. Valide o formato antes de chamar.

Endpoints

MétodoCaminhoPara que serveAutenticação
GET/api/v1/admin/blog/postsLista os posts do blogadmin
GET/api/v1/admin/blog/posts/{id}Devolve um post pelo idadmin
POST/api/v1/admin/blog/postsCria um post do blogadmin
PUT/api/v1/admin/blog/posts/{id}Altera campos de um postadmin
DELETE/api/v1/admin/blog/posts/{id}Apaga um post definitivamenteadmin
GET/api/v1/admin/blog/posts/{id}/descriptionsLista o conteúdo do post em cada idiomaadmin
PUT/api/v1/admin/blog/posts/{id}/descriptionsCria ou atualiza o conteúdo por idiomaadmin
GET/api/v1/admin/blog/categoriesLista as categorias do blogadmin
POST/api/v1/admin/blog/categoriesCria uma categoria do blogadmin
PUT/api/v1/admin/blog/categories/{id}Altera campos de uma categoriaadmin
DELETE/api/v1/admin/blog/categories/{id}Apaga uma categoria do blogadmin
GET/api/v1/admin/blog/categories/{id}/descriptionsLista nome e descrição da categoria por idiomaadmin
PUT/api/v1/admin/blog/categories/{id}/descriptionsCria ou atualiza nome e descrição por idiomaadmin
GET/api/v1/admin/blog/commentsLista os comentários dos posts para moderaçãoadmin
PUT/api/v1/admin/blog/comments/{id}/approveAprova um comentárioadmin
PUT/api/v1/admin/blog/comments/{id}/rejectRejeita um comentárioadmin
DELETE/api/v1/admin/blog/comments/{id}Apaga um comentárioadmin
POST/api/v1/admin/blog/ai/featured-image/suggest-promptSugere um texto para gerar a imagem de destaqueadmin
POST/api/v1/admin/blog/ai/featured-image/generateGera a imagem de destaque de um post com IAadmin

Erros comuns

  • Ler status do post esperando published: a resposta traz a letra A.
  • Criar o post como published com published_at no futuro e achar que ele sumiu: está agendado e só a vitrine o esconde; o painel mostra.
  • Reaproveitar o slug de outro post numa atualização: recusado com 500 already in use.
  • Apagar uma categoria em uso sem conferir os posts.
  • Chamar generate repetidas vezes: cada sucesso gera custo.
  • Esquecer title em um idioma de descriptions: a chamada inteira é recusada com 400.

Próximos passos

Posts
Listar e consultar.
Criar post
Corpo completo e agendamento.
Comentários
Moderação.
Anterior
Indicadores do CRM
Próxima
Listar e consultar posts
Nesta página
  • Como funciona
  • Conceitos importantes
  • Slug
  • Texto do post
  • Tradução
  • Post da loja e de seller
  • Identificadores inválidos
  • Endpoints
  • Erros comuns
  • Próximos passos