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.
- 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
- 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, e 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 a 8.4, com cURL e 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
- Baixe o arquivo em https://gofas.net/gcad/ e descompacte.
- Copie a pasta
modules/addons/gofascontaazulpara o diretóriomodules/addons/da sua instalação WHMCS. - Ative o módulo em
Configurações > Módulos Addons. - 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.
- Faça login em portaldevs.contaazul.com e clique em Criar Aplicação.
- Preencha o nome e a descrição.
- 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. - Em Tipo de software escolha Online/Nuvem, em Segmento do Software escolha Pagamentos e clique em Salvar e finalizar.
- 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, e 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, e 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.
Veja changelog.md.
Dúvidas, sugestões e problemas: https://gofas.net/contato/
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: