Expedição e Logística PY→SP

Pedido, separação por grade, remessa, freteiro e os painéis PY/SP do trânsito.

Este capítulo cobre o trecho do sistema que pega o aparelho depois que ele já foi triado (avaliado e classificado) e, se precisou, consertado no Paraguai — e o leva até virar entrega na mão de um cliente em São Paulo. No fluxo geral do iMportex (compra e recebimento no Paraguai → triagem com laudo e grade → assistência técnica → inventário e estoque → expedição/logística SP → venda B2B com cotações), este é o pedaço "estoquista": mover caixa física, bipar IMEI (o número de série que identifica cada aparelho), montar remessa, conferir chegada, e por fim separar/embalar/despachar o pedido do cliente.

Duas famílias de tela convivem aqui e é fácil confundir uma com a outra porque os nomes se parecem:

Logística PY→SP: move estoque interno do Paraguai para São Paulo. Não tem cliente, não tem venda — é aparelho indo de um galpão pra outro.
Expedição: depois que o aparelho já está em SP e já foi vendido, é o pacote daquela venda saindo até a casa do cliente.

Existe ainda uma terceira tela chamada Separação (sem relação direta com a aba "Separar" de dentro da Logística) — é o painel onde a operação do Paraguai decide o destino de cada aparelho recém-triado antes mesmo dele virar estoque despachável. Ela é o portão de entrada de tudo o que este capítulo descreve.

Fluxo do módulo em 1 olhada

A triagem classifica o aparelho (grade A/AB/B/C + destino: estoque, assistência ou travado) — é quem alimenta a Separação.
Separação decide, aparelho por aparelho: vai pro estoque PY (pronto pra viajar), pra assistência, fica travado, ou volta do reteste. É aqui que nasce (ou não) a grade do aparelho — sem ela, ele nunca aparece nas telas seguintes.
Painel PY é a mesa de trabalho do operador do PY — atalhos com contador pra cada fila (chegou, triado, pronto na assistência, estoque PY, remessas em rota).
Logística PY→SP é o hub do envio: o comprador pede por composição (modelo+capacidade+grade+quantidade) e já escolhe o freteiro, o operador do PY bipa o IMEI real contra o pedido — e o último bipe do pedido já monta volume e despacha a remessa sozinho (desde 07/09). Em paralelo, a mesma tela cobre despacho "direto" (sem pedido), remessas vindas dos EUA, transferências internas dentro do Brasil (com bipagem obrigatória na chegada), e a conferência de chegada em SP por bipagem.
Fretes mostra quanto o serviço de frete PY→SP faturou — de venda em dólar ou de frete avulso (mercadoria de terceiro) — e é onde se lança um frete avulso novo.
Motivos de Regrade e Placar de Grade são duas ferramentas de gestão (visíveis só pra ADMIN/GERENTE) que vivem dentro da Conferência SP: quando a grade que chegou não bate com a que o PY mandou, o operador corrige e registra um motivo — e isso vira um placar de acerto/erro por gradeador.
Painel SP é o espelho do Painel PY, do lado de quem recebe.
Expedição só entra em cena depois da venda: separa o pedido do cliente por IMEI (com bipagem anti-erro), embala, pesa na balança, despacha e confirma entrega/retirada.

Separação

Pra que serve: painel de decisão de 6 "raias" (colunas) para todo aparelho que está em triagem, em assistência ou em reteste. É aqui que a operação decide se o aparelho está pronto pra virar estoque PY (e assim entrar no fluxo de despacho pra SP), se precisa ir pra assistência, se está travado, ou se voltou reprovado do reteste. Não confundir com a aba "Separar" de dentro da Logística (que bipa IMEI contra um pedido já existente) — esta tela decide o destino, aquela confirma a identidade física.

Quem usa: ADMIN, GERENTE, OPERADOR_PY e SUPERVISOR_ASSISTENCIA têm o item no menu. Dentro da tela, duas ações são mais restritas: decidir a raia "Precisa de decisão" (enviar leva pra assistência / liberar mesmo assim) é só de ADMIN, GERENTE e OPERADOR_PY — o SUPERVISOR_ASSISTENCIA vê a tela mas só acompanha. Reclassificar um aparelho travado (pilha "Travados") é ADMIN/GERENTE apenas, e exige justificativa por escrito (fica registrada na trilha de auditoria).

Ações principais:

Liberar (1 a 1 ou "Liberar todos" em massa, até 300 por vez) — move o aparelho da raia "Pronto pra SP" pro estoque PY.
Enviar leva pra assistência — nomeia 1 técnico e manda um lote de aparelhos avulsos (raia "Precisa de decisão"), aguardando o técnico aceitar.
Soltar no estoque de assistência — manda pro estoque da assistência sem escolher técnico ainda (o supervisor distribui depois).
Liberar mesmo assim — pula a assistência e manda direto pro estoque, com justificativa obrigatória (só ADMIN/GERENTE/OPERADOR_PY).
Reclassificar (pilha Travados) — ADMIN/GERENTE decide se um aparelho bloqueado (ex.: pendência de RMA) volta a ser estoque ou assistência.

Fluxo correto:

A triagem termina e o aparelho aparece numa das 6 raias, já classificado automaticamente (não é escolha manual de raia — vem do status, do destino decidido na triagem, de OS aberta e do histórico de reteste).
Raia "Pronto pra SP": clique "Liberar" (ou selecione vários e "Liberar todos"). O aparelho fica disponível no Paraguai e passa a aparecer na Logística.
Raia "Precisa de decisão": escolha entre mandar pra assistência (leva nomeada a um técnico) ou liberar mesmo assim com justificativa.
Raias "Em assistência", "Aguardando reteste", "Reteste feito" são de acompanhamento — o aparelho volta sozinho pras raias de cima quando o ciclo de reparo/reteste terminar.
Raia "Travados": só ADMIN/GERENTE reclassifica, com justificativa.

