> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bulkroute.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia do Painel Admin

> Mapa completo dos módulos do painel do BulkRoute — o que faz cada um e quando usar.

O painel admin do BulkRoute é organizado em **8 seções** no menu lateral. Este guia explica o que cada módulo faz e quando você deve usá-lo.

## Visão

Módulos de acompanhamento geral da operação.

### Dashboard

**Rota:** `/admin/dashboard`

Visão geral do dia com KPIs em tempo real:

* Envios pendentes, em trânsito e entregues
* Cotações do dia (total e conversão)
* Faturamento estimado do mês
* Alertas de SLA e ocorrências

**Quando usar:** No início do dia, para ter um panorama da operação antes de mergulhar nos detalhes.

### Pipeline

**Rota:** `/admin/pipeline`

Quadro Kanban com todos os envios arrastáveis entre colunas (PENDING → DISPATCHED → IN\_TRANSIT → OUT\_FOR\_DELIVERY → DELIVERED). Cada card mostra tracking code, carrier, destinatário e prazo.

**Quando usar:** Quando precisa visualizar e mover envios manualmente entre status, ou filtrar por carrier/tenant/data.

***

## Pedidos

Gestão dos envios que saem do seu armazém.

### Envios (Shipments)

**Rota:** `/admin/shipments`

Tabela com todos os envios. Filtros por status, carrier, data, tenant. Cada linha abre o detalhe completo:

* Timeline de eventos de tracking
* Dados do destinatário e endereço
* Pacotes e dimensões
* Etiqueta e documentos
* Impostos e valores

**Quando usar:** Para buscar um envio específico, verificar status, cancelar, ou reimprimir etiqueta.

### Logística Reversa

**Rota:** `/admin/reverse-logistics`

Solicitações de devolução. Crie e acompanhe devoluções de produtos que precisam voltar ao armazém (troca, garantia, recall).

**Quando usar:** Quando um cliente precisa devolver um produto.

***

## Orquestra

O coração do BulkRoute — onde o frete é decidido.

### Cotações

**Rota:** `/admin/quotes`

Tabela com o histórico de cotações. Cada cotação mostra as opções retornadas pelos carriers, com preço, prazo e score. Você pode ver qual carrier foi escolhido e por quê.

**Quando usar:** Para auditar uma cotação, entender por que um carrier foi escolhido, ou ver o histórico de preços de uma rota.

### Orquestração

**Rota:** `/admin/orchestration`

Configuração do motor de decisão. Define:

* **Score mínimo** para auto-aprovação de carriers
* **Pesos** do algoritmo (preço vs prazo vs score)
* **Regras de rejeição** automática (carriers bloqueados por região, tipo de carga, etc.)
* **Bid automático** — quando o melhor carrier rejeita, o sistema cria um bid automaticamente

**Quando usar:** Quando quer ajustar como o BulkRoute escolhe a melhor transportadora para cada envio.

### Regras de Envio

**Rota:** `/admin/shipping-rules`

Editor visual de regras condicionais (flowchart). Crie regras como:

* "Se CEP de destino começa com 8 (Sul) e peso > 50kg, usar apenas Braspress"
* "Se valor da carga > R\$ 5.000, exigir seguro"
* "Se cliente é VIP, priorizar Jadlog Com"

**Quando usar:** Quando tem regras de negócio que o orquestrador padrão não cobre.

***

## Campo

Operações de frota própria e motoristas.

### Despacho Frota

**Rota:** `/admin/dispatch`

Painel de despacho para frota própria. Acompanhe:

* Motoristas disponíveis e em rota
* Check-in/check-out de envios
* Status da jornada de cada motorista
* Pacotes escaneados vs pendentes

**Quando usar:** Quando usa frota própria e precisa gerenciar o dia a dia dos motoristas.

### Roteirização (VRP)

**Rota:** `/admin/route-optimization`

Otimização de rotas com múltiplas paradas. O sistema calcula a melhor sequência de entregas considerando:

* Distância total (OSRM)
* Janelas de horário
* Capacidade do veículo
* Prioridade de paradas

**Quando usar:** Quando tem múltiplos envios para a mesma rota e quer minimizar km rodado.

### Chat

**Rota:** `/admin/chat`

Comunicação direta entre admin e motoristas via PWA. Mensagens em tempo real com notificação push.

**Quando usar:** Quando precisa falar com um motorista específico durante a rota.

### Tracking Live

**Rota:** `/admin/tracking-live`

