Taffarel.dev - Módulo Gateway Sicoob - Múltiplas Contas

Gateway Sicoob - Múltiplas Contas para Perfex CRM

Integre o Sicoob ao seu Perfex CRM e automatize completamente a cobrança de faturas com suporte a Boleto Bancário e PIX. Este módulo profissional permite cadastrar múltiplas contas Sicoob com credenciais, certificados e configurações independentes, oferecendo total flexibilidade para empresas com diferentes unidades, filiais ou CNPJs. Cada fatura pode utilizar uma conta diferente, com formas de pagamento configuráveis individualmente.

Múltiplas Contas com Configuração Independente

Cadastre quantas contas Sicoob precisar. Cada conta possui suas próprias credenciais OAuth2, certificado digital PFX, chave PIX, dados bancários, regras de juros, multa, desconto e webhooks. Na hora de emitir uma fatura, basta selecionar qual conta e qual forma de pagamento utilizar — Boleto, PIX ou ambos simultaneamente.

Boleto Bancário Completo

• Geração Automática — Ao salvar a fatura, o boleto é gerado automaticamente via API do Sicoob (v3) com código de barras, linha digitável e PDF pronto para impressão
• Juros de Mora Configuráveis — Defina o tipo de juros (valor por dia, taxa mensal ou isento), a data de início da cobrança e o valor/percentual
• Multa por Atraso — Configure multa fixa ou percentual com data de aplicação personalizada
• Desconto por Antecipação — 7 modalidades de desconto: valor fixo até data, percentual até data, valor por dia corrido/útil antecipado, percentual por dia corrido/útil antecipado
• Abatimento — Configure valor de abatimento por fatura individualmente
• Instruções Personalizadas — Até 5 linhas de instrução no boleto com suporte a merge fields dinâmicos como {invoice_number}, {invoice_total}, {boleto_valor_multa} e outros
• Prazo de Pagamento — Defina quantos dias após o vencimento o boleto ainda pode ser pago
• Visualização e Download — O cliente pode visualizar o PDF do boleto diretamente no navegador ou fazer download

PIX com Cobrança Vencimento (COBV)

• QR Code Automático — Geração automática de QR Code em imagem PNG vinculado à fatura
• Copia e Cola — Código PIX Copia e Cola disponível para o cliente copiar com um clique
• Cobrança com Vencimento — Utiliza a modalidade COBV (cobrança com vencimento) da API PIX do Sicoob, permitindo configurar data de vencimento e validade após o vencimento
• Até 3 Faixas de Desconto — Configure até 3 descontos escalonados por data para incentivar o pagamento antecipado (ex: 10% até 5 dias antes, 5% até 3 dias antes, 2% até 1 dia antes)
• Juros e Multa no PIX — 8 modalidades de juros (valor/dia, taxa/mês, taxa/ano e variações) e multa fixa ou percentual
• Abatimento no PIX — Suporte a abatimento por valor fixo ou percentual
• Informações Adicionais — Até 5 campos de informação adicional no PIX com merge fields dinâmicos para exibir dados da fatura, descontos e condições de pagamento
• Desconto Condicional Automático — Quando o cliente paga com desconto, o módulo insere automaticamente um item negativo "Desconto Condicional" na fatura e recalcula os totais

Webhooks com Confirmação Automática

• Webhook PIX — Cadastre o webhook diretamente pelo painel administrativo. Quando o cliente paga via PIX, o Sicoob notifica o sistema e o pagamento é registrado automaticamente na fatura
• Webhook Boleto — Cadastre o webhook para boletos. Ao compensar, o pagamento é confirmado automaticamente sem intervenção manual
• Gerenciamento Completo — Cadastre, consulte status e remova webhooks diretamente pela interface do módulo, sem precisar acessar o portal do Sicoob
• Webhook por Conta — Cada conta possui seus próprios webhooks independentes, identificados por hash único na URL
• Verificação em Tempo Real — Na página de pagamento do cliente, o sistema verifica o status do pagamento automaticamente a cada 3 segundos e atualiza a tela instantaneamente quando confirmado

Automações Inteligentes

• Geração Automática ao Salvar — A cobrança (Boleto e/ou PIX) é criada automaticamente ao salvar a fatura com o gateway Sicoob selecionado
• Geração ao Enviar — Se a cobrança não foi gerada ao salvar, ela é criada automaticamente ao enviar a fatura por e-mail
• Atualização Automática — Ao editar uma fatura, o boleto é cancelado e um novo é gerado com os dados atualizados. O PIX é atualizado via PATCH sem necessidade de novo QR Code
• Cancelamento Automático — Ao excluir ou cancelar uma fatura, a cobrança pode ser baixada automaticamente no Sicoob (configurável por conta)
• Regeneração Manual — Opção de forçar a recriação da cobrança diretamente pelo menu da fatura no painel administrativo, ideal para corrigir problemas ou reprocessar cobranças
• Comportamento Configurável por Conta — Defina individualmente se cada conta deve cancelar cobranças ao excluir faturas, ao marcar como cancelada, ou ao atualizar