Se pular ou errar:

⚠️ Atenção: aparelho sem grade nem pré-grade não pode ser liberado. A tela recusa com a mensagem "sem ela o aparelho fica invisível no despacho PY→SP" — essa trava existe porque já causou incidente real em produção: 131 e depois 192 aparelhos (~R$375 mil em estoque parado) foram liberados sem grade e ficaram presos, sem aparecer em nenhuma lista de despacho.

Se o aparelho está em triagem mas ela não registrou um destino de estoque (nem no campo novo, nem numa avaliação antiga que já aprovava estoque), a liberação é recusada — não dá pra contornar a raia "Precisa de decisão" chamando a ação por fora.
Cancelar a venda/pacote no exato instante da bipagem em outra tela não "reanima" o aparelho por engano — existe uma trava contra essa corrida.

Detalhes e estados: as 6 raias são Pronto pra SP, Precisa de decisão, Em assistência, Aguardando reteste, Reteste feito (reteste reprovado) e Travados. Idade "crítica" (badge vermelho) = 5+ dias sem mudança de status. 2+ reprovações no reteste geram alerta de "voltas" (sugestão de escalar pra RMA/devolução). O botão "Liberar todos" roda no servidor (não trava mais o navegador) justamente porque um acúmulo de 222 aparelhos já travou a aba no passado.

Painel PY

Pra que serve: mesa de trabalho do operador do galpão no Paraguai — nenhuma ação própria, só cartões numerados que levam direto pra tela que resolve cada fila.

Quem usa: ADMIN, GERENTE, OPERADOR_PY, TESTADOR. Quem não está nessa lista é redirecionado pro painel geral.

Ações principais: nenhuma mutação nesta tela — é um roteador visual. Também hospeda o widget de recolhimento de lote de reteste (ver abaixo).

Fluxo correto:

Cartões "Precisa de você agora": Chegaram — a triar (leva pra Estação de Triagem), Triados — a separar (leva pra Separação), Prontos na assistência (leva pra tela de reteste) — ficam destacados quando o contador é maior que zero.
Cartões "Acompanhar": Em assistência (leva pras Ordens de Serviço), Estoque PY (abre o inventário já filtrado pelo estoque PY), Remessas em rota (abre a Logística).
Se houver aparelhos prontos vindos do reteste, aparece o bloco de recolhimento em lote: o operador do PY bipa/agrupa fisicamente os aparelhos que já saíram da assistência num lote rastreável, simétrico ao lote de ida da leva de assistência.

Se pular ou errar: o recolhimento em lote é só um selo de rastreio (não muda o status do aparelho) — pular esta etapa não trava nada, mas perde a rastreabilidade de quem recolheu e quando.

Detalhes e estados: os 6 números vêm de contagens diretas por status (chegou, em triagem, em reteste, em assistência, disponível no PY) e de remessas em trânsito ou com entrega parcial — não há cache, é a foto do banco no momento em que a página carrega.

Logística PY→SP — Painel

Pra que serve: aba inicial (abre por padrão) da Central de Logística — pulso de indicadores + alertas de pendência + atalhos numerados pras outras abas.

Quem usa: ADMIN, GERENTE, OPERADOR_PY, OPERADOR_SP — a Logística inteira é liberada só pra esses 4 perfis ("os dois lados da ponte operam").

Ações principais: só navegação (clicar num atalho troca de aba) + a ação "Marcar perdido" que vem embutida no bloco de alertas (ver "Pendências" abaixo).

Fluxo correto: olhe os 4 indicadores do topo (Em rota / Atrasadas / Aguardando receber / Entregues no mês) e o bloco de pendências (só aparece se houver faltante); clique num atalho pra ir direto resolver.

Se pular ou errar: nada — é só leitura/navegação.

Detalhes e estados: o bloco de pendências lista itens de remessas que já deveriam ter chegado mas não foram nem conferidos nem marcados como perdidos, ordenados pelos mais atrasados primeiro. Ali dá pra "Marcar perdido": o aparelho vai para cancelado — mas só se ele realmente ainda estiver "em trânsito" pro trecho daquela remessa (a tela recusa marcar perdido um aparelho que já chegou, já seguiu o fluxo ou já foi vendido — cancelamento nunca é permitido em cima de um aparelho vendido, e um item nesse estado é sinal de remessa duplicada, não de sinistro real).

Logística PY→SP — Fazer pedido

Pra que serve: o comprador registra o que precisa vir do Paraguai por composição — modelo + capacidade + grade (A/AB/B/C) + quantidade — sem escolher IMEI nenhum. É um pedido de demanda, não uma reserva física ainda.

Quem usa: criar/editar/cancelar pedido é restrito a ADMIN e GERENTE (o quem compra opera com um desses dois perfis — não existe perfil dedicado "comprador").

Ações principais: criar pedido com várias linhas e um freteiro (ver abaixo); editar linhas (só as que ainda não tiveram nenhum IMEI bipado); cancelar o pedido inteiro (libera em cascata qualquer reserva ativa); ver prévia de quantas reservas ativas seriam liberadas antes de confirmar o cancelamento.

Fluxo correto:

Adicione uma ou mais linhas: modelo, capacidade, grade, quantidade.
Ao salvar, o sistema avisa (não bloqueia) quando a quantidade pedida excede o disponível hoje no estoque PY — o pedido pode nascer "otimista".
Escolha o freteiro que vai levar esta carga (mudança de 07/09) — a lista só mostra quem é elegível pro trecho PY→BR: ativo, atende o trecho, tem taxa cadastrada e tem base de cálculo definida. Este é o freteiro pra quem a remessa sai quando a separação terminar (ver "Separar" a seguir) — escolher aqui é obrigatório, não dá pra criar o pedido sem.
O pedido vira uma linha na fila de "Separar" pro operador do PY bipar.
Se precisar corrigir: uma linha só é editável enquanto nenhuma unidade dela foi separada; assim que o operador do PY bipa o primeiro IMEI daquela linha, ela trava pra edição (mas o restante do pedido continua editável).
Apagar uma linha na tela realmente apaga do sistema (não é só visual) — mas só se ela nunca foi separada.

