Administração da Plataforma

A área adm: empresas, planos, Pix e WhatsApp — só para o administrador da plataforma.

O iMportex não é um sistema de uma empresa só: é um SaaS (software vendido como serviço, por assinatura mensal) multi-empresa. Cada cliente da KL (uma revenda de iPhones usados) tem sua própria conta com o ERP completo — compra no PY, triagem, assistência, inventário, expedição pra SP e venda B2B — isolada dos dados de qualquer outra empresa. Este capítulo NÃO é sobre esse ERP do dia a dia. É sobre o painel que a própria KL (dona da plataforma) usa pra administrar TODAS as empresas-clientes ao mesmo tempo: aprovar quem pode entrar, cobrar a mensalidade, decidir o que cada plano oferece e acompanhar quem está inadimplente.

Na prática, isso é feito em dois endereços separados do mesmo sistema: app.getimportex.com é o ERP de uma empresa (o que os outros capítulos deste manual documentam), e adm.getimportex.com é o painel de administração da plataforma documentado aqui. O sistema decide sozinho para qual dos dois cada pedido vai e bloqueia o acesso cruzado: quem está no adm só acessa rotas de admin/login/logout, quem está no app é mandado de volta pro adm se tentar abrir /admin. Há ainda uma terceira tela, /assinatura, que mora DENTRO do app da empresa (não do painel adm) mas é o "outro lado" de tudo que se configura aqui: é onde a empresa-cliente paga a fatura que o super-admin gerou.

🔒 Por que este capítulo quase não tem capturas de tela: o painel adm mostra dados reais de TODAS as empresas-clientes (faturamento, inadimplência, chaves Pix da plataforma), e fotografá-lo exigiria criar um usuário de demonstração com poder de super-admin — uma porta de entrada real pra plataforma inteira. Decisão consciente: aqui a documentação é em texto, e quem tem acesso (o dono da plataforma) vê as telas ao vivo.

Fluxo do módulo em 1 olhada

Uma empresa nova se cadastra sozinha (tela pública /cadastro, fora do escopo deste capítulo), respondendo um formulário de qualificação (volume mensal, onde vende, dor principal etc). A empresa nasce com status PENDENTE.
Se o WhatsApp da plataforma estiver conectado, um alerta automático cai no número do admin avisando "nova empresa cadastrou", com o link direto pra aprovar.
O super-admin abre a Fila de aprovação (/admin/aprovacoes), lê a qualificação do lead e decide: Aprovar (libera o acesso, dispara e-mail de boas-vindas) ou Recusar.
A empresa aprovada passa a aparecer em Empresas-clientes (/admin/empresas), com status, plano contratado e consumo de aparelhos.
No dia a dia, o super-admin acompanha vencimentos pelo Dashboard (/admin). Quando a empresa paga (fora do sistema — Pix manual, comprovante por e-mail), o super-admin abre o Detalhe da empresa (/admin/empresas/[id]) e registra o pagamento: o status volta pra ATIVA e o vencimento avança 30 dias.
Se a empresa NÃO paga, uma rotina automática que roda todo dia (fora do escopo deste capítulo) degrada o status sozinha, sem intervenção humana: ATIVA -> CARÊNCIA (no dia do vencimento, só um aviso) -> READ_ONLY (3 dias depois, bloqueia o ERP inteiro da empresa) -> BLOQUEADA (10 dias depois). Isso é o que dá poder de cobrança ao sistema.
A empresa em atraso vê a cobrança pendente na tela Assinatura (/assinatura, dentro do próprio app dela) e paga via Pix — usando a chave que o super-admin configurou em Chave Pix da plataforma (/admin/pix).
Como manutenção de fundo, o super-admin mantém o catálogo de Planos (/admin/planos, preço e limites da escada de assinatura) e o canal de WhatsApp da plataforma (/admin/whatsapp, de onde saem os alertas do passo 2 e do pagamento).

Visão geral da plataforma (Dashboard) — `/admin`

