Módulo de Helpdesk (Tickets)

O módulo de Helpdesk é uma central de atendimento headless completa. Ele permite que um workspace opere um sistema de tickets com filas (categorias), SLA por prioridade, atribuição manual ou automática, notas internas, auditoria e um portal do cliente — tudo isolado por instância.

Este módulo foi projetado para ser flexível e escalável, permitindo que cada workspace tenha suas próprias instâncias do Helpdesk com configurações, agentes, clientes e tickets totalmente isolados.

Por que utilizar este módulo?

Antes de mergulharmos nos detalhes técnicos, é importante entender que este módulo não é apenas um formulário de contato. Ele foi construído com foco em:

Isolamento Total: Os dados são isolados por instância do Helpdesk (helpdesk_id é o eixo de isolamento) — um agente ou cliente de uma instância não enxerga dados de outra.
Três Públicos, Três APIs: O dono da conta gerencia a instância, o time de atendimento opera a fila e o cliente acompanha seus chamados pelo portal — cada um com sua própria autenticação.
Liberdade de Frontend: Sendo 100% headless, você consome o painel do atendente e o portal do cliente e decide como e onde exibi-los.

As Três Áreas do Módulo

O Helpdesk possui três áreas independentes, cada uma com seu prefixo de rotas e seu contexto de autenticação:

Área	Prefixo das rotas	Público	Guard
Gestão da instância	`/user/helpdesks`	Dono da conta (módulo `user`)	`user`
Staff (atendentes)	`/v1/helpdesk/agent`	Agentes, supervisores e administradores	`helpdeskAgent`
Portal do cliente	`/v1/helpdesk/customer`	Clientes/solicitantes	`helpdeskCustomer`

A gestão da instância cria e configura as instâncias do Helpdesk (domínios autorizados, storage, e-mail, gatilhos automáticos) e segue a autenticação da plataforma.
A área de staff concentra a operação do atendimento: agentes, clientes, categorias, tickets, threads, políticas de SLA, tags, respostas prontas, arquivos e métricas.
A área do cliente expõe o portal: registro e login públicos, abertura de tickets, respostas e acompanhamento da timeline pública.

Autenticação e Contexto

Identificação da Instância

