> ## 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.

# Arquitetura & Como Funciona

> Entenda como o BulkRoute orquestra chamadas, calcula cubagens complexas e gerencia eventos de rastreio.

O BulkRoute atua como uma camada de inteligência e roteamento logístico entre os seus canais de venda (E-commerce, ERPs, WMS) e os operadores físicos de entrega (Transportadoras Fracionadas, Lotação e Frota Própria).

```mermaid theme={null}
flowchart TD
    ERP[Seu ERP / E-commerce] -->|API / Webhook| BR[BulkRoute Orquestrador]
    BR --> Engine[Motor de Regras & Cubagem]
    
    Engine --> T1[Braspress / SSW / Jadlog]
    Engine --> T2[Frota Própria / PWA Driver]
    Engine --> T3[Tabelas Offline / Planilhas]
    
    T1 --> Tracking[Tracking Normalizer]
    T2 --> Tracking
    T3 --> Tracking
    
    Tracking -->|Webhook Outbound| ERP
    Tracking --> Branded[Página de Rastreio com sua Marca]
```

## Os 3 Pilares do Orquestrador

### 1. Cubagem e Fator de Peso Real

Para cargas volumosas (sofás, móveis, ferragens, maquinários), a maioria dos fretes é cobrada pelo **peso cubado** ($C \times L \times A \div 6000$ ou $5000$).
O BulkRoute compara dinamicamente o fator de cubagem contratado em cada transportadora contra o peso real da mercadoria, garantindo que você nunca pague taxas excedentes inesperadas.

### 2. Normalização de Status de Rastreio

Cada transportadora tem seu próprio vocabulário de eventos (ex: "Entrada em CD", "Manifesto gerado", "Em rota de entrega", "M2").
O BulkRoute traduz todos os eventos para uma linha do tempo única e previsível:

* `PENDING`: Aguardando processamento inicial.
* `PROCESSING`: Envio criado, aguardando coleta.
* `PICKED_UP`: Carga coletada na sua expedição.
* `IN_TRANSIT`: Em transferência entre filiais/centros de distribuição.
* `OUT_FOR_DELIVERY`: Em rota final de entrega ao destinatário.
* `DELIVERED`: Entrega finalizada com sucesso.
* `EXCEPTION`: Ocorrência ou tentativa frustrada com motivo detalhado.

### 3. Orquestração Multi-Tenant

Cada cliente do BulkRoute opera em ambiente isolado com suas próprias credenciais, regras de margem de lucro (*markup*), transportadoras ativas e motoristas.