Bradesco API - SDK PHP

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

Parâmetro	Obrigatório	Padrão	Comentário
BRADESCO_CERT_PATH	Sim	-	Caminho do certificado PKCS#7 em formato .pfx
BRADESCO_CERT_PASSWORD	Sim	-	Senha do certificado
BRADESCO_SANDBOX	Não	true	Utilizar ambiente de Homologação (true) ou Produção (false)
BRADESCO_TIMEOUT	Não	30	Timeout em segundos para estabelecer conexão com a API
BRADESCO_FOLDER_PATH	Não	""	Caminho para esta biblioteca gerar arquivos temporários, necessários parar realizar a criptografia. Os arquivos são criados com hash randômica e excluídos automaticamente, sem a necessidade de se preocupar em limpá-los periodicamente.

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'
]);

2. 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