Agentes & Autenticação (Staff)

Os agentes são o time de atendimento da instância — quem responde tickets, usa notas internas e gerencia a operação. Possuem autenticação própria do módulo, separada tanto da plataforma quanto dos clientes.

Agentes não são apagados fisicamente: como o histórico dos tickets referencia o autor das respostas, a remoção é lógica (o registro sai de todas as consultas). Para tirar alguém de operação sem remover, use isActive: false.

Headers obrigatórios

Todas as requisições devem incluir o header X-Helpdesk-Id (UUID) com o identificador da instância. Os endpoints autenticados exigem também Authorization: Bearer {token} com o token do agente (guard helpdeskAgent).

Estrutura de Dados Principal

Campo	Tipo	Descrição
`id`	`Number`	Identificador do agente.
`name`	`String`	Nome completo (máx. 150 caracteres).
`email`	`String`	E-mail de login (máx. 250 caracteres, único por instância).
`role`	`String`	Papel: `agent`, `supervisor` ou `admin` (padrão: `agent`).
`signature`	`String`	Assinatura anexada às respostas públicas (opcional).
`avatarUrl`	`String`	URL do avatar (máx. 255 caracteres, opcional).
`isAvailable`	`Boolean`	Aceita distribuição automática (round-robin).
`maxOpenTickets`	`Number`	Teto de tickets abertos na fila do agente (`null` = ilimitado).
`isActive`	`Boolean`	Agente ativo — inativos não conseguem autenticar nas rotas de staff.
`helpdeskCategories`	`Array`	Filas (categorias) que o agente atende — vínculo N:N via `categoryIds`.

Roles

Role	Permissões
`agent`	Opera tickets, threads, categorias, tags, SLA, arquivos e métricas; gerencia apenas as próprias respostas prontas.
`supervisor`	Tudo do `agent` + gerenciar agentes (criar, editar, remover).
`admin`	Tudo do `supervisor` + gerenciar respostas prontas de qualquer agente.

Ações de gerenciamento de agentes por quem não é admin/supervisor falham com 403 FORBIDDEN.

Autenticação

Autentica um agente e retorna o token de acesso da área de staff.

http

POST /v1/helpdesk/agent/agents/login

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail do agente.
`password`	`string`	Sim	Senha (8 a 32 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/agents/login" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@acme.com",
    "password": "Password@123"
  }'

Respostas

200 OK

Retorna o token Bearer com validade de 30 dias.

json

{
  "type": "bearer",
  "name": "6522b2f2-4101-4748-b7b1-f7716463e878",
  "token": "oat_Mw.Njh2OWRieE90NzF1NE1LaUhTUVFHSUJGNE02T3E3SFNiWUhESnNmeDM1MDAyNzQ2NzY",
  "abilities": ["*"],
  "lastUsedAt": null,
  "expiresAt": "2026-10-10T03:04:39.783Z"
}

422 Unprocessable Entity

Credenciais inválidas ou agente não encontrado.

json

{
  "errors": [
    {
      "message": "Email/Senha inválida"
    }
  ]
}

Logout

Invalida o token usado na requisição imediatamente.

http

POST /v1/helpdesk/agent/agents/logout

Respostas

204 No Content

Token invalidado com sucesso.

Perfil do Agente Autenticado

Retorna os dados do agente autenticado, incluindo as categorias (filas) vinculadas.

http

GET /v1/helpdesk/agent/agents/me

Respostas

200 OK

Retorna os dados do agente.

json

{
  "id": 1,
  "helpdeskId": 1,
  "name": "Maria Silva",
  "email": "maria@acme.com",
  "role": "admin",
  "signature": null,
  "avatarUrl": null,
  "isAvailable": true,
  "maxOpenTickets": null,
  "isActive": true,
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00",
  "helpdeskCategories": [
    {
      "id": 1,
      "name": "Geral"
    }
  ]
}

Atualizar Próprio Perfil

Atualiza os dados de perfil do agente autenticado (sem alterar role, filas ou disponibilidade).

http

PUT /v1/helpdesk/agent/agents/me

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Não	Nome completo (máx. 150 caracteres).
`signature`	`string`	Não	Assinatura das respostas públicas; envie `null` para remover.
`avatarUrl`	`string`	Não	URL do avatar (máx. 255 caracteres); envie `null` para remover.

Respostas

204 No Content

Perfil atualizado com sucesso.

Trocar Senha

Define uma nova senha para o agente autenticado.

http

PATCH /v1/helpdesk/agent/agents/change-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`password`	`string`	Sim	Nova senha (8 a 32 caracteres).

Respostas

204 No Content

Senha alterada com sucesso.

Gerenciamento de Agentes

Endpoints de escrita (POST, PUT, DELETE) exigem role admin ou supervisor — demais roles recebem 403 FORBIDDEN. As consultas são abertas a qualquer agente autenticado.

Listar Agentes

