Seu financeiro pronto, sem digitar nada duas vezes.

O Conta Azul cuida da gestão financeira da sua empresa. O WHMCS cuida dos seus clientes, faturas e serviços. Este módulo une os dois: cada cliente cadastrado, cada fatura emitida e cada pagamento recebido no WHMCS aparece no Conta Azul automaticamente, já classificado e já baixado no contas a receber.

Sem planilha de apoio, sem lançamento manual, sem divergência de caixa no fim do mês.

Comprar o módulo

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

• Fim do lançamento manual. A venda nasce da fatura do WHMCS, com os itens, os descontos e os tributos exatamente como o cliente pagou
• Conciliação automática. Quando a fatura é paga, a parcela correspondente é baixada na conta financeira certa, com o método de pagamento equivalente ao gateway usado
• Financeiro classificado. Cada venda entra com categoria de receita e centro de custo, alimentando o fluxo de caixa e o DRE sem retrabalho
• Notas fiscais no lugar certo. As notas emitidas no Conta Azul são relacionadas às faturas de origem e ficam disponíveis para o cliente na própria área do cliente do WHMCS
• Nada se perde. Vendas e baixas que esbarram em indisponibilidade da API voltam para uma fila e são reprocessadas pelo cron

• NFS-e no email e no WhatsApp do cliente: quando a sincronização encontra uma NFS-e nova vinculada a uma fatura, o cliente recebe o link da nota por email (modelo editável no WHMCS) e por WhatsApp, com o módulo Gofas WHMCS WhatsApp
• Criação automática de clientes. Todo cliente cadastrado no WHMCS vira uma pessoa com perfil Cliente no Conta Azul, com CPF ou CNPJ, telefone e endereço completo
• Campos personalizados prontos na ativação. O módulo cria sozinho os campos de cliente de que precisa, sem configuração manual
• Detecção automática de CPF e CNPJ. O módulo encontra os campos personalizados pelo nome e identifica o documento pela quantidade de dígitos, funcionando com um campo único para os dois ou com campos separados
• Importação de clientes em massa. Todos os clientes já existentes no WHMCS são enviados em lote pelo cron, com cursor que retoma de onde parou, sem travar o servidor
• Criação automática de vendas. A venda é gerada quando a fatura é emitida ou quando é paga, você escolhe
• Datas alternativas. A venda pode usar a data de criação ou a data de pagamento da fatura
• Vínculo automático de serviços. O campo personalizado de produto que guarda o serviço do Conta Azul é criado sozinho, produto a produto. O serviço é associado por nome quando já existe e criado quando não existe, sem duplicar
• Nada é duplicado. Cada fatura carrega a marca da venda e da baixa correspondentes. Reprocessar uma fatura, refazer um pagamento ou rodar o cron duas vezes não gera lançamento repetido
• Descontos e tributos fiéis à fatura. Itens negativos viram desconto na composição de valor da venda e os impostos entram como item próprio, mantendo o total idêntico ao do WHMCS
• Produtos ou serviços. Os itens podem ser cadastrados como serviço ou como produto, com retorno automático para serviço quando o controle de estoque do Conta Azul recusa o produto
• Classificação financeira. Categoria de receita e centro de custo aplicados a cada venda, alimentando fluxo de caixa e DRE
• Baixa automática de recebimento. Fatura paga no WHMCS vira parcela baixada no contas a receber, na conta financeira escolhida, pelo valor que estava em aberto e com o método de pagamento equivalente ao gateway usado
• Conciliação de notas fiscais. As NFS-e e NF-e emitidas no Conta Azul são relacionadas às faturas, com sincronização diária pelo cron e botão de sincronização manual
• Notas fiscais na área do cliente. Seção dedicada no front end, no mesmo formato da página de faturas, com download do PDF e do XML, sem alterar o template do WHMCS
• Painel de acompanhamento. A página do módulo mostra a validade do token, o andamento da sincronização, as contas financeiras disponíveis e a relação completa entre notas fiscais e faturas
• Filas com reprocessamento. Vendas e baixas pendentes são retentadas pelo cron. O abandono fica registrado no log de atividades do WHMCS
• Renovação automática de autorização. O token OAuth2 é renovado sozinho pelo cron. Se a renovação falhar, o módulo avisa na página do módulo
• Controle de acesso por grupo. Você define quais grupos de administradores enxergam o módulo
• Diagnóstico sob demanda. Com o Debug ligado, todas as chamadas à API ficam registradas em Registros do Módulo

