Módulo Bling para WHMCS

Integra o ERP Bling ao WHMCS: emite as notas fiscais de serviço (NFS-e) das suas faturas, exporta clientes e produtos e cria as contas a receber, tudo automaticamente. Desenvolvido pela Gofas Software.

Sumário

Download
Funcionalidades
Requisitos
Instalação
Configuração
Informações importantes
Perguntas frequentes
Suporte
Licença

Download

https://gofas.net/gbld/

Funcionalidades

Notas fiscais de serviço

Emissão automática de NFS-e. A nota é emitida quando a fatura é gerada ou quando é paga, com opção de agendar a emissão para um número de dias após o pagamento
Emissão manual de NFS-e. Botões de ação na edição da fatura, no admin do WHMCS e na página do módulo
Envio automático à prefeitura depois da criação da nota, com número máximo de tentativas configurável
Reemissão da nota cancelada, pela página do módulo
NFS-e apenas para clientes específicos, via campo personalizado "Emitir NFE" no perfil do cliente
Emissão apenas para pessoa jurídica, pelo CNPJ do cadastro
Conjunto de tributações por produto: um conjunto geral para todos os serviços ou um conjunto específico para cada serviço do WHMCS

Área do cliente

Notas fiscais na área do cliente. Seção dedicada no front end, sem interferir no template do WHMCS
NFS-e na própria fatura, com número, série, data de emissão, situação, código de verificação e link de consulta na prefeitura
Página de detalhes da nota, com os mesmos dados e o link de consulta
Aviso por email ao cliente quando a NFS-e é emitida, por template próprio do WHMCS

Cadastros e financeiro

Exportação de clientes. O cliente cadastrado no WHMCS é criado como contato no Bling
Exportação de produtos e serviços. Cada produto/serviço do WHMCS é criado no Bling, como produto ou como serviço, conforme a configuração
Contas a receber. Cada fatura publicada no WHMCS gera uma conta a receber no Bling, com categoria e vendedor escolhidos em listas alimentadas pela própria conta Bling
Recorrência replicada na conta a receber, conforme o ciclo do serviço no WHMCS

Integração e operação

API v3 do Bling com autenticação OAuth 2.0, por Client Id e Client Secret e com repetição automática das requisições quando o Bling limita a chamada
Fila de processamento com retentativas, para contas a receber e para o envio da NFS-e, com limite de contas a receber por execução
Sincronização agendada. Status das notas, envio à prefeitura e demais verificações, uma vez por dia ou a cada 5 minutos, via cron do WHMCS. Também é possível sincronizar manualmente
Aviso por email ao administrador quando a emissão falha
Registro de diagnóstico no Log de Módulo do WHMCS, opcional
Envio de estatísticas de uso, opcional e com consentimento

Requisitos

WHMCS 8.x ou superior
PHP 8.2 a 8.4, com cURL e ionCube Loader 15 ou superior
Cron do WHMCS ativo
Conta Bling com a API v3 habilitada e um aplicativo cadastrado, para obter Client Id e Client Secret
Dados da empresa, certificado digital e configurações de NFS-e ativos na conta Bling

Instalação

Baixe o módulo na sua área do cliente e descompacte.
Copie a pasta modules/addons/gofasbling para o diretório modules/addons/ da sua instalação WHMCS.
Ative o módulo em Configurações > Módulos Addons.
Abra o módulo, preencha o Client Id e o Client Secret, salve e clique em OBTER AUTORIZAÇÃO NO BLING. Autorize o acesso na tela do Bling. Você volta ao módulo com a confirmação e o selo de integração autorizada.

A autorização usa OAuth 2.0: Client Id e Client Secret sozinhos não autenticam, o aceite é obrigatório. Depois disso a renovação é automática, feita sob demanda e também pelo cron diário, sem nova intervenção.

Configuração

Pré configuração (conta Bling)

Configure o certificado digital e os dados da empresa na sua conta Bling.
Habilite a emissão de NFS-e e configure a integração com a prefeitura, conforme o manual Bling.
Em Cadastro de aplicativos, crie um aplicativo e guarde o Client Id e o Client Secret.
Ainda no cadastro do aplicativo, informe a URL de redirecionamento apontando para o seu WHMCS, exatamente neste formato:
https://SEU-WHMCS/modules/addons/gofasbling/gblcallback.php
Sem essa URL cadastrada a autorização não retorna e a integração não é ativada.
Em Todas as configurações > Serviços > Configurações de NFS-e, configure o serviço e anote o Cód. Padrão Trib. Nacional (coluna correspondente, por exemplo 010302 para hospedagem). Esse código precisa estar vinculado a um conjunto de tributações na sua conta. Sem esse vínculo o Bling recusa a emissão pela API com a mensagem "O código da lista de serviço não está vinculado a um conjunto de tributações", mesmo que a emissão manual pelo painel funcione.

