📦 Bling API — produtos, pedidos, NF-e
API REST do Bling v3. Endpoints: produtos, pedidos de venda, clientes, NF-e. Token OAuth 2.0. ERP mais comum em PME BR.
🔑 OAuth 2.0
Cliente autoriza app via OAuth. Recebe refresh_token. Guarda no Supabase com criptografia. Renova access_token automaticamente (6h TTL).
📚 GET /produtos
Lista produtos com paginação (100/página). Sync inicial pesa o Bling — faz 1x e depois usa webhook pra updates.
📋 POST /pedidos/vendas
Cria pedido. Body: cliente_id, itens[], forma_pagamento. Retorna número do pedido + link Bling.
🧾 POST /nfes
Emite NF-e a partir do pedido. Bling cuida da comunicação com SEFAZ. Retorna chave + XML + PDF.
⏱️ Rate limit
Plano básico: 3 req/s. Avançado: 10 req/s. Implementa backoff exponencial quando 429.
💡 50% dos clientes PME
Bling domina o mercado PME brasileiro. Dominar Bling = pega 50% dos clientes potenciais.
🏢 Omie e Conta Azul — alternativas
Para PMEs maiores ou setores específicos. APIs próprias, autenticação por chave de aplicação.
Omie
- • PMEs 50-500 funcionários
- • app_key + app_secret (não OAuth)
- • Endpoints SOAP-like estilo JSON
- • Pages com chamadas separadas
- • Webhook nativo
Conta Azul
- • PMEs 10-100 func, foco financeiro
- • OAuth 2.0
- • REST mais limpo que Omie
- • Foco em contas a pagar/receber
- • Sync com fiscal
📊 Padrão de adaptação
Cliente que já usa ERP X não migra. Você adapta o workflow n8n. Endpoints diferentes mas padrão JSON. 1-2 dias pra cliente novo num ERP novo.
🧾 NF-e via ERP — emissão automática
Bling/Omie/Conta Azul emitem NF-e via API. Você passa dados do pedido, ERP gera + envia à SEFAZ + retorna chave.
📖 Caso SocialHub (65 varejistas)
Integração WhatsApp + Bling + NF-e:
- • Antes: 4 horas entre venda no WhatsApp e emissão da NF-e
- • Depois: 2 minutos
- • Impacto: cliente recebe nota antes do produto chegar
🏷️ NCM correto
Cada produto cadastrado no Bling com NCM. Sem NCM, SEFAZ rejeita. Validação prévia obrigatória.
📋 CFOP
Código Fiscal de Operações. Varia por operação (venda interna, interestadual, devolução). Bling sugere padrão.
✅ Validação CNPJ/CPF
API ReceitaWS ou BrasilAPI antes de gerar nota. Cliente PJ com CNPJ inválido = rejeição SEFAZ.
📥 Download XML+PDF
Após emissão, baixa XML (obrigatório guardar 5 anos) + PDF (DANFE). Envia DANFE pro cliente via WhatsApp.
💸 PIX em fluxo — Asaas ou Mercado Pago
Gera cobrança PIX no agente, envia QR code via WhatsApp, recebe webhook de pagamento, confirma automaticamente.
🏦 Asaas (recomendado BR)
API REST simples. Cobrança PIX em <200ms. QR code dinâmico. Webhook de pagamento confirmado. Tarifa baixa (R$ 1,99 por PIX recebido).
💳 Mercado Pago
Alternativa quando cliente já tem conta MP. API mais complexa mas robusta. Integra com QR Pix + boleto + cartão.
🔁 Fluxo no agente
1) Cliente confirma pedido. 2) Agente chama gerar_pix. 3) Envia QR via WhatsApp. 4) Webhook chega, agente confirma pra cliente e cria pedido no Bling. 5) NF-e emitida.
🔄 Reconciliação
PIX expira (TTL configurável, 30 min comum). Se cliente paga depois, agente identifica via webhook tardio e reabre o fluxo.
📊 ROI mais visível
PIX em 30 segundos vs boleto em 1-3 dias = giro de caixa 30x mais rápido. Cliente percebe valor imediatamente.
🔗 Webhooks e idempotência
Cada webhook tem ID único. Você guarda IDs processados pra evitar duplicação. Caso contrário: pedido criado 2x.
🐛 Bug clássico
Asaas envia webhook de pagamento confirmado. Seu workflow demora 31s para responder. Asaas timeout em 30s. Reenvia webhook. Você processa 2x. Pedido duplicado.
🆔 Tabela idempotency
Antes de processar, INSERT no Supabase. Se já existe = ignora. Schema: `idempotency(webhook_id PK, processed_at)`.
⏱️ TTL
Mantém IDs por 7 dias (webhook duplicado raramente passa de 24h). Cron deleta IDs antigos.
🔄 Retry com backoff
Se o processamento falha, retry com 2s, 4s, 8s, 16s. Após 5 tentativas, ack pro provider e escala humano.
🐛 Tratamento de erro de API
Try/catch em cada chamada. Retry com backoff exponencial em erro 5xx. Alerta no Telegram se > 3 falhas seguidas.
📋 Try/catch obrigatório
Todo node n8n que chama API externa envolto em try/catch. Resposta de erro mapeada pra mensagem amigável.
🔄 Retry com backoff
5xx (erro do provider) → retry. 4xx (seu erro) → não retry, escala. Backoff: 1s, 2s, 4s, 8s, 16s. Total 31s max.
🚦 Circuit breaker
Se Bling falha 10x em 5 min, abre circuit por 5 min. Agente diz "sistema em manutenção" durante o intervalo.
📲 Alerta no Telegram
Bot Telegram avisa você quando: 3+ falhas seguidas, circuit aberto, custo > X/dia, latência > 5s.
🆘 Fallback humano
Quando tudo falha, agente diz "vou encaminhar pro time" e cria ticket pro champion. Cliente não fica órfão.
⚠️ Bling cai 1x/mês por 5-15 min
Provider de PME tem uptime ~99.5% (não 99.99% como AWS). Sem tratamento de erro, agente trava ou inventa resposta. Tratamento é obrigatório.
🔌 Resumo do módulo
Próximo módulo:
5.3 — Deploy em produção · shadow mode · rampa progressiva · HITL conservador · job shadowing · contingência.