Como integrar o Bling ao GoHighLevel

O que você precisa antes de começar

• Conta no Bling com um usuário que tenha a permissão Cadastro de aplicativos
• Um aplicativo criado na Área do Integrador do Bling, com os escopos de pedido de venda, nota fiscal e contatos
• Workflow Premium Features ligado na agência do GoHighLevel (Inbound Webhook e Custom Webhook são recursos premium)
• Uma camada intermediária, como n8n, Make ou um servidor próprio, para validar o aviso, renovar o token e consultar o contato na API do Bling
• Acesso de administrador à subconta do GoHighLevel

Passo a passo

1. 1

   Ative os recursos premium de workflow

   Na visão de agência do GoHighLevel, vá em Configurações → Empresa → Workflow - Premium Features e ligue a opção. Sem isso o gatilho Inbound Webhook e a ação Custom Webhook não ficam disponíveis.

   Ligar o recurso na agência não configura o rebilling de cada subconta. Se você repassa custos ao cliente, ajuste isso em cada subconta, na área de gerenciamento do cliente.

2. 2

   Crie o aplicativo no Bling

   No Bling, abra a Central de Extensões, entre na Área do Integrador e clique em Criar aplicativo. Preencha os dados básicos, informe o link de redirecionamento (usado na etapa de autorização) e adicione os escopos de que a integração precisa: pedidos de venda, notas fiscais e contatos. Guarde o client_id e o client_secret.

   O webhook de um recurso só aparece para configuração se o aplicativo tiver o escopo correspondente. Se a aba de webhooks não mostrar pedido de venda ou nota fiscal, o escopo está faltando.

3. 3

   Autorize o aplicativo e guarde os tokens na etapa intermediária

   A API v3 do Bling usa OAuth 2.0 com authorization code: o usuário autoriza o aplicativo, o Bling devolve um código e a etapa intermediária troca esse código por access_token e refresh_token em POST https://api.bling.com.br/Api/v3/oauth/token, com client_id e client_secret no cabeçalho Authorization: Basic. No exemplo da documentação, o access_token expira em 21.600 segundos (6 horas); o refresh_token vale 30 dias e serve para pedir um novo access_token.

   Os webhooks só começam a chegar depois que o aplicativo obtém os tokens no fim da autorização. E a renovação precisa ser automática: um token fixo colado num workflow para de funcionar em poucas horas.

4. 4

   Crie o workflow com o gatilho Inbound Webhook

   Na subconta do GoHighLevel, crie um workflow e escolha o gatilho Inbound Webhook. O GoHighLevel gera uma URL exclusiva para esse gatilho, que aceita requisições com corpo em JSON. Copie essa URL — é para ela que a etapa intermediária vai enviar os dados já completos.

5. 5

   Monte a etapa intermediária

   No n8n (ou ferramenta equivalente), crie um fluxo que recebe o webhook do Bling, confere a assinatura, lê o campo data.contato.id e consulta GET /contatos/{idContato} na API v3 com o access_token. A resposta traz nome, e-mail, telefone e celular do contato. Depois, envie para a URL do GoHighLevel um JSON com esses dados mais o evento (por exemplo order.created), o número do pedido, o total e o ID do pedido.

   O Bling assina cada aviso no cabeçalho X-Bling-Signature-256: um HMAC SHA-256 do corpo bruto, usando o client_secret do aplicativo como chave, no formato sha256=… Valide antes de processar. E responda com HTTP 2xx em até 5 segundos — deixe a consulta ao contato e o envio ao GoHighLevel para depois da resposta, ou o Bling trata a entrega como falha.

6. 6

   Configure os webhooks no aplicativo do Bling

   No cadastro do aplicativo, abra a aba Webhooks, configure o servidor que vai receber os eventos (a URL pública da etapa intermediária) e, em cada recurso, marque as ações desejadas e a versão do payload. Para pós-venda, os recursos úteis são Pedido de Venda (order) e Nota fiscal (invoice), com as ações created, updated e deleted. Salve as alterações.

   Mudar a situação de um registro para excluído gera updated, não deleted — deleted só chega na exclusão definitiva. Trate isso no fluxo para não disparar mensagem de agradecimento para um pedido cancelado.

