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.

Comprar o módulo

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

• NFS-e no WhatsApp do cliente: além do email, o cliente recebe o link público da NFS-e por WhatsApp quando ela é emitida, com o módulo Gofas WHMCS WhatsApp

• 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

• 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

• 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

• 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

• WHMCS 8.x ou superior
• PHP 8.2 ou superior, com cURL
• 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

1. Baixe o arquivo em https://gofas.net/gbld/ e descompacte.
2. Copie a pasta modules/addons/gofasbling para o diretório modules/addons/ da sua instalação WHMCS.
3. Ative o módulo em Configurações > Módulos Addons.
4. 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.

1. Configure o certificado digital e os dados da empresa na sua conta Bling.

2. Habilite a emissão de NFS-e e configure a integração com a prefeitura, conforme o manual Bling.

3. Em Cadastro de aplicativos, crie um aplicativo e guarde o Client Id e o Client Secret.

4. 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.

5. 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.

• 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 de consulta pública e o código de verificação da nota, uma única vez, quando a nota passa a Emitida, seja pelo cron, pelo webhook ou ao abrir a fatura. 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.

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. Com a nota emitida, aparece também DANFSe no Bling, que abre o PDF da nota no Bling (exige estar logado no Bling). O botão Reenviar email manda de novo ao cliente o email da NFS-e com o link de consulta atual.

O botão Visualizar NFS-e abre a Consulta Pública do Portal Nacional da NFS-e (nfse.gov.br) com a chave de acesso já preenchida, o mesmo link que o cliente recebe. A API do Bling devolve apenas um link interno do Bling, que exige login; por isso o módulo monta o link público a partir da chave de acesso da nota. Notas de prefeituras fora do padrão nacional que tenham link próprio continuam usando esse link.

Se a nota já não está mais Pendente e não há link de consulta, aparece um botão Sincronizar para buscar os dados de novo direto no Bling, tanto aqui quanto na lista de notas.

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 botão de consulta pública da NFS-e. No Portal Nacional, o cliente confirma o captcha e baixa a nota. Se não houver link de consulta, é 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 mesmo link de consulta pública.

• 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.

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.

Abra um tópico no fórum do módulo. Para enviar código ou logs, use um link do Gist (gist.github.com) ou do Pastebin (pastebin.com).

Contrato de licença de uso

Melhorias:

• Integração com o módulo renomeado para Gofas WHMCS WhatsApp - #128 enhancement

Melhorias:

• Avisar o cliente por WhatsApp quando a NFS-e for emitida - #127 enhancement

Melhorias:

• Atualização importante de segurança - #126

Correções:

• NFS-e: link de consulta relativo do Bling quebra o email e some da área do cliente - #124 bug

Melhorias:

• Botões de NFS-e confiam no link salvo sem validar se aponta para fora do WHMCS - #123

Correções:

• NFS-e: link de consulta relativo do Bling quebra o email e some da área do cliente - #124 bug

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

Melhorias:

• Clientes do exterior: contato sem endereço brasileiro e NFS-e bloqueada (opção A) - #121
• gbl_customer() passa adminuser inválido ao localAPI e devolve cliente vazio - #120
• Opção para incluir juros/multa no valor da NFS-e - #119
• Desativação remota: receptor roda antes do guard e intercepta o POST de outros módulos - #117
• Padronizar sanitização de telefone: remover DDI +55, zero à esquerda e validar comprimento - #108

Correções:

• NFS-e: juros/multa (LateFee) entram na base de cálculo da nota - #118 bug
• Fila: indisponibilidade temporária da prefeitura consome as 5 tentativas e exige reemissão manual - #116 bug
• webhook.php: sem validação de assinatura HMAC e processamento síncrono acima do limite do Bling - #115 bug

Correções:

• Validar bairro e Cód. Padrão Trib. Nacional antes de chamar a API - #114 bug
• Log do cron diário gravava client_secret e license_key - #113 bug
• Refresh token pode expirar por falta de renovação proativa - #112 bug
• Erro do Bling exibido como texto genérico: error.fields era lido pela chave errada - #111 bug
• Remover campo de configuração da API Key antiga (v2) e o código v2 obsoleto - #110 bug
• OAuth: módulo publicado sem botão de autorização e sem callback, integração impossível de ativar - #109 bug

