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

# Importação de Tabelas em Planilha

> Utilize tabelas de frete em CSV/Excel para transportadoras sem integração via API.

Para transportadoras regionais ou parceiros locais que não possuem API, o BulkRoute suporta o carregamento de tabelas de frete em planilha. Isso permite cotar com qualquer transportadora, mesmo sem integração técnica.

## Quando usar

| Cenário                                              | Recomendado        |
| :--------------------------------------------------- | :----------------- |
| Transportadora regional sem API                      | ✅ Planilha         |
| Transportadora com API mas sem webservice de cotação | ✅ Planilha         |
| Negociação especial (tabela customizada)             | ✅ Planilha         |
| Transportadora com API ativa                         | ❌ Use a API direta |

## Modelo de Planilha Suportado

Você pode fazer o download do modelo padrão diretamente no painel ou preparar seu arquivo `.csv` ou `.xlsx` com a seguinte estrutura:

| cep\_origem\_inicio | cep\_origem\_fim | cep\_destino\_inicio | cep\_destino\_fim | peso\_max\_kg | valor\_frete | prazo\_dias | ad\_valorem\_pct |
| :------------------ | :--------------- | :------------------- | :---------------- | :------------ | :----------- | :---------- | :--------------- |
| 01000000            | 09999999         | 80000000             | 82999999          | 30.0          | 45.90        | 3           | 0.30             |
| 01000000            | 09999999         | 80000000             | 82999999          | 100.0         | 110.00       | 3           | 0.30             |
| 01000000            | 09999999         | 80000000             | 82999999          | 500.0         | 280.00       | 4           | 0.30             |
| 01000000            | 09999999         | 83000000             | 89999999          | 30.0          | 65.00        | 4           | 0.30             |

### Campos

| Campo                | Tipo               | Descrição                                    |
| :------------------- | :----------------- | :------------------------------------------- |
| `cep_origem_inicio`  | string (8 dígitos) | CEP inicial da faixa de origem               |
| `cep_origem_fim`     | string (8 dígitos) | CEP final da faixa de origem                 |
| `cep_destino_inicio` | string (8 dígitos) | CEP inicial da faixa de destino              |
| `cep_destino_fim`    | string (8 dígitos) | CEP final da faixa de destino                |
| `peso_max_kg`        | decimal            | Peso máximo cobrado nesta faixa              |
| `valor_frete`        | decimal            | Valor do frete em BRL                        |
| `prazo_dias`         | integer            | Prazo de entrega em dias úteis               |
| `ad_valorem_pct`     | decimal            | Percentual de ad-valorem (seguro) — opcional |

### Lógica de matching

Quando uma cotação chega, o BulkRoute busca a linha que:

1. CEP de origem está dentro da faixa `cep_origem_inicio` → `cep_origem_fim`
2. CEP de destino está dentro da faixa `cep_destino_inicio` → `cep_destino_fim`
3. Peso total ≤ `peso_max_kg` (usa a linha com menor `peso_max_kg` que atenda)

Se não encontrar nenhuma linha, a planilha é descartada da cotação.

## Como Importar

1. Acesse **Transportadoras** > **Tabelas Offline / Planilhas**.
2. Clique em **Nova Tabela**.
3. Dê um nome de identificação (ex: *TransRegional - Tabela Sul 2026*).
4. Arraste seu arquivo CSV ou Excel.
5. O sistema validará a consistência de:
   * Faixas de CEP (sem sobreposição inválida)
   * Pesos (crescentes dentro da mesma faixa)
   * Campos obrigatórios preenchidos
6. Clique em **Salvar e Publicar**.

A partir desse momento, as cotações para as faixas de CEP contempladas incluirão essa opção automaticamente.

## Múltiplas Tabelas

Você pode ter múltiplas tabelas ativas simultaneamente:

* **TransRegional - Sul** → CEPs 80000-82999
* **TransRegional - Sudeste** → CEPs 00000-19999
* **Transportadora X - Nacional** → Todos os CEPs

O BulkRoute consulta todas as tabelas ativas e retorna a melhor opção para cada faixa.

## Atualização de Tabela

Quando a transportadora atualiza a tabela contratual:

1. Importe a nova planilha com o mesmo nome (ou um novo nome)
2. Se mesmo nome: o BulkRoute **substitui** a tabela anterior
3. Se novo nome: ambas ficam ativas (você pode desativar a antiga depois)

<Tip>
  Mantenha um padrão de nomenclatura com ano/semestre: `TransRegional-Sul-2026H2`. Isso facilita saber qual tabela está vigente.
</Tip>

## Limitações

<Warning>
  Planilhas offline **não suportam**:

  * **Emissão de etiqueta** — não há API para gerar etiqueta. Use a etiqueta genérica do BulkRoute (PDF 100×150mm com Code-128).
  * **Solicitação de coleta** — você precisa agendar a coleta diretamente com a transportadora.
  * **Rastreamento automático** — sem API, o BulkRoute não consegue fazer polling. O status precisa ser atualizado manualmente ou via webhook outbound do seu ERP.
  * **Cancelamento automático** — você precisa cancelar diretamente com a transportadora.
</Warning>

## Rastreamento manual

Para shipments despachados via planilha offline:

1. Quando a transportadora atualizar o status, atualize manualmente no painel
2. Ou configure um webhook do seu ERP para atualizar via API: `PATCH /shipments/{id}/status`
3. O cliente final recebe as notificações normalmente

## Troubleshooting

| Problema                       | Causa                      | Solução                                             |
| :----------------------------- | :------------------------- | :-------------------------------------------------- |
| Cotação não retorna a planilha | CEP fora da faixa          | Verificar faixas de CEP na planilha                 |
| `Validation Error` no upload   | Faixas sobrepostas         | Corrigir sobreposição no CSV                        |
| Peso não encontrado            | Peso acima do máximo       | Adicionar linha com peso maior                      |
| Valor errado                   | Linha com peso\_max errado | Verificar se a linha correta está sendo selecionada |