Acesso, Perfis e Portais Públicos

Este capítulo documenta a "porta de entrada" do iMportex em dois sentidos diferentes. De um lado, o acesso interno: como uma loja nova entra no sistema (cadastro self-service, sem precisar de ninguém da KL criar a conta na mão), como o time da KL — e de qualquer outra loja cliente da plataforma — faz login todo dia, e como recupera a senha quando esquece. Do outro lado, os portais públicos: páginas que não pedem login nenhum porque quem abre não é funcionário — é o cliente final acompanhando a entrega, um comprador conferindo a qualidade de um iPhone pelo QR Code da etiqueta, ou o próprio operador da bancada de despacho usando o celular só pra bipar peso e foto. Estas páginas aparecem em pontos espalhados por todo o fluxo macro Paraguai → SP → venda: o certificado de qualidade nasce na Triagem (PY) e viaja colado no aparelho até a venda; a conferência de despacho acontece na saída de SP; o rastreio e a proposta de cotação são o que o cliente vê depois que a venda é fechada. Por fim, o capítulo fecha com o middleware (o "segurança da porta" que decide, em toda requisição, o que é público e o que exige sessão) e com o mapa de perfis RBAC (controle de acesso baseado em função/perfil — a referência de "quem pode o quê" usada pelos demais capítulos deste manual).

Fluxo do módulo em 1 olhada

1. Loja nova se cadastra sozinha em /cadastro (site público, sem login) → conta nasce inativa, aguardando aprovação (manual ou por pagamento da assinatura).
2. Time já com conta faz login em /login todo dia → o sistema decide o destino sozinho: painel de super-admin (/admin) ou o ERP da loja (/dashboard).
3. Esqueceu a senha → /recuperar-senha (pede e-mail) → e-mail chega com link → o sistema troca o link por uma sessão temporária → /redefinir-senha (troca a senha) → volta pro /login.
4. Enquanto o time opera o ERP por dentro, o sistema gera e expõe pontos públicos (sem exigir login de quem está do outro lado):
   • Na Triagem (PY), cada aparelho aprovado ganha uma etiqueta com QR que aponta pro certificado público /verificar/[id] — viaja colado no aparelho até o cliente final.
   • Na venda, o vendedor manda pro cliente o link da proposta /c/[token] (cotação).
   • Na Expedição (saída de SP), o operador da bancada da balança escaneia o QR do pacote e usa /despacho/[token] pra registrar foto e peso, sem logar no celular compartilhado.
   • Depois que o pacote sai, o cliente recebe automaticamente (via WhatsApp) o link de /r/[token] pra acompanhar a entrega.
5. Todo esse trânsito — o que pede login e o que não pede — é decidido em UM lugar central: o middleware, um filtro que roda antes de qualquer página renderizar (ver seção abaixo).

Middleware — o que é público vs. o que exige login

O middleware roda em toda requisição (exceto arquivos estáticos, como imagens e ícones) e faz três coisas, em ordem:

1. Roteamento por subdomínio. O iMportex usa 3 subdomínios: www.getimportex.com (site/vitrine pública: a página inicial de apresentação, este manual, as páginas jurídicas de Privacidade e Termos de Uso, e o cadastro — todas estáticas, sem ação operacional), app.getimportex.com (o ERP em si, onde o time da loja trabalha) e adm.getimportex.com (painel de super-admin da plataforma — ver Admin). O sistema redireciona quem está no subdomínio errado pro certo (ex.: alguém tentando abrir /admin em app. é mandado pra adm.). Em desenvolvimento (acesso por IP ou localhost puro), esse redirecionamento é pulado e tudo se comporta como se fosse app.
2. Renovação de sessão. Em toda requisição, o sistema tenta renovar o token de sessão (se estiver perto de expirar) junto do Supabase (a plataforma que cuida do login e do banco de dados por trás do iMportex) e propaga o cookie novo tanto pra própria requisição atual quanto pra resposta que volta ao navegador. Isso já foi causa de um bug de PROD (17/07/2026: sessão antiga em loop de redirecionamento entre /dashboard e /login no Safari) — hoje corrigido.
3. Trava de rota por sessão (não por perfil — perfil é responsabilidade de camadas mais internas, ver seção seguinte). O sistema trabalha por lista branca (só passa quem está autorizado; por padrão, ninguém passa): só as rotas abaixo passam sem sessão; qualquer outra página redireciona pra /login, e qualquer outra rota de API devolve um erro 401 (não autorizado) num formato de dados padronizado (JSON) — nunca redireciona uma chamada de API (se redirecionasse, quem chamou receberia uma tela de login disfarçada de resposta válida e tentaria interpretar como dado, escondendo o erro real).