Pra que serve: primeira tela do painel. Dá o resumo de saúde do negócio SaaS: quantas empresas ativas, quanto de MRR (receita mensal recorrente — a soma do valor de todas as assinaturas ativas), quem está pendente de aprovação, quem está inadimplente e quem vence nos próximos dias. Também mostra gráficos de evolução (novas empresas por mês, receita por mês) e listas rápidas de vencimentos e leads aguardando aprovação.
Quem usa: exclusivamente quem está numa lista fixa de administradores da plataforma, cadastrada direto no banco de dados — o sistema confere isso de novo a cada acesso. Não há níveis dentro do admin da plataforma — é um cargo binário (está na lista ou não está), diferente dos 9 perfis (ADMIN, GERENTE, VENDEDOR, FINANCEIRO, TECNICO_PROPRIO, OPERADOR_SP, OPERADOR_PY, TESTADOR, SUPERVISOR_ASSISTENCIA) que existem dentro do ERP de cada empresa. Não há nenhuma tela para gerenciar quem tem esse acesso — inclusão e remoção são feitas direto no banco, por fora do sistema.
Ações principais: só leitura — 6 cartões de KPI (empresas ativas, MRR, aguardando aprovação, inadimplentes, vencem em 7 dias, total de empresas), 2 gráficos de barra mensal (novas empresas, receita recebida), 2 gráficos de distribuição (por status, por plano) e 2 listas clicáveis (vencendo nos próximos 14 dias, leads aguardando aprovação) que levam direto ao detalhe da empresa.
Fluxo correto: 1) abrir o painel ao logar; 2) olhar o cartão "Inadimplentes" e a lista de vencimentos pra saber quem cobrar; 3) olhar "Aguardando aprovação" e clicar em "ver todos" se houver leads na fila; 4) usar os gráficos pra acompanhar tendência (crescimento de empresas x receita).
Se pular ou errar: nada quebra — é uma tela 100% de leitura, sem escrita. O risco de "pular" está em não olhar a tela: vencimento e inadimplência só aparecem aqui e no detalhe da empresa.

⚠️ Atenção: quem não abre o painel com regularidade não percebe uma empresa entrando em bloqueio (READ_ONLY, que trava o ERP inteiro dela) até ela mesma reclamar.
Gotchas e estados: os números são recalculados no banco a cada carregamento, e o banco confere de novo se quem está pedindo é realmente admin da plataforma — mesmo que alguém tente pular a tela e pedir os dados direto, sem ser admin da plataforma o pedido é recusado.

Fila de aprovação — `/admin/aprovacoes`

Pra que serve: lista as empresas que se cadastraram sozinhas (self-service) e estão esperando o "sim" da KL pra começar a usar o sistema. Cada card mostra os dados de contato e as respostas da qualificação do lead (quantos iPhones move por mês, onde vende, dor principal etc) — informação pensada pra quem for fechar a venda saber o que falar.
Quem usa: super-admin da plataforma (mesma trava de acesso do resto do painel).
Ações principais: por card, dois botões: Aprovar (libera o acesso da empresa e dispara e-mail "conta liberada" pro admin da empresa — é enviado de melhor esforço, ou seja, o sistema tenta mas não garante: se o e-mail falhar, a aprovação acontece do mesmo jeito) e Recusar. Também há link direto pra abrir o WhatsApp do lead e pro e-mail dele, quando cadastrados.
Fluxo correto: 1) abrir a fila (direto ou clicando em "ver todos" a partir do Dashboard); 2) ler a qualificação — o campo "dor principal" vem destacado, é o gancho pra abordagem comercial; 3) clicar em Aprovar (ou entrar em contato antes, se a qualificação levantar dúvida) ou Recusar.
Se pular ou errar: empresa aprovada sem checagem vira cliente com acesso total ao ERP mesmo sem qualificação real (cadastros antigos podem não ter dados de qualificação — a tela mostra "Sem dados de qualificação" nesse caso, mas não bloqueia a aprovação). Recusar é permanente nesta tela — não há um botão de "desfazer recusa".
Gotchas e estados: só aparecem aqui empresas com status PENDENTE. Aprovar também ativa automaticamente o usuário ADMIN da empresa e garante que existe uma assinatura vinculada (usa o plano ativo mais barato se a empresa não tiver escolhido nenhum). Aprovar e Recusar atualizam a tela na hora — os contadores do Dashboard refletem a mudança imediatamente, sem precisar recarregar.