Se pular ou errar: tentar editar uma linha já parcialmente separada devolve erro explícito listando qual linha está travada — nada é salvo parcialmente (o sistema aborta tudo antes de gravar). Um pedido não pode ficar com zero linhas (use "Cancelar" em vez de apagar a última linha).

⚠️ Atenção: freteiro sem taxa PY→BR (ou sem base de cálculo, ou inativo, ou que não atende o trecho) bloqueia a criação do pedido — a tela não deixa escolher esse freteiro e diz o motivo exato ("está sem taxa de frete PY→BR. Cadastre a taxa dele em Cadastros → Freteiros..."). É proposital: até 07/09 essa checagem só existia lá na frente, no despacho manual, e um freteiro sem taxa saía com frete zero em silêncio — foi a causa de 1.918 aparelhos despachados sem frete no custo (R$ 293.255,56).

Detalhes e estados: o status do pedido evolui sozinho conforme o operador do PY bipa: Aberto → Em separação → Separado parcial → Separado total → Recebido parcial → Recebido total (ou Cancelado a qualquer momento antes do fim). A grade aceita só A, AB, B, C neste pedido — não existe grade "MIX" aqui (MIX é um conceito de venda ao cliente, resolvido lá nas Vendas — ver a seção Expedição mais adiante neste capítulo pra entender como o MIX chega até o pacote). Pedido criado antes de 07/09 não tem freteiro gravado (o campo é opcional só pra esses casos antigos) — ver "Separar" a seguir pra entender o que isso muda no despacho.

Nesta mesma tela, um aviso ("já tem dono") aparece quando existe estoque PY disponível mas preso por reserva de outro pedido — o caso que nasceu do Kelven procurando "50 aparelhos que estão aqui mas não aparecem": não era cadastro faltando, eram 50 aparelhos já reservados pelo pedido #48. Medido em 07/09, 83% do estoque PY disponível (1.869 de 2.241 aparelhos, em 48 pedidos) estava assim, o mais antigo parado havia 52 dias, e nenhuma tela mostrava isso. O aviso soma quantos aparelhos e quantos pedidos estão segurando, marca em destaque os que passaram de 7 dias parados, e lista os pedidos donos (com link) — pra liberar, é preciso avançar ou cancelar o pedido que segura, nunca um destravamento automático (reserva de pedido separado não expira sozinha, de propósito: soltar sozinho faria dois pedidos disputarem o mesmo aparelho em silêncio).

Logística PY→SP — Separar

Pra que serve: o operador do PY vai ao estoque físico do Paraguai e bipa o IMEI real de cada aparelho, casando-o com uma linha do pedido do comprador. Cada bipe válido cria uma reserva daquele aparelho específico para aquela linha.

Quem usa: ADMIN, GERENTE, OPERADOR_PY.

Ações principais: bipar IMEI (câmera ou digitação); desfazer 1 bipagem (devolve o aparelho e reduz o progresso da linha); imprimir a lista de separação do pedido (ver a versão de impressão mais abaixo).

Fluxo correto:

Escolha o pedido na fila (mesma lista da aba "Fazer pedido", filtrada pelo que ainda tem o que separar).
Bipe o IMEI. O sistema tenta encontrar a linha certa sozinho: busca o aparelho pelo IMEI, olha seu modelo+capacidade+grade, e procura qual linha pendente do pedido bate.
- 1 linha compatível → bipa direto.
- 2+ linhas compatíveis (ambíguo) → a tela pergunta qual linha usar.
- 0 compatíveis → erro "sem linha compatível".
Repita até a linha bater a quantidade pedida (linha completa).
Bipou = despachou (mudança de 07/09): quando o bipe que você acabou de dar fecha a separação do pedido inteiro (todas as linhas completas, não só uma), o sistema fecha o volume sozinho e despacha a remessa automaticamente — sem precisar abrir a aba "Despachar › Volumes". Antes disso existir, o operador do Paraguai simplesmente não sabia que os passos de montar/fechar/despachar volume existiam ("pra mim, na hora que faz o pedido é bipado, ele já tá sendo despachado" — Kelven), e isso deixou 4.823 aparelhos presos como estoque parado e 1.918 sem frete rateado no custo.

Se pular ou errar:

Aparelho existe mas está sem grade registrada → mensagem específica: "não entra em nenhuma linha do pedido. Regularize na triagem antes de separar" — não é mais confundido com "IMEI não encontrado" (era um bug já corrigido: a mensagem antiga mandava o operador conferir o IMEI errado).
Aparelho já reservado para outro pedido → recusado (evita disputa).
Aparelho bloqueado para despacho, ou fora do estoque PY → recusado com o motivo.
Linha já completa → aviso "linha já está completa", sem duplicar a reserva.
Se o freteiro do pedido deixou de ser elegível entre a criação e o fim da separação (perdeu a taxa, foi inativado), o despacho automático não acontece e a tela mostra um aviso âmbar explicando o motivo — nunca vermelho de propósito, porque a separação em si valeu (a reserva já está gravada) e um aviso vermelho faria o operador achar que perdeu o trabalho e bipar tudo de novo. Nesse caso, feche/despache manualmente pela aba "Despachar › Volumes" a seguir.

Detalhes e estados: o scanner de câmera é compartilhado com a Conferência SP (mesmo componente) e só pode ficar ativo numa aba por vez — por isso a Logística usa só a câmera da aba selecionada (trocar de aba desliga a câmera da anterior). A reserva criada aqui é o que a montagem de Volume (próxima aba) vai empacotar. O despacho automático usa a taxa vigente do freteiro agora (lida do cadastro no momento do despacho, não a de quando o pedido nasceu) — se o freteiro reajustou o preço nesse meio-tempo, vale o valor atual. Pedido criado antes de 07/09 (sem freteiro gravado) nunca despacha sozinho — a separação termina normalmente e o aviso pede pra usar a aba "Despachar › Volumes".

