API atual/Referência completa/Conteúdo da vitrine

Comentários do blog

Lista os comentários aprovados de um post e envia um comentário novo, que fica em moderação.

Leitores podem comentar nos posts do blog, com ou sem conta. Todo comentário novo entra pendente e só aparece na lista depois que um administrador o aprova no painel. Por isso, depois de enviar, a tela deve avisar "seu comentário foi enviado e aguarda aprovação", e não tentar exibi-lo.

GET/api/v1/storefront/blog/posts/{postId}/commentsPública

Listar os comentários aprovados

Parâmetros de caminho

postIduuidobrigatório

Id do post.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

limitintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/blog/posts/$POST_ID/comments?limit=20"

Resposta

200Comentários

json

{
  "items": [
    {
      "id": "c0a8d1e2-7b6f-4a3c-9d2e-1f0a9b8c7d6e",
      "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "post_title": "Como escolher o mouse perfeito para o seu dia a dia",
      "user_name": "Carlos",
      "user_email": "carlos@example.com",
      "body": "Ótimo guia, comprei o modelo sem fio.",
      "status": "approved",
      "created_at": "2026-10-10T12:00:00Z",
      "updated_at": "2026-10-10T13:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Campos da resposta

itemsarray

Comentários aprovados do post, do mais novo para o mais antigo. [] quando não há nenhum.

items[].iduuid

Id do comentário.

items[].post_iduuid

Post comentado.

items[].post_titlestring

Título do post.

items[].user_iduuid

Conta de quem comentou. Ausente em comentário de visitante.

items[].user_namestring

Nome exibido.

items[].user_emailstring

E-mail informado por quem comentou. É dado pessoal: não exiba na vitrine.

items[].bodystring

Texto do comentário.

items[].statusstring

pendingapprovedrejected

Aqui sempre approved.

items[].ip_addressstring

IP de quem comentou, quando registrado. É dado pessoal: não exiba.

items[].created_atstring

Quando foi enviado (RFC 3339).

items[].updated_atstring

Última alteração, por exemplo a aprovação (RFC 3339).

totalinteger

Total de comentários aprovados do post.

pageinteger

Página devolvida.

limitinteger

Itens por página aplicados.

Erros

Status	Quando	Corpo
403	Módulo `blog` desligado.	`{"error":"module_disabled","module":"blog"}`
500	`postId` que não é UUID (por exemplo, o slug), ou falha ao consultar.	`{"error":"failed to list comments","detail":"..."}`

POST/api/v1/storefront/blog/posts/{postId}/commentsPública

Enviar um comentário

Parâmetros de caminho

postIduuidobrigatório

Id do post.

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional; liga o comentário à conta.

Corpo da requisição

user_namestringobrigatório

Nome a exibir. Espaços nas pontas são removidos.

user_emailstring

E-mail de quem comenta. Opcional; a rota não valida o formato.

bodystringobrigatório

Texto do comentário. HTML perigoso é removido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/blog/posts/$POST_ID/comments" \
  -H "Content-Type: application/json" \
  -d '{"user_name":"Carlos","user_email":"carlos@example.com","body":"Ótimo guia!"}'

Resposta

201Comentário recebido

json

{
  "id": "c0a8d1e2-7b6f-4a3c-9d2e-1f0a9b8c7d6e",
  "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "user_name": "Carlos",
  "user_email": "carlos@example.com",
  "body": "Ótimo guia!",
  "status": "pending",
  "ip_address": "203.0.113.10",
  "created_at": "2026-10-11T21:00:00Z",
  "updated_at": "2026-10-11T21:00:00Z"
}

A resposta tem os mesmos campos de items[]; aqui o status é pending.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`body` vazio.	`{"error":"comment body is required"}`
400	`user_name` vazio.	`{"error":"user_name is required"}`
403	Módulo `blog` desligado.	`{"error":"module_disabled","module":"blog"}`
500	`postId` que não é UUID ou que não existe, ou falha ao gravar.	`{"error":"failed to create comment","detail":"..."}`

Veja também

Comentários do blog

Lista os comentários aprovados de um post e envia um comentário novo, que fica em moderação.

GET/api/v1/storefront/blog/posts/{postId}/commentsPública

Listar os comentários aprovados

Parâmetros de caminho

postIduuidobrigatório

Id do post.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

limitintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/blog/posts/$POST_ID/comments?limit=20"

Resposta

200Comentários

json

{
  "items": [
    {
      "id": "c0a8d1e2-7b6f-4a3c-9d2e-1f0a9b8c7d6e",
      "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
      "post_title": "Como escolher o mouse perfeito para o seu dia a dia",
      "user_name": "Carlos",
      "user_email": "carlos@example.com",
      "body": "Ótimo guia, comprei o modelo sem fio.",
      "status": "approved",
      "created_at": "2026-10-10T12:00:00Z",
      "updated_at": "2026-10-10T13:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Campos da resposta

itemsarray

Comentários aprovados do post, do mais novo para o mais antigo. [] quando não há nenhum.

items[].iduuid

Id do comentário.

items[].post_iduuid

Post comentado.

items[].post_titlestring

Título do post.

items[].user_iduuid

Conta de quem comentou. Ausente em comentário de visitante.

items[].user_namestring

Nome exibido.

items[].user_emailstring

E-mail informado por quem comentou. É dado pessoal: não exiba na vitrine.

items[].bodystring

Texto do comentário.

items[].statusstring

pendingapprovedrejected

Aqui sempre approved.

items[].ip_addressstring

IP de quem comentou, quando registrado. É dado pessoal: não exiba.

items[].created_atstring

Quando foi enviado (RFC 3339).

items[].updated_atstring

Última alteração, por exemplo a aprovação (RFC 3339).

totalinteger

Total de comentários aprovados do post.

pageinteger

Página devolvida.

limitinteger

Itens por página aplicados.

Erros

Status	Quando	Corpo
403	Módulo `blog` desligado.	`{"error":"module_disabled","module":"blog"}`
500	`postId` que não é UUID (por exemplo, o slug), ou falha ao consultar.	`{"error":"failed to list comments","detail":"..."}`

POST/api/v1/storefront/blog/posts/{postId}/commentsPública

Enviar um comentário

Parâmetros de caminho

postIduuidobrigatório

Id do post.

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional; liga o comentário à conta.

Corpo da requisição

user_namestringobrigatório

Nome a exibir. Espaços nas pontas são removidos.

user_emailstring

E-mail de quem comenta. Opcional; a rota não valida o formato.

bodystringobrigatório

Texto do comentário. HTML perigoso é removido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/blog/posts/$POST_ID/comments" \
  -H "Content-Type: application/json" \
  -d '{"user_name":"Carlos","user_email":"carlos@example.com","body":"Ótimo guia!"}'

Resposta

201Comentário recebido

json

{
  "id": "c0a8d1e2-7b6f-4a3c-9d2e-1f0a9b8c7d6e",
  "post_id": "91af684b-cf41-4243-a37d-a133a39d6ed3",
  "user_name": "Carlos",
  "user_email": "carlos@example.com",
  "body": "Ótimo guia!",
  "status": "pending",
  "ip_address": "203.0.113.10",
  "created_at": "2026-10-11T21:00:00Z",
  "updated_at": "2026-10-11T21:00:00Z"
}

A resposta tem os mesmos campos de items[]; aqui o status é pending.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`body` vazio.	`{"error":"comment body is required"}`
400	`user_name` vazio.	`{"error":"user_name is required"}`
403	Módulo `blog` desligado.	`{"error":"module_disabled","module":"blog"}`
500	`postId` que não é UUID ou que não existe, ou falha ao gravar.	`{"error":"failed to create comment","detail":"..."}`