Empresas-clientes (lista) — `/admin/empresas`

Pra que serve: lista todas as empresas-clientes da plataforma (aprovadas ou não) com busca por nome/CNPJ e filtro por status. Mostra, por empresa, o plano contratado e quantos aparelhos ativos ela tem cadastrados frente ao teto do plano — pra flagrar quem está estourando a faixa que paga.
Quem usa: super-admin da plataforma.
Ações principais: busca por texto (nome ou CNPJ) e filtro por status; clicar no nome da empresa abre o detalhe dela.
Fluxo correto: 1) abrir a lista; 2) filtrar por status quando procurando um grupo específico (ex: "READ_ONLY" pra ver quem está bloqueado); 3) olhar a coluna Aparelhos — barra colorida indica proximidade do limite do plano; 4) clicar na empresa pra agir (registrar pagamento, mudar plano etc, na tela de detalhe).
Se pular ou errar: não há trava técnica — é só uma tela de leitura e navegação. O risco prático é comercial: não acompanhar a barra de consumo de aparelhos significa não perceber uma empresa que cresceu e deveria fazer upgrade de plano (a tela NÃO bloqueia o cadastro de aparelhos além do limite, só mostra o número pra abrir a conversa).
Gotchas e estados: 6 status possíveis (mesma máquina de estados do resto do painel): ATIVA, PENDENTE, CARENCIA, READ_ONLY, BLOQUEADA, CANCELADA. A barra de consumo só aparece quando o plano tem um teto de aparelhos definido; sem teto, mostra só o número cru com "(sem faixa)" em vez de inventar uma porcentagem. A cor muda em 85% de uso ("atenção", amarelo) e ao ultrapassar 100% ("estourado", vermelho) — 85% foi calibrado pra ainda caber um lote típico de importação da KL (400-500 aparelhos) antes de virar problema.

Detalhe da empresa — `/admin/empresas/[id]`

Pra que serve: o "centro de comando" de uma empresa-cliente específica. Mostra dados da conta (usuários, último acesso, plano, país), a qualificação original do lead, o histórico de ações administrativas (auditoria) e o histórico de pagamentos — e concentra TODAS as ações de gestão comercial daquela empresa: registrar pagamento, trocar plano, estender vencimento e mudar status.
Quem usa: super-admin da plataforma.
Ações principais: (1) Registrar pagamento Pix — informa valor recebido e observação, ativa a empresa e empurra o vencimento +30 dias; (2) Trocar plano — troca o plano contratado sem mexer no status/vencimento; (3) Estender vencimento — botões rápidos de +7/+15/+30 dias (cortesia, sem pagamento associado); (4) Status da assinatura — botões pra forçar um dos estados manualmente.
Fluxo correto: 1) abrir a empresa (pela lista, pelo Dashboard ou pela fila de aprovação); 2) conferir o resumo (usuários, último acesso, plano); 3) quando a empresa manda comprovante de Pix, preencher valor + observação e clicar "Registrar pagamento Pix" — isso sozinho já reativa a conta e renova o vencimento, não precisa mexer no status à parte; 4) usar "Trocar plano" só quando a empresa faz upgrade/downgrade comercial; 5) usar os botões de status manual só para os casos permitidos (ver Gotchas) — nunca pra "ativar na mão".
Se pular ou errar: o próprio sistema impede o erro mais perigoso — o botão "ATIVA" nem existe na lista de status manuais. Tentar forçar ATIVA ou PENDENTE por fora devolve o erro "Ativação só é permitida via registro de pagamento, não manualmente". Esquecer de registrar um pagamento recebido mantém a empresa contando os dias pra rotina automática de vencimento derrubar o acesso dela sozinha.

