, (*1)
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., (*2)
Índice
Funcionalidades
- [x] Inclusão/Registro de boletos
- [x] Sondagem de boletos registrados
- [x] Tratamento de erros de comunicação com o serviço do Santander
Requisitos
Suporte para PHP 5.6 e 7.0 terminará em dezembro de 2018., (*3)
É fortemente recomendável que se migre para versões superiores., (*4)
Com as seguintes extensões ativas:, (*5)
Guia Básico de Uso
Instalação da Biblioteca
WS Boleto Santander pode ser instalado via Composer usando o comando:, (*6)
composer require tiexpert/ws-boleto-santander
O Composer automaticamente verificará seu ambiente para determinar se seu servidor pode rodar a biblioteca WSBoletoSantander., (*7)
Montagem do Boleto
Para registrar o boleto serão necessárias as seguintes classes:, (*8)
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., (*9)
$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., (*10)
$convenio->setCodigoBanco("0033");
$convenio->setCodigoConvenio("123456");
Então, defina as informações do pagador do boleto., (*11)
$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., (*12)
Por fim, um objeto composto que são as informações do título bancário., (*13)
Comece definindo as instruções do título., (*14)
$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., (*15)
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., (*16)
Enfim, usaremos essas instruções para compor as informações do título na classe Titulo., (*17)
$titulo = new Titulo($valor, $nossoNumero, $seuNumero, $dataVencimento, $mensagem, $dataEmissao, $especie, $instrucoes);
Assim como as demais classes, todas as propriedades têm seus respectivos set., (*18)
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., (*19)
Agora, com todas as partes prontas, basta montar o boleto., (*20)
$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., (*21)
Primeiramente, vamos preparar o serviço injetando um comunicador no cliente do serviço., (*22)
$comunicador = new ComunicadorCurlSOAP ();
$svc = new BoletoSantanderServico($comunicador);
Agora, devemos solicitar um tíquete com o método solicitarTicketInclusao
., (*23)
Qualquer erro que o WebService retornar será lançado como um Exception pelo método., (*24)
$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., (*25)
$ticket->setNsu(1);
Com o tíquete pronto, basta passá-lo como parâmetro no método incluirTitulo
., (*26)
$resultado = $svc->incluirTitulo($ticket);, (*27)
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., (*28)
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., (*29)
Outra coisa, seu certificado digital também deve respeitar algumas regras., (*30)
Primeiro, ele deve ser do tipo cliente ou ambos, ou seja, ele deve de qualquer forma prover meios de comprovar sua identidade., (*31)
, (*32)
Além disso, seu certificado deve ter 4 informações importantes:, (*33)
1) O tamanho da chave chave-pública deve ser de 2048 bits., (*34)
, (*35)
2) Deve conter número de série., (*36)
, (*37)
3) Possuir uma impressão digital., (*38)
, (*39)
4) E, um Common Name., (*40)
, (*41)
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., (*42)
Ele pode ser encontrado aqui: https://www.entrust.com/get-support/ssl-certificate-support/root-certificate-downloads/, (*43)
Também será necessário exportar seu certificado digital para o formato PEM., (*44)
Com ambos os arquivos, configure-os no arquivo config.ini do WSBoletoSantander., (*45)
Exemplo:, (*46)
[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., (*47)
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., (*48)
Maiores informações, acesse http://www.apache.org/licenses/LICENSE-2.0., (*49)
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., (*50)
O software é oferecido aqui "como está" e nenhuma garantia é proferida. Portanto, o uso deste software é de inteira responsabilidade do utilizador., (*51)