Correções:

• Listas de categorias e vendedores: falha de consulta não pode virar lista vazia cacheada - #107 bug
• Deduplicação de contato e produto: consulta que falha não pode virar criação às cegas - #106 bug
• NFS-e: criação sem id é tratada como sucesso e gera loop de "Nota sem id" com log vazio - #105 bug

Melhorias:

• logModuleCall de gbl_update_stats grava sempre, ignorando o debug - #104 enhancement

Correções:

• Chamadas ao stats.php sem timeout podem travar a tela do cliente - #103 bug
• Verify (gbl_get_version) ignora consent_stats e envia URL e contato do admin no opt-out - #102 bug
• Mesmo defeito latente no hook ProductEdit: gbl_produto_upsert sem o lib carregado - #101 bug
• Fatal ao salvar cliente: gbl_contato_upsert indefinida nos hooks ClientAdd/ClientEdit - #100 bug

Melhorias:

• NFS-e na fatura do cliente: adotar o formato da tabela Livro contábil - #99
• readme: seção Funcionalidades não reflete o que a v3 entrega - #98
• NFS-e na fatura do cliente: mover para o rodapé e ampliar dados e botões - #97
• Página do addon: botão Visualizar NFS-e sempre desabilitado e situação Disponível para consulta não tratada - #96
• consent_stats não definido é tratado como recusa, contrariando o default yes - #95
• Erro de JavaScript na página de detalhes da NFS-e: elemento do menu não existe - #94
• Detalhes da NFS-e sempre vazio: verificação de posse compara id de usuário com id de cliente - #93
• Tela de configurações não exibe o selo de status da licença - #92
• Hooks inativos: condição de licença legada não existe mais após a refatoração do synchronize.php - #91
• Fatura do cliente: exibir a NFS-e em painel (estilo gnfa) em vez de botão - #90
• Área do cliente: refazer viewnfse com painel branded - #89

Melhorias:

