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

# Conectando o Bling (ERP)

> Importe pedidos do Bling automaticamente e sincronize o tracking de volta.

O [Bling](https://www.bling.com.br) é um dos ERPs mais usados por e-commerces brasileiros. A integração com o BulkRoute importa pedidos pagos como shipments e devolve o tracking code para o Bling.

## Como funciona

```
Bling (OAuth 2.0) → BulkRoute importa pedidos → cria shipments
BulkRoute atualiza tracking → Bling recebe o tracking code
```

## Conectando

### 1. Autorizar OAuth

1. Acesse **Integrações** > **Bling**
2. Clique em **Conectar Bling**
3. Você será redirecionado para o Bling — faça login e autorize
4. O Bling retorna para o BulkRoute com o token de acesso

### 2. Mapear carriers

O Bling usa nomes de transportadoras (ex: "Braspress", "Correios"). O BulkRoute usa códigos (ex: `BRASPRESS`, `CORREIOS`). Você precisa mapear:

| Carrier no Bling | Carrier no BulkRoute |
| :--------------- | :------------------- |
| Braspress        | `BRASPRESS`          |
| Correios         | `CORREIOS`           |
| Jadlog           | `JADLOG`             |
| (outro)          | `BLING` (fallback)   |

1. Acesse **Integrações** > **Bling** > **Mapeamento**
2. Para cada carrier do Bling, selecione o carrier correspondente no BulkRoute
3. Salve

### 3. Ativar sincronização

1. Em **Integrações** > **Bling**, ative **Sincronização automática**
2. Defina o intervalo (padrão: 30 minutos)
3. Salve

A partir desse momento:

* Pedidos pagos no Bling aparecem no BulkRoute em até 30 minutos
* Tracking codes gerados no BulkRoute são enviados de volta ao Bling

## O que é importado

Para cada pedido pago no Bling, o BulkRoute cria um shipment com:

| Campo do Bling                               | Campo no BulkRoute   |
| :------------------------------------------- | :------------------- |
| `numero`                                     | `external_order_id`  |
| `contato.nome`                               | `recipient.name`     |
| `contato.fone`                               | `recipient.phone`    |
| `transporte.cep`                             | `destination_zip`    |
| `itens[].produto.peso`                       | `items[].weight`     |
| `itens[].produto.altura/largura/comprimento` | `items[].dimensions` |
| `itens[].valor`                              | `items[].value`      |

## Sincronização de tracking

Quando o BulkRoute gera um tracking code para um shipment originado do Bling:

1. O worker `bling-sync` envia `POST /rastreio` na API do Bling
2. O Bling atualiza o pedido com o tracking code
3. O cliente final pode rastrear pelo Bling ou pelo link do BulkRoute

## Troubleshooting

| Problema              | Causa                               | Solução                    |
| :-------------------- | :---------------------------------- | :------------------------- |
| Pedidos não importam  | Token OAuth expirou                 | Reconectar Bling           |
| CEP inválido          | Pedido sem CEP no Bling             | Preencher CEP no Bling     |
| Carrier não mapeado   | Carrier do Bling não tem mapeamento | Adicionar mapeamento       |
| Rate limit (HTTP 429) | Muitas requisições ao Bling         | Aumentar intervalo de sync |