Rotas públicas (lista branca):

Duas travas adicionais vivem só no middleware, sem tela própria, e valem citar aqui:

• Circuit-breaker (disjuntor automático) anti-loop de redirecionamento: se uma sessão válida bater em /login 3 vezes em menos de 20 segundos (sintoma de algum bug de redirecionamento, não importa a causa), o sistema interrompe o ciclo sozinho e devolve uma página de erro (código 508) em vez de deixar o navegador travar em "muitos redirecionamentos". Nasceu do incidente de 27/07/2026.
• Cookie corrompido: se o sistema não encontra o usuário mas existe um cookie de sessão presente (caso raro do Safari iOS perdendo um "pedaço" do cookie grande do Supabase), ele apaga esse cookie ruim pra não reentrar em loop na próxima requisição.
• Redirecionamento de etiqueta antiga: quem escaneia (sem login) uma etiqueta impressa antes de 15/07/2026, cujo QR aponta pra uma rota interna antiga (/triagem/[id]/laudo), é automaticamente redirecionado pro certificado público equivalente (/verificar/[id]) em vez de bater num /login sem sentido pra um comprador.

Mapa de perfis RBAC (fonte canônica de "quem pode o quê")

O iMportex tem dois eixos de permissão independentes, e é importante não confundi-los:

Eixo 1 — Perfil dentro da empresa

São 9 perfis ao todo:

Existe uma trava central que decide "este perfil pode fazer X?" — uma camada interna do sistema com 42 "capacidades" (poderes de negócio nomeados, ex.: ver_dinheiro, criar_venda, operar_expedicao, gerir_usuarios, abrir_chamado), cada uma com uma lista fechada de perfis autorizados — exceto quando a capacidade é declarada explicitamente "de todo mundo" (caso de abrir_chamado desde 10/09/2026: todos os 9 perfis abrem chamado na Central de Chamados, sem lista fixa que precise ser lembrada a cada perfil novo). Essa lista nasceu de uma decisão de 08/07/2026 e de uma comparação linha a linha com as travas de segurança do banco de dados em produção (o ambiente real, em uso pelos clientes), feita depois de a auditoria encontrar telas que "prometiam" uma ação no menu e o sistema recusava em silêncio. O menu de navegação e as ações do sistema consultam só esse mapa de capacidades; a trava do banco de dados é a segunda camada de proteção (defesa em profundidade), nunca a única. O detalhamento completo das 37 capacidades e quem as usa cabe aos capítulos de cada módulo — este capítulo documenta o eixo, não a lista inteira.

Dois gates (travas de passagem) adicionais, fora do perfil, também bloqueiam o acesso ao ERP inteiro:

• Conta ativa: conta recém-criada (seja pelo cadastro self-service, seja criada automaticamente por outro processo interno) nasce inativa. Ela consegue logar (a senha já vale), mas cai numa tela "Conta aguardando ativação" sem ver nenhum menu, até um ADMIN da própria empresa ativá-la.
• Status da assinatura da empresa (verificado automaticamente pelo sistema a cada acesso): PENDENTE, BLOQUEADA, CANCELADA ou READ_ONLY bloqueiam o acesso por completo (tela de cobrança, sem menu lateral); CARENCIA mostra um banner de aviso mas libera acesso total; qualquer status desconhecido ou vazio é tratado como normal ("fail-open" deliberado — um glitch de cobrança não pode derrubar o ERP de uma loja inteira).

Eixo 2 — Super-admin de plataforma

Separado da lista de perfis de cada loja, existe um segundo nível: o super-admin da plataforma iMportex (a KL administrando o SaaS — software vendido como serviço, por assinatura — em si, não uma loja cliente). É decidido por uma checagem própria do sistema, vive no subdomínio adm.getimportex.com, e dá acesso ao painel de administração (aprovar empresas novas, ver faturamento da plataforma, gerenciar planos, configurar PIX, canal de WhatsApp da própria plataforma). O /login é compartilhado entre os dois eixos: ao autenticar com sucesso, o sistema verifica automaticamente qual é o caso e decide o destino — /admin se for super-admin de plataforma, /dashboard nos demais casos. Esse painel de administração não fazia parte do escopo deste capítulo e não foi documentado tela a tela aqui.