Logística PY→SP — Despachar › Volumes

Pra que serve: depois de bipado, o operador do PY agrupa os aparelhos reservados em caixas físicas (volumes) antes de mandar pra estrada. Desde 07/09, um pedido com freteiro cadastrado despacha sozinho ao fim da bipagem (ver "Separar" → "bipou = despachou") — esta aba continua existindo pra despacho direto (sem pedido por trás), pra pedido antigo sem freteiro, e como caminho manual quando o despacho automático não sai (freteiro deixou de ser elegível no meio do caminho).

Quem usa: montar/fechar/reabrir volume é ADMIN, GERENTE, OPERADOR_PY. Despachar o volume (criar a remessa de verdade) é ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY.

Ações principais: criar volume com uma ou mais reservas; adicionar/remover item de um volume ainda em montagem; fechar volume (exige pelo menos 1 item); reabrir volume fechado (corrigir composição antes de despachar); despachar 1+ volumes fechados numa remessa com freteiro, valor declarado e previsão de chegada.

Fluxo correto:

Selecione reservas ativas ainda sem caixa e "Criar volume" (ou adicione a um volume já em montagem).
Quando a caixa estiver completa fisicamente, feche o volume.
Repita para quantas caixas forem precisas.
Selecione 1+ volumes fechados, escolha o freteiro (só os que atendem o trecho PY→BR aparecem), informe o valor declarado (opcional) e despache.
O sistema calcula o frete pela regra do freteiro (valor real da remessa, valor por aparelho, ou percentual sobre o valor declarado — inclusive um modo em dólar) e rateia o custo entre os aparelhos, em centavos exatos (nunca sobra nem falta 1 centavo na soma).

Se pular ou errar:

Volume vazio não fecha ("adicione ao menos 1 item antes de fechar").

⚠️ Atenção: uma vez fechado, o volume só aceita despacho. Despachar um volume que não está fechado é recusado, citando o código da caixa e o status atual — se precisar corrigir a composição, reabra a caixa antes, porque despachar consome as reservas de verdade e não dá pra desfazer depois (só marcar item como perdido se ele nunca chegar).

Despacho parcial (algum pedido envolvido ainda não teve 100% das linhas separadas) só é permitido para ADMIN/GERENTE — OPERADOR_PY/OPERADOR_SP levam erro explícito citando o número do pedido incompleto.
Se o valor declarado divergir mais de 15% do valor real calculado (soma do custo de compra dos aparelhos), o sistema não bloqueia, mas exige uma segunda confirmação explícita antes de prosseguir — é uma checagem que depende de decisão humana, não um bloqueio automático.

⚠️ Atenção: se o despacho físico falhar no meio do caminho (ex.: uma instabilidade momentânea do sistema), a resposta de erro informa quantos aparelhos já foram despachados antes de parar — não há desfazer automático dos que já saíram. O cálculo do rateio de frete só é gravado depois que todo o processo termina; se essa gravação falhar, o aparelho já foi movido fisicamente mas a remessa fica "com dinheiro pendente" — nesse caso, a orientação é contatar o suporte pra reprocessar.

Detalhes e estados: o status do volume segue Em montagem → Fechado → Em remessa. O consumo da reserva (de ativa pra consumida) só acontece no despacho de verdade, nunca ao só fechar a caixa.

Logística PY→SP — Despachar › Direto pro SP

Pra que serve: o caminho antigo de despacho — escolhe aparelhos diretamente por checkbox (sem passar por pedido/bipagem/volume) e despacha. Ainda ativo e usado em paralelo ao fluxo por pedido.

Quem usa: ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY.

Ações principais: listar aparelhos elegíveis; escolher freteiro; despachar com valor real, valor por aparelho, ou percentual sobre valor declarado.

Fluxo correto:

A lista de elegíveis só mostra aparelhos disponíveis no Paraguai, não bloqueados e com modelo, capacidade e grade preenchidos — e que não estejam já reservados para um pedido de logística do comprador (senão duas telas disputariam o mesmo aparelho).
Marque os aparelhos, escolha o freteiro do trecho PY→BR, e despache.

Se pular ou errar: a mesma checagem de elegibilidade é revalidada no servidor no momento do despacho (nunca confia só na lista que a tela mostrou) — se algo mudou de status entretanto, o despacho inteiro é recusado, listando cada aparelho inelegível e o motivo (status errado, bloqueado, ou composição incompleta).

Detalhes e estados: este é exatamente o caminho onde a trava de "grade nula = invisível" (ver a seção Separação) evita que um aparelho incompleto passe — aqui ele simplesmente nunca aparece na lista, sem erro nenhum, o que no passado já escondeu centenas de aparelhos em silêncio até alguém desconfiar do estoque parado.

Logística PY→SP — Despachar › Dos EUA

Pra que serve: despacho do primeiro trecho da viagem (EUA → Paraguai), anterior ao PY→SP — é a primeira perna de um aparelho comprado nos EUA, antes de sequer entrar no galpão do Paraguai.

Quem usa: ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY.

Ações principais: listar elegíveis (aparelhos aguardando chegada, ainda não em outro envio EUA→PY ativo); despachar com freteiro do trecho EUA→PY e frete opcional.

Fluxo correto: selecione os aparelhos aguardando chegada, escolha o freteiro que atende o trecho EUA→PY, informe o frete se souber (ou deixe em branco — a remessa só agrupa sem custo). Diferente do trecho PY→SP, o status do aparelho não muda neste despacho — ele continua aguardando chegada; quem representa "em trânsito" é a remessa em si, não um novo status do aparelho.