Merge Fields para E-mails

O módulo disponibiliza campos personalizados nos templates de e-mail do Perfex CRM, permitindo incluir informações de pagamento diretamente nos e-mails de fatura enviados aos clientes:

• {invoice_sicoob_pix_copia_e_cola} — Insere o código PIX Copia e Cola no corpo do e-mail
• {invoice_sicoob_img_qrcode} — Insere a URL da imagem do QR Code PIX para exibição no e-mail

Página de Pagamento Exclusiva

O cliente acessa uma página de pagamento dedicada e responsiva com a identidade visual da sua empresa. A página exibe o valor da fatura, data de vencimento, status atual e abas para selecionar entre PIX e Boleto. No PIX, o QR Code é exibido em destaque junto com o código Copia e Cola com botão de copiar. No Boleto, a linha digitável é exibida com opções de visualizar e baixar o PDF. Ao efetuar o pagamento, a página é atualizada automaticamente exibindo a confirmação em tempo real.

Autenticação Segura com mTLS

O módulo utiliza autenticação mútua TLS (mTLS) com certificado digital PFX/P12, conforme exigido pela API do Sicoob. O certificado é enviado em todas as requisições, garantindo segurança de ponta a ponta. O token OAuth2 é gerenciado automaticamente com renovação inteligente 30 segundos antes da expiração, eliminando falhas por token expirado.

Ambiente Sandbox e Produção

Cada conta pode ser configurada independentemente como Sandbox ou Produção. Teste suas integrações e configurações no ambiente de homologação do Sicoob antes de ativar em produção, com total segurança e sem afetar cobranças reais.

Painel Administrativo Completo

• Listagem de Contas — Visualize todas as contas com nome, apelido, ambiente, chave PIX, status ativo/inativo e ações rápidas
• Formulário Multi-Abas — Configuração organizada em 4 abas: Dados Básicos, Configuração de Boleto, Configuração de PIX e Configuração de Webhook
• Teste de Token — Botão para testar a geração do token OAuth2 diretamente pelo painel, validando credenciais e certificado
• Ativar/Desativar Contas — Alterne o status de cada conta com um clique sem precisar editar
• Log de Atividades — Modo debug com registro detalhado de todas as operações, requisições API e respostas do Sicoob no log de atividades do Perfex CRM

Campos Personalizados na Fatura

O módulo cria automaticamente campos personalizados na fatura para controle granular de cada cobrança:

• Forma de Pagamento — Selecione Boleto, PIX ou ambos por fatura
• Conta Sicoob — Escolha qual conta utilizar (dropdown atualizado automaticamente)
• Desconto Boleto — Tipo, data e valor do desconto específico para cada boleto
• Desconto PIX — Até 3 faixas de desconto com dias de antecedência e valores individuais
• Abatimento — Valor de abatimento por fatura
• PIX Copia e Cola — Campo visível no portal do cliente com o código PIX

Validação de Dados do Cliente

Antes de gerar a cobrança, o módulo valida automaticamente se o cliente possui CPF/CNPJ, CEP, cidade e estado preenchidos. Campos personalizados para número do endereço e bairro são criados automaticamente na instalação, garantindo que os dados obrigatórios para a API do Sicoob estejam sempre disponíveis.

Compatibilidade com E-mail Financeiro

O módulo busca automaticamente o e-mail financeiro do cliente (campo personalizado customers_e_mail_financeiro) para incluir na cobrança. Caso não exista, utiliza o e-mail do contato principal.

Como Funciona

1. Instale o módulo no Perfex CRM e ative o gateway nas configurações de pagamento
2. Cadastre suas contas Sicoob com credenciais OAuth2, certificado PFX e chave PIX
3. Configure os webhooks para PIX e Boleto diretamente pelo painel
4. Crie uma fatura, selecione o gateway Sicoob, escolha a conta e a forma de pagamento
5. A cobrança é gerada automaticamente ao salvar — o cliente recebe o boleto e/ou QR Code PIX
6. O pagamento é confirmado automaticamente via webhook, sem intervenção manual

Requisitos

• Perfex CRM 3.0 ou superior
• Conta no Sicoob com acesso ao Portal Developer
• Certificado digital PFX/P12 para autenticação mTLS
• PHP 7.4 ou superior com extensão OpenSSL habilitada
• Chave PIX cadastrada no Sicoob (para cobranças PIX)

Suporte

Inclui 90 dias de suporte técnico após a compra. Para dúvidas, problemas ou solicitações, acesse a área de suporte em taffarel.dev.

Este módulo está licenciado sob a Licença MIT.