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

# Integrações com ERPs e Marketplaces

> Conecte Bling, Tiny, Omie, Mercado Livre e Shopify para importar pedidos automaticamente.

O BulkRoute importa pedidos de ERPs e marketplaces e os transforma em **shipments** automaticamente. Quando o tracking é atualizado no BulkRoute, ele sincroniza de volta para a plataforma de origem.

## Como funciona

```mermaid theme={null}
flowchart LR
    ERP[ERP / Marketplace] -->|Pedido pago| BR[BulkRoute]
    BR --> Shipment[Cria Shipment]
    Shipment --> Carrier[Despacha com carrier]
    Carrier --> Tracking[Tracking atualizado]
    Tracking -->|Sincroniza tracking| ERP
```

## Integrações disponíveis

| Plataforma        | Tipo        | Status      | Como conectar            |
| :---------------- | :---------- | :---------- | :----------------------- |
| **Bling**         | ERP         | ✅ Produção  | OAuth 2.0                |
| **Tiny**          | ERP         | ✅ Produção  | API Key                  |
| **Omie**          | ERP         | ✅ Produção  | App Key + App Secret     |
| **Mercado Livre** | Marketplace | ✅ Produção  | OAuth 2.0                |
| **Shopify**       | E-commerce  | ✅ Produção  | OAuth 2.0 (app embedded) |
| **Nuvemshop**     | E-commerce  | 🔲 Em breve | —                        |
| **Tray**          | E-commerce  | 🔲 Em breve | —                        |
| **VTEX**          | Enterprise  | 🔲 Em breve | —                        |

## O que é sincronizado

### Do ERP/Marketplace → BulkRoute

* **Pedidos pagos** → viram shipments no BulkRoute
* **Dados do destinatário** (nome, CPF/CNPJ, endereço, telefone)
* **Itens do pedido** (SKU, descrição, peso, dimensões, valor)
* **CEP de origem** (se diferente do CD padrão)

### Do BulkRoute → ERP/Marketplace

* **Tracking code** enviado de volta ao pedido
* **Status de entrega** sincronizado quando muda

<Warning>
  O BulkRoute **importa pedidos como envios**. Não sincroniza catálogo de produtos nem estoque. Para sincronizar catálogo, use a API do seu ERP diretamente.
</Warning>

## Configuração geral

Para todas as integrações:

1. Acesse **Integrações** no menu lateral
2. Selecione a plataforma desejada
3. Autorize a conexão (OAuth ou credenciais)
4. Mapeie os carriers (qual carrier do BulkRoute corresponde a qual carrier do ERP)
5. Ative a sincronização automática
6. Configure o **intervalo de sync** (padrão: a cada 30 minutos)

## Logs de sincronização

Cada sincronização gera um log visível no painel:

* **Registros processados** / **sucesso** / **erro**
* **Detalhe do erro** (ex: "CEP inválido no pedido #123")
* **Retry manual** disponível para registros com erro
* **DLQ (Dead Letter Queue)** para registros que falharam 3+ vezes

## Worker de sincronização

A sincronização roda em background via BullMQ:

* Cada integração tem seu próprio worker
* Concorrência configurável (padrão: 2 jobs simultâneos)
* Retry exponencial em caso de falha (HTTP 429, timeout, etc.)
* Não bloqueia o painel — você continua trabalhando enquanto sincroniza