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

• 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

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, 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/

Contrato de licença de uso