7. 7

   Teste e ramifique o workflow por evento

   Crie um pedido de venda de teste no Bling para disparar o evento. No gatilho do GoHighLevel, clique em Test Trigger, escolha a requisição recebida e salve como amostra. Mapeie e-mail, telefone e nome na ação de criar ou atualizar contato. Depois, use uma condição sobre o campo do evento: pedido criado registra a venda na oportunidade e envia o agradecimento; nota fiscal emitida pode iniciar a sequência de pedido de avaliação; uma espera longa no fim do fluxo cria o lembrete de recompra.

   As chaves do JSON enviado ao GoHighLevel não podem ter espaços: use snake_case ou camelCase. Se o contato do Bling não tiver e-mail nem telefone cadastrados, o GoHighLevel não consegue identificá-lo — filtre esses casos na etapa intermediária.

8. 8

   Opcional: crie pedidos no Bling a partir do GoHighLevel

   Para o caminho inverso — negócio ganho no GoHighLevel virando pedido de venda no Bling —, use a ação Custom Webhook do workflow para avisar a etapa intermediária. Ela localiza ou cadastra o contato no Bling (GET /contatos aceita pesquisa por e-mail, nome ou CPF/CNPJ) e cria o pedido em POST /pedidos/vendas, que exige o ID do contato, os itens e as parcelas.

   Não chame a API do Bling direto do Custom Webhook com o token colado no workflow: o access_token expira e precisa ser renovado com o refresh_token. Deixe a chamada na etapa intermediária, que guarda as credenciais e cuida da renovação.

Limitações que valem saber antes

• Não há integração nativa documentada: a central de ajuda da HighLevel não traz o Bling, então pedidos, notas e estoque não sincronizam sozinhos com o CRM.
• Os webhooks de pedido de venda e de nota fiscal trazem só o ID do contato. Sem uma etapa que consulte a API do Bling, o GoHighLevel não consegue identificar o cliente.
• Inbound Webhook e Custom Webhook são execuções premium: cada subconta tem 100 execuções gratuitas vitalícias, e depois a HighLevel cobra US$ 0,01 por execução. Os planos Workflow Pro incluem uma franquia mensal e cobram o excedente com desconto.
• O Bling pode entregar o mesmo evento mais de uma vez e não garante a ordem — um updated pode chegar antes do created. Guarde o eventId e descarte duplicados, ou o cliente recebe o agradecimento duas vezes.
• Se o endpoint não responder com 2xx em 5 segundos, o Bling tenta de novo por até 3 dias. Se continuar falhando, o webhook daquele recurso é desativado e só volta quando alguém o reativa manualmente no aplicativo.
• A API v3 tem limite de 3 requisições por segundo e 120 mil por dia, aplicado à conta inteira. Cada pedido consome ao menos uma consulta de contato, o que pesa em dias de pico.
• Os webhooks cobrem pedido de venda, produto, estoque, estoque virtual, produto fornecedor, nota fiscal e nota fiscal de consumidor. Não há webhook de contato: alterações no cadastro de clientes do Bling não chegam ao CRM por esse caminho.

Perguntas frequentes

Qual evento usar para disparar o pós-venda: pedido criado ou nota emitida?

Depende de quando a venda é considerada concluída na sua operação. order.created chega quando o pedido de venda entra no Bling; invoice.created chega quando a nota fiscal é criada. O payload da nota traz o campo situacao, mas o Bling não documenta no webhook o significado de cada valor — confira na sua conta antes de usar como filtro. Para pedido de avaliação, a nota costuma estar mais perto da entrega do que o pedido.

Dá para apontar o webhook do Bling direto para o GoHighLevel, sem n8n?

O GoHighLevel até recebe o aviso, mas não consegue achar o contato: o Inbound Webhook precisa de e-mail ou telefone, e o webhook do Bling traz apenas o ID do contato. Além disso, a documentação do gatilho não descreve validação de assinatura, então o cabeçalho X-Bling-Signature-256 não seria conferido, e o prazo de 5 segundos para resposta fica fora do seu controle. Por isso a etapa intermediária é o caminho recomendado.

O estoque do Bling aparece no GoHighLevel?

Não automaticamente. O Bling tem webhooks de estoque e estoque virtual, mas o GoHighLevel não tem onde receber saldo de produto de forma nativa. Dá para gravar um valor num campo personalizado via etapa intermediária, mas o uso mais comum da integração é o relacionamento com o cliente depois da compra, não o controle de estoque.

Como testar sem atrapalhar a operação real?

A documentação do Bling oferece um ambiente de teste para experimentar os endpoints, mas os webhooks vêm da sua conta. O caminho seguro é criar um pedido de venda de teste com um contato seu, acompanhar o evento até o workflow do GoHighLevel e depois excluí-lo — lembrando que essa exclusão também vai gerar evento.