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

# Cotações & Regras de Decisão

> Como funcionam as cotações, regras de despacho e margens de frete.

O módulo de cotações do BulkRoute permite simulações pontuais no painel ou milhares de cotações por minuto via API integrada ao seu checkout de e-commerce.

## Como o BulkRoute escolhe a melhor transportadora

Ao solicitar uma cotação, os seguintes filtros são aplicados em sequência:

```mermaid theme={null}
graph TD
    A[Cotação Solicitada] --> B{Faixa de CEP Atendida?}
    B -- Não --> X[Descartada]
    B -- Sim --> C{Dimensões e Peso Suportados?}
    C -- Não --> X
    C -- Sim --> D{Restrições do Produto ou Veículo?}
    D -- Bloqueado --> X
    D -- Permitido --> E[Cálculo de Preço & Prazo com Cubagem]
    E --> F[Ordenação: Menor Custo ou Menor Prazo]
```

## Regras de Cubagem Customizadas

Você pode definir se a sua empresa deseja repassar o fator de cubagem integralmente ao cliente final ou se prefere aplicar um fator bonificado para aumentar a conversão do checkout.

### Como funciona o peso cubado

Para cargas volumosas (móveis, autopeças, eletrodomésticos), a transportadora cobra pelo **maior valor** entre:

* **Peso real**: o peso bruto da mercadoria na balança
* **Peso cubado**: calculado pela fórmula `(C × L × A) ÷ fator`

O fator varia por transportadora:

| Transportadora   | Fator de Cubagem |
| :--------------- | :--------------- |
| Braspress        | 300 (rodoviário) |
| Jadlog           | 300              |
| SSW              | 300              |
| Correios (PAC)   | 6000 (cm³)       |
| Correios (SEDEX) | 6000 (cm³)       |

### Exemplo prático

Um sofá de 3 lugares com 40 kg reais e dimensões 200×90×85 cm:

* **Peso real**: 40 kg
* **Peso cubado** (fator 300): `(200 × 90 × 85) ÷ 300 = 5.100 kg` → inviável
* **Peso cubado** (fator 6000): `(200 × 90 × 85) ÷ 6000 = 255 kg`

A transportadora cobra pelo **maior** — neste caso, o peso cubado. O BulkRoute calcula isso automaticamente para cada carrier e mostra o preço real que você vai pagar.

## Regras de Envio (Shipping Rules)

Além da cubagem, você pode criar **regras condicionais** que alteram o comportamento da cotação:

### Tipos de condição

| Campo        | Operadores                    | Exemplo                                    |
| :----------- | :---------------------------- | :----------------------------------------- |
| `peso`       | maior\_que, menor\_que, igual | "Se peso > 30kg → aplicar surcharge"       |
| `valor`      | maior\_que, menor\_que, igual | "Se valor > R\$ 500 → exigir seguro"       |
| `cep`        | contem                        | "Se CEP começa com 0 → bloquear carrier X" |
| `regiao`     | igual                         | "Se região = Sul → usar apenas SSW"        |
| `quantidade` | maior\_que, menor\_que        | "Se > 5 volumes → dividir em 2 shipments"  |

### Ações disponíveis

* **Surcharge**: adiciona um valor fixo ao frete (ex: +R\$ 15 para frágil)
* **Bloquear carriers**: impede carriers específicos de cotarem
* **Preço mínimo/máximo**: limita a faixa de preço aceitável
* **Prazo máximo**: descarta carriers que não entregam no prazo

### Como criar uma regra

1. Vá em **Configurações da Empresa** > **Regras & Orquestração**
2. Clique em **Nova Regra**
3. Defina a **condição** (ex: peso > 30kg)
4. Defina a **ação** (ex: surcharge R\$ 20)
5. Defina a **ordem de execução** (regras menores executam primeiro)
6. Salve e ative

## Orquestrador Visual (Flow Builder)

Clientes Enterprise podem criar fluxos visuais de decisão no estilo "no-code":

1. Acesse **Orquestração** > **Flow Builder**
2. Arraste nós de condição (CEP, peso, valor, região)
3. Conecte a nós de ação (escolher carrier, aplicar regra, rejeitar)
4. Publique o fluxo — ele passa a ser aplicado em todas as cotações

O orquestrador também gera um **log de raciocínio** linha a linha, explicando por que cada carrier foi aceito ou rejeitado em cada cotação.

## Cotação via API

Para integrar cotações no seu checkout:

```bash theme={null}
curl -X POST "https://api.bulkroute.com.br/api/quotes" \
  -H "X-API-Key: bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destinationZip": "01310100",
    "originZip": "80000000",
    "items": [
      {
        "weight": 40,
        "length": 200,
        "width": 90,
        "height": 85,
        "value": 2500,
        "quantity": 1
      }
    ]
  }'
```

A resposta retorna todos os carriers elegíveis com preço, prazo e score de qualidade ordenados pelo melhor custo-benefício.

<Tip>
  Use o endpoint `POST /orchestrator/evaluate` para receber também o log de raciocínio e a decisão recomendada (auto/humano/rejeitado) — ideal para auditoria e transparência.
</Tip>