Lista os agentes da instância, com paginação, busca e filtros.

http

GET /v1/helpdesk/agent/agents

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 ou e-mail (máx. 150 caracteres).
`role`	`string`	Não	Filtra por papel: `agent`, `supervisor` ou `admin`.
`isAvailable`	`boolean`	Não	Filtra por disponibilidade para round-robin.
`isActive`	`boolean`	Não	Filtra por agentes ativos/inativos.
`orderBy`	`string`	Não	Campo de ordenação: `id`, `name`, `email` ou `createdAt`.
`orderDirection`	`string`	Não	Direção: `asc` ou `desc`.

Respostas

200 OK

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

Retorna os agentes em formato simplificado (value/label), ideal para selects de atribuição no frontend.

http

GET /v1/helpdesk/agent/agents/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Busca por termo no nome (máx. 150 caracteres).
`isAvailable`	`boolean`	Não	Filtra por disponibilidade.
`isActive`	`boolean`	Não	Filtra por ativos/inativos.

Respostas

200 OK

Retorna um array com os agentes em formato value/label.

json

[
  {
    "value": 1,
    "label": "Maria Silva"
  }
]

Obter Agente por ID

Recupera os detalhes de um agente da instância.

http

GET /v1/helpdesk/agent/agents/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do agente.

Respostas

200 OK

Retorna os dados do agente, incluindo as categorias vinculadas.

404 Not Found

Ocorre quando o agente não existe na instância.

Criar Agente

Cria um novo agente na instância. O e-mail deve ser único entre os agentes ativos da instância.

http

POST /v1/helpdesk/agent/agents

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome completo (máx. 150 caracteres).
`email`	`string`	Sim	E-mail de login (máx. 250 caracteres, único por instância).
`password`	`string`	Sim	Senha inicial (8 a 32 caracteres).
`role`	`string`	Não	Papel: `agent`, `supervisor` ou `admin` (padrão: `agent`).
`signature`	`string`	Não	Assinatura das respostas públicas.
`avatarUrl`	`string`	Não	URL do avatar (máx. 255 caracteres).
`isAvailable`	`boolean`	Não	Disponível para round-robin (padrão: `true`).
`maxOpenTickets`	`number`	Não	Teto de tickets abertos (mín. 1; `null` = ilimitado).
`isActive`	`boolean`	Não	Agente ativo (padrão: `true`).
`categoryIds`	`number[]`	Não	IDs das categorias (filas) que o agente atende.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/agents" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Souza",
    "email": "joao@acme.com",
    "password": "Password@123",
    "role": "agent",
    "maxOpenTickets": 10,
    "categoryIds": [1, 2]
  }'

Respostas

201 Created

Retorna o ID do agente criado.

json

{
  "id": 2
}

403 Forbidden

O agente autenticado não é admin nem supervisor.

json

{
  "message": "Você não tem permissão para gerenciar este recurso",
  "code": "FORBIDDEN"
}

Atualizar Agente

Atualiza os dados de um agente. Se categoryIds for enviado, os vínculos de filas são substituídos pela nova lista.

http

PUT /v1/helpdesk/agent/agents/:id

Payload (Body)

Todos os campos da criação são opcionais no update, incluindo password (para redefinir a senha do agente) e categoryIds.

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Agente

Remove um agente via soft delete — as respostas e o histórico de auditoria que ele assinou são preservados.

http

DELETE /v1/helpdesk/agent/agents/:id

Respostas

204 No Content

Remoção concluída com sucesso.

Agentes & Autenticação (Staff) ​

Estrutura de Dados Principal ​

Roles ​

Autenticação ​

Login ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Logout ​

Respostas ​

Perfil do Agente Autenticado ​

Respostas ​

Atualizar Próprio Perfil ​

Payload (Body) ​

Respostas ​

Trocar Senha ​

Payload (Body) ​

Respostas ​

Gerenciamento de Agentes ​

Listar Agentes ​

Parâmetros de Query ​

Respostas ​

Listar Agentes para Dropdown ​

Parâmetros de Query ​

Respostas ​

Obter Agente por ID ​

Parâmetros de Rota ​

Respostas ​

Criar Agente ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Agente ​

Payload (Body) ​

Respostas ​

Remover Agente ​

Respostas ​

Agentes & Autenticação (Staff)

Estrutura de Dados Principal

Roles

Autenticação

Login

Payload (Body)

Exemplo de Requisição

Respostas

Logout

Respostas

Perfil do Agente Autenticado

Respostas

Atualizar Próprio Perfil

Payload (Body)

Respostas

Trocar Senha

Payload (Body)

Respostas

Gerenciamento de Agentes

Listar Agentes

Parâmetros de Query

Respostas

Listar Agentes para Dropdown

Parâmetros de Query

Respostas

Obter Agente por ID

Parâmetros de Rota

Respostas

Criar Agente

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Agente

Payload (Body)

Respostas

Remover Agente

Respostas