vitorccs/bradesco-api-php

SDK PHP para a API de Registro de Boletos do Bradesco

v1.6.2 2022-10-17 21:13 UTC

Requires

• php: >=7.1
• ext-json: *
• ext-openssl: *
• guzzlehttp/guzzle: ^6.3.3|^7.0.1

Requires (Dev)

• php: >=7.2
• phpunit/phpunit: ^8.5

GPL-3.0

• Vitor Siqueira

• boleto
• bradesco
• cobranca
• registro
• titulo

README

SDK PHP para a API de Registro On-line de Boletos de Cobrança Bradesco

Requisitos

• PHP >= 7.1

Descrição

SDK em PHP para integração com os serviços de Registro On-line de Boletos de Cobrança Bradesco

Manual_Registro_de_Boleto_Bancario_Online_Janeiro 2019.pdf

Instalação

Via Composer

composer require vitorccs/bradesco-api-php

Parâmetros

Como usar

1. Os parâmetros podem ser definidos por váriaveis de ambiente:

putenv('BRADESCO_SANDBOX=true');
putenv('BRADESCO_TIMEOUT=20');
putenv('BRADESCO_CERT_PATH=myCertificate.pfx');
putenv('BRADESCO_CERT_PASSWORD=myPassword');

ou passados por array:

\BradescoApi\Http\Bradesco::setParams([
    'BRADESCO_SANDBOX' => true,
    'BRADESCO_TIMEOUT' => 20,
    'BRADESCO_CERT_PATH' => 'myCertificate.pfx',
    'BRADESCO_CERT_PASSWORD' => 'myPassword'
]);

1. Em seguida, basta utilizar o comando abaixo passando os dados do boleto em formato array.

$boleto = \BradescoApi\BankSlip::create($data);

Normalização de dados

Foram adicionadas diversas funções para normalizar os dados conforme exigido pela API do Bradesco:

• Campos ausentes são inseridos com seus respectivos valores padrão (página 19 do manual).
• Valores em null são trocados para vazio "".
• Valores em integer ou float são convertidos para string.
• Valores com caracteres especiais (ção) são substituídos por caracteres básicos (cao).
• Valores de nome e endereço do pagador são recortados para a quantidade máxima de caracteres.
• Datas no formato "yyyy-mm-dd" ou "dd/mm/yyy" são normalizadas para "dd.mm.yyyy".
• Moedas no formato 14.90 ou "14,90" são normalizadas para "1490".
• Números de CPF e CNPJ "123.456.789-01" são normalizadas para "00012345678901".

Exemplo de implementação

error_reporting(E_ALL);
ini_set('display_errors', 1);

require __DIR__.'/vendor/autoload.php';

putenv('BRADESCO_SANDBOX=true');
putenv('BRADESCO_TIMEOUT=20');
putenv('BRADESCO_CERT_PATH=myCertificate.pfx');
putenv('BRADESCO_CERT_PASSWORD=myPassword');

use BradescoApi\Exceptions\BradescoApiException;
use BradescoApi\Exceptions\BradescoRequestException;

$data = [
  "nuCPFCNPJ" => "123456789",
  "filialCPFCNPJ" => "0001",
  "ctrlCPFCNPJ" => "39",
  "idProduto" => "09",
  "nuNegociacao" => "123400000001234567",
  "nuCliente" => "123456",
  "dtEmissaoTitulo" => "25/05/2017",
  "dtVencimentoTitulo" => "2017-06-20",
  "vlNominalTitulo" => 100.00,
  "cdEspecieTitulo" => "04",
  "nomePagador" => "Cliente Teste",
  "logradouroPagador" => "Rua Teste",
  "nuLogradouroPagador" => "90",
  "complementoLogradouroPagador" => null,
  "cepPagador" => "12345",
  "complementoCepPagador" => "500",
  "bairroPagador" => "Bairro Teste",
  "municipioPagador" => "Cidade Teste",
  "ufPagador" => "SP",
  "nuCpfcnpjPagador" => "549.435.260-98",
];

try {
    $bankSlip = \BradescoApi\BankSlip::create($data);
    print_r($bankSlip);
} catch (BradescoApiException $e) { // erros retornados pela API Bradesco
    echo $e->getErrorCode() == 69 // este é o único código de erro que não exige tratativa
         ? "API Bradesco indica que boleto já foi registrado"
         : sprintf("%s (%s)", $e->getMessage(), $e->getErrorCode());
} catch (BradescoRequestException $e) { // erros não tratados (erros HTTP 4xx e 5xx)
    echo sprintf("%s (%s)", $e->getMessage(), $e->getErrorCode());
} catch (\Exception $e) { // demais erros
    echo $e->getMessage();
}

Dicas

• Mesmo em ambiente Sandbox é necessário utilizar o arquivo e senha correta do certificado, e utilizar os dados reais do beneficiário (nuCPFCNPJ, filialCPFCNPJ, ctrlCPFCNPJ, nuNegociacao). Também é necessário que a sua carteira de boletos já esteja autorizada junto ao Bradesco para utilizar a API de Registro On-line.
• Como qualquer serviço, a API do Bradesco não possui 100% de disponibilidade. É recomendável armazenar o status de sucesso, e prever algum tratamento de retentativa para os casos que não retornaram sucesso.
• A exceção BradescoApiException é lançada quando é detectado alguma mensagem de erro retornada pela própria API Bradesco, e a exceção BradescoRequestException para problemas diversos de servidor e conexão (erros HTTP 4xx e 5xx)
• A única exceção que não exige retentativa, é a de código 69 pois representa que o Boleto já se encontra registrado

OpenSSL 3

A partir da versão 3 do OpenSSL, o certificado .pfx pode apresentar erro de leitura e será necessário habilitar o modo "legacy" (veja no StackOverflow)

Testes

Caso queira contribuir, por favor, implementar testes de unidade em PHPUnit.

Para executar:

1. Faça uma cópia de phpunit.xml.dist em phpunit.xml na raíz do projeto
2. Altere os parâmtros ENV com os dados de seu acesso
3. Execute o comando abaixo no terminal dentro da pasta deste projeto:

composer test