Criar conta (cadastro self-service)

Pra que serve: é a porta de entrada de uma loja nova virando cliente do iMportex — um formulário público (site institucional, sem login) que cadastra a empresa sozinha, sem depender de alguém da KL criar a conta manualmente.

Quem usa: qualquer visitante do site (www.getimportex.com/cadastro). Não há perfil aqui — é quem ainda não tem conta.

Ações principais: wizard (formulário em etapas) de 3 passos — Passo 1 "Crie sua conta" (nome da loja, e-mail, senha); Passo 2 "Sobre sua operação" (CNPJ opcional, telefone, volume mensal, onde vende, canais de venda, tamanho da equipe); Passo 3 "O que vamos resolver primeiro?" (dor principal, sistema atual, faturamento, origem do lead) → botão "Criar minha conta".

Fluxo correto:

1. Preencher os 3 passos (cada um valida antes de avançar).
2. Ao enviar, o sistema processa o cadastro: cria a empresa (inativa), cria o usuário ADMIN dessa empresa (também inativo) e uma assinatura com status PENDENTE.
3. Tela de sucesso avisa "nosso time vai te chamar pra liberar seu acesso".
4. Dispara (melhor esforço, nunca trava o cadastro) um alerta por WhatsApp pro admin da plataforma avisando da empresa nova.
5. Só depois de um super-admin de plataforma aprovar (ver Admin) ou a assinatura ser paga é que a conta libera de verdade.

Se pular ou errar: e-mail já cadastrado é recusado ("Este e-mail já está cadastrado"); senha fraca (menos de 12 caracteres, ou sem letra e número) é recusada com a mesma regra do login; CNPJ é opcional desde 11/06/2026 (decisão do dono) — só é validado (14 dígitos) se for preenchido; tentar logar imediatamente depois do cadastro funciona (a senha já é válida), mas cai direto na tela "Conta aguardando ativação" — nunca vê o menu do sistema até ser ativado.

Detalhes e estados: ?plano=<uuid> na URL pré-seleciona um plano de assinatura — só é aceito se for um código único (UUID) válido, senão o sistema usa o plano padrão ativo; a política de senha (12+ caracteres, letra E número) é a mesma do login — um bug de 10/06/2026 (uma atualização interna recriou a validação com a regra antiga, por engano) chegou a deixar cadastrar com senha mais fraca do que o login aceitava; foi corrigido ainda naquele mês.

Login

Pra que serve: o portão de entrada de todo dia — tanto pro time operacional do ERP (app.getimportex.com) quanto pro super-admin da plataforma (adm.getimportex.com, mesma tela, destino diferente após autenticar).

Quem usa: qualquer um dos 9 perfis com conta ativa — ADMIN, GERENTE, VENDEDOR, FINANCEIRO, OPERADOR_PY, OPERADOR_SP, TESTADOR, TECNICO_PROPRIO, SUPERVISOR_ASSISTENCIA — e também o super-admin de plataforma (eixo separado, ver seção RBAC acima).

Ações principais: campo e-mail, campo senha (com botão mostrar/ocultar), checkbox "Lembrar de mim neste dispositivo" (marcado por padrão), botão "Entrar", link "Esqueceu a senha?".

Fluxo correto:

1. Acessar /login (ou ser redirecionado pra lá automaticamente ao tentar abrir qualquer rota protegida sem sessão).
2. Digitar e-mail e senha.
3. Clicar "Entrar".
4. O sistema decide o destino sozinho: /admin se for super-admin de plataforma, /dashboard (o ERP da loja) nos demais casos.

Se pular ou errar: 5 tentativas erradas com o mesmo e-mail em 15 minutos bloqueiam novas tentativas (proteção contra ataque de força bruta, compartilhada entre os servidores do sistema, com um reforço local se algo cair), com contagem regressiva na mensagem de erro; senha/e-mail incorretos nunca dizem qual dos dois está errado (mensagem sempre genérica, decisão de segurança — não vazar se um e-mail existe no sistema); conta nova (inativa) consegue autenticar mas cai numa tela "Conta aguardando ativação", sem menu nenhum; empresa com assinatura PENDENTE/BLOQUEADA/CANCELADA cai numa tela de bloqueio com botão "Pagar assinatura".

