Categorias do Blog

As categorias permitem que você organize as postagens do seu blog de forma lógica e hierárquica. Além de facilitar a navegação para o usuário, uma boa estrutura de categorias é fundamental para o SEO, permitindo que os motores de busca compreendam a semântica do seu conteúdo.

Neste módulo, você encontrará endpoints para gerenciar o ciclo de vida completo das categorias, desde a criação de estruturas em árvore até a recuperação pública de dados para o frontend.

Nota

Todas as requisições para este módulo exigem o cabeçalho X-Blog-Id para identificar o contexto do blog.

Endpoints Públicos

Estes endpoints são otimizados para consumo no frontend do seu blog e não requerem autenticação de usuário administrativo.

Obter Árvore de Categorias

Este endpoint retorna todas as categorias organizadas em uma estrutura de árvore (ninhos de pais e filhos), ideal para construir menus de navegação ou sidebars complexas.

GET /v1/blog/categories/public/tree

Parâmetro	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Filtra categorias pelo nome.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/blog/categories/public/tree" \
     -H "X-Blog-Id: 1" \
     -H "Accept: application/json"

Resposta de Sucesso (200 OK)

json

[
  {
    "id": "1",
    "parentId": null,
    "blogImageId": "5",
    "name": "Tecnologia",
    "slug": "tecnologia",
    "blogImage": {
      "id": "5",
      "uri": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c.jpg",
      "uriThumb": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c_thumb_small.jpg"
    },
    "children": [
      {
        "id": "2",
        "parentId": "1",
        "blogImageId": "5",
        "name": "Desenvolvimento",
        "slug": "desenvolvimento",
        "blogImage": {
          "id": "5",
          "uri": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c.jpg",
          "uriThumb": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c_thumb_small.jpg"
        },
        "children": []
      }
    ]
  }
]

Obter Detalhes por Slug

Recupere informações detalhadas de uma categoria específica utilizando sua URL amigável (slug). Este endpoint é essencial para carregar os metadados (SEO) de uma página de listagem de categoria.

GET /v1/blog/categories/public/slug/:slug

Parâmetro	Tipo	Obrigatório	Descrição
`slug`	`string`	Sim	O slug único da categoria.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/blog/categories/public/slug/category-three" \
     -H "X-Blog-Id: 1"

Resposta de Sucesso (200 OK)

json

{
  "id": "7",
  "parentId": null,
  "blogImageId": "5",
  "name": "Category Three",
  "slug": "category-three",
  "seoTitle": "Título SEO para Category Three",
  "seoDescription": "Descrição detalhada para SEO da Category Three.",
  "createdAt": "2026-03-25T11:11:30.619-03:00",
  "updatedAt": "2026-03-25T15:28:32.412-03:00",
  "parent": null,
  "blogImage": {
    "id": "5",
    "uri": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c.jpg",
    "uriThumb": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c_thumb_small.jpg"
  }
}

Obter Detalhes por ID

Recupere informações completas de uma categoria utilizando seu identificador numérico.

GET /v1/blog/categories/public/:id

Parâmetro	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID único da categoria.

Resposta de Sucesso (200 OK)

json

{
  "id": "7",
  "parentId": "5",
  "blogImageId": "5",
  "name": "Category Eight",
  "slug": "category-eight",
  "seoTitle": "Lorem ipsum dolor sit amet",
  "seoDescription": "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
  "createdAt": "2026-03-25T11:11:30.619-03:00",
  "updatedAt": "2026-03-25T11:18:37.479-03:00",
  "parent": {
    "id": "5",
    "name": "Sub category",
    "slug": "sub-category"
  },
  "blogImage": {
    "id": "5",
    "uri": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c.jpg",
    "uriThumb": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c_thumb_small.jpg"
  }
}

Listar para Seleção

Retorna uma lista simplificada de todas as categorias, ideal para preencher componentes de Select ou Autocomplete no frontend.

GET /v1/blog/categories/public/list

Parâmetro	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Filtra categorias pelo nome.

Resposta de Sucesso (200 OK)

json

[
  {
    "value": "1",
    "label": "Tecnologia"
  },
  {
    "value": "2",
    "label": "Desenvolvimento"
  }
]

Endpoints Administrativos

Atenção

Estes endpoints exigem autenticação via token (Bearer) e permissões de blogUser.

Criar Nova Categoria