• WHMCS 8.x ou superior
• PHP 8.2 ou superior, com cURL
• ionCube Loader 15 ou superior
• Cron do WHMCS ativo
• Conta no Conta Azul com acesso à API
• Pelo menos uma conta financeira cadastrada no Conta Azul, em Financeiro > Outras contas, obrigatória para o registro das baixas

1. Baixe o arquivo em https://gofas.net/gcad/ e descompacte.
2. Copie a pasta modules/addons/gofascontaazul para o diretório modules/addons/ da sua instalação WHMCS.
3. Ative o módulo em Configurações > Módulos Addons.
4. Ainda na ativação, defina os grupos de administradores que terão acesso ao módulo. Apenas quem já tem autorização para acessar o painel do Conta Azul deve ter acesso a essa área.

1. Faça login em portaldevs.contaazul.com e clique em Criar Aplicação.
2. Preencha o nome e a descrição.
3. Em URI de redirecionamento, informe o endereço de callback exibido nas configurações do módulo, no formato https://SEU-WHMCS/modules/addons/gofascontaazul/callback.php. Clique em Avançar.
4. Em Tipo de software escolha Online/Nuvem, em Segmento do Software escolha Pagamentos e clique em Salvar e finalizar.
5. Guarde o Client ID e o Client Secret, eles são usados no passo seguinte.

Se ainda não tiver, cadastre também uma conta financeira em Financeiro > Outras contas do Conta Azul. Sem ela a API recusa o registro das baixas.

Do lado do WHMCS não é preciso preparar nada: na ativação o módulo cria sozinho os campos personalizados de cliente que faltarem, um para CPF/CNPJ e outro chamado ID Conta Azul, e respeita os que você já tiver com esses nomes. Se quiser enviar o complemento do endereço, crie um campo de cliente chamado Complemento. O módulo localiza todos pelo nome, você não informa id em lugar nenhum.

• Chave de licença: obtida ao adquirir o módulo. Sem licença ativa o módulo não sincroniza, não cria vendas, não registra baixas e não consulta notas fiscais
• Client ID e Client secret: da aplicação criada no passo anterior
• Administrador do WHMCS: usuário administrador usado nas operações internas do módulo
• Quando criar a venda: na emissão da fatura ou no pagamento
• Data da venda: data de criação da fatura ou data do pagamento
• Nota administrativa: texto padrão adicionado às vendas. É também onde ficam as marcas de vínculo [ca-venda:id] e [ca-baixa:id], que garantem que nenhuma venda ou baixa seja duplicada
• Debug: registra as chamadas à API em Registros do Módulo
• Cadastrar produtos como: serviço ou produto no Conta Azul
• Baixa automática no Conta Azul: registra o recebimento quando a fatura é paga no WHMCS
• Conta financeira da baixa: conta que recebe as baixas, no formato nome #id. Apenas contas ativas são listadas, porque uma conta desativada é recusada pela API. Sem seleção, o módulo usa a conta padrão do Conta Azul e, na falta dela, a primeira conta ativa
• Categoria financeira da venda e Centro de custo da venda: classificação aplicada às vendas
• Sincronizar notas fiscais: liga a consulta diária das notas emitidas no Conta Azul
• Tipo de nota a consultar: NFS-e, NF-e ou ambas
• Período da consulta em dias: dias retroativos consultados a cada sincronização
• Enviar estatísticas de uso: telemetria identificada opcional

Acesse Addons > Gofas Conta Azul e clique em Obter Autorização. Você será levado ao Conta Azul e, ao confirmar, volta ao WHMCS com a mensagem de sucesso.

