WSBoletoSantander
WS Boleto Santander é um conjunto de classes criadas para facilitar a integração entre aplicativos feitos em PHP e a geração de boletos online no banco Santander.
Índice
Funcionalidades
- Inclusão/Registro de boletos
- Sondagem de boletos registrados
- Tratamento de erros de comunicação com o serviço do Santander
Requisitos
- PHP 5.6 ou superior
Suporte para PHP 5.6 e 7.0 terminará em dezembro de 2018.
É fortemente recomendável que se migre para versões superiores.
Com as seguintes extensões ativas:
- cURL
- DOM
- XmlWriter
Guia Básico de Uso
Instalação da Biblioteca
WS Boleto Santander pode ser instalado via Composer usando o comando:
composer require tiexpert/ws-boleto-santanderO Composer automaticamente verificará seu ambiente para determinar se seu servidor pode rodar a biblioteca WSBoletoSantander.
Montagem do Boleto
Para registrar o boleto serão necessárias as seguintes classes:
use TIExpert\WSBoletoSantander\Boleto;
use TIExpert\WSBoletoSantander\BoletoSantanderServico;
use TIExpert\WSBoletoSantander\ComunicadorCurlSOAP;
use TIExpert\WSBoletoSantander\Convenio;
use TIExpert\WSBoletoSantander\InstrucoesDeTitulo;
use TIExpert\WSBoletoSantander\Pagador;
use TIExpert\WSBoletoSantander\Titulo;Agora, em seu script, defina o convênio.
$convenio = new Convenio();Se o arquivo de configuração estiver já pronto, as informações de convênio já estarão corretas. Caso não, você pode definí-las agora.
$convenio->setCodigoBanco("0033");
$convenio->setCodigoConvenio("123456");Então, defina as informações do pagador do boleto.
$pagador = new Pagador($tipoDoc, $numeroDoc, $nome, $endereco, $bairro, $cidade, $UF, $CEP);Se não desejar instanciar Pagador já com os dados é possível. Pagador tem um construtor padrão sem argumentos e cada propriedade tem um método set para definir valor como, por exemplo, setNome, setCidade, setCEP,etc.
Por fim, um objeto composto que são as informações do título bancário.
Comece definindo as instruções do título.
$instrucoes = new InstrucoesDeTitulo();As instruções mais corriqueiras são configuráveis via config.ini. Mas, todas as propriedades como $multa, $multarApos, $juros, $tipoDesconto, $valorDesconto, $dataLimiteDesconto, $valorAbatimento, $tipoProtesto, $protestarApos, $baixarApos tem métodos set.
Propriedades que são representações de data devem ser usadas instâncias de DateTime, ou uma string no formato "dmY". Exemplo: $instrucao->setDataLimiteDesconto("28032017"), ou seja, o desconto deve ser aplicado até 28/03/2017.
Enfim, usaremos essas instruções para compor as informações do título na classe Titulo.
$titulo = new Titulo($valor, $nossoNumero, $seuNumero, $dataVencimento, $mensagem, $dataEmissao, $especie, $instrucoes);Assim como as demais classes, todas as propriedades têm seus respectivos set.
Importante salientar que toda instância de Título deve conter uma instância de InstrucoesDeTitulo. Caso contrário, um erro acontecerá na exportação do XML.
Agora, com todas as partes prontas, basta montar o boleto.
$boleto = new Boleto($convenio, $pagador, $titulo);Registrando o Boleto
Com o boleto já montado, ou seja, com seus objetos e campos populados, deve-se fazer o registro em dois passos: solicitar um tíquete de registro de boleto e depois ratificá-lo.
Primeiramente, vamos preparar o serviço injetando um comunicador no cliente do serviço.
$comunicador = new ComunicadorCurlSOAP ();
$svc = new BoletoSantanderServico($comunicador);Agora, devemos solicitar um tíquete com o método solicitarTicketInclusao.
Qualquer erro que o WebService retornar será lançado como um Exception pelo método.
$ticket = $svc->solicitarTicketInclusao($boleto);Se nada deu errado, então, uma instância de Ticket é criada com uma autenticação de segurança do banco. Nesse momento, será necessário determinar um número sequencial único (NSU) que será a identificação de seu boleto. Para cada registro de boleto, este NSU deverá ser único por dia e por convênio, ou seja, não se pode usar o mesmo NSU no mesmo dia para o mesmo convênio.
$ticket->setNsu(1);Com o tíquete pronto, basta passá-lo como parâmetro no método incluirTitulo.
$resultado = $svc->incluirTitulo($ticket);
Este método retorna true em caso de registro com sucesso, ou false. Embora, em casos de falha, o mais provável é que seja lançado um Exception com o motivo da falha.
Questões Importantes
Antes de qualquer tentativa de comunicação com o banco, deve-se primeiro pedir para eles cadastrarem seu certificado digital lá. Sem isso, não tem como o serviço do banco saber a autenticidade de quem o está requisitando.
Outra coisa, seu certificado digital também deve respeitar algumas regras.
Primeiro, ele deve ser do tipo cliente ou ambos, ou seja, ele deve de qualquer forma prover meios de comprovar sua identidade.
Além disso, seu certificado deve ter 4 informações importantes:
- O tamanho da chave chave-pública deve ser de 2048 bits.
- Deve conter número de série.
- Possuir uma impressão digital.
- E, um Common Name.
Para facilitar o processo de comunicação com o serviço do Santander, é interessante baixar o certificado da CA deles, que atualmente é Entrust Root Certificate Authority—G2.
Ele pode ser encontrado aqui: https://www.entrust.com/get-support/ssl-certificate-support/root-certificate-downloads/
Também será necessário exportar seu certificado digital para o formato PEM.
Com ambos os arquivos, configure-os no arquivo config.ini do WSBoletoSantander.
Exemplo:
[certificado]
arquivo = "/var/www/html/meu_certificado_digital.pem"
senha = "Senha do meu certificado"
tipo_arquivo = "PEM"
arquivo_ca = "/var/www/html/entrust_g2_ca.cer"Mais Documentação
Em breve, na Wiki do projeto.
Licença
WS Boleto Santander é distribuído sob a Licença Apache 2.0 e não pode ser usado de forma diferente que a expressa por essa licença.
Maiores informações, acesse http://www.apache.org/licenses/LICENSE-2.0.
Aviso Legal
O autor deste projeto não tem nenhuma afiliação, vínculo ou qualquer outra relação com o banco Santander S.A.
O software é oferecido aqui "como está" e nenhuma garantia é proferida. Portanto, o uso deste software é de inteira responsabilidade do utilizador.