Se pular ou errar: despachar o mesmo aparelho duas vezes em envios EUA→PY ativos é recusado ("já em despacho EUA→PY ativo") — sem essa trava, o mesmo aparelho ficaria preso em duas remessas ao mesmo tempo.

Detalhes e estados: a criação da remessa, a gravação do custo e o vínculo de cada aparelho acontecem numa operação só no banco — se qualquer coisa falhar no meio, tudo desfaz (não deixa custo gravado sem remessa, um problema que já existiu quando isso era feito em passos separados).

Logística PY→SP — Na estrada

Pra que serve: acompanhamento somente leitura de todas as remessas (dos 3 trechos: EUA→PY, PY→BR, BR interno) — "Em andamento" e "Concluídas".

Quem usa: os mesmos 4 perfis da Logística (ADMIN, GERENTE, OPERADOR_PY, OPERADOR_SP) — sem restrição extra, é leitura.

Ações principais: clicar numa remessa expande a relação de aparelhos (IMEI + modelo + se já foi conferido), carregada sob demanda.

Fluxo correto: olhe a lista pra saber o que está a caminho e o que já chegou; remessas atrasadas (previsão de chegada vencida) ganham um selo vermelho com a data prevista.

Se pular ou errar: nada — não há mutação aqui.

Detalhes e estados: status possíveis de remessa: preparando, em trânsito, entregue parcial, entregue, cancelada.

Logística PY→SP — Receber (conferência SP)

Pra que serve: fecha o ciclo entre países: quando a remessa PY→BR chega fisicamente em São Paulo, o operador escaneia IMEI a IMEI contra a lista esperada daquele freteiro.

Quem usa: ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY podem conferir. Corrigir a grade durante a conferência é mais restrito: ADMIN, GERENTE, OPERADOR_SP — o OPERADOR_PY fica de fora de propósito, porque ele é justamente quem está sendo avaliado no Placar de Grade (deixá-lo corrigir a própria nota destruiria a justiça do placar).

Ações principais: bipar IMEI (câmera ou digitação); ao final, "Finalizar conferência" (apura faltantes/sobras); quando a grade que chegou diverge da grade enviada do Paraguai, "Corrigir e imprimir etiqueta" (escolhe a grade certa + um motivo obrigatório).

Fluxo correto:

Escolha o freteiro/remessa que chegou.
Bipe cada IMEI. Cada bipe válido move o aparelho de "em trânsito" para disponível/estoque em SP — e mostra a grade enviada (a que o PY declarou no despacho) pra o operador confirmar visualmente se bate.
Se a grade física não bater com a enviada, use "Corrigir e imprimir etiqueta": escolha a grade certa e um motivo da lista (ver Motivos de Regrade); a correção grava a grade nova, registra a divergência (alimenta o Placar de Grade) e já imprime a etiqueta nova sozinha na impressora térmica, sem precisar abrir outra aba.
No fim, "Finalizar conferência" recalcula no servidor (nunca confia na lista que o navegador acumulou) quem faltou e quem sobrou.

Se pular ou errar:

IMEI que não existe na empresa, ou que existe mas não pertence a essa remessa específica (não estava em trânsito por aquele freteiro) → vira sobra: só é sinalizado, nunca move o aparelho nem cadastra nada sozinho.
IMEI já vendido → bipe recusado (o sistema não mexe em aparelho vendido).
Bipar o mesmo IMEI duas vezes → aviso de "duplicado", sem duplicar o movimento.
Faltante (esperado mas nunca bipado) não some — o aparelho continua "em trânsito" pra sempre até alguém decidir (ex.: marcar perdido no painel de pendências). Se houver qualquer faltante ou sobra ao finalizar, um alerta interno avisa o dono automaticamente.
Desde 07/09, "Corrigir e imprimir etiqueta" recusa corrigir a grade de um aparelho que já está VENDIDO ou CANCELADO ("já saiu do fluxo") — a grade define o preço de tabela e descreve o que foi entregue; mudá-la depois da venda reescreveria, sem o item de venda saber, a característica de um aparelho que o cliente já levou. Aparelho DEVOLVIDO continua podendo ser corrigido normalmente — ele volta pra triagem e pode ser regradeado de verdade.

Detalhes e estados: o scanner de câmera desta tela é o mesmo componente da aba "Separar" — só uma câmera ativa por vez no navegador. "Remessa", tecnicamente, não é um registro isolado aqui: é o conjunto de movimentações que compartilham o mesmo freteiro e a mesma janela de despacho.

Logística PY→SP — Interno BR

Pra que serve: move aparelhos dentro do Brasil — do estoque de SP para a área de expedição e depois confirma a chegada no destino final. O status do aparelho não muda (segue disponível em SP) — só a localização física.

Quem usa: ADMIN, GERENTE, OPERADOR_SP, OPERADOR_PY (mesmos 4 da Logística).

Ações principais: listar elegíveis (disponíveis em SP, ainda não numa transferência interna ativa); despachar transferência com freteiro/custo opcional; bipar IMEI a IMEI na chegada (mudança de 06/09, ver abaixo); "Confirmar entrega" pra fechar a transferência depois que tudo foi bipado.

Fluxo correto:

Selecione os aparelhos, escolha o freteiro que atende o trecho interno no Brasil, despache. Isso move a localização para a área de expedição.
Quando chegarem fisicamente no destino, bipe o IMEI de cada aparelho da transferência — o mesmo padrão da Conferência SP (câmera ou digitação): cada bipe válido confere e move aquele aparelho, um por vez, para o estoque de SP.
Só depois de bipar tudo, clique em "Confirmar entrega" para fechar a transferência — esta ação não move mais nenhum aparelho, só confere que todo item não-perdido foi bipado e recalcula o status da transferência.

