Instâncias & Setup

Uma instância de Helpdesk é a central de atendimento da sua empresa dentro da plataforma: tickets, clientes, agentes, categorias e políticas de SLA vivem dentro dela. Antes de usar qualquer endpoint do Helpdesk (/v1/helpdesk/...), você precisa provisionar uma instância — e é isso que estes endpoints fazem.

A criação é mais do que um simples INSERT: em uma única transação, a plataforma cria a categoria padrão Geral, as 4 políticas de SLA padrão e o primeiro agente com papel de admin, devolvendo as credenciais de acesso e o tokenHeader que identifica a instância em todas as chamadas seguintes.

Headers obrigatórios

Estes endpoints pertencem à área do dono da conta na plataforma. Todas as requisições exigem Authorization: Bearer {token} (autenticação da plataforma, guard user) e o parâmetro de query workspaceId com o ID do projeto. O header X-Helpdesk-Id não é usado aqui — ele é o tokenHeader gerado na criação da instância. Limite de 100 requisições por minuto (429 ao exceder).

---

Estrutura de Dados Principal

Uma instância de Helpdesk contém as seguintes informações principais:

Campo	Tipo	Descrição
name	String	Nome da instância (máx. 150 caracteres).
slug	String	Slug gerado automaticamente a partir do nome.
tokenHeader	String	UUID que identifica a instância — usado como X-Helpdesk-Id nas APIs /v1/helpdesk/**.
timezone	String	Fuso horário da instância (padrão: UTC) — usado no cálculo de SLA em horário comercial.
locale	String	Locale padrão (padrão: pt_BR).
ticketPrefix	String	Prefixo da numeração dos tickets (máx. 10 caracteres, padrão: TCK).
lastTicketNumber	Number	Contador sequencial de tickets da instância.
isAutoReopenSolved	Boolean	Resposta do cliente reabre ticket solved (padrão: true).
isAutoPendingOnAgentReply	Boolean	Resposta pública do agente move ticket open para pending (padrão: true).
autoCloseAfterDays	Number	Dias para fechar tickets solved automaticamente (nulo = nunca).
settings	Object	Configurações livres da instância (JSONB) — ver abaixo.
isActive	Boolean	Indica se a instância está ativa.
workspaceStorageId	Number	Provedor de armazenamento do projeto (nulo se não vinculado).
workspaceMailId	Number	Provedor de e-mail do projeto (nulo se não vinculado).

Configurações (settings)

O objeto settings é livre, mas duas chaves têm comportamento nativo:

Chave	Formato	Efeito
businessHours	{ weekDays: number[], start: 'HH:mm', end: 'HH:mm' }	Janela de horário comercial usada por políticas de SLA com isBusinessHoursOnly. weekDays usa 0 = domingo até 6 = sábado.
autoAssign	boolean	Quando true, tickets criados sem agente são distribuídos automaticamente (round-robin).

{
  "businessHours": { "weekDays": [1, 2, 3, 4, 5], "start": "09:00", "end": "18:00" },
  "autoAssign": true
}

Validação do businessHours

A configuração só é aplicada se for válida: start/end no formato HH:mm com start < end e ao menos um dia da semana entre 0 e 6. Caso contrário, o SLA cai no cálculo em tempo corrido.

Gatilhos Automáticos

Gatilho	Campo	Comportamento
Auto-reopen	isAutoReopenSolved	Cliente responde um ticket solved → status volta para open, solvedAt é zerado e reopenedCount incrementa.
Auto-pending	isAutoPendingOnAgentReply	Agente envia resposta pública em ticket open → status muda para pending.
Auto-close	autoCloseAfterDays	O comando helpdesk:auto-close fecha (closed) tickets solved há mais dias que o configurado.

Auto-close via comando Ace

O fechamento automático não é um agendador interno: rode node ace helpdesk:auto-close (idealmente em cron) para processar todas as instâncias ativas com autoCloseAfterDays configurado. Cada fechamento gera um evento de sistema na timeline do ticket.

---

Setup Inicial

O POST /user/helpdesks executa todo o provisionamento em uma única transação — se qualquer etapa falhar, nada é persistido:

1. Categoria default: chamada Geral (slug: geral), ativa.

2. 4 políticas de SLA padrão: uma por prioridade, todas em tempo corrido (isBusinessHoursOnly: false):

   Prioridade	Nome	Primeira resposta	Resolução
   low	Baixa	1440 min (24h)	4320 min (72h)
   normal	Normal	480 min (8h)	1440 min (24h)
   high	Alta	120 min (2h)	480 min (8h)
   urgent	Urgente	15 min	240 min (4h)

3. Primeiro agente: criado com o nome e e-mail do usuário autenticado na plataforma, papel admin, disponível para round-robin e vinculado à categoria Geral.

4. Resposta 201: inclui email, password (senha temporária, exibida uma única vez) e tokenHeader.

Guarde a senha temporária e o tokenHeader imediatamente — eles não podem ser recuperados depois (o token pode ser regerado, a senha não).

---

Endpoints

Listar Instâncias

Lista as instâncias de Helpdesk do projeto, com paginação e busca por nome.

GET /user/helpdesks

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
workspaceId	number	Sim	ID do projeto (workspace) ao qual a instância pertence.
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 da instância (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/user/helpdesks?workspaceId=1&page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de instâncias.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "1",
      "name": "Suporte Acme",
      "slug": "suporte-acme",
      "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ticketPrefix": "TCK",
      "isActive": true,
      "createdAt": "2026-09-01T10:05:33.000+00:00",
      "updatedAt": "2026-09-01T10:05:33.000+00:00"
    }
  ]
}

403 Forbidden

Ocorre quando o workspaceId não é informado ou o projeto pertence a outro usuário.

{
  "notice": "O projeto precisa ser informado",
  "field": "workspaceId"
}

Criar Instância

Provisiona uma nova instância de Helpdesk, executando o setup inicial completo em transação.

POST /user/helpdesks

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
helpdesk.name	string	Sim	Nome da instância (máx. 150 caracteres).
helpdesk.workspaceStorageId	number	Não	ID do provedor de armazenamento do projeto (deve existir e estar ativo); necessário para uploads de arquivos.
helpdesk.workspaceMailId	number	Não	ID do provedor de e-mail do projeto (deve existir e estar ativo).
helpdesk.timezone	string	Não	Fuso horário (máx. 64 caracteres, padrão: UTC).
helpdesk.locale	string	Não	Locale padrão (máx. 10 caracteres, padrão: pt_BR).
helpdesk.ticketPrefix	string	Não	Prefixo da numeração de tickets (máx. 10 caracteres, padrão: TCK).
helpdesk.isAutoReopenSolved	boolean	Não	Reabre ticket solved quando o cliente responde (padrão: true).
helpdesk.isAutoPendingOnAgentReply	boolean	Não	Move ticket open para pending quando o agente responde (padrão: true).
helpdesk.autoCloseAfterDays	number	Não	Dias para auto-close de tickets solved (mín. 1; null = nunca).
helpdesk.isActive	boolean	Não	Indica se a instância já nasce ativa (padrão: true).
workspaceDomains	number[]	Sim	IDs dos domínios do projeto vinculados à instância (pode ser um array vazio).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/user/helpdesks?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "helpdesk": {
      "name": "Suporte Acme",
      "workspaceStorageId": null,
      "workspaceMailId": null,
      "ticketPrefix": "SUP",
      "autoCloseAfterDays": 7
    },
    "workspaceDomains": [3]
  }'

Respostas

201 Created

Retorna as credenciais do primeiro agente (admin) e o token da instância. A senha temporária é exibida uma única vez.

{
  "email": "maria@acme.com",
  "password": "a1b2c3d4",
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "helpdesk.name"
    }
  ]
}

Obter Instância por ID

Recupera os detalhes de uma instância, incluindo os domínios, o provedor de armazenamento e o provedor de e-mail vinculados.

GET /user/helpdesks/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da instância.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/user/helpdesks/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna a instância com workspaceDomains, workspaceStorage e workspaceMail.

{
  "id": "1",
  "workspaceId": "1",
  "workspaceMailId": null,
  "workspaceStorageId": null,
  "name": "Suporte Acme",
  "slug": "suporte-acme",
  "timezone": "UTC",
  "locale": "pt_BR",
  "ticketPrefix": "TCK",
  "lastTicketNumber": "0",
  "isAutoReopenSolved": true,
  "isAutoPendingOnAgentReply": true,
  "autoCloseAfterDays": 7,
  "settings": {},
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isActive": true,
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00",
  "deletedAt": null,
  "workspaceDomains": [
    {
      "id": "3",
      "uri": "suporte.acme.com"
    }
  ],
  "workspaceStorage": null,
  "workspaceMail": null
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Atualizar Instância

Atualiza as configurações de uma instância e sincroniza os domínios vinculados. Usa o mesmo schema da criação: o objeto helpdesk (com name obrigatório) e o array workspaceDomains (que substitui os vínculos atuais).

PUT /user/helpdesks/:id

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/user/helpdesks/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "helpdesk": {
      "name": "Suporte Acme",
      "isAutoReopenSolved": false,
      "autoCloseAfterDays": null
    },
    "workspaceDomains": [3]
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Remover Instância

Remove uma instância via soft delete — o registro deixa de aparecer em qualquer consulta, mas não é apagado fisicamente.

DELETE /user/helpdesks/:id

Exemplo de Requisição

curl -X DELETE "https://api.us.basis.tavares.in/user/helpdesks/1?workspaceId=1" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Listar para Dropdown

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

GET /user/helpdesks/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
workspaceId	number	Sim	ID do projeto (workspace).
search	string	Não	Busca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/user/helpdesks/list?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com as instâncias.

[
  {
    "value": 1,
    "label": "Suporte Acme"
  }
]

Regerar Token da Instância

Gera um novo tokenHeader (UUID) para a instância. O token anterior deixa de ser válido imediatamente — todas as integrações que usam o header X-Helpdesk-Id precisam ser atualizadas.

PATCH /user/helpdesks/:id/change-token

Exemplo de Requisição

curl -X PATCH "https://api.us.basis.tavares.in/user/helpdesks/1/change-token?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o novo token da instância.

{
  "tokenHeader": "9b2f7c1e-4d3a-4e5f-8a6b-1c2d3e4f5a6b"
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.