MÓDULO COBREGRÁTIS WHMCS v1.0 ÍNDICE SOBRE... 2 PRINCIPAIS FUNCIONALIDADES... 2 REQUISITOS... 2 INSTALAÇÃO... 2 CONFIGURAÇÃO INICIAL... 3 CONFIGURAÇÕES OPCIONAIS... 5 Taxa Boleto... 5 Demonstrativo Boleto... 5 Prazo Vencimento... 6 Ajustar Fatura Vencida... 6 Exibir Texto Fatura Vencida... 7 Instruções Boleto... 7 Destinatário Boleto... 8 Registrar Boleto... 8 Notificar Cliente... 9 Campo CPF/CNPJ... 10 Redirecionar... 11 URL do botão... 11 DEBUG... 12 RETORNO AUTOMÁTICO... 13 LOG RETORNO AUTOMÁTICO... 14 SUPORTE/DÚVIDAS... 15 PERGUNTAS/RESPOSTAS... 15 1
SOBRE Módulo desenvolvido utilizando a API oficial http://bit.ly/qhrwkc da CobreGrátis que permite emissão/baixa automática de boletos no WHMCS. PRINCIPAIS FUNCIONALIDADES - Fácil integração dispensando usuário/senha de acesso; - Retorno Automático após quitação do boleto; - Possibilidade de adicionar taxa sobre o boleto; - Controle inteligente sobre o vencimento da fatura; - Instruções do boleto; - Destinatário/Demonstrativo do boleto personalizado; - Notificação automática via e-mail após o cliente acessar/gerar o boleto; - Redirecionamento automático após o cliente acessar a fatura; - Personalização do botão pagar agora via URL. REQUISITOS - Conta CobreGrátis Premium ou Max - WHMCS (qualquer versão/charset); INSTALAÇÃO Após efetuar o pedido/pagamento http://cobregratis.edvan.com.br/ você receberá o e-mail com as instruções de instalação/configuração. Descompacte o arquivo cobregratis.zip e envie as pastas/arquivos para raiz do seu WHMCS. Lembre-se de cadastrar a licença fornecida pela Edvan.com.br no arquivo licencas.php que fica dentro da pasta /includes/hooks/ Em seguida acesse http://seuwhmcs/admin/configgateways.php ou clique em Setup Payments Payment Gateways Em Activate Module localize o módulo Boleto via CobreGrátis e clique em Activate Módulo instalado. 2
CONFIGURAÇÃO INICIAL 1) Acesse https://app.cobregratis.com.br/myinfo insira seu e-mail/senha. Copie o TOKEN DE AUTENTICAÇÃO Insira o TOKEN DE AUTENTICAÇÃO no módulo WHMCS campo Token: 2) Acesse https://app.cobregratis.com.br/services clique em Incluir Novo... Siga as orientações da página... Ao chegar à opção INTEGRAÇÃO Marque a opção: 3
Na página de configuração do módulo WHMCS, copie a sugestão de código que foi gerada automaticamente: d41d8cd98f00b204e9800998ecf8427e E insira em Código de Segurança Por fim no campo Código WebHook clique em URL Você obterá a URL de notificação: Caso a URL apresentada esteja inválida utilize o padrão: http://url-do-whmcs/modules/gateways/callback/retornocobregratis.php Em URL-DO-WHMCS substitua pela localização do seu sistema. Copie a URL e insira no campo URL para Webhook de pagamento de boletos Configuração inicial realizada! Agora você poderá emitir boletos via CobreGrátis. 4
CONFIGURAÇÕES OPCIONAIS: - Taxa Boleto: permite cobrar uma taxa que será somada ao total da fatura. Caso opte por não cobrar taxa deixe o campo em branco ou com valor 0.00 ====================================================================================== - Demonstrativo Boleto: configuração especial que será informada diretamente na linha Demonstrativo do boleto bancário. É possível utilizar 3 opções! 1- Nome da empresa 2 Nome da Empresa + ID da fatura. 5
3 Nome da Empresa + ID da fatura + 1ª Linha da fatura. ====================================================================================== - Prazo Vencimento: possibilita acrescentar um prazo ( em dias ) sobre o vencimento da fatura. Exemplo, a fatura teve vencimento em 05/09/2012 Ao acessar o boleto o vencimento terá acréscimo de 1 dia, 06/09/2012 ====================================================================================== - Ajustar Fatura Vencida: Se essa opção for ativada a data de vencimento do boleto será data corrente/atual que o cliente acessar a fatura assim facilitando o pagamento do boleto atualizado. Essa condição só irá funcionar se a fatura estiver vencida! Vale lembrar que a data de vencimento da fatura = data de vencimento do boleto. No exemplo abaixo a fatura venceu em 28/09/2012 E a data corrente/atual é 1/10/2012 6
A data de vencimento do boleto será 01/10/2012. Se a data corrente/atual for sábado ou domingo será acrescentado 2 dias para sábado e 1 dia para Domingo, assim a fatura sempre cairá em um dia útil. ====================================================================================== - Exibir Texto Fatura Vencida: ao marcar essa opção o cliente será notificado que a fatura está vencida e informará o novo vencimento. ====================================================================================== - Instruções Boleto: será possível customizar as instruções do boleto. 7
- Destinatário Boleto: personalização que possibilita configurar o Destinatário (sacado) do Boleto. É possível utilizar 3 opções baseadas nos dados do Profile/Perfil de cada cliente. 1 Nome (First Name) e Sobrenome (Last Name) do Cliente. 2 - Empresa (Company Name) do Cliente. 3 - Empresa + Nome/Sobrenome do Cliente. Se porventura o CompanyName (nome da empresa) estiver em branco/vazio as opções 2 e 3 não funcionaram e será atribuído por padrão a opção 1. ====================================================================================== - Registrar Boleto: irá informar no campo Transações ( cliente ) / Transactions ( admin ) a data/hora que o cliente gerou o boleto. Cliente: Admin: 8
- Notificar Cliente: o cliente receberá via e-mail de cadastro (profile) os dados do boleto ( Linha Digitável, Vencimento, Valor, URL do boleto e etc... ) Será possível personalizar o assunto do e-mail, campo Assunto Email e a possibilidade do administrador receber uma cópia oculta da mensagem ao informar o endereço de e-mail no campo Cópia oculta. Caso a opção Notificar Cliente esteja habilitada e o campo Assunto Email esteja em branco será assumido o padrão Boleto para Pagamento. O e-mail será enviado utilizando a plataforma da Cobre Grátis bem como os dados cadastrais da conta: 9
- Campo CPF/CNPJ: informar no boleto o CPF/CNPJ do seu cliente. Para isso você precisa ter/criar um Custom Field. E informar o Field Name ( nome do campo ) no Campo CPF/CNPJ Além do que o cliente ou administrador precisa ter armazenado o valor do CPF/CNPJ. O sistema da Cobre Grátis só aceita CPF/CNPJ válidos! Sugiro que só ative essa opção caso você valide o CPF/CNPJ. 10
- Redirecionar: permite o redirecionamento automático para o boleto bancário quando o cliente acessar a fatura. No campo Tempo você define o tempo em segundos para o redirecionamento. Caso o campo esteja em branco/vazio será assumido o valor 0. O redirecionamento automático também irá funcionar caso o cliente efetuar um pedido e no checkout esteja configurada a opção Automatically forward the user to the payment gateway que fica configurado em General Settings, aba Ordering opção Auto Redirect on Checkout ====================================================================================== - URL do botão: é possível customizar o botão de pagamento através de uma imagem via URL. Caso o campo URL do botão esteja em branco será assumido o valor padrão ( $_LANG["invoicespaynow"] = "Pagar agora"; ) disponível no seu arquivo de linguagem local. 11
DEBUG: O módulo disponibiliza 2 tipos de debug: - Debug Módulo/Sistema = fornece as variáveis do módulo, sistema e dados do cliente. - Debug CobreGrátis - Envio/Retorno = exibe os dados enviados para o CobreGrátis e o retorno dos dados via XML/JSON. O debug funciona apenas na visualização de uma fatura/invoice, exemplo: http://seuwhmcs.com/viewinvoice.php?id=xxxx&debugsistema=licencacobregratis XXXX = representa o número da fatura/invoice do cliente; LicencaCobreGratis = Licença fornecida pela Edvan.com.br, que você inseriu no arquivo licencas.php dentro da pasta /includes/hooks/ 12
RETORNO AUTOMÁTICO Acesse https://app.cobregratis.com.br/bank_billets - Baixa Manual: Clique no boleto que deseja quitar... Clique no botão Quitar Boleto - Baixa Automática: Clique em Enviar Arquivo... E siga as instruções da página. Dúvidas em relação aos processos citados favor entrar em contato com o suporte da CobreGrátis. Observações: O módulo não depende da API do WHMCS e não necessita de liberação IP para retorno automático ( baixa na fatura ). A quitação do boleto ( manual ) ou automática ( processamento via arquivo de retorno ) só será possível se: 1) A fatura no WHMCS estiver com status Unpaid/Em Aberto; 2) Se as configurações de INTEGRAÇÃO: - Opção Usar Integração... estiver marcada; - Código de Segurança for igual ao Código WebHook cadastrado no módulo. - URL para webhook estiver válida. 3) Se seu servidor/firewall não esteja bloqueando o WebHook POST da CobreGrátis. 4) Módulo CobreGrátis estiver ativo no WHMCS. 5) Não existir autenticação/proteção da pasta (/modules/gateways/callback/). 13
LOG RETORNO AUTOMÁTICO Você poderá acompanhar os logs dos retornos de cada transação através do menu Billing opção Gateway Log ou http://seuwhmcs/admin/gatewaylog.php O campo Debug Data armazena os dados do Retorno, e o Result o status. Será possível encontrar 3 resultados. 1- Baixa Fatura Fatura foi quitada normalmente sem erros. 2- Erro Fatura Paga ou Cancelada Caso a fatura esteja com status Paga (Paid) ou Cancelada (Cancelled) não será possível processar o retorno. Assim evitando duplicidade ou crédito indevido! 3- Erro Fraude/Análise Apesar do sucesso no retorno o boleto foi pago com valor inferior ao valor total da fatura. Exemplo a fatura era de R$ 150,00, o cliente pagou R$ 15,00. Algumas ferramentas possibilitam manipulação no boleto e com isso o cliente pode manipular o valor do boleto ou durante a confirmação manual via CobreGratis você informou um valor incorreto na quitação. Será acrescentado o valor de 0.00 na transação 14
SUPORTE/DÚVIDAS Dúvidas, sugestões ou problemas referente ao módulo CobreGrátis para WHMCS entre em contato através do link http://suporte.edvan.com.br Dúvidas de utilização do sistema CobreGrátis http://suporte.cobregratis.com.br PERGUNTAS/RESPOSTAS P= É possível cadastrar a logomarca da empresa no módulo? R= Não! Será necessário logar no site da CobreGrátis. Vá no Menu Serviços clique em Exibir. Em seguida clique em Enviar a Logomarca. P= O código WebHook cadastrado no módulo pode ser diferente do gerado automaticamente? R= Sim! A sugestão é apenas para facilitar. Caso altere o Código WebHoook no módulo lembre-se de alterar também no site da cobregrátis. P= Ao tentar QUITAR um boleto (baixa no boleto) manual ou automático surgiu um erro Application Error. R= Entre em contato com a CobreGrátis http://suporte.cobregratis.com.br P= É possível à quitação automática do boleto sem precisa enviar o arquivo de retorno? R= Não, você precisa baixar o arquivo de retorno no seu banco e enviar para o sistema da CobreGrátis. P= Quando ocorre a autenticação/validação da licença? R= Ocorre a cada 15 dias, e caso o servidor de autenticação esteja fora do ar sua licença não deixará de funcionar. Sua licença continuará válida durante 5 dias até que consiga validar/autenticar. P= Desejo alterar o IP, URL do WHMCS será necessário alterar minha licença? R= Sim, visite o link http://bit.ly/yknp28 e confira como resetar sua licença. P= Caso eu esqueça de resetar a licença o módulo ficará inutilizado? R= Sim, a página de pagamento (/configgateways.php) irá apresentar um erro, o retorno/baixa não funcionará mas seu cliente conseguirá efetuar normalmente o pagamento do boleto. P= Posso utilizar o módulo em 2 WHMCS distintos? R= Não, entre em contato com http://suporte.edvan.com.br/ e te daremos um desconto especial. 15