• Tela de config: versão local vazia quando o embed retorna vazio - #88
• NFS-e v3: mapear situacao e campos pela documentação (schema real) - #87
• Remover definições duplicadas em includes/functions.php - #86
• NFS-e v3 Etapa 3: limpeza do transporte v2 e telas admin - #85
• NFS-e v3 Etapa 2: sync de status e PDF/link/XML no WHMCS - #84
• Religar emissão e envio da NFS-e à API v3 (issuenfse) - #83
• Recorrência da conta a receber na v3: códigos de ocorrencia.tipo levantados por sondagem da API - #82
• Bling limita POSTs seguidos em /contas/receber e o módulo perde lançamentos em lote - #81
• Categoria e Vendedor viram listas alimentadas pela conta Bling - #80
• Separação de logradouro, número e complemento falha quando o nome da rua tem número - #79
• Atualização da v2 para a v3: trocar o Código de Serviço pelo Conjunto de Tributações do Bling - #78
• Renomear o prefixo gblg_ para gbl_ (retoma a #66) - #77
• Implementar a telemetria padrão Gofas - #76
• Auditar entrypoints web sem guarda WHMCS - #75
• Remover os condicionais de PHP 7.4 e os requires órfãos - #74
• Revisar a verificação de licença conforme o padrão do gca - #73
• Migrar contatos, produtos, contas a receber e NFS-e para a API v3 - #72
• Criar lib/gbl_api.php com OAuth 2.0 e retry - #71
• Reconstrução do módulo para a API v3 do Bling (v3.0.0) - #70
• Remover o diretório includesd (variante PHP 7.4) - #69
• Padronizar readme.md e criar a página do módulo (13633) - #68
• Link de suporte aponta para post inexistente (?p=12313) - #67
• Renomear prefixo gblg_ para gbl_ - #66
• Enviar NFS-e à prefeitura após a criação - #41 enhancement
• Emitir NFS-e apenas para pessoa jurídica (cadastros que possuem CNPJ) - #38 enhancement
• Incluir hooks da pasta /hooks/ automaticamente - #35 enhancement
• verificar a existência da fatura antes de exibr as NFS-es - #32
• Email admin em caso de erros - #8 enhancement
• Download da nota fiscal na fatura - #4 enhancement
• Email com NFS-e quando status é Emitida - #2 enhancement

Correções:

• Corrigidos os erros de compatibilidade do PHP na tela de notas no admin - #65 bug

Correções:

• Corrigido o erro no front end quando não há emissões array_keys(): Argument #1 ($array) must be of type array output.php:83 - #64 bug

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Compatibilidade com PHP 7.4 e 8.1 no mesmo módulo - #63 enhancement
• Previne erro retornado no PHP 8 ao processar uma variável como array quando a mesma é string - #62
• Melhoria na obtenção de informações da instalação do WHMCS - #61
• Corrigido o erro retornado em consultas em massa quando o cliente não possui serviços ou produtos associados à sua conta - #60
• Dispensa a necessidade de selecionar o admin do WHMCS nas configurações. Agora o admin que realiza a instalação é definido como responsável pelas chamadas à API interna do WHMCS - #58

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Link "sincronizar" removido da página de exibição das NFS-es no admin - #40 enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Template da área do cliente adaptado para os padrões técnicos do WHMCS 8.6+ - #59
• Corrigido o erro que quebrava o layout da edição de faturas no WHMCS v8.6+ - #56
• Substitui separador de itens da fatura por quebra de linha na descrição dos serviços da NFS-e - #48 enhancement
• Melhora formatação dos links das notas fiscais na página de edição das faturas - #47 enhancement
• Obtém URLs do sistema a partir das configurações gerais utilizando funções nativas do WHMCS - #46 enhancement
• Atualizar status da NFS-e cancelada ao sincronizar - #42 enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• compatibilidade php8+ - #54 bug enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Sincronização de serviços - #53 enhancement
• Sincronização de clientes - #52 enhancement
• Contas a receber - #51 enhancement
• Adiciona novos dados ao Log - #49 enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Agrupa itens de linha da fatura no campo serviços para evitar erros de integração - #45 enhancement

Correções:

• Corrige a obtenção do número no endereço do cliente quando este está na mesma linha do nome da rua - #44 bug

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Nova Opção: Vincular Código de Serviço aos respectivos serviços no WHMCS - #39 enhancement
• Campo "Emitir NFE" no perfil do cliente - #37 enhancement
• Adicionar hook EmailPreSend para gerar NFS-e ao gerar a fatura via cron diário - #36 bug enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• Campo "Emitir NFE" no perfil do cliente - #37 enhancement
• Adicionar hook EmailPreSend para gerar NFS-e ao gerar a fatura via cron diário - #36 bug enhancement

Vale mencionar:

• Documentação e lançamento - #1 documentation

Melhorias:

• User-Agent no header da requisição ao verificar atualizações no gofas.net - #33 enhancement
• Suporte ao custom field "número" - #28 enhancement
• Melhora formatação do endereço quando Logradouro + nº estão na mesma linha (address1) - #25 enhancement
• Suporte a custom field "Inscrição Estadual" - #23 enhancement
• Remove função depreciada - #16 enhancement
• Suporte ao custom field "complemento" - #12 enhancement

Correções:

• Verificar a obtenção de todos os items de linha da fatura ao definir os serviços da NFS-e - #31 bug
• Corrigido erro no nome da setting gblglocalkey (estava gblggblglocalkey) - #30 bug
• Inclui ID da fatura no campo "número da loja" de NFS-es geradas sob agendamento - #26 bug
• Aprimorada a obtenção de dados do cliente da função gblg_customer - #20 bug
• Erro de exibição na área do cliente em versões do WHMCS menor que 8.0 - #18 bug

Documentation:

• Automatização e aprimoramento do log de alterações (Changelog) - #34 documentation
• Documentação e lançamento - #1 documentation

Melhorias:

• Remove função depreciada - #16 enhancement
• Notas sequenciais via cron - #10 enhancement
• Opção: código de serviço - #9 enhancement
• Página com lista de notas fiscais na área do cliente - #3 enhancement

Documentation:

• Lista de Prefeituras que possuem integração com o Bling para emissão de NFS-e - #19 documentation
• Tela de configuração - #11 documentation
• Documentação e lançamento - #1 documentation