Detalhes e estados: o botão "Entrar" só fica clicável depois que a página termina de carregar totalmente no navegador — existe pra nunca deixar um envio de formulário "cru" jogar e-mail e senha na URL (aconteceu de verdade em 28/07/2026, quando uma imagem pesada atrasava esse carregamento em 26 segundos; a imagem foi corrigida, a proteção ficou); ver também o circuit-breaker anti-loop e a limpeza de cookie corrompido, ambos na seção Middleware acima; "Lembrar de mim" desmarcado grava um cookie de sessão (some ao fechar o navegador); marcado grava por ~400 dias; senha exige mínimo 12 caracteres com letra e número — mesma regra do cadastro e da redefinição.

Recuperar senha

Pra que serve: recuperar o acesso quando esqueceu a senha. Desde 06/09/2026 a tela tem duas portas lado a lado (abas "Por e-mail" / "Por WhatsApp") — nasceu de um caso real: uma usuária da KL pediu recuperação por e-mail 7 vezes em 20 minutos e nunca conseguiu entrar porque o que ela tinha esquecido era justamente o e-mail de cadastro, não a senha.

Quem usa: qualquer pessoa com e-mail ou telefone cadastrado no sistema — rota pública, não exige sessão.

Ações principais:

• Por e-mail (a porta de sempre, continua a principal): campo e-mail, botão "Enviar link de recuperação".
• Por WhatsApp (nova): um único campo "E-mail ou telefone" (aceita qualquer um dos dois, pra quem lembra só de um deles) → botão "Receber código no WhatsApp" → chega um código de 6 números por WhatsApp (nunca um link, de propósito — link no WhatsApp vira preview/golpe) → campo pro código + campo de nova senha (mín. 12 caracteres, letra e número) → botão "Trocar senha".

Fluxo correto (WhatsApp):

1. Escolher a aba "Por WhatsApp".
2. Informar e-mail ou telefone cadastrado.
3. Receber o código de 6 números no WhatsApp cadastrado.
4. Digitar o código e a nova senha na mesma tela (2 passos, sem trocar de página) e confirmar.
5. Sucesso leva direto pro /login, senha já trocada.

Se pular ou errar:

• E-mail: nada visível quebra — a resposta é sempre a mesma mensagem de sucesso ("Se este e-mail estiver cadastrado, você receberá as instruções...") exista ou não o e-mail no banco (proteção deliberada contra "enumeração de usuários").
• WhatsApp: o primeiro passo também responde de forma neutra (não revela se o e-mail/telefone existe); código errado ou expirado mostra "Código inválido ou expirado. Peça um novo." (a mesma mensagem pros dois casos, de propósito); pedir um código novo invalida o anterior; o código vale por 10 minutos com até 5 tentativas, e há limite de pedidos (1 por minuto / 5 por hora) contra abuso.

Detalhes e estados: o WhatsApp é alternativa, nunca substituto do e-mail — a API de WhatsApp usada não é oficial e o número pode ser banido sem aviso, então o e-mail continua sendo a porta principal e a única pra quem não tem telefone cadastrado. O código é guardado com hash (nunca em texto puro), amarrado ao próprio usuário — uma eventual tabela pronta de hashes de 6 dígitos não serviria pra atacar todo mundo de uma vez.

Redefinir senha

Pra que serve: trocar a senha de fato, depois de clicar no link recebido por e-mail.

Quem usa: quem tem uma sessão temporária válida, criada automaticamente ao clicar no link de e-mail.

Ações principais: campo "Nova senha", campo "Confirmar nova senha", botão "Redefinir senha".

Fluxo correto:

1. Clicar no link recebido por e-mail.
2. O sistema troca automaticamente esse link por uma sessão temporária e leva você direto pra esta tela.
3. Digitar a nova senha duas vezes.
4. Sucesso → redireciona pro /login?senha=redefinida.

Se pular ou errar: sem sessão válida (link expirado, já usado, ou acesso direto à URL sem ter vindo do e-mail), a tela mostra "Link expirado ou inválido. Solicite a recuperação de senha novamente." e não deixa trocar nada; senha fraca (menos de 12 caracteres, sem letra e número) é recusada; os dois campos de senha diferentes entre si são recusados ("As senhas não conferem").

Detalhes e estados: link já usado uma vez (ou de qualquer forma inválido) redireciona direto pro /login?erro=link_invalido, nunca chega a abrir esta tela.

Verificação de qualidade (certificado público do aparelho)

