Tags

As tags são a classificação livre e transversal do Helpdesk, paralela à categoria. Enquanto a categoria roteia (um valor, decide a fila), a tag descreve (vários valores, serve para relatório e filtro: "bug", "cobrança duplicada", "cliente VIP").

As tags se vinculam aos tickets em uma relação N:N. A sincronização dos vínculos não é feita aqui: ela acontece no ticket, pelo atributo tagIds (criação, update ou POST /tickets/:id/tags — veja Tickets). Este recurso cuida apenas do catálogo de tags da instância.

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 tag.
name	String	Nome da tag (máx. 150 caracteres).
color	String	Cor em hexadecimal (máx. 7 caracteres, opcional).
createdAt	String	Data de criação (ISO 8601).
updatedAt	String	Data da última atualização (ISO 8601).

---

Endpoints

Listar Tags

Lista as tags da instância, com paginação e busca por nome.

GET /v1/helpdesk/agent/tags

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).
orderBy	string	Não	Campo de ordenação: id, name ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.

Respostas

200 OK

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

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "name": "bug",
      "color": "#E63946",
      "createdAt": "2026-09-01T10:05:33.000+00:00",
      "updatedAt": "2026-09-01T10:05:33.000+00:00"
    }
  ]
}

Listar Tags para Dropdown

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

GET /v1/helpdesk/agent/tags/list

Parâmetros de Query

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

Respostas

200 OK

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

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

Obter Tag por ID

GET /v1/helpdesk/agent/tags/:id

Respostas

200 OK

Retorna os dados da tag.

404 Not Found

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

Criar Tag

POST /v1/helpdesk/agent/tags

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag (máx. 150 caracteres).
color	string	Não	Cor em hexadecimal (máx. 7 caracteres).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/tags" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cliente VIP",
    "color": "#F4A261"
  }'

Respostas

201 Created

Retorna o ID da tag criada.

{
  "id": 2
}

Atualizar Tag

PUT /v1/helpdesk/agent/tags/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Não	Nome da tag (máx. 150 caracteres).
color	string	Não	Cor em hexadecimal (máx. 7 caracteres); envie null para remover.

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Tag

Remove uma tag da instância (exclusão lógica).

DELETE /v1/helpdesk/agent/tags/:id

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

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