⚠️ Atenção: até 06/09, "Confirmar entrega" movia a remessa inteira pro estoque de SP sem checar um aparelho sequer (a query buscava exatamente os itens ainda não conferidos e movia todos). Um aparelho que sumisse no caminho entre a loja e o CD virava "chegou no estoque SP" no banco e nunca aparecia como faltante. Por isso a bipagem virou obrigatória: só o item realmente escaneado é que muda de local.

Se pular ou errar:

Como o status não muda neste trecho, existe uma guarda específica contra despacho duplo (um mesmo aparelho em duas transferências internas ativas ao mesmo tempo) — sem ela, o item viraria "fantasma" e poderia ser cancelado indevidamente depois via "marcar perdido".
IMEI que não pertence a essa transferência → vira sobra, só sinaliza, não move nada.
Bipar o mesmo IMEI duas vezes → aviso de "duplicado".
Item já baixado como perdido (pelo painel de faltantes) não volta a existir por bipagem — o scanner recusa, porque senão o aparelho reapareceria com localização de estoque SP depois de já ter sido dado como extraviado.
"Confirmar entrega" com algum item não-perdido ainda sem bipe → recusada, dizendo quantos aparelhos faltam bipar.

Detalhes e estados: só é contado como "entregue" o item cuja atualização realmente aconteceu no banco (a tela não finge sucesso se a permissão barrar em silêncio). O movimento pro estoque de SP acontece na bipagem, nunca mais na confirmação — a confirmação virou só o "fechar" da transferência.

Motivos de Regrade

Pra que serve: cadastro (criar, editar, ativar/desativar) da lista de motivos que aparece no menu de "Corrigir e imprimir etiqueta" da Conferência SP (ex.: "risco não visto na foto", "bateria divergente" etc. — o texto exato depende do que a operação cadastrar).

Quem usa: ADMIN, GERENTE. Tela sem entrada no menu, de propósito — só é alcançada pelo link discreto que aparece no cabeçalho da Logística pra quem é gestão, ou digitando o endereço direto (a permissão real é conferida no servidor, então acessar sem ser ADMIN/GERENTE simplesmente redireciona pra outra tela).

Ações principais: criar motivo (nome + ordem de exibição); editar nome/ordem; ativar/desativar (não existe apagar).

Fluxo correto: cadastre o motivo, defina a ordem se quiser controlar a posição no menu, e ative. Se um motivo deixou de fazer sentido, desative — ele some do menu mas o histórico de correções que já usaram aquele motivo continua íntegro.

Se pular ou errar: nome duplicado (por empresa) é recusado com mensagem amigável ("já existe um motivo com esse nome").

Detalhes e estados: não existe apagar — desativar é o único caminho, porque o histórico de correções de grade referencia o motivo, e apagar quebraria os dados usados no Placar de Grade.

Placar de Grade

Pra que serve: ferramenta de gestão de desempenho — cruza quantas grades cada gradeador do Paraguai enviou (um número congelado no momento do despacho, que não muda mesmo se o aparelho for reparado depois) contra quantas foram corrigidas na conferência de SP, e mostra a taxa de erro por pessoa.

Quem usa: ADMIN, GERENTE. OPERADOR_PY e OPERADOR_SP não veem o próprio placar — decisão deliberada, é ferramenta de avaliação, não de operação.

Ações principais: trocar o período de análise (7, 30 ou 90 dias).

Fluxo correto: escolha o período; a tabela mostra, por gradeador: quantas grades ele enviou, quantas divergiram na conferência, e a taxa (%). Taxa igual ou acima de 20% aparece em vermelho, igual ou acima de 10% em amarelo.

Se pular ou errar: nada — é leitura pura.

Detalhes e estados: o cálculo é feito processando linha por linha sobre até milhares de registros por período — por isso a tela busca os dados em partes pra não truncar o resultado num período de 90 dias com volume alto.

Pedido de logística (impressão)

Pra que serve: versão imprimível (Ctrl+P → Salvar como PDF) de um pedido de logística — usa exatamente os mesmos dados da tela de bipagem (aba "Separar").

Quem usa: ADMIN, GERENTE, OPERADOR_PY, FINANCEIRO.

Ações principais: só visualização/impressão — o botão "Imprimir" ainda não estava plugado na tela do pedido no momento em que este manual foi escrito; se ele não aparecer, use o endereço da impressão direto.

Fluxo correto: abra o pedido específico, confira modelo/capacidade/grade/ quantidade solicitada vs. separada, e a lista de IMEIs já bipados com quem bipou. Use Ctrl+P.

Se pular ou errar: perfil fora da lista de acesso vê "Sem permissão para ver este pedido" em vez do documento.

Detalhes e estados: o documento não mostra preço nem custo — só composição e progresso de separação.

Nota do freteiro (impressão)

Pra que serve: o documento (manifesto/romaneio — a relação oficial da carga) que o comprador entrega ou anexa para o transportador do trecho PY→BR, declarando o valor declarado da remessa (base pra seguro/alfândega) e a relação completa de aparelhos por modelo, capacidade, grade e cor.

Quem usa: ADMIN, GERENTE, OPERADOR_PY, OPERADOR_SP.

Ações principais: só visualização/impressão.

Fluxo correto: abra a nota da remessa despachada, confira o valor declarado e a lista de aparelhos, imprima e entregue ao freteiro.

Se pular ou errar: sem essa nota o freteiro não tem comprovante formal do valor declarado nem da lista transportada.

Detalhes e estados: por desenho, a nota nunca mostra custo real de compra, preço de venda, margem ou o rateio interno de frete — só o valor declarado (que pode ser diferente do custo real) e a identificação dos itens. Itens marcados como perdidos na remessa são excluídos da lista (não aparecem como se tivessem viajado).

Painel SP

Pra que serve: espelho do Painel PY, do lado de São Paulo — mesa de trabalho do operador local: conferir chegada → estocar → reservar → expedir.

Quem usa: ADMIN, GERENTE, OPERADOR_SP.

