Categorias

As categorias são as filas do atendimento: Financeiro, Técnico, Comercial. Elas definem para qual fila o chamado cai, têm defaultAgentId como fallback de atribuição e aceitam hierarquia via parentId (ex.: Técnico → Infraestrutura).

A categoria também participa da distribuição automática: no round-robin, apenas agentes vinculados à categoria do ticket entram na disputa. Os vínculos agente ↔ categoria são definidos no cadastro do agente (categoryIds) — veja Agentes.

Headers obrigatórios

Todas as requisições devem incluir o header X-Helpdesk-Id (UUID) e Authorization: Bearer {token} com o token do agente (guard helpdeskAgent).

---

Estrutura de Dados Principal

Campo	Tipo	Descrição
id	Number	Identificador da categoria.
parentId	Number	Categoria pai (null = raiz).
name	String	Nome da categoria (máx. 150 caracteres).
slug	String	Slug gerado a partir do nome.
description	String	Descrição da fila (opcional).
color	String	Cor em hexadecimal (máx. 7 caracteres, opcional).
defaultAgentId	Number	Agente padrão da fila — fallback de atribuição (opcional).
sortOrder	Number	Ordem de exibição.
isActive	Boolean	Categoria ativa.

---

Endpoints

Listar Categorias

Lista as categorias da instância, com paginação, busca e filtros.

GET /v1/helpdesk/agent/categories

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
parentId	number	Não	Filtra por categoria pai; envie null para listar apenas raízes.
isActive	boolean	Não	Filtra por ativas/inativas.
orderBy	string	Não	Campo de ordenação: id, name, sortOrder ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de categorias.

Listar Categorias para Dropdown

Retorna as categorias em formato simplificado (value/label), ideal para selects no frontend.

GET /v1/helpdesk/agent/categories/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
isActive	boolean	Não	Filtra por ativas/inativas.
limit	number	Não	Quantidade máxima de itens (entre 1 e 100).

Respostas

200 OK

Retorna um array com as categorias em formato value/label.

[
  {
    "value": 1,
    "label": "Geral"
  }
]

Árvore de Categorias

Retorna a hierarquia completa (raízes com suas subcategorias aninhadas), ideal para renders em árvore no frontend.

GET /v1/helpdesk/agent/categories/tree

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
isActive	boolean	Não	Filtra por ativas/inativas.
limit	number	Não	Quantidade máxima de itens (entre 1 e 100).

Respostas

200 OK

Retorna as categorias raiz com children aninhados.

[
  {
    "id": 2,
    "name": "Técnico",
    "children": [
      {
        "id": 5,
        "name": "Infraestrutura",
        "children": []
      }
    ]
  }
]

Obter Categoria por ID

GET /v1/helpdesk/agent/categories/:id

Respostas

200 OK

Retorna os dados da categoria.

404 Not Found

Ocorre quando a categoria não existe na instância.

Criar Categoria

POST /v1/helpdesk/agent/categories

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da categoria (máx. 150 caracteres).
parentId	number	Não	Categoria pai (deve existir na instância).
description	string	Não	Descrição da fila.
color	string	Não	Cor em hexadecimal (máx. 7 caracteres).
defaultAgentId	number	Não	Agente padrão da fila (deve existir na instância).
sortOrder	number	Não	Ordem de exibição.
isActive	boolean	Não	Categoria ativa (padrão: true).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/categories" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Infraestrutura",
    "parentId": 2,
    "color": "#1D4ED8",
    "defaultAgentId": 3,
    "sortOrder": 10
  }'

Respostas

201 Created

Retorna o ID da categoria criada.

{
  "id": 5
}

Atualizar Categoria

Todos os campos da criação são opcionais no update; envie parentId: null para tornar a categoria raiz.

PUT /v1/helpdesk/agent/categories/:id

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Categoria

Remove uma categoria via soft delete.

DELETE /v1/helpdesk/agent/categories/:id

Respostas

204 No Content

Remoção concluída com sucesso.