Posts

O módulo de posts é o coração do seu blog. Ele permite que você crie, gerencie e publique artigos ricos em conteúdo, com suporte a SEO, categorias, tags e imagens de capa.

Cada post passa por um ciclo de vida que inclui rascunhos, agendamento de publicação e arquivamento, garantindo controle total sobre o que seu público vê.

---

Estrutura de Dados Principal

Um post contém as seguintes informações principais:

Campo	Tipo	Descrição
title	String	Título principal do artigo (máx. 150 caracteres).
slug	String	URL amigável (ex: meu-artigo-incrivel).
excerpt	String	Resumo curto do artigo (máx. 500 caracteres).
content	String	Conteúdo completo (suporta HTML/Markdown).
readingTime	Integer	Tempo de leitura estimado em segundos (calculado automaticamente).
status	Enum	draft, published ou archived.
isFeatured	Boolean	Indica se o post está em destaque.
viewCount	Integer	Contador de visualizações.

---

Endpoints Públicos

Estes endpoints são voltados para o frontend do blog e não exigem autenticação administrativa. Eles retornam apenas posts com o status published.

Listar Posts Publicados

Retorna uma lista paginada de todos os posts publicados.

GET /v1/blog/posts/public/published

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (padrão: 1).
perPage	number	Não	Itens por página (padrão: 20).
search	string	Não	Busca por termo no título.
isFeatured	boolean	Não	Filtra apenas posts em destaque.
categories	number[]	Não	Filtra por IDs de categorias.
tags	number[]	Não	Filtra por IDs de tags.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/blog/posts/public/published?page=1&perPage=10" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de posts e metadados.

{
  "meta": {
    "total": 50,
    "per_page": 10,
    "current_page": 1,
    "last_page": 5,
    "first_page": 1
  },
  "data": [
    {
      "id": 16,
      "title": "Novidades da Versão 2.0",
      "slug": "novidades-versao-2-0",
      "excerpt": "Um resumo sobre as novidades...",
      "publishedAt": "2026-03-25T17:17:00.000+00:00",
      "blogUser": {
        "firstName": "Gerson",
        "lastName": "Tavares"
      },
      "blogImage": {
        "uri": "https://cdn.exemplo.com/imagem.jpg"
      }
    }
  ]
}

Obter Post por Slug

Recupera os detalhes completos de um post através do seu slug único.

GET /v1/blog/posts/public/slug/:slug

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
slug	string	Sim	O slug único do post (ex: novidades-versao-2-0).

Exemplo de Requisição

fetch('https://api.us.basis.tavares.in/v1/blog/posts/public/slug/novidades-versao-2-0')
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

404 Not Found

Ocorre quando o post não existe ou não está publicado.

---

Endpoints Administrativos

Endpoints protegidos para gerenciamento de conteúdo. Requerem autenticação de usuário do blog.

Listar Todos os Posts

Lista todos os posts, incluindo rascunhos e arquivados.

GET /v1/blog/posts

Parâmetros de Query

Além dos filtros de paginação e busca (page, perPage, search, isFeatured), permite filtrar por status, categorias e tags:

Nome	Tipo	Descrição
status	enum	Filtra por published ou draft.
categories	number[]	Filtra por IDs de categorias.
tags	number[]	Filtra por IDs de tags.

Criar Novo Post

Cria um novo post e vincula categorias e tags.

POST /v1/blog/posts

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
post.title	string	Sim	Título (máx. 150 caracteres).
post.slug	string	Sim	Slug único.
post.content	string	Sim	Conteúdo principal (HTML/Markdown).
post.blogImageId	number	Sim	ID da imagem de capa.
post.status	enum	Não	draft ou published.
tags	array	Não	IDs das tags (ex: [1, 2]).
categories	array	Não	IDs das categorias (ex: [5]).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/blog/posts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "title": "Novo Artigo",
      "slug": "novo-artigo",
      "content": "<p>Conteúdo aqui...</p>",
      "blogImageId": 5,
      "isFeatured": true
    },
    "tags": [1, 2],
    "categories": [5]
  }'

Respostas

201 Created

Retorna o ID do post criado.

{
  "id": 18
}

400 Validation Error

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "Slug já cadastrado",
      "rule": "database.unique",
      "field": "post.slug"
    }
  ]
}

Atualizar Post

Atualiza um post existente. O tempo de leitura é recalculado automaticamente.

PUT /v1/blog/posts/:id

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/blog/posts/18" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "title": "Título Atualizado"
    }
  }'

Remover Post

Exclui um post permanentemente (Soft Delete).

DELETE /v1/blog/posts/:id

204 No Content

Remoção concluída com sucesso.