Ações principais: navegação por cartões; hospeda também o Motor de Comanda — quando esta tela fica aberta na estação da expedição, ela imprime sozinha (sem clique manual) o pedido na impressora térmica assim que uma venda fecha (o mesmo padrão de uma "comanda de cozinha").

Fluxo correto:

Cartões "Precisa de você agora": Chegaram em SP — conferir (leva pra Logística), A expedir (leva pra Expedição), Reservados — a faturar.
Cartões "Acompanhar": Estoque SP, A caminho de SP (leva pra Logística), Remessas em rota (leva pra Logística).

Se pular ou errar: nada — é roteador visual.

Detalhes e estados: a página se atualiza sozinha (auto-refresh) — pensada pra ficar aberta o dia inteiro numa tela fixa da bancada, não só como um link que se abre e fecha.

Fretes

Pra que serve: tela nova (07/09) que responde uma pergunta que a Logística não responde — quanto o serviço de frete faturou, e de quem. "Logística" segue respondendo "onde está a carga"; "Fretes" responde "quanto isso rendeu". Reúne, na mesma lista, todo pedido de logística que tem um serviço cobrado em cima — seja porque nasceu de uma venda em dólar (o cliente compra o aparelho e paga também pelo frete PY→SP), seja porque é um frete avulso (o cliente comprou a mercadoria em outro lugar e só contrata o transporte da KL).

Quem usa: aparece no menu (dentro de "Saída & Expedição", ao lado de Logística e Expedição) pra ADMIN, GERENTE e OPERADOR_SP. Criar um frete avulso, porém, reusa por baixo a mesma ação de criar pedido de logística — e essa ação só aceita ADMIN ou GERENTE; um OPERADOR_SP vê a lista e o total faturado, mas a tentativa de criar um frete novo é recusada no servidor.

Ações principais: ver a lista de fretes (número, cliente, origem — "venda" ou "avulso" —, valor da mercadoria em US$, percentual aplicado, valor do serviço) com o total faturado no topo; "+ Novo frete" pra lançar um frete avulso: escolher o cliente, o que vai (modelo/quantidade) e quanto vale a mercadoria em dólar — só isso, o percentual e o valor do serviço saem calculados sozinhos.

Fluxo correto:

Pra acompanhar o faturamento do serviço, basta abrir a tela — a lista já vem com os fretes mais recentes primeiro e o total somado no topo.
Pra lançar um frete avulso (mercadoria que não é da KL): clique "+ Novo frete", escolha o cliente, descreva o que vai e a quantidade, informe quanto vale a mercadoria em US$, e confirme.
Por baixo, isso cria um pedido de logística normal (origem "TERCEIRO"), que segue o mesmo fluxo de bipagem/despacho documentado nas seções de Logística acima — só que sem reservar estoque da KL (a mercadoria é do cliente, não do lojista) e sem vincular venda nenhuma.

Se pular ou errar: tentar criar um frete sem escolher cliente, sem descrever o item ou sem informar o valor da mercadoria é bloqueado pelo próprio formulário (botão desabilitado) — não chega a errar no servidor.

Detalhes e estados:

O percentual do serviço é resolvido assim: percentual do cliente (se cadastrado) ou percentual padrão da loja ou 8% — nessa ordem. Uma vez que o pedido/frete é criado, esse percentual fica congelado nele — editar o cadastro do cliente depois não muda o frete que já foi cobrado, pelo mesmo motivo pelo qual este sistema não recalcula câmbio de lote já fechado (ver Compras & Lotes).
O banco re-deriva o valor do serviço (mercadoria × percentual) e recusa gravar um número que não bate com a conta — trava contra valor forjado, mesmo por quem chama a API direto.
Pedido de logística interno (mover estoque próprio, sem cobrar ninguém) continua nascendo do jeito de sempre — sem valor de mercadoria, sem percentual, sem aparecer nesta tela.

Expedição

Pra que serve: o "último quilômetro" — depois que a venda já existe, esta tela cuida do pacote daquela venda desde a separação física até a entrega/retirada pelo cliente. Pode abrir já filtrada (a separar, atrasados, ou em rota) quando vem de um atalho da tela principal.

Quem usa: aparece no menu de ADMIN, GERENTE, VENDEDOR, OPERADOR_SP, OPERADOR_PY — mas operar de fato (separar/embalar/despachar/cancelar) é só de ADMIN, GERENTE, OPERADOR_SP e OPERADOR_PY (este último só enxerga os pacotes da venda em dólar, que é operação do Paraguai). O VENDEDOR vê a tela (acompanha as próprias vendas), mas qualquer botão de operação é recusado pelo sistema — é uma questão de clareza na tela, não uma falha de segurança. Registrar peso/foto manual na balança (a via de escape quando o celular/QR falha) é ADMIN/GERENTE apenas.

Ações principais:

Bipar IMEI pra separar um item do pacote (anti-erro: só aceita o IMEI do aparelho realmente vendido naquele item).
Avançar status (embalar → aguardar despacho → despachar/coletar → em transporte/saiu pra entrega → entregue/retirado), conforme o modal de entrega escolhido na venda (retirada balcão, motoboy, transportadora, sedex, ônibus, outro).
Registrar falha de entrega / Cancelar pacote (desvios, disponíveis a qualquer momento antes do estado final).
Registrar balança manual (foto + peso pelo desktop, quando o QR/celular da bancada falha).

Fluxo correto:

O pacote nasce aguardando separação. Bipe cada IMEI do pedido — se todos os itens já têm o aparelho atribuído (venda por IMEI), o bipe só confirma; se algum item foi vendido por grade/MIX (sem IMEI fixo, resolvido nas Vendas), o próprio bipe da Expedição atribui o aparelho físico àquele item na hora, respeitando a composição da grade vendida (nunca entrega um aparelho fora da grade combinada).
Quando o último item é separado, o pacote vira "separado" automaticamente.
Avance pra "embalado".
Ao chegar em "aguardando despacho", o ritual da balança entra em cena: é preciso foto do pacote na balança e peso registrado (normalmente feito por QR/celular na bancada) antes de conseguir avançar por "despachar/coletar". Cancelar ou registrar falha não exige balança — só o avanço normal exige. Só ADMIN/GERENTE têm o atalho manual (foto+peso pelo desktop); qualquer outro perfil precisa do fluxo mobile/QR normal, não existe outro jeito de pular essa etapa.
Siga o fluxo do modal escolhido até o status final (entregue/retirado).
Se a entrega falhar, é possível reentregar (volta pro passo de saída/coleta) — única exceção à regra de "nunca voltar atrás" no fluxo.

Se pular ou errar:

Bipar um IMEI que não pertence a nenhum item deste pacote → recusado.
Tentar avançar pra despacho sem foto+peso na balança → bloqueado com mensagem específica (só foto, só peso, ou nenhum dos dois).
Tentar avançar um status fora da sequência válida do modal escolhido → "Transição inválida".
Toda mudança de status é protegida contra dois cliques simultâneos ou duas abas abertas ao mesmo tempo — se o pacote mudou de status entre a leitura e a escrita, a ação é recusada pedindo pra recarregar, em vez de aplicar em cima de um estado que já não existe mais.

Detalhes e estados: status possíveis incluem aguardando separação, em separação, separado, em embalagem, embalado, aguardando despacho, depois um dos três ramos por modal (retirada balcão / motoboy / transportadora), até entregue/retirado/devolvido/cancelado/extraviado/entrega falhou. O QR gerado em "aguardando despacho" (usado pela página mobile de balança) é anulado automaticamente sempre que o pacote sai desse status — por avanço ou por desvio — pra o link parar de valer. As mensagens ao cliente via WhatsApp disparam nos pontos-chave (saiu para entrega/coletado, entregue/retirado), em modo best-effort (o sistema tenta enviar, mas uma falha no envio não trava o fluxo).

Lista de separação do pacote (impressão)

Pra que serve: versão imprimível de um pacote específico da Expedição — planilha de conferência física pra quem está separando na bancada em SP, com checkbox em branco por item.

Quem usa: a tela usa as mesmas permissões de acesso ao banco da tela principal de Expedição — sem gate de perfil extra próprio nesta página, herda o acesso de quem já pode ver aquele pacote.

Ações principais: só visualização/impressão (Ctrl+P → Salvar como PDF).

Fluxo correto: abra a URL do pacote, confira cliente/transporte/previsão de entrega/endereço no cabeçalho, e a lista de IMEI/modelo/memória/cor por item; imprima e leve pra bancada.

Se pular ou errar: pacote inexistente ou fora de escopo devolve mensagem de erro em vez do documento.

Detalhes e estados: documento não mostra preço nem dado financeiro — o separador não precisa disso e uma trava no banco já bloqueia esse acesso a quem só separa. Itens com bateria abaixo de 80% ganham um aviso visual (🔋<80%) direto na coluna de memória.

Erros comuns e como evitar

Liberar aparelho sem grade na Separação. É a causa raiz mais cara já medida neste módulo (incidentes de 131 e 192 aparelhos, ~R$375 mil em estoque "invisível"). A trava já existe (não deixa liberar sem grade nem pré-grade) — o erro só volta a acontecer se alguém tentar contornar a tela por fora, ou se um aparelho antigo escapou antes da trava existir.
Confundir a aba "Separar" da Logística com a tela Separação. São coisas diferentes: uma decide o destino do aparelho recém-triado; a outra bipa o IMEI físico contra um pedido já aprovado.
Despachar "Direto pro SP" um aparelho que já está reservado num pedido do comprador. A lista de elegíveis já filtra isso, mas se dois operadores estiverem trabalhando ao mesmo tempo, o despacho revalida no servidor e recusa listando o motivo — não é silencioso.
Fechar o volume errado ou esquecer de reabrir pra corrigir. Uma vez fechado, o volume só aceita despacho — reabra antes de mexer na composição, e lembre que despachar consome as reservas de verdade (não dá pra "desfazer" um despacho já feito, só marcar item como perdido se ele nunca chegar).
Confirmar divergência de valor declarado sem checar o motivo. O gate de 15% existe justamente pra frear subdeclaração acidental (ou intencional) do valor de transporte — confirmar sem olhar o percentual mostrado na tela anula o propósito do aviso.
Deixar o "Corrigir grade" na mão do OPERADOR_PY. O sistema já impede isso (só ADMIN/GERENTE/OPERADOR_SP corrigem), porque senão o Placar de Grade perderia sentido — quem erra não pode ser quem corrige a própria nota.
Marcar "perdido" um item que na verdade já chegou por outro caminho. A tela recusa se o aparelho não estiver mais "em trânsito" pro trecho daquela remessa — isso normalmente é sinal de remessa duplicada, não de sinistro real; investigue no inventário antes de insistir.
Tentar avançar o pacote da Expedição pra despacho sem o ritual da balança. Só ADMIN/GERENTE têm o atalho manual (foto+peso pelo desktop); qualquer outro perfil precisa do fluxo mobile/QR normal — não existe outro jeito de pular essa etapa.
Criar um pedido de logística com freteiro sem taxa PY→BR cadastrada. Desde 07/09 isso é bloqueado na criação, e não por acaso: um freteiro sem taxa gerava remessa com frete zero em silêncio (1.918 aparelhos, R$ 293.255,56 sem frete no custo). Cadastre a taxa em Cadastros → Freteiros antes de usá-lo num pedido.
Confirmar entrega de transferência interna BR sem bipar os aparelhos antes. Até 06/09 "Confirmar entrega" movia a remessa inteira sem checar nada — hoje o botão recusa enquanto sobrar item sem bipe. Bipe primeiro, confirme depois.