Opções do módulo

Chave de licença: obtida ao adquirir o módulo.
Client Id e Client Secret: credenciais do aplicativo criado na sua conta Bling.
Debug: salva informações de diagnóstico no Log de Módulo do WHMCS.
Exportar clientes: cadastra o cliente no Bling quando ele é cadastrado no WHMCS. Mesmo desativada, o cliente é criado no Bling na emissão da NFS-e.
Exportar produtos/serviços: cria o produto no Bling quando um produto ou serviço é criado no WHMCS.
Criar produtos ou serviços: define se os produtos/serviços do WHMCS correspondem a produtos ou a serviços no Bling.
Criar Contas a Receber: cria a conta a receber no Bling quando a fatura é publicada no WHMCS.
Categoria: categoria das contas a receber criadas.
Vendedor: vendedor das contas a receber criadas.
Replicar a recorrência no Bling: repete no Bling o ciclo de cobrança do serviço no WHMCS.
Contas a receber por execução: quantas contas a receber pendentes são processadas a cada execução do cron.
Emitir NFS-e: quando a fatura é gerada ou quando é paga.
Agendar Emissão: número de dias após o pagamento da fatura para emitir a nota. Preencher esse campo desativa a opção anterior.
Emitir NFE para: todos os clientes ou clientes selecionados via campo personalizado "Emitir NFE" (checkbox).
Emitir NFS-e apenas para PJ: ignora as faturas de clientes sem CNPJ.
Incluir juros/multa no valor da NFS-e: desligada, que é o padrão, os juros e a multa por atraso lançados na fatura ficam de fora do valor e da descrição da nota. A base de cálculo do ISS considera apenas os serviços. Ligada, o valor e a descrição da nota passam a incluir também os juros e a multa. Vale para a emissão automática, a manual e a do cron. Na dúvida, consulte a sua contabilidade.
Avisar o cliente por email quando a NFS-e for emitida: envia ao cliente o link e o código de verificação da nota. O texto é editável em Configurações > Modelos de Email, no modelo "Gofas Bling NFS-e Emitida".
Sincronizar NFS-e, clientes, serviços e contas a receber: frequência da sincronização agendada, uma vez por dia ou a cada 5 minutos.
Máx. tentativas (contas a receber) e Máx. tentativas (envio de NFS-e): quantas vezes a fila tenta novamente antes de desistir de um item.
Cód. Padrão Trib. Nacional: código aplicado a todos os serviços e itens de fatura do WHMCS, por exemplo 010302 para hospedagem. Localize-o no painel do Bling em ícone do perfil > Todas as configurações > Serviços > Configurações de NFS-e, na linha do serviço, coluna Cod. Padrão Trib. Nacional. O código precisa estar vinculado a um conjunto de tributações na sua conta.
Cód. Padrão Trib. Nacional por produto/serviço: código específico por produto/serviço do WHMCS. Deixe em branco os que usam o código geral.
Enviar estatísticas de uso (opcional): envia dados de uso do módulo para a Gofas. Pode ser desligada a qualquer momento.

Gerenciamento das notas fiscais no WHMCS

Acesse Configurações > Módulos Addons > Gofas Bling. A página lista as NFS-e emitidas pela integração, com informações da fatura e do cliente e as ações disponíveis conforme o status de cada nota.

Enquanto a integração não estiver autorizada, a página exibe o aviso com a URL de redirecionamento a cadastrar no Bling e o botão de autorização. Após autorizar, passa a exibir a confirmação e o prazo restante de renovação.

Na página de edição de cada fatura, o administrador vê o número e a situação da NFS-e vinculada e pode emitir, editar no painel Bling ou visualizar a nota.

Se o link de consulta salvo estiver vazio ou inválido em uma nota que já não está mais Pendente, aparece um botão Sincronizar para buscar os dados de novo direto no Bling, tanto aqui quanto na lista de notas.

O que o cliente vê

O menu "Minhas Notas Fiscais" na área do cliente lista as notas emitidas para ele.

Cada nota tem uma página com os dados completos e o link de consulta na prefeitura. O botão de consulta só aparece quando o link salvo é uma URL externa válida; caso contrário, é exibido um aviso no lugar do botão.

A própria fatura exibe a NFS-e vinculada, com número, situação, código de verificação e o link de consulta. O mesmo cuidado com links inválidos se aplica aqui.

Informações importantes