Todas as requisições para os endpoints /v1/helpdesk/** (públicos ou privados) devem incluir o identificador da instância:

Header	Tipo	Obrigatório	Descrição
`X-Helpdesk-Id`	`UUID`	Sim	O `tokenHeader` da instância, obtido no painel administrativo do workspace.

Como funciona o X-Helpdesk-Id

O middleware resolve a instância pelo tokenHeader e valida se o domínio (ou IP) de origem está na lista de domínios autorizados do workspace, conforme a configuração allowBy (domain ou ip) de cada domínio vinculado. Requisições sem o header, com instância inexistente ou com origem não autorizada recebem 401 Unauthorized. Instâncias inativas (ou cujo workspace está inativo) recebem 503 Service Unavailable.

bash

curl -X GET "https://api.us.basis.tavares.in/v1/helpdesk/customer/tickets" \
  -H "X-Helpdesk-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Tokens de Acesso

Staff e cliente possuem tokens e credenciais separados, obtidos em endpoints de login distintos:

Contexto	Endpoint de login	Credenciais
Staff	`POST /v1/helpdesk/agent/agents/login`	`email` + `password`
Cliente	`POST /v1/helpdesk/customer/users/login` (ou registro em `POST /v1/helpdesk/customer/users`)	`email` + `password`

Ambos retornam um token Bearer com validade de 30 dias. O logout invalida o token imediatamente.

Para endpoints protegidos, forneça o token do contexto correspondente:

Header	Valor	Descrição
`Authorization`	`Bearer <token>`	Token obtido no login do staff ou do cliente.

Tokens não são intercambiáveis

Um token de staff não acessa endpoints de cliente e vice-versa. Cada contexto possui seu próprio endpoint de login e sua própria base de credenciais.

Resumo dos Headers

http

GET /v1/helpdesk/agent/tickets
X-Helpdesk-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}
Accept: application/json

Controle de Acesso (RBAC)

O staff possui três papéis (roles), definidos no cadastro do agente:

Role	Escopo
`admin`	Acesso total à instância, incluindo gerenciamento de agentes e respostas prontas de qualquer pessoa.
`supervisor`	Pode gerenciar agentes (criar, editar, remover).
`agent`	Opera tickets, threads, categorias, tags e os demais recursos operacionais.

Regras adicionais:

Criar, editar e remover agentes exige admin ou supervisor — demais roles recebem 403 FORBIDDEN.
Respostas prontas são pessoais: só o autor ou um admin pode editá-las ou removê-las.
No portal, o cliente só enxerga os próprios tickets, threads e arquivos — recursos de terceiros retornam 404 Not Found.

Billing e Limites de Plano

Todas as rotas do módulo (públicas e privadas) passam por limite de plano (usageLimit) e contabilização de uso horário (workspaceHourlyUsage). Quando o plano não permite a operação, a API responde 402 Payment Required com um dos seguintes códigos:

Code	Significado
`PENDING_INVOICES`	Existem faturas pendentes no workspace.
`PLAN_REQUIRED`	O workspace não possui um plano ativo para o módulo.
`USAGE_LIMIT_EXCEEDED`	O limite de uso do plano foi atingido.

Convenções da API

Os endpoints /v1/helpdesk/** seguem convenções consistentes em todas as áreas:

Paginação: parâmetros page/perPage (máx. 100) com resposta no formato { "meta": { "currentPage", "perPage" }, "data": [...] }.
Listas para dropdown: endpoints GET .../list retornam [{ "value", "label" }], com search opcional — ideais para selects e filtros no frontend.
Ordenação: orderBy (campos permitidos por recurso) + orderDirection (asc/desc).
Soft delete: registros removidos não aparecem em nenhuma consulta.
Erros de validação: 422 Unprocessable Entity com errors: [{ "message", "rule", "field" }] (mensagens em pt/en via i18n).
Datas: sempre em ISO 8601; filtros de período usam YYYY-MM-DD.
IDs: tratados como números, sem assumir tamanho (as tabelas usam bigint).
Rate limit: 3000 req/min para o módulo (global); as rotas de gestão da instância (/user/helpdesks) seguem o throttle do módulo user (100 req/min).
Numeração de tickets: sequencial por instância (1, 2, 3...), exibida com o prefixo configurável (ticketPrefix, padrão TCK) — TCK-1, TCK-2, etc.

Códigos de Erro de Negócio

Erros de regra de negócio retornam status 4xx com um code identificador no corpo da resposta:

Code	Status	Significado
`FORBIDDEN`	403	Papel sem permissão para a ação (gerenciar agentes, resposta pronta de outro autor).
`AGENT_NOT_FOUND`	404	Agente informado na atribuição/transferência não existe.
`TICKET_ALREADY_ASSIGNED`	409	O ticket já foi atribuído a outro agente (trava de concorrência no `assign`).
`TICKET_CLOSED`	422	Cliente tentou responder um ticket `closed`.
`INVALID_INTERNAL_NOTE`	422	Notas internas (`isInternal`) são exclusivas de agentes.

Automações Nativas

A instância carrega gatilhos configuráveis que mudam o estado dos tickets sem intervenção manual:

Auto-reopen: resposta do cliente em ticket solved reabre o chamado (isAutoReopenSolved).
Auto-pending: resposta pública do agente em ticket open move o chamado para pending (isAutoPendingOnAgentReply).
Auto-assign: distribuição round-robin na criação quando settings.autoAssign === true.
Auto-close: comando helpdesk:auto-close fecha tickets solved além do prazo (autoCloseAfterDays).

Detalhes em Instâncias & Setup e Tickets.

Próximos Passos

Agora que você entende a base do módulo, explore as funcionalidades detalhadas:

Módulo de Helpdesk (Tickets) ​

Por que utilizar este módulo? ​

As Três Áreas do Módulo ​

Autenticação e Contexto ​

Identificação da Instância ​

Tokens de Acesso ​

Resumo dos Headers ​

Controle de Acesso (RBAC) ​

Billing e Limites de Plano ​

Convenções da API ​

Códigos de Erro de Negócio ​

Automações Nativas ​

Próximos Passos ​