Conectando o Bling (ERP) - BulkRoute Central de Ajuda

O Bling é 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 v3) → BulkRoute importa pedidos → cria shipments
BulkRoute atualiza tracking → Bling recebe o tracking code

Conectando

1. Autorizar OAuth 2.0

O Bling usa OAuth 2.0 (API v3). O fluxo é:

Acesse Integrações > Bling
Clique em Conectar Bling
Você será redirecionado para o Bling (https://www.bling.com.br/Api/v3/oauth/authorize) — faça login e autorize
O Bling retorna para o BulkRoute no endpoint /integrations/bling/callback com o código de autorização
O BulkRoute troca o código por access_token e refresh_token e armazena na integração

O refresh_token é usado automaticamente quando o access_token expira. Você não precisa reconectar manualmente enquanto o refresh token for válido.

2. Mapear carriers

O Bling identifica transportadoras por transporte.transportadora.id (ID numérico). O BulkRoute usa códigos (ex: BRASPRESS, CORREIOS). Você precisa mapear via Integrações > Bling > Mapeamentos:

Carrier no Bling (ID)	Carrier no BulkRoute
ID da Braspress	`BRASPRESS`
ID dos Correios	`CORREIOS`
ID da Jadlog	`JADLOG`
(outro)	`BLING` (fallback automático)

Se não houver mapeamento, o BulkRoute faz fallback por nome: se o nome da transportadora contiver “CORREIOS”, “JADLOG” ou “BRASPRESS”, usa o carrier correspondente; caso contrário, usa BLING.

3. Disparar sincronização

A sincronização é manual — não há cron automático. Para importar pedidos:

Em Integrações > Bling, clique em Sincronizar Agora
Escolha o tipo de sync:
- orders — importa pedidos pagos do Bling
- tracking — envia tracking codes de volta ao Bling
- full — executa ambos
O job entra na fila BullMQ e processa em background (concurrency 2)
Acompanhe o progresso em Sync History

Você também pode reprocessar um sync que falhou via Sync History > Retry.

O que é importado

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

Campo do Bling	Campo no BulkRoute
`order.numero` ou `order.id`	`external_order_id`
`transporte.transportadora.id`	`carrier_code` (via mapeamento)
`transporte.cep` ou `contato.cep`	`destination_zip`
`contato.nome` ou `transporte.nome`	`recipient.name`
`contato.fone` ou `transporte.fone`	`recipient.phone`
`itens[].produto.codigo`	`items[].sku`
`itens[].produto.descricao`	`items[].description`
`itens[].quantidade`	`items[].quantity`
`itens[].produto.peso`	`items[].weight`
`itens[].produto.altura`	`items[].height`
`itens[].produto.largura`	`items[].width`
`itens[].produto.comprimento`	`items[].length`
`itens[].valor` ou `itens[].produto.valor`	`items[].value`

Metadados adicionais salvos: blingOrderId, blingCarrierName, blingCarrierId, syncedAt. O status inicial do shipment é sempre PENDING e is_own_fleet: false.

Sincronização de tracking

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

O sync tracking busca shipments com tracking_code preenchido e metadata.blingOrderId (limite 200 por execução)
Para cada um, chama POST /pedidos/vendas/{orderId}/rastreio na API v3 do Bling

Corpo enviado:

{
  "rastreio": {
    "codigoRastreio": "BR123456789BR",
    "transportadora": "Braspress"
  }
}

O Bling atualiza o pedido com o tracking code

Endpoints da API BulkRoute

Método	Endpoint	Descrição
`GET`	`/integrations/bling/auth-url`	Gera URL de autorização OAuth
`GET`	`/integrations/bling/callback`	Callback OAuth (público)
`GET`	`/integrations/bling/status`	Status da conexão
`GET`	`/integrations/bling/sync-history`	Histórico de sincronizações
`GET`	`/integrations/bling/sync-history/:id`	Detalhe de um sync
`POST`	`/integrations/bling/sync`	Disparar sincronização
`POST`	`/integrations/bling/sync-history/:id/retry`	Reprocessar sync falho
`GET`	`/integrations/bling/mappings`	Listar mapeamentos
`POST`	`/integrations/bling/mappings`	Criar mapeamento
`PUT`	`/integrations/bling/mappings/:id`	Atualizar mapeamento
`DELETE`	`/integrations/bling/mappings/:id`	Remover mapeamento

Rate limit e retry

O Bling API tem rate limit. Quando retorna 429 Too Many Requests, o BulkRoute respeita o header Retry-After (default 2s) e tenta novamente (até 3 vezes)
A fila BullMQ tem 3 tentativas com backoff exponencial de 10s
Concorrência do worker: 2 jobs em paralelo

Troubleshooting

Problema	Causa	Solução
Pedidos não importam	Token OAuth expirado	Reconectar Bling (refresh token inválido)
CEP inválido	Pedido sem CEP no Bling	Preencher CEP no Bling
Carrier não mapeado	Carrier do Bling sem mapeamento	Adicionar mapeamento em Integrações > Bling > Mapeamentos
Rate limit (HTTP 429)	Muitas requisições ao Bling	Aguardar — o BulkRoute faz retry automático
Sync não processa	Worker offline	Verificar status do worker no painel admin

​Como funciona

​Conectando

​1. Autorizar OAuth 2.0

​2. Mapear carriers

​3. Disparar sincronização

​O que é importado

​Sincronização de tracking

​Endpoints da API BulkRoute

​Rate limit e retry

​Troubleshooting

Como funciona

Conectando

1. Autorizar OAuth 2.0

2. Mapear carriers

3. Disparar sincronização

O que é importado

Sincronização de tracking

Endpoints da API BulkRoute

Rate limit e retry

Troubleshooting