Atualização da v2 para a v3: o campo Cód. Padrão Trib. Nacional substitui o antigo Código de Serviço. Quem vem da v2 tem gravado ali o código da lista de serviços da LC 116 (por exemplo 1.03), que a API v3 do Bling recusa. Antes de emitir notas na v3, troque o valor desse campo e dos campos por produto pelo Cód. Padrão Trib. Nacional da sua conta Bling.
Bairro: o Bling exige o bairro do tomador. No WHMCS o bairro é o campo "Endereço 2" (address2) do perfil do cliente, o que costuma causar confusão. Sem ele preenchido a emissão é recusada. O módulo avisa antes de chamar o Bling.
Clientes do exterior: para cliente com país diferente de Brasil, o módulo cadastra o contato no Bling sem CEP, cidade, estado e bairro, porque o Bling só aceita município da tabela do IBGE e recusa cidade estrangeira. O endereço completo, o país e o telefone ficam registrados no campo Complemento do contato, já que o Bling também recusa telefone que não seja brasileiro. A conta a receber continua sendo criada normalmente. A NFS-e não é emitida, porque o Bling exige CPF ou CNPJ, cidade, estado e bairro brasileiros do tomador. Nesse caso emita a nota de exportação de serviço direto no portal da prefeitura. O módulo registra o motivo no log e informa na tela da fatura.
Autorização: se o Client Id ou o Client Secret forem alterados, a autorização anterior deixa de valer e o módulo pede uma nova, pelo botão OBTER AUTORIZAÇÃO NO BLING.
Campo personalizado CPF/CNPJ: crie um campo personalizado de cliente para CPF e/ou CNPJ. O módulo identifica o campo automaticamente pelo nome.
Endereço: preencha no formato padrão do WHMCS, com logradouro e número na mesma linha (campo "Endereço 1"), ex.: "Avenida Brasil, 1234".
Erro ao enviar a NFS-e à prefeitura: normalmente indica configuração incompleta na conta Bling ou pendência junto à prefeitura, como o certificado digital. Emita a nota manualmente para ver a mensagem retornada pela prefeitura.
Sempre faça backup antes de alterar qualquer coisa no seu sistema.
Personalizações podem ser feitas por hooks, sem editar o código do módulo, mantendo a atualização possível.

Perguntas frequentes

A nota saiu com valor diferente do total da fatura. Por quê? Quando a fatura tem juros ou multa por atraso, o padrão do módulo é deixar esses valores de fora da nota, emitindo apenas o valor dos serviços. Para incluí-los, ligue a opção "Incluir juros/multa no valor da NFS-e". Confirme com a sua contabilidade qual das duas formas se aplica ao seu caso.

O Bling recusou a emissão com "O código da lista de serviço não está vinculado a um conjunto de tributações". O que fazer? O Cód. Padrão Trib. Nacional informado no módulo existe, mas não está vinculado a um conjunto de tributações na sua conta Bling. Acesse ícone do perfil > Todas as configurações > Serviços > Configurações de NFS-e e faça esse vínculo. A emissão manual pelo painel pode funcionar mesmo sem ele, então o teste pelo painel não confirma que a API vai aceitar.

A emissão falhou com "Bairro ausente no cadastro do cliente", mas o bairro está preenchido. No WHMCS o bairro fica no campo "Endereço 2" (address2), não no "Endereço 1". Confira se o bairro está nesse campo do perfil do cliente.

Tenho cliente no exterior. O módulo emite a nota? Não. O Bling exige CPF ou CNPJ, cidade, estado e bairro brasileiros do tomador da NFS-e. O contato e a conta a receber são criados normalmente, mas a nota de exportação de serviço precisa ser emitida direto no portal da prefeitura.

A nota ficou como Pendente e não foi para a prefeitura. A nota foi criada no Bling, mas o envio à prefeitura falhou e foi reagendado na fila do módulo. As tentativas seguem o limite configurado em "Máx. tentativas (envio de NFS-e)". Verifique no painel do Bling a mensagem retornada e se o seu município está homologado, na lista de prefeituras.

Preciso autorizar a integração de novo depois de atualizar o módulo? Não. A autorização só precisa ser refeita se o Client Id ou o Client Secret forem alterados na conta Bling.

Onde vejo o motivo exato de uma falha? Ligue a opção Debug e consulte Configurações > Logs > Log de Módulo. O módulo grava ali a chamada e a resposta do Bling.

Suporte

Abrir issue no fórum do módulo.

Licença

Contrato de licença de uso

Changelog

v3.0.6 — Botões de NFS-e não confiam mais em link salvo sem validar e gbl_config() unificada - 29/08/2026

Melhorias:

Botões de NFS-e confiam no link salvo sem validar se aponta para fora do WHMCS - #123
gbl_config() definida duas vezes com assinaturas diferentes: a versão sem parâmetro sempre vence - #122