Pra que serve: é o "cartão de visita" de cada aparelho individual — a página que abre quando alguém escaneia o QR Code impresso na etiqueta colada nele (etiqueta gerada na Triagem, no Paraguai). Mostra que o aparelho passou pela inspeção de qualidade: grade (a classificação de estado de conservação do aparelho: A/AB/B/C/MIX), percentual de bateria, IMEI (o número de série único do aparelho), selo "APROVADO".

Quem usa: duas faces na mesma URL, decidido automaticamente por ter ou não sessão:

1. Sem sessão (o caso normal — comprador final, qualquer pessoa com o link/QR): vê o certificado público, sanitizado, sem custo/preço/nome de cliente.
2. Com sessão de um usuário da EMPRESA DONA daquele aparelho: vê a "ficha interna" — histórico completo (marcos do processo, reparos, retestes, RMAs, localização física atual, se está bloqueado e por quê). Requer também a capacidade ver_dinheiro (perfis ADMIN/GERENTE/FINANCEIRO) pra enxergar o custo do reparo dentro dessa ficha — os demais perfis logados veem a ficha interna sem o valor em R$.
3. Com sessão de outra empresa (ou aparelho que não existe): cai na mesma versão pública — por desenho, os três casos ("não é seu", "não existe", "acesso recusado pelo banco") ficam indistinguíveis, por segurança.

Ações principais: nenhuma ação de escrita — é 100% leitura/exibição (selo, QR próprio, ficha técnica e, na versão interna, linha do tempo).

Fluxo correto:

1. Aparelho passa pela Triagem e recebe grade/laudo.
2. Etiqueta impressa carrega um QR apontando pra /verificar/[id] (id = código único do próprio aparelho — um UUID, praticamente impossível de adivinhar — que funciona como token de acesso).
3. Qualquer pessoa que escaneia (cliente final, comprador, o próprio time em campo) vê o certificado público.
4. Funcionário logado da mesma empresa que escaneia vê a versão interna — útil pra achar rápido "onde está esse aparelho agora / quem mexeu nele por último".

Se pular ou errar: aparelho que ainda não passou pela triagem mostra "Aparelho ainda não certificado"; id inválido ou inexistente mostra "Certificado não encontrado" — a mensagem nunca revela qual dos dois motivos ocorreu.

Detalhes e estados: desde 10/08/2026 o selo público sempre mostra "APROVADO" — antes mostrava o destino real do aparelho (ex.: ASSISTENCIA), e isso vazava estado desatualizado: o campo de destino fica "congelado" depois do reparo, então 463 aparelhos já vendidos ainda carregavam o rótulo antigo de assistência na página pública; a versão pública nunca devolve custo, preço, cliente ou histórico de movimentação; /laudo/[id] é a rota antiga (etiquetas impressas antes de 15/07/2026) e hoje é só um redirecionamento permanente pra /verificar/[id] — mantida viva unicamente pra não quebrar etiqueta/link já impresso (ver seção Laudo abaixo).

Laudo (redirecionamento antigo)

Pra que serve: hoje, só redirecionar de forma permanente para /verificar/[id] — não é mais uma tela própria. Existiu como certificado público independente até 15/07/2026, quando os dois certificados públicos que o sistema tinha (/laudo e /verificar) foram unificados num só, canônico em /verificar/[id] ("o melhor dos dois mundos", decisão do dono).

Quem usa: ninguém interage com conteúdo aqui — é atravessada em uma fração de segundo por quem escaneia uma etiqueta impressa antes de 15/07/2026 ou abre um link antigo já compartilhado.

Ações principais: nenhuma — a página não tem tela própria, só direciona automaticamente pra /verificar/[id].

Fluxo correto:

1. Alguém escaneia uma etiqueta antiga ou abre um link salvo no formato /laudo/[id].
2. O sistema já resolve o redirecionamento permanente antes de qualquer conteúdo aparecer.
3. O navegador é levado direto para /verificar/[id], que aí sim monta o certificado (ver seção acima).

Se pular ou errar: não há como "errar" esta rota — não tem formulário, campo ou decisão; o único jeito de ela se comportar diferente seria removerem o redirecionamento, o que quebraria toda etiqueta impressa antes da unificação.

Detalhes e estados: uma função antiga que esta rota usava diretamente continua existindo por compatibilidade, mas não é mais chamada por este caminho público — o certificado real, hoje, é sempre montado a partir de /verificar/[id].

