README

Biblioteca PHP para integração com o webservice da Caixa Econômica Federal para criação, registro e consulta de boletos bancários.

🔒 Segurança - Versão 1.2.0

Todas as vulnerabilidades críticas foram corrigidas!

✅ Verificação SSL/TLS habilitada ✅ Validação robusta de entrada de dados ✅ Proteção contra XML Injection ✅ Tratamento seguro de erros ✅ Timeouts configurados

Ver detalhes completos de segurança | Ver changelog

🔍 Sobre

WSCaixa é uma biblioteca PHP leve (sem dependências externas) que facilita a integração com o webservice SOAP da Caixa Econômica Federal para gestão de boletos bancários registrados. Ideal para sistemas de e-commerce, ERPs e aplicações que necessitam emitir boletos bancários.

Baseado no código original de: wagnermengue

✨ Características

✅ Inclusão de Boletos: Registro de novos boletos na Caixa
✅ Consulta de Boletos: Consulta de boletos já registrados
✅ Sem Dependências: Usa apenas bibliotecas nativas do PHP
✅ Autenticação SHA256: Geração automática de hash de autenticação
✅ Suporte a Descontos: Configuração de descontos no boleto
✅ Juros e Multa: Configuração de juros e multa por atraso
✅ SOAP XML: Construção automática de requisições SOAP
✅ Ambiente Produção/Homologação: Suporte a ambos ambientes
🔒 Segurança Hardened: Verificação SSL, validação de dados e proteção contra injeções
🔒 Validação Automática: CPF, CNPJ, valores e formatos validados automaticamente
🔒 Sanitização XML: Proteção contra XML Injection attacks

📦 Requisitos

PHP >= 5.4
Extensões PHP:
- php-curl - Para requisições HTTP
- php-xml - Para manipulação de XML
- php-soap - Para comunicação SOAP
- php-json - Para manipulação JSON

🚀 Instalação

Via Composer

composer require cassone200/wscaixa

Instalação Manual

git clone https://github.com/cassone200/wscaixa.git
cd wscaixa
composer install

🎯 Uso Rápido

<?php
require_once 'vendor/autoload.php';

use WSCaixa\WSCaixa;

// Dados do boleto
$dadosBoleto = [
    'urlIntegracao' => 'https://barramento.caixa.gov.br/sibar/ManutencaoCobrancaBancaria/Boleto/Externo',
    'codigoCedente' => '123456',
    'nossoNumero' => '14000000000000001',
    'dataVencimento' => '2025-12-31',
    'valorNominal' => 100.00,
    'cnpj' => '12345678000199',
    // ... outros dados
];

// Criar instância
$wsCaixa = new WSCaixa($dadosBoleto);

// Registrar boleto
$resultado = $wsCaixa->realizarRegistro();

// Verificar resultado
if (isset($resultado['COD_RETORNO']) && $resultado['COD_RETORNO'] == '0') {
    echo "Boleto registrado com sucesso!";
    echo "Nosso Número: " . $resultado['NOSSO_NUMERO'];
} else {
    echo "Erro: " . $resultado['MENSAGEM'];
}

📚 Documentação

A documentação completa está disponível na pasta /docs:

API Reference - Documentação detalhada de classes e métodos
Arquitetura - Visão geral da arquitetura do projeto
Exemplos - Exemplos práticos de uso
Configuração - Guia de configuração detalhado
Segurança - Boas práticas e considerações de segurança
Melhorias Propostas - Roadmap e melhorias futuras

📖 Exemplos

Registrar Boleto com Desconto

$dadosBoleto = [...];

// Definir descontos
$descontos = [
    [
        'DATA_DESCONTO_1' => '2025-11-15',
        'VALOR_DESCONTO_1' => 10.00
    ]
];

$wsCaixa = new WSCaixa($dadosBoleto, $descontos);
$resultado = $wsCaixa->realizarRegistro();

Consultar Boleto Existente

$dadosConsulta = [
    'codigoCedente' => '123456',
    'nossoNumero' => '14000000000000001',
    // ... outros dados necessários
];

$wsCaixa = new WSCaixa($dadosConsulta, null, 'CONSULTA_BOLETO');
$resultado = $wsCaixa->consultarRegistro();

Para mais exemplos, consulte docs/EXAMPLES.md.

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

Fazer um Fork do projeto
Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Adiciona nova feature')
Push para a branch (git push origin feature/MinhaFeature)
Abrir um Pull Request

👨‍💻 Autor

Thiago Edson

📝 Licença

Este projeto está sob a licença ISC. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

Wagner Mengue - Código base original
Caixa Econômica Federal - Documentação da API

📞 Suporte

Para reportar bugs ou solicitar features, por favor abra uma issue.

⚠️ Nota: Esta biblioteca foi desenvolvida para uso interno e não possui vínculo oficial com a Caixa Econômica Federal.

cassone200 / wscaixa

Maintainers

Details