tickets

Dono do ciclo de vida do chamado: abertura por qualquer canal, transições de status, atribuição, relógio de SLA, avaliação de satisfação e a página pública de acompanhamento.

Caminho de origem: libraries/sac/src/ticket

Arquivo do módulo: ticket.module.ts

Introdução

Os chamados são o centro do módulo. Toda entrada converge para cá: o formulário público do site (`POST /sac/public/tickets`), uma submissão interna de outra biblioteca, um atendente abrindo chamado no painel, e os canais de entrada (e-mail e WhatsApp).

O número público de acompanhamento fica em `protocol`, no formato `AAAAMM-NNNNNN`, gerado por um default do Postgres (`sac_next_protocol()`) e não pelo código da aplicação — então duas submissões simultâneas nunca colidem nele. A sequência é global, e não por mês: `202608-000004` significa "o quarto chamado de todos os tempos, aberto em agosto de 2026".

O relógio do SLA fica no próprio chamado (`first_response_due_at`, `resolution_due_at`, `paused_at`, `paused_ms`) e é recalculado conforme ele se move. Passar para `waiting_customer` pausa o relógio; a resposta do cliente o retoma e desloca os prazos pelo tempo parado, de modo que a espera pelo cliente nunca conta contra a equipe.

`requester_email` é opcional: um chamado de WhatsApp não tem e-mail, e o solicitante é identificado por `requester_phone`. Submissões duplicadas são colapsadas por `dedupe_hash` dentro de uma janela configurável, que é o que faz um formulário com duplo clique devolver o protocolo original em vez de abrir um segundo chamado.

Endpoints HTTP

8 endpoints

Listagem paginada com os filtros usados pelas telas de lista e de quadro.

Query: page, pageSize, search, status, priority, category_id, assignee_user_id

Contadores agregados da linha de KPIs (abertos, vencidos, sem responsável, resolvidos).

Chamado completo, com solicitante, estado do SLA, categoria, canal e anexos.

Params: id (int)

Abre um chamado pelo painel, no canal `admin`.

Body

Field	Type	Required	Notes
requester_name	string	yes	—
requester_email	string (email)	no	Optional: a WhatsApp ticket is identified by phone instead
requester_phone	string	no	—
subject	string	yes	—
description	string	yes	—
category_id	int	no	—
priority	low \| normal \| high \| urgent	no	—

Move o chamado pela máquina de status, pausando ou retomando o relógio do SLA conforme o caso.

Params: id (int)

Resposta do atendente ou nota interna. Uma resposta pública é entregue pelo canal do chamado — e-mail, ou WhatsApp quando o canal é do tipo whatsapp.

Params: id (int)

Body

Field	Type	Required	Notes
body_html	string	no	Sanitized on write; plain `body` is derived from it
visibility	public \| internal	no	An internal note is never delivered to the customer and never counts as the first response

Formulário de contato do site. Honeypot, CAPTCHA opcional e uma chave geral o protegem.

Página de acompanhamento do solicitante. O e-mail precisa bater com o chamado; caso contrário, só o protocolo permitiria enumerar chamados alheios.

Params: protocol
Query: email