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 (UUID) 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.

http

GET /v1/blog/categories/public/tree

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Filtra categorias pelo nome (máx. 150 caracteres).
`limit`	`number`	Não	Quantidade máxima de categorias retornadas (mínimo: 1, máximo: 300).

Exemplo de Requisição

bash

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

Respostas

200 OK

Retorna um array com as categorias raiz e seus filhos aninhados em children.

json

[
  {
    "id": "3",
    "blogImageId": null,
    "parentId": null,
    "name": "Tecnologia",
    "slug": "tecnologia",
    "blogImage": null,
    "children": [
      {
        "id": "5",
        "blogImageId": "5",
        "parentId": "3",
        "name": "Desenvolvimento",
        "slug": "desenvolvimento",
        "blogImage": {
          "id": "5",
          "uri": "https://cdn.exemplo.com/images/1635fe4c-c41f-439b-8dd8-0ab0613d569e.jpg"
        },
        "children": []
      }
    ]
  },
  {
    "id": "4",
    "blogImageId": null,
    "parentId": null,
    "name": "Inovação",
    "slug": "inovacao",
    "blogImage": null,
    "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.

http

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

Parâmetros de Rota

Nome	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/tecnologia" \
  -H "X-Blog-Id: {blog-id}"

Respostas

200 OK

Retorna o objeto completo da categoria, incluindo os campos de SEO.

json

{
  "id": "7",
  "parentId": null,
  "blogImageId": "5",
  "name": "Tecnologia",
  "slug": "tecnologia",
  "seoTitle": "Tudo sobre Tecnologia",
  "seoDescription": "Artigos, tutoriais e novidades do mundo da tecnologia.",
  "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://cdn.exemplo.com/images/1635fe4c-c41f-439b-8dd8-0ab0613d569e.jpg"
  }
}

Obter Detalhes por ID

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

http

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

Parâmetros de Rota

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

Respostas

200 OK

Retorna o objeto completo da categoria, incluindo a categoria pai (quando existente).

json

{
  "id": "7",
  "parentId": "5",
  "blogImageId": "5",
  "name": "Desenvolvimento Web",
  "slug": "desenvolvimento-web",
  "seoTitle": "Guias de Desenvolvimento Web",
  "seoDescription": "Aprenda desenvolvimento web com artigos práticos.",
  "createdAt": "2026-03-25T11:11:30.619-03:00",
  "updatedAt": "2026-03-25T11:18:37.479-03:00",
  "parent": {
    "id": "5",
    "name": "Desenvolvimento",
    "slug": "desenvolvimento"
  },
  "blogImage": {
    "id": "5",
    "uri": "https://cdn.exemplo.com/images/1635fe4c-c41f-439b-8dd8-0ab0613d569e.jpg"
  }
}

Listar para Seleção

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

http

GET /v1/blog/categories/public/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Filtra categorias pelo nome (máx. 150 caracteres).
`limit`	`number`	Não	Quantidade máxima de itens retornados (mínimo: 1, máximo: 300).
`orderBy`	`enum`	Não	Campo de ordenação: `value` ou `label`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/blog/categories/public/list?orderBy=label&orderDirection=asc" \
  -H "X-Blog-Id: {blog-id}"

Respostas

200 OK

Retorna um array de opções no formato value/label.

json

[
  {
    "value": "3",
    "label": "Tecnologia"
  },
  {
    "value": "5",
    "label": "Desenvolvimento"
  }
]

Endpoints Administrativos

Atenção

Estes endpoints exigem autenticação via token (Bearer) de um usuário do blog.

Listar Categorias (Gerenciamento)

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

http

GET /v1/blog/categories

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	Número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (mínimo: 1, máximo: 100).
`search`	`string`	Não	Busca por nome da categoria (máx. 150 caracteres).
`orderBy`	`enum`	Não	Campo de ordenação: `id`, `name` ou `createdAt`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/blog/categories?page=1&perPage=25&orderBy=id&orderDirection=desc" \
  -H "Authorization: Bearer {token}" \
  -H "X-Blog-Id: {blog-id}"

Respostas

200 OK

Retorna a lista de categorias com os metadados de paginação.

json

{
  "meta": {
    "currentPage": "1",
    "perPage": "25"
  },
  "data": [
    {
      "id": "7",
      "blogImageId": "5",
      "name": "Desenvolvimento Web",
      "slug": "desenvolvimento-web",
      "parentId": "5",
      "createdAt": "2026-03-25T11:11:30.619-03:00",
      "updatedAt": "2026-03-25T11:18:37.479-03:00",
      "parent": {
        "id": "5",
        "name": "Desenvolvimento",
        "slug": "desenvolvimento"
      },
      "blogImage": {
        "id": "5",
        "uri": "https://cdn.exemplo.com/images/1635fe4c-c41f-439b-8dd8-0ab0613d569e.jpg"
      }
    }
  ]
}

422 Unprocessable Entity

Erro de validação nos parâmetros de query.

json

{
  "errors": [
    {
      "message": "Valor mínimo deve ser 1",
      "rule": "min",
      "field": "page",
      "meta": {
        "min": 1
      }
    }
  ]
}

Criar Nova Categoria

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

http

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). Aceita `null`.
`blogImageId`	`number`	Não	ID da imagem associada à categoria (deve pertencer ao blog). Aceita `null`.
`seoTitle`	`string`	Não	Título personalizado para SEO (máx. 200 caracteres). Aceita `null`.
`seoDescription`	`string`	Não	Descrição para SEO (máx. 200 caracteres). Aceita `null`.

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: {blog-id}" \
  -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

Retorna o ID da categoria criada.

json

{
  "id": "9"
}

422 Unprocessable Entity

Falha na validação dos dados enviados.

json

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

Atualizar Categoria

Atualiza os dados de uma categoria existente. Ao alterar o name, o slug é recalculado automaticamente. Aceita os mesmos campos do cadastro.

http

PUT /v1/blog/categories/:id

Parâmetros de Rota

Nome	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 "X-Blog-Id: {blog-id}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tecnologia Avançada",
    "parentId": null,
    "blogImageId": 5,
    "seoTitle": "Tecnologia de Ponta",
    "seoDescription": "O que há de mais moderno em tecnologia."
  }'

Respostas

204 No Content

Categoria atualizada com sucesso. A resposta não contém corpo.

Remover Categoria

Exclui uma categoria do blog.

http

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}" \
  -H "X-Blog-Id: {blog-id}"

Respostas

204 No Content

A categoria foi removida com sucesso. A resposta não contém corpo.

Categorias do Blog ​

Endpoints Públicos ​

Obter Árvore de Categorias ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Obter Detalhes por Slug ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Obter Detalhes por ID ​

Parâmetros de Rota ​

Respostas ​

Listar para Seleção ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Endpoints Administrativos ​

Listar Categorias (Gerenciamento) ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Nova Categoria ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Categoria ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Remover Categoria ​

Exemplo de Requisição ​

Respostas ​

Categorias do Blog

Endpoints Públicos

Obter Árvore de Categorias

Parâmetros de Query

Exemplo de Requisição

Respostas

Obter Detalhes por Slug

Parâmetros de Rota

Exemplo de Requisição

Respostas

Obter Detalhes por ID

Parâmetros de Rota

Respostas

Listar para Seleção

Parâmetros de Query

Exemplo de Requisição

Respostas

Endpoints Administrativos

Listar Categorias (Gerenciamento)

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Nova Categoria

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Categoria

Parâmetros de Rota

Exemplo de Requisição

Respostas

Remover Categoria

Exemplo de Requisição

Respostas