Mapa em tempo real com a posição de todos os motoristas da frota (GPS do PWA). Mostra:

* Posição atual de cada veículo
* Status do envio em andamento
* ETA calculado

**Quando usar:** Quando quer saber onde está cada motorista em tempo real.

### Motoristas

**Rota:** `/admin/drivers`

Cadastro de motoristas. Cada motorista tem:

* Dados pessoais (CPF, telefone, CNH)
* Veículo associado
* Status (disponível, em rota, offline)
* Histórico de entregas

**Quando usar:** Para cadastrar, editar ou desativar motoristas.

### Frota (Veículos)

**Rota:** `/admin/fleet`

Cadastro de veículos da frota própria. Cada veículo tem:

* Placa, modelo, ano
* Capacidade (peso e volume)
* Tipo (caminhonete, baú, toco, carreta)
* Status (ativo, manutenção, inativo)

**Quando usar:** Para cadastrar e gerenciar os veículos da sua frota.

### CDs (Centros de Distribuição)

**Rota:** `/admin/distribution-centers`

Cadastro de armazéns/CDs. Necessário para cotação multi-CD e para definir a origem dos envios.

**Quando usar:** Quando tem múltiplos armazéns e quer cotar a partir do mais próximo do destino.

### Cotação Multi-CD

**Rota:** `/admin/multi-warehouse`

Cotação simultânea de todos os CDs ativos. O sistema retorna a melhor opção considerando:

* Frete do CD ao destino
* Distância (km)
* Prazo total
* Score do carrier

**Quando usar:** Quando tem estoque em múltiplos CDs e quer despachar do mais eficiente.

***

## Parceiros

Gestão de transportadoras e clientes.

### Transportadoras

**Rota:** `/admin/carriers`

Lista de todas as transportadoras conectadas. Para cada uma:

* Status (ativa/inativa)
* Credenciais configuradas
* Tipo de conexão (API, planilha, frota própria)
* Configurações (markup, serviços ativos)

**Quando usar:** Para ativar/desativar transportadoras, configurar credenciais, ou ajustar markup.

### Scorecard

**Rota:** `/admin/carriers/scorecards`

Ranking de performance das transportadoras com métricas:

* On-time delivery (%)
* Taxa de avaria
* Taxa de extravio
* Tempo médio de trânsito
* POD rate (proof of delivery)
* Score consolidado (0-100)

**Quando usar:** Para decidir quais carriers manter ativos e quais negociar melhor.

### Clientes (Tenants)

**Rota:** `/admin/tenants`

Lista de todos os tenants (clientes) da plataforma. Cada tenant tem:

* Plano e faturamento
* Transportadoras ativadas
* Usuários e permissões
* Configurações de SSO, branding, webhooks

**Quando usar:** Para gerenciar clientes (apenas admin BulkRoute).

### Minha Empresa

**Rota:** `/admin/my-tenant`

Configurações do seu próprio tenant. Equivalente ao detalhe do tenant, mas sem precisar ser admin BulkRoute.

**Quando usar:** Para gerenciar chaves de API, webhooks, branding e transportadoras do seu tenant.

### Contratos

**Rota:** `/admin/contracts`

Cadastro de contratos de frete com transportadoras. Cada contrato define:

* Tabela de preços (ou percentual sobre tabela pública)
* Prazos acordados
* Vigência (início/fim)
* Condições especiais (coleta, etiqueta, rastreio)

**Quando usar:** Para registrar negociações fechadas com transportadoras.

***

## Integrações

Conexões com ERPs e marketplaces.

### Integrações

**Rota:** `/admin/integrations`

Lista de integrações ativas. Submenu com:

* **Bling** — importação de pedidos como envios
* **Mercado Livre** — importação de vendas
* **Shopify** — app nativo da Shopify App Store
* **Tiny** — importação de pedidos
* **Omie** — importação de pedidos

Cada integração mostra status da última sincronização, logs e configurações.

**Quando usar:** Para conectar seu ERP/e-commerce ao BulkRoute e importar pedidos automaticamente.

***

## Financeiro

Tudo que envolve custo e auditoria de frete.

### Faturas

**Rota:** `/admin/invoices`

Faturas geradas pelo BulkRoute (mensalidade + excedente) e faturas de frete por carrier. Filtros por tenant, carrier, status e período.

**Quando usar:** Para acompanhar e pagar faturas, ou conciliar com o que o carrier cobrou.