⚠️ Atenção: essa trava foi fechada em 2026-06-10 depois de uma auditoria — antes dava pra "marcar inadimplente como ATIVA na mão" e mascarar um calote. Não existe atalho legítimo: o único caminho pra reativar uma empresa é "Registrar pagamento Pix".
Gotchas e estados: os botões manuais só aceitam CARÊNCIA, READ_ONLY, BLOQUEADA ou CANCELADA. Registrar pagamento sempre grava o método como Pix manual e empurra o vencimento para 30 dias a partir de hoje ou do vencimento atual (o que for mais tarde) — ou seja, pagar adiantado NÃO empilha além do próximo vencimento normal, só garante que nunca fica no passado. Toda ação (aprovar, recusar, registrar pagamento, mudar status, trocar plano, estender vencimento) grava uma linha de auditoria, visível na seção "Histórico de ações" da própria tela — nada aqui é silencioso.

Planos — `/admin/planos`

Pra que serve: cadastra e mantém a "escada" de planos de assinatura do SaaS (nome, preço mensal, limite de usuários, cota de WhatsApp incluída, ordem de exibição, destaque de "mais popular"). É o catálogo que alimenta tanto o cadastro público de novas empresas quanto o seletor de plano na tela de detalhe da empresa.
Quem usa: super-admin da plataforma.
Ações principais: + Novo plano (abre formulário); em cada card de plano existente: Editar (abre o mesmo formulário preenchido) e Ativar/Inativar (não deleta, só tira da escada visível pra novos clientes).
Fluxo correto: 1) abrir a tela; 2) pra criar, clicar "+ Novo plano" e preencher nome, valor mensal, ordem, limite de usuários (vazio = ilimitado), cota de WhatsApp/mês (0 = sem WhatsApp incluso) e descrição; 3) pra ajustar preço/limite de um plano existente, clicar "Editar" no card; 4) pra tirar um plano de circulação sem apagar quem já está nele, usar "Inativar" (as empresas já contratadas continuam no plano, só novos clientes deixam de vê-lo).
Se pular ou errar: criar um plano sem limite claro de usuários ou de aparelhos faz a tela de Empresas mostrar "(sem faixa)" no lugar da barra de consumo — perde a visibilidade de estouro. Inativar um plano que ainda tem empresas ativas nele NÃO desliga essas empresas nem força migração — o card mostra "N empresa(s) neste plano" como aviso, mas a ação é só informativa.
Gotchas e estados: cada card mostra quantas empresas estão nesse plano hoje — o número vem direto do banco, não é calculado na tela. O campo de destaque só controla um selo visual ("mais popular"); não muda nenhuma regra de negócio.

Chave Pix da plataforma — `/admin/pix`

Pra que serve: cadastra a chave Pix (ou o "copia-e-cola" pronto do banco) que a KL usa pra RECEBER o pagamento da mensalidade de TODAS as empresas-clientes. É o dado que a tela de Assinatura (do lado da empresa-cliente) lê pra montar o QR Code de cobrança.
Quem usa: super-admin da plataforma.
Ações principais: escolher o modo — "Informar a chave" (CPF/CNPJ/e-mail/telefone/aleatória, o sistema monta o QR) ou "Colar o copia-e-cola pronto do banco" (código completo, validado antes de salvar); preencher nome do recebedor e cidade (campos exigidos pelo padrão Pix, com limite de caracteres); Salvar chave Pix.
Fluxo correto: 1) abrir a tela; 2) escolher o modo mais simples pra sua situação (chave direta é mais fácil de manter; copia-e-cola serve quando o banco só oferece o código pronto com valor fixo); 3) preencher os campos e salvar — não precisa de nenhuma atualização do sistema, o valor é lido em tempo real por quem gera a cobrança.
Se pular ou errar: enquanto não houver chave configurada, a tela de Assinatura das empresas mostra "O pagamento por Pix ainda não está disponível. Fale com o suporte" no lugar do QR Code.