Cria uma nova categoria para o blog. O slug será gerado automaticamente a partir do name.

POST /v1/blog/categories

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome da categoria (máx 150 caracteres).
`parentId`	`number`	Não	ID da categoria pai (deve pertencer ao mesmo blog).
`blogImageId`	`number`	Não	ID da imagem associada à categoria.
`seoTitle`	`string`	Não	Título personalizado para SEO (máx 200 caracteres).
`seoDescription`	`string`	Não	Descrição para SEO (máx 200 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/blog/categories" \
     -H "Authorization: Bearer {token}" \
     -H "X-Blog-Id: 1" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Inovação",
       "parentId": 5,
       "blogImageId": 5,
       "seoTitle": "Inovação e Futuro",
       "seoDescription": "Fique por dentro das novidades do futuro."
     }'

Respostas

201 Created: Categoria criada com sucesso.
json
```
{ "id": "9" }
```

422 Unprocessable Entity: Falha na validação dos dados.

json

{
  "errors": [
    { "message": "Nome é obrigatório", "field": "name" }
  ]
}

Atualizar Categoria

Atualiza os dados de uma categoria existente. Ao alterar o nome, o slug será recalculado.

PUT /v1/blog/categories/:id

Parâmetro	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	ID da categoria a ser atualizada.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/blog/categories/7" \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Tecnologia Avançada",
       "seoTitle": "Tecnologia de Ponta"
     }'

Resposta de Sucesso (204 No Content)

A resposta não contém corpo em caso de sucesso.

Remover Categoria

Exclui permanentemente uma categoria do banco de dados.

DELETE /v1/blog/categories/:id

Nota

Ao excluir uma categoria, verifique se existem posts vinculados a ela para evitar inconsistências no frontend.

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/v1/blog/categories/7" \
     -H "Authorization: Bearer {token}"

Resposta de Sucesso (204 No Content)

A categoria foi removida com sucesso.

Listar Categorias (Gerenciamento)

Lista todas as categorias de forma plana, útil para tabelas de gerenciamento no dashboard.

GET /v1/blog/categories

Parâmetro	Tipo	Obrigatório	Descrição
`page`	`number`	Nã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 nome da categoria.

Resposta de Sucesso (200 OK)

json

{
  "meta": {
    "total": 5,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1
  },
  "data": [
    {
      "id": "7",
      "blogImageId": "5",
      "name": "Category Three",
      "slug": "category-three",
      "parentId": "5",
      "createdAt": "2026-03-25T11:11:30.619-03:00",
      "updatedAt": "2026-03-25T11:18:37.479-03:00",
      "parent": {
        "id": "5",
        "name": "Sub category",
        "slug": "sub-category"
      },
      "blogImage": {
        "id": "5",
        "uri": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c.jpg",
        "uriThumb": "https://tavares-dev.s3.amazonaws.com/images/1635fe4c_thumb_small.jpg"
      }
    }
  ]
}

Categorias do Blog ​

Endpoints Públicos ​

Obter Árvore de Categorias ​

Exemplo de Requisição ​

Resposta de Sucesso (200 OK) ​

Obter Detalhes por Slug ​

Exemplo de Requisição ​

Resposta de Sucesso (200 OK) ​

Obter Detalhes por ID ​

Resposta de Sucesso (200 OK) ​

Listar para Seleção ​

Resposta de Sucesso (200 OK) ​

Endpoints Administrativos ​

Criar Nova Categoria ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Categoria ​

Exemplo de Requisição ​

Resposta de Sucesso (204 No Content) ​

Remover Categoria ​

Exemplo de Requisição ​

Resposta de Sucesso (204 No Content) ​

Listar Categorias (Gerenciamento) ​

Resposta de Sucesso (200 OK) ​

Categorias do Blog

Endpoints Públicos

Obter Árvore de Categorias

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Obter Detalhes por Slug

Exemplo de Requisição

Resposta de Sucesso (200 OK)

Obter Detalhes por ID

Resposta de Sucesso (200 OK)

Listar para Seleção

Resposta de Sucesso (200 OK)

Endpoints Administrativos

Criar Nova Categoria

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Categoria

Exemplo de Requisição

Resposta de Sucesso (204 No Content)

Remover Categoria

Exemplo de Requisição

Resposta de Sucesso (204 No Content)

Listar Categorias (Gerenciamento)

Resposta de Sucesso (200 OK)