### Custo por Rota

**Rota:** `/admin/route-costs`

Análise de custo por rota (origem → destino). Mostra o custo médio, mínimo e máximo por carrier, permitindo identificar rotas caras.

**Quando usar:** Para otimizar custos identificando rotas onde você está pagando mais do que deveria.

### Economia (ROI)

**Rota:** `/admin/roi`

Dashboard de retorno sobre investimento. Mostra quanto o BulkRoute economizou para você:

* Economia por carrier (comparação com cotação mais cara)
* Economia por mês
* Economia acumulada
* ROI percentual

**Quando usar:** Para justificar o custo do BulkRoute para a diretoria.

### Auditoria CT-e

**Rota:** `/admin/freight-audit`

Auditoria de Conhecimentos de Transporte Eletrônicos (CT-e). O sistema:

* Importa CT-e (XML ou Excel)
* Compara o valor cobrado com o valor cotado
* Identifica divergências (cobrança indevida, peso errado, taxa extra)
* Permite aprovar, rejeitar ou disputar divergências

**Quando usar:** Para garantir que as transportadoras estão cobrando o que foi cotado.

### Seguro de Frete

**Rota:** `/admin/insurance`

Gestão de apólices de seguro de carga. Cote e contrate seguro para envios de alto valor.

**Quando usar:** Quando envia produtos de alto valor e precisa de cobertura de seguro.

### EDI

**Rota:** `/admin/edi`

Intercâmbio Eletrônico de Dados com transportadoras que usam EDI (NFe, CT-e, Ocorrências). Upload e download de arquivos EDI.

**Quando usar:** Quando a transportadora exige troca de dados via EDI em vez de API.

### Relatórios

**Rota:** `/admin/reports`

Exportação de relatórios em Excel/CSV:

* Envios por período
* Cotações por período
* Custos por carrier
* Performance por motorista
* Auditoria CT-e

**Quando usar:** Quando precisa extrair dados para análise externa ou prestação de contas.

***

## Sistema

Configurações avançadas da plataforma.

### Equipe

**Rota:** `/admin/team`

Gestão de usuários do painel. Convide membros da equipe com roles:

* **Admin** — acesso total
* **Manager** — operação + configurações, sem gestão de tenants
* **Viewer** — somente leitura

**Quando usar:** Para adicionar, remover ou alterar permissões de usuários.

### Notificações

**Rota:** `/admin/notifications`

Log de todas as notificações enviadas (WhatsApp, SMS, e-mail). Veja o status de cada envio (entregue, lido, falhou).

**Quando usar:** Para auditar se os clientes estão recebendo as notificações de rastreio.

### ML Rate Shopping

**Rota:** `/admin/ml-rate-shopping`

Predições de machine learning para carriers:

* Risco de atraso (0-100%)
* Risco de avaria
* Custo predito
* Prazo predito

O sistema usa histórico de performance para prever o comportamento de cada carrier em cada rota.

**Quando usar:** Quando quer ir além do scorecard e usar predição para escolher carriers.

### Pegada de Carbono

**Rota:** `/admin/carbon`

Cálculo de emissões de CO₂ por envio. Mostra:

* CO₂ total por mês
* CO₂ por carrier
* Comparação entre carriers (qual emite menos)
* Certificado de carbono compensado

**Quando usar:** Para relatórios de ESG ou para escolher carriers mais sustentáveis.

### Configurações

**Rota:** `/admin/settings`

Configurações gerais do tenant:

* Dados da empresa (CNPJ, endereço, logo)
* Preferências de idioma e moeda
* Integrações de pagamento (Asaas)
* SSO corporativo (SAML 2.0)
* Branding (customização do tracking page)

**Quando usar:** Para configurar a identidade e integrações do seu tenant.

***

## Resumo rápido

| Seção           | O que faz                                         |
| :-------------- | :------------------------------------------------ |
| **Visão**       | Panorama geral (Dashboard, Pipeline)              |
| **Pedidos**     | Gestão de envios e devoluções                     |
| **Orquestra**   | Cotação, decisão e regras de frete                |
| **Campo**       | Frota, motoristas, roteirização e tracking live   |
| **Parceiros**   | Transportadoras, clientes e contratos             |
| **Integrações** | ERPs e marketplaces conectados                    |
| **Financeiro**  | Faturas, auditoria CT-e, ROI, seguro, EDI         |
| **Sistema**     | Equipe, notificações, ML, carbono e configurações |