Proposta de cotação (link público de venda)

Pra que serve: a página que o cliente abre ao receber, pelo WhatsApp, o link de uma cotação/proposta montada por um vendedor — mostra os aparelhos, quantidades e valores propostos, sem exigir login.

Quem usa: cliente final (sem login) que recebeu o link do vendedor.

Ações principais: só leitura — não há botão de "fechar negócio" nesta página; o fechamento continua sendo conversa (WhatsApp) com o vendedor, a tela é a "vitrine" da proposta.

Fluxo correto:

1. Vendedor monta a cotação dentro do sistema, logado, na tela de Cotações (ver Vendas).
2. Ao clicar "Enviar", o sistema reserva o estoque da grade/modelo por um prazo (até a validade da proposta) e gera um token novo (um código longo e imprevisível).
3. O link /c/<token> aparece num aviso dentro do próprio sistema — o vendedor copia e cola manualmente no WhatsApp do cliente (não há disparo automático; é decisão de escopo deliberada — a integração automática de WhatsApp fica pra uma fase futura).
4. Cliente abre o link e vê a proposta com preço unitário e total, em BRL ou USD conforme a moeda em que a cotação foi montada.

Se pular ou errar: token errado e cotação cancelada dão o mesmo resultado (página "não encontrada" genérica) — impossível adivinhar se um link já existiu algum dia; proposta vencida continua abrindo, mas com aviso amarelo ("Esta proposta venceu em [data]") em vez do banner verde de confirmação.

⚠️ Atenção: esta página nunca mostra o custo do aparelho — só o preço de venda — porque o link pode circular livremente pelo WhatsApp e chegar até um concorrente. Mostrar o custo aqui exporia a margem da loja.

Detalhes e estados: a leitura desta página usa só uma função pública de consulta, sem nunca usar a chave de acesso total ao banco de dados — então mesmo um eventual bug nesta página não teria como revelar nada além do que essa função entrega de propósito; a página também nunca fica em cache (é sempre recarregada na hora), porque o vendedor pode cancelar a proposta a qualquer momento.

Conferência de despacho (bancada da balança)

Pra que serve: tela mobile aberta pelo QR de um pacote, na bancada de despacho (SP) — o operador fotografa o pacote em cima da balança e digita o peso, sem precisar logar no celular compartilhado da bancada.

Quem usa: operador de SP fisicamente na bancada — escaneia o QR com o próprio celular; a tela não exige login (é um "modo bancada" pensado pra evitar o atrito de logar num aparelho compartilhado por vários operadores).

Ações principais: tirar foto (câmera traseira) do pacote na balança, digitar o peso em kg, botão "Confirmar foto e peso".

Fluxo correto:

1. Na Expedição, um pacote entra no status AGUARDANDO_DESPACHO — o sistema gera sozinho um código de acesso único (token) pra esse pacote.
2. A etiqueta impressa do pacote carrega o QR apontando pra /despacho/<token>.
3. Operador escaneia e vê o número do pacote (ex.: PAC-0001) e o nome do cliente.
4. Tira a foto e digita o peso.
5. Confirma — o sistema valida tudo e grava a foto num espaço de armazenamento próprio de comprovantes e o peso no pacote.

Se pular ou errar: pacote que já saiu do status AGUARDANDO_DESPACHO (avançou ou foi cancelado) recusa o registro com "Este pacote não está mais aguardando despacho" — trava contra forjar o comprovante depois do fato e contra corrida entre duas pessoas mexendo no mesmo pacote ao mesmo tempo; token inválido mostra "Link inválido"; arquivo enviado que não é PNG/JPEG de verdade é recusado mesmo que o navegador diga que é imagem (checagem pelos bytes reais do arquivo — "magic bytes" — não pelo tipo que o celular declara); peso vazio ou não numérico é recusado; upload maior que 8MB é recusado.

Detalhes e estados: limite de tentativas por IP (endereço de internet de quem está enviando, não por token) contra abuso — 5 tentativas a cada 15 minutos; o envio da foto acontece do lado do servidor, usando uma credencial de acesso total (não pelo celular anônimo diretamente), sempre associada à empresa dona daquele pacote — necessário porque a trava de segurança do armazenamento exige saber de qual empresa é o arquivo, informação que um visitante anônimo não carrega; reabrir o link depois do pacote já registrado mostra direto a tela "Registrado!" — não deixa sobrescrever o comprovante à toa; a bancada de teste da impressora QL-800 (/teste-ql800) é vizinha operacionalmente deste fluxo, mas só é pública fora de produção (ver seção Middleware acima).