A primeira autorização é manual por exigência da API. Depois disso a renovação acontece sozinha pelo cron do WHMCS e você não precisa voltar a essa tela, a menos que reconfigure o módulo. Se a renovação falhar, o módulo exibe um aviso na página do módulo pedindo nova autorização.

A primeira carga de clientes e serviços roda em lote pelo cron, para não sobrecarregar o servidor. O andamento aparece na página do módulo, com a contagem de clientes e serviços já processados. O botão Sincronizar agora força o processamento do próximo lote.

Em Addons > Gofas Conta Azul você acompanha a situação do token, o andamento da sincronização, a relação de contas financeiras com a que está em uso e a tabela que relaciona cada nota fiscal com a fatura de origem, com links para o PDF e o XML.

Com a sincronização de notas fiscais ligada, o cliente passa a ver Minhas Notas Fiscais no menu Faturamento, com as notas das próprias faturas e os links de download. A listagem continua disponível ao cliente mesmo que a licença do módulo esteja inativa, para que uma pendência comercial do provedor nunca prejudique o cliente final.

• Campo personalizado CPF/CNPJ: criado automaticamente se você ainda não tiver um. Pode ser um campo único onde o cliente informa qualquer um dos dois documentos, ou dois campos separados. O módulo identifica os campos pelo nome e reconhece o documento pela quantidade de dígitos. O Conta Azul exige o documento, então o campo nasce obrigatório e visível no cadastro
• Endereço: preencha no formato padrão do WHMCS, com logradouro e número na mesma linha, no campo Endereço 1, por exemplo "Avenida Brasil, 1234"
• Campo personalizado Complemento: se existir um campo de cliente chamado Complemento, ele é enviado junto com o endereço
• Campo personalizado do ID Conta Azul: criado automaticamente e visível apenas para administradores. É ele que associa cada cliente do WHMCS à pessoa correspondente no Conta Azul, preenchido na primeira sincronização de cada cliente. Se você já usava os dois sistemas antes de instalar o módulo, pode preencher esse campo com os IDs existentes para aproveitar os cadastros e evitar cadastros repetidos
• A API do Conta Azul não emite notas fiscais, apenas consulta. A emissão continua sendo feita dentro do ERP. O módulo concilia as notas já emitidas com as faturas do WHMCS
• Janela de consulta da NFS-e: a API aceita no máximo 15 dias por requisição. O módulo divide o período configurado em janelas automaticamente
• Consistência eventual: a parcela em contas a receber só existe depois que a venda é aprovada no Conta Azul. A propagação leva até dois minutos. Por isso a baixa entra numa fila reprocessada pelo cron
• O cron do WHMCS precisa estar ativo. É ele que renova a autorização da API, processa as filas, sincroniza as notas fiscais e revalida a licença
• Sempre faça backup antes de alterar qualquer coisa no seu sistema
• Personalizações podem ser feitas sem editar o código original, via hooks, mantendo o módulo atualizável

Consigo enviar lançamentos retroativos para o Conta Azul?

Não. O botão Sincronizar agora envia apenas clientes e serviços. As vendas são criadas pelos hooks de fatura gerada ou fatura paga, conforme a opção Quando criar a venda, então só chegam ao Conta Azul as faturas que passarem por esse evento depois da instalação do módulo. Faturas anteriores precisam ser lançadas manualmente no Conta Azul.

A opção de NFS-e aparece na fatura ou é uma nova página na área do cliente?

É uma nova página na área do cliente, em Faturamento > Minhas Notas Fiscais. A fatura não é alterada. O menu só aparece quando a opção Sincronizar notas fiscais está ligada nas configurações do módulo. Cada cliente vê apenas as notas das próprias faturas, com os links de PDF e XML.

O cron que envia essas informações é o diário ou o que roda a cada hora?

É o cron principal do WHMCS, pelo hook AfterCronJob, executado em toda rodada do cron (a cada 5 minutos na configuração padrão). Em cada rodada o módulo renova o token da API, processa até 20 itens da fila de vendas, até 20 clientes e 20 serviços da sincronização em lote e a fila de baixas. A consulta de notas fiscais é a única com trava própria: roda no máximo uma vez por dia.