⚠️ Atenção: sem esta tela preenchida, NENHUMA empresa-cliente consegue pagar pelo sistema, só por fora (WhatsApp, e-mail) — isso quebra o fluxo de autocobrança que justifica o próprio painel. Configure a chave Pix antes de aprovar a primeira empresa.
Gotchas e estados: a validação acontece no servidor antes de salvar — chave mal formatada ou copia-e-cola inválido é recusado com mensagem de erro, nunca salvo quebrado. A chave é global da plataforma (uma só pra todas as empresas), não por empresa-cliente.

WhatsApp da plataforma — `/admin/whatsapp`

Pra que serve: conecta um número de WhatsApp (chip dedicado) pra a plataforma ENVIAR alertas automáticos pro super-admin — hoje: "nova empresa cadastrou" (na aprovação) e "pagamento registrado". Usa a mesma infraestrutura de WhatsApp que outros módulos do sistema.
Quem usa: super-admin da plataforma.
Ações principais: salvar o número que recebe os alertas (com DDI); Conectar WhatsApp (gera QR Code pra escanear no celular do chip); Gerar novo QR (se o QR expirar); Enviar teste (manda uma mensagem de confirmação, só aparece quando já conectado); Desconectar.
Fluxo correto: 1) preencher e salvar o número que vai RECEBER os alertas; 2) clicar "Conectar WhatsApp"; 3) escanear o QR Code que aparece na tela usando o WhatsApp do celular do chip dedicado (Aparelhos conectados -> Conectar aparelho); 4) aguardar o status virar "conectado" (a tela verifica sozinha a cada 4 segundos); 5) opcionalmente, clicar "Enviar teste" pra confirmar que a mensagem chega.
Se pular ou errar: se a integração de WhatsApp não estiver configurada na infraestrutura (fora desta tela), qualquer tentativa de conectar falha silenciosamente com um erro genérico — a tela só mostra "Erro:" sem detalhar. Sem número de admin salvo, o botão de teste recusa com "Salve o número do admin primeiro". Em qualquer um dos dois casos, os alertas automáticos (nova empresa, pagamento) simplesmente não saem — são só avisos de melhor esforço, nunca travam o cadastro/pagamento em si, só o aviso que silenciosamente não acontece.
Gotchas e estados: 4 status possíveis — desconectado, aguardando_qr, conectado, falhou. Enquanto em aguardando_qr, a tela faz verificação automática a cada 4s buscando o QR e o status novo. Esta configuração é SEPARADA do WhatsApp que cada empresa-cliente conecta dentro do próprio ERP dela — são dois canais distintos, um da plataforma e outro de cada empresa.

Assinatura (cobrança da empresa-cliente) — `/assinatura`