Rastreio do pedido

Pra que serve: página pública onde o cliente acompanha, sem login, o andamento da entrega do pacote que comprou — 4 fases visuais (preparando → embalando → a caminho → entregue).

Quem usa: cliente final, sem login — recebe o link automaticamente por WhatsApp quando o pacote muda de status.

Ações principais: só leitura — barra de progresso de 4 fases + histórico de eventos, mais recente primeiro.

Fluxo correto:

1. Todo pacote é criado com um código de rastreio próprio (token).
2. Quando o status do pacote muda pra "saiu para entrega"/"coletado" ou "entregue"/"retirado", o sistema dispara (melhor esforço, não trava o fluxo se falhar) uma notificação ao cliente com o link https://app.getimportex.com/r/<token>.
3. Cliente abre o link a qualquer momento e vê a fase atual, a data prevista ou já realizada de entrega, e o histórico de eventos.

Se pular ou errar: token que não bate com nenhum pacote mostra "Não encontramos esse pedido. Confira o link com a loja." — sem detalhar o motivo.

Detalhes e estados: cada status interno (ex.: EM_SEPARACAO, AGUARDANDO_COLETA, SAIU_PARA_ENTREGA) é traduzido pra uma mensagem amigável ao cliente (ex.: "A caminho") — o mapa interno cobre 17 status diferentes; status de falha (ENTREGA_FALHOU, DEVOLVIDO, CANCELADO, EXTRAVIADO) zera a barra de progresso e troca o ícone por um alerta; o envio automático do link por WhatsApp é melhor-esforço — se o canal WhatsApp da empresa estiver desconectado, o pacote continua avançando normalmente, só o aviso automático que não sai (o cliente ainda pode pedir o link direto pra loja, que consegue recuperá-lo).

Erros comuns e como evitar

1. Confundir os dois eixos de permissão. O perfil de cada funcionário (ADMIN/GERENTE/VENDEDOR/...) decide o que ele faz dentro da própria loja; o super-admin de plataforma decide se a pessoa administra a plataforma inteira (o sistema como um todo, entre lojas clientes diferentes). São checagens separadas — ver a seção RBAC acima antes de assumir que um "ADMIN" de uma loja enxerga o painel de administração.
2. Achar que conta criada = conta funcionando. Tanto o cadastro self-service quanto a criação automática de usuário deixam a conta inativa por padrão — ela loga, mas não vê nada até alguém ativar. Se um usuário disser "criei a conta e não consigo entrar", primeiro pergunte se ele entra (autentica) mas vê uma tela de "aguardando ativação" — são dois problemas diferentes.
3. Mandar o link de cotação (/c/) errado. O sistema não envia esse link sozinho — o vendedor precisa copiar do aviso que aparece após "Enviar" e colar manualmente no WhatsApp. Esquecer esse passo faz a reserva de estoque existir no sistema sem o cliente nunca ter visto a proposta.
4. Reimprimir etiqueta achando que /laudo/[id] sumiu. Não sumiu — virou um redirecionamento permanente pra /verificar/[id]. Etiquetas antigas continuam funcionando; não há necessidade de reimprimir o estoque todo por causa da unificação de 15/07/2026.
5. Testar o certificado público logado e achar que "está mostrando dado demais". Se você testar /verificar/[id] logado como usuário da própria empresa, vai ver a ficha interna completa (histórico, técnico, reparo) — isso é esperado, não é vazamento. Pra ver exatamente o que o cliente final vê, teste em aba anônima/deslogado.
6. Achar que a senha do cadastro é mais fraca que a do login. Já foi verdade por um bug entre 10/06 e 11/06/2026 (uma atualização interna perdeu a validação forte por engano) — hoje as duas exigem a mesma regra (12+ caracteres, letra e número). Se algum dia voltar a divergir, é regressão, não comportamento esperado.
7. Assumir que a Estação de Triagem, /raio-x e /pendencias também são cobertas por este capítulo. Não são — este capítulo documenta só as rotas de acesso/portal listadas acima, mais o middleware e o mapa RBAC de referência. As reformas do "Programa Navegação" (grade obrigatória, redirecionamentos de /raio-x//pendencias pro Painel do Dia, Estação Única de triagem etc.) ficam para os capítulos dos respectivos módulos.