Clientes
Criado por Igor Ribeiro em 30 de setembro de 2026
Atualizado por Igor Ribeiro em 01 de outubro de 2026
Clientes — Painel
A tela Clientes é onde a transportadora cadastra e gerencia os clientes de entrega — os destinatários finais das mercadorias transportadas, cujos endereços alimentam as rotas de entrega.
Visão Geral
A tela Clientes é onde a transportadora cadastra e gerencia os clientes de entrega — os destinatários finais das mercadorias transportadas, cujos endereços alimentam as rotas de entrega. Não deve ser confundida com o cadastro de empresas clientes da própria plataforma (isso é feito em uma área administrativa restrita à equipe interna, fora do escopo desta tela). Na tela Clientes, o usuário cadastra e edita dados gerais, endereço com posição geográfica, contato e parâmetros de roteirização de cada cliente de entrega, ativa ou inativa registros e, para transportadoras clientes do sistema integrado Atak, sincroniza em lote os clientes já atualizados nesse sistema integrado. É complementar à tela de Entregas, que usa o endereço cadastrado aqui como destino de cada entrega.
Pré-requisitos
Para que a tela Clientes funcione, as seguintes condições precisam estar atendidas:
- Sessão autenticada válida. Sem uma sessão ativa, o sistema recusa qualquer ação nesta tela.
- Módulo Clientes ativo nas permissões do usuário. Ao abrir a tela sem essa permissão, o usuário é redirecionado automaticamente para a tela Início, sem ver nenhum conteúdo da tela Clientes. Administradores do sistema têm acesso irrestrito.
- Permissão de edição para as ações que alteram dados. O botão ADICIONAR e, em cada linha da lista, os ícones de editar e de ativar/inativar ficam desabilitados para usuários sem permissão de edição na área Clientes, mesmo que o módulo esteja ativo apenas para consulta.
- Integração e endereço da API configurados (apenas para Sincronizar). O botão SINCRONIZAR só é exibido para transportadoras clientes do sistema integrado Atak, e só funciona se a integração e o endereço da API do sistema integrado estiverem configurados em Configurações → Roteirização.
Fluxo Operacional
- O usuário acessa a tela Clientes a partir do menu do Painel.
- A tela carrega em paralelo a lista de cidades disponíveis para filtro e a lista de clientes já cadastrados; se a transportadora for cliente do sistema integrado Atak, carrega também as configurações de integração antes de finalizar a abertura.
- O usuário pode filtrar a lista por status, documento, código, nome, CEP, logradouro, bairro, cidade e UF, e ordenar pelas colunas Nome, Cidade ou UF.
- Pelo botão ADICIONAR, o usuário abre o formulário de cadastro de um cliente novo; pelo ícone de editar de um cliente da lista, abre o mesmo formulário pré-preenchido.
- No formulário, o usuário preenche dados gerais, endereço (com posição confirmada num mapa), contato e, opcionalmente, o tempo médio de descarregamento e os horários habilitados para descarregamento por dia da semana.
- Pelo ícone de ativar/inativar da lista, o usuário alterna o status de um cliente, mediante confirmação.
- Transportadoras clientes do sistema integrado Atak podem, alternativamente, sincronizar em lote os clientes atualizados nesse sistema integrado.
- Ações de cadastro, edição, ativação/inativação e sincronização atualizam a lista de clientes automaticamente ao serem concluídas.
Interface e Comportamentos
Lista de Clientes Cadastrados
A lista exibe Nome, CPF/CNPJ, CEP, Endereço, Número, Complemento, Bairro, Cidade e UF de cada cliente, com paginação selecionável entre 25 (padrão), 50, 75 ou 100 registros por página. Apenas as colunas Nome, Cidade e UF podem ser usadas para ordenar a lista pelo cabeçalho; a ordenação padrão é por nome, em ordem crescente. Um painel de filtros (recolhido por padrão) permite localizar clientes por status, documento, código, nome, CEP, logradouro, bairro, cidade (seleção múltipla) e UF (seleção múltipla); ao acionar uma nova busca pelo botão Filtrar, a lista volta sempre para a primeira página. O botão Limpar restaura todos os filtros aos valores padrão, incluindo status ATIVO.
As opções de cidade do filtro são agrupadas por nome normalizado (sem acentuação, em maiúsculas); ao marcar um grupo de cidade, a busca é expandida para todas as variações de grafia associadas a ele. A lista de cidades e UFs disponível para filtro é obtida a partir dos endereços já usados em entregas da transportadora — uma cidade que só existe em cadastros de cliente, mas nunca foi associada a uma entrega, não aparece como opção de filtro.
Para cada cliente da lista, estão disponíveis os ícones: editar (abre o formulário de edição) e ativar/inativar (alterna o status do cliente).
Cadastro e Edição de Cliente
Pelo botão ADICIONAR (ou pelo ícone de editar de um cliente já cadastrado), a tela abre um formulário com Status, CPF/CNPJ, Nome, endereço completo, telefone, Whatsapp, e-mail de contato e parâmetros de roteirização; para transportadoras clientes Atak, também o código do cliente e o código do tipo de cadastro no sistema integrado. O CPF/CNPJ só pode ser digitado no cadastro de um cliente novo — na edição de um cliente já existente, o campo fica bloqueado. Ao editar, os campos de endereço (logradouro, bairro, cidade, UF, país) são exibidos em maiúsculas.
Endereço e Posição no Mapa
Ao preencher um CEP completo, a tela consulta automaticamente o endereço correspondente e preenche logradouro, bairro, cidade e UF; se o CEP não for localizado, os campos de endereço (exceto o CEP) são limpos, sem exibir mensagem de erro. A cada alteração relevante do endereço, a tela busca automaticamente a posição correspondente e a marca num mapa. Se a posição obtida tiver baixa precisão, a tela exibe um alerta pedindo que o usuário posicione manualmente o marcador no local correto; o usuário pode arrastar o marcador para ajustar a posição, o que atualiza o cadastro e remove o alerta.
Parâmetros de Roteirização e Horário de Descarregamento
O formulário permite informar o tempo médio de descarregamento do cliente e habilitar, por uma opção específica, o controle de horário de descarregamento por dia da semana. Quando habilitado, cada dia (segunda a domingo) aceita até 3 intervalos de horário (início e fim); o ícone de adicionar intervalo só aparece enquanto houver menos de 3 cadastrados para o dia, e o de remover só aparece enquanto houver mais de 1.
Ativar/Inativar Cliente
Pelo ícone de ativar/inativar de um cliente da lista, a tela solicita confirmação antes de enviar a alteração de status, com o texto perguntando se deseja mesmo “INATIVAR” ou “ATIVAR” aquele cliente, conforme o status atual.
Sincronização de Clientes com Sistema Integrado (Atak)
Disponível apenas para transportadoras clientes do sistema integrado Atak, pelo botão SINCRONIZAR a tela abre um modal com um formulário inicial (data de atualização e tipo de cadastro) e, ao buscar, uma lista dos clientes atualizados a partir dessa data no sistema integrado. Cada registro aparece com um resumo de situação: pronto para sincronizar, ou com erro/pendência (posição ambígua, posição imprecisa, ou dado inválido no sistema integrado). Todo registro sem erro vem pré-selecionado. A lista pode ser filtrada por palavra-chave (código, documento, nome, endereço, telefone e e-mail) e por situação (todos, prontos, ou com erro). Registros com posição de endereço ambígua ou imprecisa exigem que o usuário confira e confirme manualmente a posição correta num mapa antes de poderem ser sincronizados; ao confirmar a posição de um endereço compartilhado por mais de um cliente da mesma leva, a correção é aplicada a todos os registros afetados. Ao salvar, cada cliente selecionado é processado individualmente, em sequência, com indicador de progresso percentual, e o resultado de cada um é exibido em tempo real na lista.
Tour Guiado da Tela Clientes
A tela conta com um botão TOUR que destaca em sequência as principais áreas (seção, tutorial, botão Adicionar, filtro e lista), com um passo adicional sobre o botão Sincronizar apenas para transportadoras clientes do sistema integrado Atak.
Feedbacks ao Usuário
Carregamento Inicial e Sessão
| Situação | Feedback | Texto exato |
|---|---|---|
| Sessão expirada em qualquer requisição da tela | Notificação de erro; a sessão é encerrada automaticamente 2 segundos depois | “Desculpe, sua sessão expirou.” |
| Falha de comunicação ao carregar as configurações da transportadora | Notificação de erro | “Não foi possível obter todas as informações de configuração.” |
| Falha de comunicação ao carregar a lista de cidades | Notificação de erro | “Não foi possível obter todas as informações de cidades.” |
| Falha de comunicação ao carregar a lista de clientes | Notificação de erro | “Não foi possível obter a lista de clientes.” |
| Servidor não retorna a lista de clientes (sem detalhe de erro) | Notificação de erro | “Não foi possível obter a lista.” |
| Situação | Feedback | Mensagem |
|---|---|---|
| O sistema recusa qualquer requisição da tela por um motivo diferente de sessão expirada | Notificação de erro | A tela exibe, sem alteração, o texto de erro devolvido para o motivo específico. |
Cadastro e Edição de Cliente
| Situação | Feedback | Texto exato |
|---|---|---|
| Status, CPF/CNPJ ou Nome em branco ao salvar | Notificação de erro, campo destacado | “‘STATUS’ deve ser preenchido.”, “‘CPF/CNPJ’ deve ser preenchido.” ou “‘NOME’ deve ser preenchido.” |
| CEP, Logradouro, Cidade ou UF do endereço em branco ao salvar | Notificação de erro, campo destacado | “‘CEP’ deve ser preenchido.”, “‘LOGRADOURO’ deve ser preenchido.”, “‘CIDADE’ deve ser preenchido.” ou “‘UF’ deve ser preenchido.” |
| Latitude/longitude do endereço não identificadas ao salvar | Notificação de erro | “Não foi possível identificar a Latitude e Longitude, favor selecionar o endereço novamente.” |
| Horário de descarregamento com apenas início ou fim preenchido, ou hora inválida | Notificação de erro | “Hora inválida no dia {dia da semana}, linha {número}” ou “Ambos os campos de hora inicial e final devem ser preenchidos no dia {dia da semana}, linha {número}” |
| Edição de cliente existente, confirmação antes de salvar | Diálogo de confirmação | “Deseja mesmo EDITAR esse cliente?” |
| Falha de comunicação ao salvar o cadastro/edição | Notificação de erro | “Não foi possível processar as informações.” |
| Cadastro ou edição salvos com sucesso | Notificação de sucesso | “Cliente cadastrado com sucesso.” |
| Situação | Feedback | Mensagem |
|---|---|---|
| O sistema recusa o cadastro/edição por regra de negócio (documento inválido ou duplicado, endereço inválido, coordenada inválida, entre outras) | Notificação de erro | A tela exibe, sem alteração, a mensagem de validação retornada. |
Endereço no Mapa
| Situação | Feedback | Mensagem |
|---|---|---|
| Coordenada obtida com baixa precisão | Alerta na área do mapa | Pede para o usuário posicionar manualmente o marcador no local correto do endereço. |
| Coordenada inválida ou não identificada | Alerta na área do mapa | Informa que uma coordenada válida é obrigatória para o endereço. |
| Falha de comunicação ao obter a coordenada do endereço | Notificação de erro | “Não possível obter a coordenada do endereço.” |
Sincronização com Sistema Integrado
| Situação | Feedback | Texto exato |
|---|---|---|
| Integração não configurada (transportadora não cliente Atak) | Notificação de erro; modal fecha | “Configuração de integração não selecionada em: Configurações -> Roteirização.” |
| Endereço da API de integração não informado | Notificação de erro; modal fecha | “Endereço da API de integração não informado em: Configurações -> Roteirização.” |
| Falha de comunicação ao autenticar com o sistema integrado | Notificação de erro | “Não foi possível conectar com o sistema integrado.” |
| Falha ao obter a autorização do sistema integrado | Notificação de erro | “Não foi possível obter a autorização do sistema integrado.” |
| Falha de comunicação ao buscar clientes do sistema integrado | Notificação de erro | “Não foi possível sincronizar os clientes.” |
| Nenhum cliente atualizado encontrado a partir da data informada | Notificação de erro; modal volta ao formulário | “Não foram encontrados registros de clientes atualizados a partir desta data.” |
| Tentativa de salvar com registros ainda pendentes de confirmação de posição | Notificação de erro | “Ainda há registros que necessitam de confirmação da posição do endereço.” |
| Tentativa de salvar sem nenhum registro selecionado | Notificação de erro | “Selecione ao menos um registro.” |
| Falha ao sincronizar um cliente específico (comunicação) | Indicador de erro na linha do registro | “Não foi possível sincronizar” |
| Sessão expirada durante a sincronização de um registro | Indicador de erro na linha do registro | “Sessão expirada” |
| Cliente sincronizado com sucesso | Indicador de resultado na linha do registro | “Sincronizado” |
| Posição de endereço confirmada manualmente no mapa | Notificação de sucesso | “Posição atualizada.” |
Regras de Negócio
Cadastro e Documento
- Status, CPF/CNPJ e Nome são obrigatórios; o CPF/CNPJ precisa ser um documento válido.
- Não é permitido cadastrar dois clientes da mesma transportadora com o mesmo documento e o mesmo código externo; a validação de duplicidade não distingue clientes ativos de inativos.
- Nome, Logradouro, Complemento, Bairro, Cidade, UF e País são armazenados em maiúsculas; uma vez cadastrado, o documento de um cliente não pode mais ser alterado pela edição.
- Os campos Código do cliente e Código do tipo de cadastro só existem para transportadoras clientes do sistema integrado Atak.
Endereço e Geolocalização
- CEP, Logradouro, Cidade, UF e a posição (latitude/longitude) do endereço são obrigatórios.
- Um mesmo registro de endereço (mesmos CEP, logradouro, número, complemento, bairro, cidade, UF e país) é reaproveitado entre clientes diferentes que compartilhem o mesmo endereço; apenas a posição no mapa é atualizada quando reaproveitado.
- Ao editar o cadastro de um cliente, o endereço das entregas desse cliente que ainda estejam aguardando ou sem rastreamento é atualizado automaticamente para o novo endereço.
- Ao consultar a posição de um endereço já cadastrado, o sistema reaproveita a posição já salva, sem nova busca; para um endereço novo, essa busca de posição aceita um resultado menos preciso do que em outras telas do sistema, exigindo confirmação manual do usuário nesses casos.
Horário de Descarregamento
- O tempo médio de descarregamento e o horário de descarregamento por dia da semana são opcionais.
- Quando o horário de descarregamento está habilitado, cada intervalo informado precisa ter início e fim preenchidos, em formato de hora válido, com até 3 intervalos por dia da semana.
Listagem e Filtros
- A busca textual localiza clientes por correspondência parcial em documento, código, nome, CEP, logradouro e bairro; cidade e UF podem ser filtradas por múltipla seleção.
- A ordenação padrão é por nome, em ordem crescente; apenas Nome, Cidade e UF podem ser usadas para ordenar a lista pelo cabeçalho.
- As opções de cidade e UF do filtro derivam do histórico de endereços de entrega da transportadora, não do cadastro de clientes.
Sincronização com o Sistema Integrado
- A sincronização de clientes atualiza apenas clientes já cadastrados e ativos localmente (mesmo documento e código do sistema integrado); nunca cria um cliente novo.
- Um cliente do sistema integrado com documento ou nome inválido não pode ser selecionado para sincronização.
- Um cliente cujo endereço retornado tenha mais de uma posição possível, ou apenas uma posição aproximada da cidade, precisa ter a posição confirmada manualmente antes de poder ser sincronizado.
- Ao sincronizar, os horários de descarregamento do cliente são integralmente substituídos pelos informados pelo sistema integrado (ou removidos, se nenhum for informado), e o endereço das entregas pendentes desse cliente, junto com a nota fiscal (DANFE) associada a elas, é atualizado.
Evidências e Documentos Gerados
A sincronização automática com o sistema integrado Atak é a única operação desta tela que também atualiza um documento fiscal já emitido: quando o endereço de um cliente muda por essa via e esse cliente já tem entregas aguardando ou sem rastreamento, a nota fiscal (DANFE) já vinculada a essas entregas é atualizada com o endereço novo. A edição manual do cadastro do cliente pelo formulário atualiza o endereço vinculado dessas mesmas entregas, mas não atualiza a nota fiscal (DANFE) já emitida para elas.
Geolocalização e Rastreamento
Todo endereço de cliente cadastrado ou sincronizado nesta tela precisa de uma posição confirmada num mapa. No cadastro manual, a posição é obtida automaticamente a partir do CEP e do endereço digitado; se a precisão obtida for baixa, a tela pede que o usuário posicione manualmente o marcador. Na sincronização com o sistema integrado, quando é encontrada mais de uma posição candidata para o endereço, ou apenas a posição aproximada do centro da cidade, o cliente fica marcado para confirmação manual da posição num mapa antes de poder ser sincronizado; ao confirmar a posição de um endereço compartilhado por mais de um cliente da mesma leva de sincronização, a correção é aplicada automaticamente a todos os registros que compartilhavam a posição original.
Troubleshooting
A tela informa que a sessão expirou
Cenário: o sistema identificou que a sessão do usuário não é mais válida ao processar qualquer ação da tela Clientes.
Mensagem exibida: “Desculpe, sua sessão expirou.”
O que fazer: aguardar o encerramento automático da sessão (ocorre 2 segundos após o aviso) e efetuar login novamente.
A lista de clientes ou de cidades não carrega
Cenário: o navegador não conseguiu se comunicar com o sistema ao carregar a lista de clientes ou a lista de cidades para o filtro.
Mensagem exibida: “Não foi possível obter a lista de clientes.” ou “Não foi possível obter todas as informações de cidades.”
O que fazer: verificar a conexão com a internet e recarregar a tela; se persistir, contatar o suporte.
O cadastro/edição não salva por campo obrigatório em branco
Cenário: o usuário tentou salvar o cadastro ou edição de um cliente sem preencher Status, CPF/CNPJ, Nome, CEP, Logradouro, Cidade ou UF.
Mensagem exibida: mensagem específica do campo, por exemplo “‘NOME’ deve ser preenchido.” ou “‘CEP’ deve ser preenchido.”
O que fazer: preencher o campo indicado e salvar novamente.
O cadastro/edição não salva por falta de posição do endereço
Cenário: o endereço informado não teve uma posição válida confirmada no mapa.
Mensagem exibida: “Não foi possível identificar a Latitude e Longitude, favor selecionar o endereço novamente.”
O que fazer: conferir o CEP e o endereço digitado, aguardar o mapa atualizar a posição ou ajustar manualmente o marcador, e salvar novamente.
O cadastro/edição não salva por horário de descarregamento incompleto ou inválido
Cenário: o usuário habilitou o Horário de Descarregamento e deixou um intervalo com apenas o início ou o fim preenchido, ou com uma hora em formato inválido.
Mensagem exibida: “Hora inválida no dia {dia}, linha {número}” ou “Ambos os campos de hora inicial e final devem ser preenchidos no dia {dia}, linha {número}”
O que fazer: completar ou corrigir o intervalo de horário apontado na mensagem, ou removê-lo, e salvar novamente.
O sistema recusa o cadastro/edição de um cliente por documento duplicado ou dado inválido
Cenário: o documento e o código informados já pertencem a outro cliente da transportadora, ou algum dado do endereço não passou na validação.
Mensagem exibida: mensagem específica para o motivo, por exemplo “Há registro de cliente cadastrado com a mesma documentação.” ou “CEP é inválido.”
O que fazer: corrigir o dado apontado pela mensagem e salvar novamente.
O mapa do endereço exibe alerta de posição imprecisa
Cenário: a posição obtida automaticamente para o endereço do cliente teve baixa precisão.
Mensagem exibida: alerta pedindo para posicionar manualmente o marcador no local correto do endereço.
O que fazer: arrastar o marcador no mapa até o ponto correto do endereço antes de salvar o cadastro.
Um cliente não aparece na lista após alterar o filtro de cidade
Cenário: o usuário filtrou a lista de clientes por uma cidade que nunca teve nenhuma entrega associada a ela.
Mensagem exibida: Nenhuma — a cidade procurada simplesmente não aparece entre as opções do filtro.
O que fazer: limpar o filtro de cidade e localizar o cliente por outro campo (nome, documento ou CEP), já que o filtro de cidade só lista localidades com histórico de entregas.
Sincronizar recusa abrir por falta de configuração de integração
Cenário: a transportadora não tem uma integração configurada, ou o endereço da API de integração não está preenchido, em Configurações → Roteirização.
Mensagem exibida: “Configuração de integração não selecionada em: Configurações -> Roteirização.” ou “Endereço da API de integração não informado em: Configurações -> Roteirização.”
O que fazer: completar a configuração de integração na tela Configurações antes de sincronizar.
A sincronização não retorna nenhum cliente
Cenário: a busca de clientes atualizados no sistema integrado, a partir da data informada, não encontrou nenhum registro.
Mensagem exibida: “Não foram encontrados registros de clientes atualizados a partir desta data.”
O que fazer: confirmar se existem clientes atualizados no sistema integrado a partir da data escolhida, ou informar uma data anterior.
A sincronização bloqueia o salvamento por posição pendente de confirmação
Cenário: um ou mais clientes selecionados para sincronização têm o endereço com posição ambígua ou imprecisa, ainda não confirmada manualmente no mapa.
Mensagem exibida: “Ainda há registros que necessitam de confirmação da posição do endereço.”
O que fazer: abrir “Editar posição” de cada registro pendente, confirmar a posição correta no mapa e tentar sincronizar novamente.
Um cliente aparece bloqueado na lista de sincronização
Cenário: o usuário abriu a Sincronização e um dos clientes retornados aparece marcado com erro, impedindo a seleção.
Mensagem exibida: mensagem específica do motivo retornado pelo sistema integrado, indicando documento ou nome inválido.
O que fazer: corrigir o cadastro desse cliente no sistema integrado e sincronizar novamente.
A busca por bairro na tela de Sincronização não encontra resultado
Cenário: o usuário digitou um termo de busca correspondente ao bairro de um cliente, na lista de seleção da Sincronização, e o registro esperado não aparece.
Mensagem exibida: Nenhuma — a lista simplesmente não exibe o registro esperado ao buscar por bairro, mesmo que ele exista na lista.
O que fazer: buscar pelo código, documento, nome ou outro campo do endereço (CEP, logradouro, cidade ou UF) em vez do bairro; ou localizar o registro percorrendo a lista completa.
Casos de Uso
Caso 1 — Cadastro manual de um cliente novo
Uma transportadora precisa cadastrar um novo destinatário de entregas. O usuário clica em ADICIONAR, preenche Status, CPF/CNPJ, Nome, informa o CEP (que preenche automaticamente logradouro, bairro, cidade e UF), confirma a posição sugerida no mapa e preenche telefone e e-mail de contato. A tela informa “Cliente cadastrado com sucesso.” e o novo cliente aparece na lista, pronto para ser usado como destino de entregas.
Caso 2 — Edição de cliente com habilitação de horário de descarregamento
Um cliente já cadastrado passa a exigir descarregamento apenas em horários específicos. O usuário localiza o cliente na lista, clica em editar, habilita a opção Horário de Descarregamento, informa os intervalos de horário para os dias em que o cliente recebe carga e confirma a edição (após a pergunta “Deseja mesmo EDITAR esse cliente?”). A tela informa o salvamento com sucesso e os horários passam a valer para o cálculo das entregas desse cliente.
Caso 3 — Ativação/inativação de um cliente
Um cliente deixa de operar com a transportadora. O usuário localiza o cliente na lista e clica no ícone de inativar; a tela pergunta “Deseja mesmo INATIVAR este cliente?” e, após confirmar, exibe “Atualizado com sucesso.” O cliente passa a não aparecer mais na lista com o filtro padrão de status ATIVO, mas pode ser localizado filtrando por status INATIVO e reativado da mesma forma.
Caso 4 — Sincronização em lote de clientes atualizados no sistema integrado
Uma transportadora integrada ao sistema Atak atualiza cadastros de clientes diretamente nesse sistema. No Painel, o usuário clica em SINCRONIZAR, informa a data a partir da qual quer buscar atualizações e confirma a busca. A tela lista os clientes atualizados; um deles aparece com alerta de posição ambígua, e o usuário confirma a posição correta no mapa antes de prosseguir. Ao clicar em SALVAR, a tela processa cada cliente selecionado, mostrando o progresso e o resultado individual de cada um ao final.