Pra que serve: é a tela que fica DENTRO do app de cada empresa-cliente (não do painel adm) onde ela vê o status da própria assinatura e paga a mensalidade via Pix. É o ponto onde toda a configuração feita em "Chave Pix da plataforma" e "Planos" chega até o cliente final.
Quem usa: qualquer usuário logado da empresa-cliente consegue abrir a URL — a tela só exige estar logado, sem checar perfil, de propósito: é a tela que um cliente BLOQUEADO precisa alcançar pra se regularizar, então não pode estar atrás do mesmo bloqueio que ela existe pra resolver. Na navegação normal (menu lateral), o link "Assinatura" só aparece pro perfil ADMIN e GERENTE da empresa; os demais perfis não veem o link no menu, mas conseguem acessar digitando a URL direto.
Ações principais: ver plano contratado, status atual e próximo vencimento; ver o valor devido; Copiar código Pix (copia o "copia-e-cola" pra colar no app do banco); ler o QR Code direto na tela.
Fluxo correto: 1) empresa recebe aviso (banner de carência, tela bloqueada, ou aviso via WhatsApp/e-mail) de que precisa pagar; 2) abre /assinatura; 3) escaneia o QR ou copia o código Pix; 4) paga no próprio banco, conferindo que o valor bate (nem todo Pix gerado tem valor embutido — a tela avisa quando precisa digitar o valor manualmente); 5) manda o comprovante pro suporte (contato@getimportex.com) — a liberação NÃO é automática, depende do super-admin registrar o pagamento no detalhe da empresa; 6) recarrega a página pra ver o status atualizado depois da liberação.
Se pular ou errar: se a chave Pix da plataforma não estiver configurada, a tela mostra "O pagamento por Pix ainda não está disponível" e a empresa fica sem meio de pagar pelo sistema. Se a geração do QR falhar por algum motivo técnico, mostra "Não foi possível gerar a cobrança" — em ambos os casos a saída oferecida é "fale com o suporte", nunca trava com erro cru.
Gotchas e estados: a página nunca fica em cache — sempre busca o status mais recente do banco a cada carregamento, essencial numa tela de cobrança. O pagamento em si NÃO é automático: é sempre manual, o cliente manda comprovante e o super-admin confirma na tela de detalhe da empresa.

Erros comuns e como evitar

Confundir os dois "admin". Existe o admin da PLATAFORMA (adm.getimportex.com, este capítulo — mexe com TODAS as empresas) e existe um grupo de menu chamado "Admin" DENTRO do app de cada empresa (/cadastros/empresas, /assinatura, /configuracoes etc — mexe só com os dados daquela UMA empresa). São sistemas de permissão diferentes: o primeiro é binário (está numa lista fixa de admins ou não, sem níveis), o segundo usa os 9 perfis do ERP.
Esquecer de configurar a Chave Pix antes de aprovar empresas. Sem essa chave preenchida, toda empresa aprovada fica sem conseguir pagar pelo próprio sistema assim que vencer.
Tentar forçar status ATIVA na mão. O sistema recusa de propósito (trava fechada desde 2026-06-10) — o único caminho pra ATIVA é "Registrar pagamento Pix" no detalhe da empresa. Se o cliente pagou, registra o pagamento; não existe atalho de "só mudar o status".
Não acompanhar o Dashboard/lista de Empresas com regularidade. A rotina automática de vencimento degrada status sozinha (ATIVA -> CARÊNCIA -> READ_ONLY -> BLOQUEADA) sem avisar ninguém do lado da KL — quem descobre primeiro que uma empresa foi bloqueada costuma ser a própria empresa reclamando, se ninguém olhar o painel antes.
Inativar um plano com empresas ainda nele, achando que isso as move. Inativar só tira o plano da vitrine pra clientes NOVOS; quem já está no plano continua exatamente ali até alguém trocar manualmente no detalhe da empresa.
Esperar que o e-mail de aprovação ou o alerta de WhatsApp sejam garantidos. Ambos são só avisos de melhor esforço: se o serviço de e-mail ou o WhatsApp estiver fora do ar, a aprovação/pagamento acontece do mesmo jeito, só o aviso automático que não sai — vale conferir manualmente com o cliente em caso de dúvida.
Achar que "Estender vencimento" é a mesma coisa que "Registrar pagamento". Estender é cortesia (empurra a data sem criar linha de pagamento no histórico); registrar pagamento cria a linha no histórico de pagamentos E reativa a assinatura. Usar o botão errado para o caso errado bagunça o histórico financeiro da empresa.
Digitar a URL /assinatura esperando que ela exija o mesmo perfil do link do menu. A tela é acessível por qualquer login da empresa (de propósito, pra não trancar quem precisa pagar), então não serve como controle de quem PODE ver a cobrança — se isso for um problema de privacidade interna da empresa-cliente, precisa ser resolvido por fora (processo, não pelo sistema).