Integrações Efí: WHMCS

Se você utiliza a Efí para fazer suas cobranças pelo WHMCS ou deseja utilizar o sistema, este post é para você tirar suas dúvidas.

O WHMCS é um gerenciador financeiro e administrativo para empresas de hospedagem, auxiliando em todo o processo de cobrança. Para fazer a integração, confira em nossa documentação oficial os requisitos do sistema.

Ao realizar a integração, todas as cobranças geradas pelo módulo ficam disponíveis no painel da API da Efí. Quando o pagamento for confirmado, o status no seu painel administrativo WHMCS será atualizado automaticamente.

Para começar, faça o download  da última versão do módulo e siga os passos abaixo:

1. Descompacte o arquivo baixado;
2. Copie o arquivo gerencianetcharge.php e a pasta gerencianet_lib, disponíveis na pasta gn-api-whmcs de nosso módulo, para o diretório modules/gateways da instalação de seu WHMCS;
3. Copie o arquivo gerencianetcharge.php, disponível no diretório gn-api-whmcs/callback de nosso módulo, para o diretório modules/gateways/callback da instalação de seu WHMCS. Ele deve seguir o modelo modules/gateways/callback/gerencianetcharge.php; 
4. Copie o arquivo gerencianet.php, disponível no diretório gn-api-whmcs/hooks de nosso módulo, e cole no diretório /includes/hooks da instalação de seu WHMCS. Ele deverá seguir o modelo includes/hooks/gerencianet.php.

Após este procedimento, faça as configurações no módulo Efí para WHMCS:

1. Acesse o menu “Setup > Payments > Payment Gateway”;
2. No campo “Active Module”, escolha a opção “Efí”;
3. No formulário que será apresentado, preencha os dados de acordo com as informações encontradas na sua aplicação dentro do menu “API > Minhas Aplicações” da sua conta Efí e com as informações da cobrança. Em caso de dúvida, confira a documentação completa do módulo.

Como cancelar uma cobrança

Sempre que uma fatura for cancelada no WHMCS, ela é automaticamente cancelada na Efí.

Para cancelar a cobrança no WHMCS, siga os passos abaixo:

1. Acesse “Orders > List All Orders”;
2. Clique no ID da invoice desejada;
3. Em seguida, clique em “Cancel Order”.

Pronto! A cobrança será cancelada no WHMCS e na Efí.

Como alterar a data de vencimento da cobrança

Sempre que a fatura tem a data de vencimento modificada no WHMCS, esta informação também é atualizada na Efí.

Veja como alterar o vencimento da cobrança:

1. Acesse “Orders > List All Orders”;
2. Clique na ID da invoice;
3. Na sub-aba “Options”e em “Due Date” selecione a nova data de vencimento e clique em “Save Changes”.

Descontos no WHMCS

Nesta integração é possível gerar boletos considerando os descontos dos cupons promocionais fornecidos pelo WHMCS. O desconto escolhido no WHMCS (porcentagem, valor fixo, substituição de preço e isenção de tarifas) é convertido em reais e repassado à API Efí no momento da geração do boleto.

Além dos descontos fornecidos pelo WHMCS, é possível disponibilizar descontos exclusivos para os boletos gerados na Efí. Esta opção é configurada nos campos “Desconto do Boleto” e “Tipo de desconto” na conta Efí. Uma vez configurado, ele será exibido no boleto e, assim que for pago, o valor do pedido e da cobrança no WHMCS é atualizado considerando o desconto da Efí.

Os créditos que o usuário possui no WHMCS também são uma opção de desconto. Assim, caso você aplique um determinado crédito no pedido do WHMCS, a quantia é convertida em desconto no boleto Efí.

Erros Comuns de Integração

Antes da geração de uma cobrança alguns campos requisitados na integração passam por validação. Os erros que podem retornar são:

1. Nome Inválido: O nome informado pelo cliente final é muito curto. É necessário informar o nome completo.
2. E-mail Inválido: O e-mail informado pelo cliente final é inválido (não segue o padrão [email protected]) ou não existe.
3. Telefone Inválido: O telefone informado pelo cliente final não existe ou o DDD está incorreto.
4. Documento Inválido: O número do CPF ou CNPJ do cliente final é invalido.
5. Documento Nulo: O campo referente ao CPF e/ou CNPJ do cliente não existe no WHMCS ou não está preenchido.
6. Razão Social Inválida: A Razão Social é inválida. O cliente deve digitar no campo “Empresa” do WHMCS o nome empresarial que consta na Receita Federal.
7. Razão Social Nula: O campo “Empresa” do WHMCS não está preenchido.
8. Erro Inesperado: Houve algum erro na integração. Provavelmente você não preencheu todos os campos do módulo corretamente ou a versão do PHP do WHMCS não é compatível com a API Efí. Você deverá ativar o modo Debug do módulo para saber mais detalhes.

Ainda que nenhum destes erros de validação sejam retornados, a API Efí poderá retornar erros referentes à geração da cobrança. Para interpretar os retornos da API e, claro, corrigir possíveis erros de validação de dados ou outros similares, acesse a página “Interpretando Erros da API“.

Outros módulos

Além do módulo para WHMCS desenvolvido internamente por nossa equipe, a Efí possui um parceiro oficial que desenvolveu à parte um módulo para o WHMCS. A solução é homologada pela empresa e se preferir, você pode utilizá-lo:

Módulo Efí para WHMCS (cartão de crédito e boleto bancário) (desenvolvido por Maurício Gofas)

Para conhecer a documentação completa (incluindo imagens) do módulo de integração Efí com o WHMCS, clique aqui.

Se você ainda tem alguma dúvida, envie um ticket para nosso suporte.