Centros de Distribuição
Criado por Igor Ribeiro em 30 de setembro de 2026
Atualizado por Igor Ribeiro em 01 de outubro de 2026
Centros de Distribuição — Painel
A tela Centros de Distribuição é onde a transportadora cadastra, edita e remove os locais físicos (centros de distribuição) que servem de origem para as entregas roteirizadas.
Visão Geral
A tela Centros de Distribuição é onde a transportadora cadastra, edita e remove os locais físicos (centros de distribuição) que servem de origem para as entregas roteirizadas. É uma tela de cadastro simples — uma lista paginada e um formulário único de cadastro/edição, sem abas — e só existe para empresas que contrataram o módulo de roteirização: os centros cadastrados aqui alimentam diretamente o motor de roteirização e a lista de origens disponível na tela de Entregas e na tela de Roteirizações.
Pré-requisitos
Para a tela Centros de Distribuição funcionar, é necessário que:
- o usuário tenha uma sessão autenticada válida no Painel — sem sessão ativa, qualquer requisição retorna erro de sessão expirada (ver Troubleshooting).
- o perfil do usuário tenha a permissão de área “Centros de Distribuição” ativa, ou seja administrador da conta — sem essa permissão, uma tentativa de acesso pela URL redireciona automaticamente para a tela Início, sem nenhum aviso, e o item de menu não é exibido.
- a empresa tenha a roteirização contratada — mesmo com a permissão de área ativa, sem a roteirização contratada o acesso é bloqueado da mesma forma (redirecionamento silencioso para a tela Início) e o item de menu também fica oculto.
- para cadastrar, editar ou remover um centro (não apenas consultar a lista) é necessária a permissão de EDIÇÃO da área “Centros de Distribuição” — sem ela, os botões ADICIONAR, editar e remover continuam visíveis, porém desabilitados.
Fluxo Operacional
- O usuário acessa a tela Centros de Distribuição pelo menu (item exibido apenas com a permissão e a roteirização contratada).
- A tela carrega automaticamente a lista de centros já cadastrados da empresa, ordenada por nome.
- O usuário pode filtrar a lista digitando um termo e pressionando Enter, e pode reordenar a lista clicando nas colunas Nome, Cidade ou UF.
- Para cadastrar um novo centro, o usuário clica em ADICIONAR, preenche o nome, o CEP (que dispara a busca automática do restante do endereço), confere o posicionamento no mapa e clica em SALVAR.
- Para editar um centro existente, o usuário clica no ícone de edição da linha correspondente, confirma a intenção de editar, ajusta os campos necessários e salva.
- Para remover um centro, o usuário clica no ícone de remoção da linha correspondente e confirma a exclusão.
Interface e Comportamentos
Lista de Centros de Distribuição
A lista de Centros de Distribuição exibe, por registro, Nome, CEP, Endereço, Número, Complemento, Bairro, Cidade e UF. O CEP é sempre reformatado para o padrão `XXXXX-XXX` na exibição, independentemente de como foi digitado no cadastro. Nome, Endereço, Número, Bairro e Cidade são exibidos com uma formatação visual “capitalizada” (aparência de Título Inicial Maiúsculo); o Complemento é exibido como um traço “-” quando não informado. A lista é paginada (20 registros por página) e mostra o total de resultados encontrados. A busca por texto só é disparada ao pressionar Enter no campo de filtro (não a cada tecla digitada) e volta a lista para a primeira página; o termo digitado é comparado, por correspondência parcial, contra o nome do centro, o CEP, o logradouro, o bairro, a cidade e a UF — uma correspondência em qualquer um desses campos já retorna o registro. Apenas as colunas Nome, Cidade e UF podem ser usadas para reordenar a lista clicando no cabeçalho.
Cada linha tem dois botões de ação — editar e remover — ambos desabilitados sem a permissão de edição da área. O botão ADICIONAR, no topo da lista, segue a mesma regra de habilitação. Um botão de TOUR reabre o tutorial guiado da tela, e um link “ABRIR TUTORIAL” abre, em uma nova aba, um documento PDF de ajuda.
Cadastro e Edição de Centro de Distribuição
Ao clicar em ADICIONAR ou no ícone de edição de uma linha, abre-se um modal com o título “NOVO CENTRO DE DISTRIBUIÇÃO” ou “EDITAR CENTRO DE DISTRIBUIÇÃO”, conforme o caso. O modal reúne: o campo Nome (obrigatório); quando a empresa é integrada ao ERP Atak, um campo adicional “Código do estoque” (opcional, chave de referência do estoque no sistema integrado — inexistente para empresas não integradas); os campos de endereço e posicionamento no mapa (ver subseção seguinte); e um campo de Observação de texto livre (opcional).
Ao clicar em SALVAR na edição de um centro já existente, o sistema pede confirmação antes de prosseguir (“Deseja mesmo EDITAR esse centro de distribuição?”); ao criar um novo centro, o salvamento ocorre direto, sem essa confirmação prévia.
Preenchimento de Endereço e Posicionamento no Mapa
O grupo de campos de endereço, compartilhado com outras telas de cadastro do Painel, pede CEP (obrigatório, com máscara de captura `#####-###`), Logradouro (obrigatório), Número (opcional), Complemento (opcional), Bairro (opcional), Cidade (obrigatória) e UF (obrigatória), além de Latitude e Longitude (apresentados como campos numéricos editáveis, com indicação visual de obrigatórios) e um mapa com um marcador arrastável.
Quando o campo CEP perde o foco, o sistema consulta automaticamente um serviço externo de busca de endereço por CEP e, quando encontrado, preenche Logradouro, Bairro, Cidade e UF automaticamente (Número e Complemento são sempre limpos nesse preenchimento automático, pois o serviço consultado não devolve esses dados). Toda vez que Logradouro, Número, Bairro, Cidade ou UF perdem o foco, o sistema tenta localizar automaticamente a coordenada geográfica do endereço já digitado e reposiciona o marcador no mapa; a mesma tentativa ocorre ao editar manualmente os campos de Latitude/Longitude. O marcador também pode ser reposicionado manualmente arrastando-o no mapa, o que atualiza Latitude, Longitude e os demais campos de endereço a partir da nova posição.
Quando a coordenada localizada automaticamente tem baixa precisão, um aviso é exibido sobre o mapa pedindo que o usuário posicione manualmente o marcador no local correto; quando não há nenhuma coordenada válida disponível, um aviso diferente indica que uma coordenada válida é necessária para o endereço.
Feedbacks ao Usuário
Lista de Centros de Distribuição
| Situação | Feedback | Texto exato |
|---|---|---|
| Falha de comunicação ao carregar a lista | Notificação de erro | “Não foi possível obter a lista dos centros de distribuição.” |
| Sessão expirada ao carregar a lista | Notificação de erro; a sessão é encerrada automaticamente 2 segundos depois | “Desculpe, sua sessão expirou.” |
| Servidor retorna um erro de negócio ao carregar a lista | Notificação de erro | mensagem devolvida pelo servidor |
| Servidor não retorna nenhum dado ao carregar a lista | Notificação de erro | “Não foi possível obter a lista.” |
Remoção de Centro de Distribuição
| Situação | Feedback | Texto exato |
|---|---|---|
| Antes de remover um centro | Caixa de diálogo de confirmação (título “REMOVER”) | “Deseja mesmo remover o centro de distribuição?” |
| Falha de comunicação ao remover | Notificação de erro | “Não foi possível remover o centro de distribuição.” |
| Sessão expirada ao remover | Notificação de erro; a sessão é encerrada automaticamente 2 segundos depois | “Desculpe, sua sessão expirou.” |
| Servidor recusa a remoção (registro não encontrado) | Notificação de erro | mensagem devolvida pelo servidor |
| Centro removido com sucesso | Notificação de sucesso | “Centro de distribuição removido com sucesso.” |
| Servidor não retorna nenhum resultado ao remover | Notificação de erro | “Não foi possível fazer a remoção.” |
Cadastro e Edição — Confirmação e Resultado
| Situação | Feedback | Texto exato |
|---|---|---|
| Antes de salvar a edição de um centro já existente | Caixa de diálogo de confirmação (título padrão “CONFIRMAR”) | “Deseja mesmo EDITAR esse centro de distribuição?” |
| Falha de comunicação ao salvar (criar ou editar) | Notificação de erro | “Não foi possível salvar as informações.” |
| Servidor recusa o salvamento (validação) | Uma notificação de erro por mensagem devolvida pelo servidor | mensagem(ns) devolvida(s) pelo servidor |
| Centro editado com sucesso | Notificação de sucesso | “Alterado com sucesso.” |
| Centro criado com sucesso | Notificação de sucesso | “Adicionado com sucesso.” |
Cadastro e Edição — Validação de Campos
| Situação | Feedback | Texto exato |
|---|---|---|
| Nome não preenchido | Notificação de erro | “‘NOME’ deve ser preenchido.” ou “‘NOME’ não pode ser vazio.” |
| CEP não preenchido | Notificação de erro | “‘CEP’ deve ser preenchido.” ou “‘CEP’ não pode ser vazio.” |
| CEP em formato inválido | Notificação de erro | “‘CEP’ inválido.” |
| Logradouro não preenchido | Notificação de erro | “‘ENDEREÇO’ deve ser preenchido.” ou “‘ENDEREÇO’ não pode ser vazio.” |
| Cidade não preenchida | Notificação de erro | “‘CIDADE’ deve ser preenchido.” ou “‘CIDADE’ não pode ser vazio.” |
| UF não preenchida | Notificação de erro | “‘UF’ deve ser preenchido.” ou “‘UF’ não pode ser vazio.” |
| Coordenadas ausentes ou inválidas | Notificação de erro | “‘COORDENADAS’ deve ser preenchida.” ou “‘COORDENADAS’ inválida.” |
| Nenhuma informação enviada ao salvar | Notificação de erro | “Informações não enviadas.” |
| Id do centro não identificado ao editar | Notificação de erro | “Não foi possível identificar o Centro de Distribuição.” |
| Centro não pertence à empresa da sessão ao editar | Notificação de erro | “Não foi possível identificar a relação entre o Centro e a Empresa.” |
Preenchimento de Endereço e Mapa
| Situação | Feedback | Texto exato |
|---|---|---|
| Falha de comunicação ao localizar a coordenada do endereço | Notificação de erro | mensagem devolvida pelo servidor, ou “Não possível obter a coordenada do endereço.” |
| Sessão expirada ao localizar a coordenada | Notificação de erro; a sessão é encerrada automaticamente 2 segundos depois | “Desculpe, sua sessão expirou.” |
| Servidor não retorna nenhuma coordenada | Notificação de erro | “Não foi possível obter a coordenada. Por favor, tente novamente.” |
| Coordenada localizada com baixa precisão | Aviso sobre o mapa | “Não foi possível localizar uma coordendada mais precisa, por favor, posicione o marcador no local correto do endereço” |
| Nenhuma coordenada válida disponível | Aviso sobre o mapa | “Coordenada inválida. É necessário uma coordenada válida para o endereço.” |
Regras de Negócio
Formatação de Exibição do CEP
O CEP é sempre exibido na lista no formato `XXXXX-XXX`, independentemente de como foi originalmente digitado no cadastro.
Ordenação e Paginação da Lista
A lista de centros de distribuição é ordenada, por padrão, por Nome em ordem crescente. O usuário só pode reordenar por Nome, Cidade ou UF. A lista é paginada em blocos de 20 registros.
Código do Estoque para Empresas Integradas ao ERP Atak
O campo “Código do estoque” (chave de referência do estoque no sistema integrado) só existe na tela, e só é enviado ao salvar, para empresas com integração com o sistema ERP Atak. Para as demais empresas, o campo não é exibido.
Acesso Também Liberado por Entregas ou Roteirizações
Mesmo sem a permissão de área “Centros de Distribuição” diretamente concedida, um usuário com permissão ativa na área “Entregas” ou na área “Roteirizações” também consegue acessar as informações desta tela.
Remoção de um Centro é Imediata e Não Verifica Entregas Vinculadas
A remoção de um centro de distribuição é definitiva e concluída imediatamente após a confirmação. O sistema não verifica nem impede a remoção de um centro que ainda tenha entregas em andamento vinculadas a ele — confirme, antes de remover, que o centro não está mais em uso por nenhuma entrega em curso.
Troubleshooting
Lista de centros de distribuição não carrega por falha de comunicação
Cenário: o usuário abre a tela Centros de Distribuição e a lista não aparece.
Mensagem exibida: “Não foi possível obter a lista dos centros de distribuição.”
O que fazer: verificar a conexão com a internet e recarregar a página; se persistir, contatar o suporte informando o horário da falha.
Sessão expira ao carregar a lista de centros de distribuição
Cenário: o usuário estava com a tela aberta havia tempo e a sessão expirou ao tentar recarregar a lista.
Mensagem exibida: “Desculpe, sua sessão expirou.”
O que fazer: aguardar o redirecionamento automático (ocorre 2 segundos depois da mensagem) e fazer login novamente.
Servidor não retorna nenhum dado ao carregar a lista
Cenário: a requisição de carregamento da lista é concluída, mas sem nenhum conteúdo utilizável na resposta.
Mensagem exibida: “Não foi possível obter a lista.”
O que fazer: recarregar a página; se persistir, contatar o suporte informando o horário da falha.
Centro de distribuição não é removido por falha de comunicação
Cenário: o usuário confirma a remoção de um centro e a requisição não é concluída.
Mensagem exibida: “Não foi possível remover o centro de distribuição.”
O que fazer: tentar novamente; se persistir, contatar o suporte informando o horário da falha.
Sessão expira ao tentar remover um centro de distribuição
Cenário: a sessão expira entre a confirmação da exclusão e a resposta do servidor.
Mensagem exibida: “Desculpe, sua sessão expirou.”
O que fazer: aguardar o redirecionamento automático (2 segundos) e fazer login novamente; repetir a remoção depois de logado.
Remoção de um centro de distribuição é recusada pelo servidor
Cenário: o identificador do centro que está sendo removido não corresponde a um registro da empresa (por exemplo, se o registro já tiver sido removido em outra sessão simultânea).
Mensagem exibida: mensagem devolvida pelo servidor (ex.: “Não foi possível identificar a relação entre o registro e a empresa logada.”)
O que fazer: recarregar a lista antes de tentar novamente.
Clicar em SALVAR com o campo Nome vazio não exibe nenhuma mensagem
Cenário: o usuário tenta salvar um centro de distribuição (novo ou em edição) deixando o campo Nome em branco.
Mensagem exibida: Nenhuma — nenhuma notificação aparece, e o formulário permanece aberto sem indicar o que está errado.
O que fazer: preencher o campo Nome antes de salvar, mesmo sem receber indicação explícita da tela; se o problema persistir mesmo com o Nome preenchido, contatar o suporte.
Sessão expira ao salvar ou editar um centro de distribuição
Cenário: a sessão expira entre o clique em SALVAR e a resposta do servidor.
Mensagem exibida: Nenhuma mensagem compreensível — uma sequência de notificações de um único caractere cada aparece na tela, e a sessão não é encerrada automaticamente como acontece ao carregar ou remover.
O que fazer: fechar o formulário, recarregar a página manualmente e fazer login novamente antes de repetir o cadastro ou a edição.
Falha de comunicação ao salvar ou editar um centro de distribuição
Cenário: a requisição de salvamento (criação ou edição) não é concluída.
Mensagem exibida: “Não foi possível salvar as informações.”
O que fazer: tentar novamente; se persistir, contatar o suporte informando o horário da falha.
Salvamento recusado por coordenadas ausentes ou inválidas, sem indicação no campo
Cenário: o usuário salva um centro de distribuição sem que uma coordenada válida de latitude/longitude tenha sido localizada (por exemplo, editando manualmente os campos de coordenada e deixando-os vazios ou inválidos).
Mensagem exibida: “‘COORDENADAS’ deve ser preenchida.” ou “‘COORDENADAS’ inválida.” — sem que os campos Latitude/Longitude sejam destacados na tela.
O que fazer: preencher novamente o CEP ou o endereço para que o sistema localize a coordenada automaticamente, ou ajustar manualmente o marcador no mapa antes de salvar novamente.
Endereço não é preenchido automaticamente após informar o CEP
Cenário: o usuário digita um CEP válido e sai do campo, mas nenhum dos campos de endereço (Logradouro, Bairro, Cidade, UF) é preenchido, e nenhum aviso aparece.
Mensagem exibida: Nenhuma — os campos de endereço permanecem como estavam, sem nenhum aviso de que a busca não encontrou o CEP informado.
O que fazer: conferir se o CEP foi digitado corretamente e preencher os demais campos de endereço manualmente.
Endereço é preenchido com valores inválidos após informar um CEP
Cenário: o usuário digita um CEP e, no momento da busca automática, há uma falha de comunicação com o serviço de consulta de CEP (diferente de “CEP não encontrado”).
Mensagem exibida: Nenhuma — os campos de Logradouro, Bairro, Cidade e UF são preenchidos com um valor inválido (aparecendo como texto “undefined” ou em branco), sem nenhum aviso de que a busca falhou.
O que fazer: apagar manualmente o conteúdo inválido preenchido nos campos de endereço e digitá-los à mão; tentar novamente mais tarde a busca automática pelo CEP.
Marcador do mapa exige ajuste manual por falta de precisão
Cenário: o sistema localiza uma coordenada para o endereço informado, mas com baixa confiabilidade.
Mensagem exibida: “Não foi possível localizar uma coordendada mais precisa, por favor, posicione o marcador no local correto do endereço”
O que fazer: arrastar o marcador manualmente até a posição correta do endereço no mapa antes de salvar.
Falha ao obter a coordenada do endereço automaticamente
Cenário: o sistema tenta localizar a coordenada do endereço digitado (ao sair de um dos campos de endereço) e a requisição não é concluída com sucesso.
Mensagem exibida: mensagem devolvida pelo servidor, ou “Não possível obter a coordenada do endereço.” (falha de comunicação), ou “Não foi possível obter a coordenada. Por favor, tente novamente.” (servidor não retornou resultado)
O que fazer: conferir a conexão com a internet e tentar novamente saindo de um dos campos de endereço; se persistir, posicionar o marcador manualmente no mapa.
Sessão expira ao buscar a coordenada do endereço
Cenário: a sessão expira durante a tentativa automática de localizar a coordenada do endereço.
Mensagem exibida: “Desculpe, sua sessão expirou.”
O que fazer: aguardar o redirecionamento automático (2 segundos) e fazer login novamente.
Acesso à tela de Centros de Distribuição é bloqueado silenciosamente
Cenário: o usuário tenta acessar a tela Centros de Distribuição diretamente pela URL sem ter a permissão de área correspondente ativa, ou a empresa não tem a roteirização contratada.
Mensagem exibida: Nenhuma — o sistema redireciona silenciosamente para a tela Início.
O que fazer: solicitar a um administrador da conta a permissão de área “Centros de Distribuição”, ou confirmar com o suporte se a empresa tem a roteirização contratada.
Nenhuma coordenada válida disponível ao editar o mapa manualmente
Cenário: os campos de Latitude/Longitude ficam vazios ou com um valor não numérico durante a edição do endereço.
Mensagem exibida: “Coordenada inválida. É necessário uma coordenada válida para o endereço.”
O que fazer: informar novamente o CEP para que a coordenada seja localizada automaticamente, ou arrastar o marcador para uma posição válida no mapa.
Casos de Uso
Caso 1 — Cadastro de um novo centro de distribuição a partir do CEP
Um usuário com permissão de edição em Centros de Distribuição clica em ADICIONAR, informa o Nome “Galpão Central” e o CEP. Ao sair do campo CEP, o sistema busca automaticamente o Logradouro, o Bairro, a Cidade e a UF, e localiza a coordenada aproximada no mapa. O usuário confirma visualmente que o marcador está no local correto, preenche o Número e uma Observação, e clica em SALVAR — recebendo “Adicionado com sucesso.”.
Caso 2 — Empresa integrada ao ERP Atak cadastra um centro com código do estoque
Um usuário de uma empresa integrada ao sistema ERP Atak abre o cadastro de um novo centro de distribuição e, além dos campos padrão de nome e endereço, preenche o campo adicional “Código do estoque” com a chave do estoque correspondente no sistema integrado, permitindo que a sincronização de cargas relacione automaticamente os registros dos dois sistemas.
Caso 3 — Edição de um centro de distribuição existente
Um usuário abre a lista, localiza um centro pelo filtro de busca (digitando parte do nome e pressionando Enter) e clica no ícone de edição. Confirma a intenção de editar (“Deseja mesmo EDITAR esse centro de distribuição?”), atualiza o Complemento do endereço e ajusta manualmente a posição do marcador no mapa antes de salvar, recebendo “Alterado com sucesso.”.
Caso 4 — Remoção de um centro de distribuição
Um usuário clica no ícone de remoção de um centro que não é mais utilizado, confirma a exclusão (“Deseja mesmo remover o centro de distribuição?”) e recebe a confirmação “Centro de distribuição removido com sucesso.”. O sistema não verifica, no momento da remoção, se existem entregas em andamento vinculadas a esse centro — a exclusão é sempre concluída quando o registro pertence à empresa, então vale confirmar antes que o centro não está mais em uso.
