Clientes & Portal

Os clientes (solicitantes) são quem abre chamados e acompanha a timeline pública pelo portal. Possuem autenticação própria do módulo e enxergam apenas os próprios dados — tickets, threads públicas e arquivos de outros clientes retornam 404 Not Found.

O cadastro pode acontecer por dois caminhos: o staff cria o cliente pela área de agentes (útil para tickets criados por telefone ou e-mail), ou o próprio cliente se registra no portal público.

Senha opcional no cadastro pelo staff

Quando o staff cria um cliente sem informar password, o registro existe sem senha — o cliente não consegue fazer login no portal até que uma senha seja definida (via update do staff). O login de conta sem senha falha com 422.

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} — token do agente na área de staff, token do cliente no portal.

---

Estrutura de Dados Principal

Campo	Tipo	Descrição
id	Number	Identificador do cliente.
firstName	String	Nome (máx. 100 caracteres).
lastName	String	Sobrenome (máx. 100 caracteres).
email	String	E-mail de login (máx. 250 caracteres, único por instância).
phone	String	Telefone (máx. 30 caracteres, opcional).
company	String	Organização do solicitante, texto livre (máx. 150 caracteres, opcional).
externalIdentifier	String	ID no sistema de origem — ERP, CRM etc. (máx. 150 caracteres, opcional).
locale	String	Locale do cliente (máx. 10 caracteres, opcional).
timezone	String	Fuso horário do cliente (máx. 50 caracteres, opcional).
avatarUrl	String	URL do avatar (máx. 255 caracteres, opcional).
isActive	Boolean	Cliente ativo — inativos não conseguem autenticar no portal.

---

Gestão pelo Staff

Endpoints da área de agentes (/v1/helpdesk/agent/users), disponíveis para qualquer agente autenticado.

Listar Clientes

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

GET /v1/helpdesk/agent/users

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, e-mail ou empresa (máx. 150 caracteres).
isActive	boolean	Não	Filtra por clientes ativos/inativos.
orderBy	string	Não	Campo de ordenação: id, firstName, email, company ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.

Respostas

200 OK

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

Listar Clientes para Dropdown

Retorna os clientes em formato simplificado (value/label), ideal para selects no frontend (ex.: escolher o solicitante ao criar um ticket).

GET /v1/helpdesk/agent/users/list

Parâmetros de Query

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

Respostas

200 OK

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

[
  {
    "value": 1,
    "label": "Carlos Pereira"
  }
]

Obter Cliente por ID

GET /v1/helpdesk/agent/users/:id

Respostas

200 OK

Retorna os dados do cliente.

404 Not Found

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

Criar Cliente

Cria um cliente na instância. O e-mail deve ser único entre os clientes ativos da instância.

POST /v1/helpdesk/agent/users

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
firstName	string	Sim	Nome (máx. 100 caracteres).
lastName	string	Sim	Sobrenome (máx. 100 caracteres).
email	string	Sim	E-mail (máx. 250 caracteres, único por instância).
password	string	Não	Senha do portal (8 a 32 caracteres); omitido, o cliente fica sem acesso ao portal.
phone	string	Não	Telefone (máx. 30 caracteres).
company	string	Não	Empresa (máx. 150 caracteres).
externalIdentifier	string	Não	ID no sistema de origem (máx. 150 caracteres).
locale	string	Não	Locale (máx. 10 caracteres).
timezone	string	Não	Fuso horário (máx. 50 caracteres).
avatarUrl	string	Não	URL do avatar (máx. 255 caracteres).
isActive	boolean	Não	Cliente ativo (padrão: true).

Respostas

201 Created

Retorna o ID do cliente criado.

{
  "id": 1
}

Atualizar Cliente

Atualiza os dados de um cliente — todos os campos da criação são opcionais, incluindo password.

PUT /v1/helpdesk/agent/users/:id

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Cliente

Remove um cliente via soft delete.

DELETE /v1/helpdesk/agent/users/:id

Respostas

204 No Content

Remoção concluída com sucesso.

---

Portal do Cliente

Endpoints da área do cliente (/v1/helpdesk/customer/users). Registro e login são públicos (exigem apenas o X-Helpdesk-Id); os demais exigem o token do cliente (guard helpdeskCustomer).

Registrar-se

Cria a conta do cliente no portal. Endpoint público.

POST /v1/helpdesk/customer/users

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
firstName	string	Sim	Nome (máx. 100 caracteres).
lastName	string	Sim	Sobrenome (máx. 100 caracteres).
email	string	Sim	E-mail (máx. 250 caracteres, único por instância).
password	string	Sim	Senha (8 a 32 caracteres).
phone	string	Não	Telefone (máx. 30 caracteres).
company	string	Não	Empresa (máx. 150 caracteres).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/customer/users" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Carlos",
    "lastName": "Pereira",
    "email": "carlos@cliente.com",
    "password": "Password@123"
  }'

Respostas

201 Created

Retorna o ID do cliente criado.

{
  "id": 1
}

422 Unprocessable Entity

Erro de validação — por exemplo, e-mail já utilizado por outro cliente da instância.

Login

Autentica um cliente e retorna o token de acesso do portal. Endpoint público.

POST /v1/helpdesk/customer/users/login

Payload (Body)

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

Respostas

200 OK

Retorna o token Bearer com validade de 30 dias.

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

422 Unprocessable Entity

Credenciais inválidas, cliente não encontrado ou conta criada sem senha.

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

Logout

Invalida o token usado na requisição imediatamente.

POST /v1/helpdesk/customer/users/logout

Respostas

204 No Content

Token invalidado com sucesso.

Perfil do Cliente Autenticado

Retorna os dados do cliente autenticado.

GET /v1/helpdesk/customer/users/me

Respostas

200 OK

Retorna os dados do cliente.

{
  "id": 1,
  "helpdeskId": 1,
  "firstName": "Carlos",
  "lastName": "Pereira",
  "email": "carlos@cliente.com",
  "phone": null,
  "company": null,
  "locale": null,
  "timezone": null,
  "avatarUrl": null,
  "isActive": true,
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00"
}

Atualizar Próprio Perfil

Atualiza os dados de perfil do cliente autenticado.

PUT /v1/helpdesk/customer/users/me

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
firstName	string	Não	Nome (máx. 100 caracteres).
lastName	string	Não	Sobrenome (máx. 100 caracteres).
phone	string	Não	Telefone (máx. 30 caracteres); envie null para remover.
company	string	Não	Empresa (máx. 150 caracteres); envie null para remover.
locale	string	Não	Locale (máx. 10 caracteres); envie null para remover.
timezone	string	Não	Fuso horário (máx. 50 caracteres); 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 cliente autenticado.

PATCH /v1/helpdesk/customer/users/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.

---

Próximos Passos

Com o cliente autenticado, ele já pode abrir e acompanhar chamados — veja Tickets e Threads & Timeline.