Lista de Clientes
Módulo: Pessoas Caminho na aplicação: Menu > Pessoas > Clientes (/clientes) Última atualização: 20/04/2026
Para que serve
Exibe todos os clientes cadastrados na empresa. Permite pesquisar, filtrar por tipo de pessoa e remover registros. O ícone Editar (lápis) na coluna de ações abre o cadastro para edição.
Quem pode usar
Todos os usuários autenticados.
Como usar (passo a passo)
- Acesse Menu > Pessoas > Clientes.
- A lista carrega automaticamente os primeiros 50 registros.
- Use o campo de busca para filtrar por nome, documento ou e-mail.
- Use o filtro Tipo pessoa para restringir a Pessoa Física ou Pessoa Jurídica.
- Role a página para baixo para carregar mais registros (scroll infinito, 50 por vez).
- Clique em Novo Cliente para abrir o cadastro.
- Clique no ícone Editar (lápis) na coluna de ações da linha para editar o cliente.
- Para remover, clique no ícone de lixeira na linha desejada e confirme a exclusão.
- Clique em Limpar para redefinir os filtros.
Campos da tela
Listagem com as seguintes colunas e filtros:
| Campo | Tipo | Descrição |
|---|---|---|
| ID | Coluna | Identificador interno sequencial (id_interno). |
| Nome | Coluna | Razão social (PJ) ou nome completo (PF). |
| Fantasia | Coluna | Nome fantasia; exibe "—" se não informado. |
| Tipo | Coluna | Tag PJ (azul) ou PF (verde). |
| Documento | Coluna | CNPJ ou CPF formatado. |
| Situação | Coluna | Situação cadastral na Receita (somente PJ); exibe "—" para PF. |
| Cidade/UF | Coluna | Cidade e UF do endereço. |
| Status | Coluna | Tag Ativo (verde) ou Inativo (cinza). |
| Busca | Filtro | Pesquisa por nome, documento ou e-mail. |
| Tipo pessoa | Filtro | Seleciona Pessoa Física ou Pessoa Jurídica. |
Validações e regras
- Remoção: ao confirmar a exclusão o sistema executa soft delete (desativa o registro, não o apaga fisicamente). A lista é recarregada do início após a operação.
- Scroll infinito: ao chegar perto do fim da página o sistema carrega a próxima página de 50 registros automaticamente. Quando todos os registros estiverem carregados exibe "Todos os registros carregados".
- Filtros reativos: qualquer alteração no campo de busca ou no filtro de tipo recarrega a lista a partir da página 1.
Mensagens de erro e o que fazer
| Mensagem | Causa | Como resolver |
|---|---|---|
| "Erro ao carregar clientes" | Falha na requisição à API ao listar. | Verifique a conexão e recarregue a página. |
| "Erro ao remover cliente" | Falha na requisição à API ao deletar. | Verifique a conexão e tente novamente. |
| "Cliente removido com sucesso" | Confirmação de remoção bem-sucedida. | Nenhuma ação necessária. |
Integrações e dependências
- Endpoint:
GET /clientes(parâmetros:page,limit,busca,tipo_pessoa). - Endpoint:
DELETE /clientes/:id. - Tela de destino ao ícone Editar ou "Novo Cliente": Cadastro de Cliente.
Dúvidas frequentes
A exclusão apaga o cliente do banco de dados? Não. O sistema aplica soft delete: o cliente é desativado e deixa de aparecer na listagem, mas o registro permanece no banco.
Por que o campo "Situação" aparece "—" para clientes PF? A situação cadastral vem da Receita Federal e é válida apenas para CNPJ. Para CPF este campo não se aplica.
Como voltar ao topo da lista depois de rolar? Altere qualquer filtro ou clique em Limpar — a lista volta à página 1 automaticamente.
Histórico de alterações
| Data | Alteração |
|---|---|
| 20/04/2026 | Documento inicial criado. |