O Bling já possui integrações nativas com vários canais. Uma integração customizada faz sentido quando o marketplace, portal B2B ou fluxo comercial não é atendido, ou quando regras intermediárias precisam ser aplicadas antes de criar o pedido.
O maior risco não é deixar de importar uma vez; é importar duas. Webhooks podem ser repetidos ou chegar fora de ordem, e a conexão precisa tratar isso como comportamento normal.
Contrato entre canal e Bling
O integrador recebe pedido, cliente, entrega, itens, frete, descontos e identificador externo. Antes de criar, valida moeda, datas, documentos e soma dos itens. O payload bruto é preservado para auditoria.
Contato e produto usam chaves estáveis, como ID externo e SKU. Nome ou descrição não são suficientes. Um mapa registra IDs do canal e do Bling e permite corrigir cadastros sem perder o vínculo.
API e autenticação
A API Bling é REST, usa JSON e OAuth 2.0, com operações GET, POST, PUT, PATCH e DELETE. Tokens devem ser renovados no backend, com escopos mínimos e isolamento por empresa.
O pedido é criado pelo endpoint suportado e o ID retornado é salvo junto ao ID externo. Antes de repetir uma operação após timeout, o sistema consulta a correlação local ou o registro remoto.
Webhooks sem corrida
Webhooks do Bling informam criação, atualização e exclusão de pedidos. O receptor valida o HMAC no cabeçalho X-Bling-Signature-256, responde 2xx em até cinco segundos e processa em fila.
Como a documentação alerta que entregas não são ordenadas, cada evento usa eventId para deduplicação e data/versão para decisão. Uma atualização antiga não pode sobrescrever um estado mais novo.
Fiscal e estoque continuam no ERP
Criar pedido não equivale a emitir nota. Situação, reserva, estoque e faturamento seguem o processo configurado no Bling. O integrador só avança automaticamente nas etapas aprovadas.
Cancelamento e alteração após faturamento precisam de regra própria. Em caso de divergência, a operação aparece em fila com os dois estados em vez de forçar sincronização.
Piloto
Comece com um canal, um depósito e SKUs já conciliados. Inclua casos de reenvio, cancelamento, frete e pedido parcialmente inválido nos testes.
Precisamos de documentação do canal, aplicativo Bling, amostras de pedidos e regra de situação. O sucesso é pedido único, rastreável e reconciliado, não apenas resposta HTTP 201.