O histórico de versões fica no final desta página.

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 - #54 enhancement

Melhorias:

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

Melhorias:

• Estatísticas de uso com padrão desmarcado - #52

Correções:

• callback.php: redirects de erro usam caminho relativo e apontam para URL inexistente - #48 bug

Melhorias:

• Atualização importante de segurança - #51
• callback: receptor de acesso direto roda antes do guard e interfere entre módulos co-instalados - #50
• Suporte a clientes estrangeiros (tipo_pessoa Estrangeira) na sincronização com o Conta Azul - #49
• callback.php: guard por basename faz o fluxo OAuth do gca rodar em callbacks de outros módulos - #47

Melhorias:

• Suporte a clientes estrangeiros (tipo_pessoa Estrangeira) na sincronização com o Conta Azul - #49

Correções:

• Telefone internacional (+55) e 0800 abortam a sincronização da pessoa na Conta Azul - #46 bug

Melhorias:

• Reconhecer/linkar pessoa já existente na CA por documento ou email - #45 enhancement

Melhorias:

• Sincronizar status Ativo/Inativo do cliente com o Conta Azul - #42 enhancement
• readme: incluir seção Perguntas frequentes - #39
• Requisitos do readme desatualizados para a distribuição atual - #38

Correções:

• Trocar Client ID/Secret nao exige reautorizacao (token antigo continua valido) - #43 bug
• Clientes sem CPF/CNPJ geram POST inválido em /v1/pessoas - #41 bug
• Sincronização em lote pula clientes que falham e nunca os reprocessa - #40 bug

Melhorias:

• Reorganização interna de arquivos para o empacotamento da próxima versão - #37
• Padronizar o readme com os botões de versão, downloads e suporte - #36

Melhorias:

• v3.1.1: remover arquivos orfaos sem autenticacao e recriar os campos personalizados na ativacao - #35

Melhorias:

• v3.1.0: baixa automatica de parcelas, classificacao e consulta de notas fiscais - #34

Melhorias:

• v3.0.0 Fase 4: readme/changelog padrao, screenshot versionado, empacotamento - #33
• v3.0.0 Fase 3: fix ativacao PHP 8.1+, telemetria/consent, CURLOPT_TIMEOUT, licenca ionCube - #32
• v3.0.0 Fase 2: camada de dados api-v2 (pessoas, venda) e remapeamento de payload - #31
• v3.0.0 Fase 1: camada de autenticacao OAuth2 Cognito (auth.contaazul.com) - #30
• v3.0.0: reescrita completa para nova API Cognito (legado descontinuado em nov/2025) - #29
• Automatização do changelog - #27 enhancement

Melhorias:

• User-Agent no header da requisição ao verificar atualizações no gofas.net - #26 enhancement

Melhorias:

• Cria a venda quando a invoice for paga no WHMCS - #24 enhancement
• Criar o cliente no CA quando for cadastrado no WHMCS - #23 enhancement
• Permitir vinculo de serviço do CA com múltiplos produtos no WHMCS - #22 enhancement
• Permitir configurar qual será a DATA da venda no CA [Data de criação da invoice | Data do pagamento] - #20 enhancement
• Importar clientes do WHMCS para CA - #19 enhancement
• Adicionar "Última verificação em xx/xx/xxxx às 00:00h" - #17 enhancement
• Pega campo "Complemento" pelo nome do client custom field - #15 enhancement
• Adicionar opção "Debug - Ativar/Desativar" - #13 enhancement
• Configuração associar CA IDs aos WHMCS Services IDs - #11 enhancement
• versão do módulo no debug - #10 enhancement
• administrador do WHMCS - #9 enhancement
• Gerar venda quando a fatura é criada - #7 enhancement
• Criar campo personalizado de cliente ao ativar o módulo - #6 enhancement
• Nova opção: Definir nota administrativa padrão das vendas - #4 enhancement
• ID de serviço geral - #2 enhancement
• Melhoria na aplicação de descontos - #1 enhancement

Correções:

• Verificar Access Token duplicado ao rodar o cron - #14 bug
• configurar adicionais dos produtos ao criar a venda - #5 bug