Boleto Híbrido - ACBrBoleto via API com PIX

[José M. S. Junior]

Olá,

Recentemente diversas empresas estão emitindo boletos com QrCode para pagamento via PIX (Boleto Híbrido), ficando a critério do pagador escolher a forma de pagamento através da ficha de compensação "Código de Barras / Linha Digitável' ou com o PIX "QRCode".

Mas até então isso não estava formalizado pelo Banco em si, ou seja, o controle de Baixa do título caso seja pago por PIX ficaria a cargo da própria empresa, como ocorre no fluxo de várias API hoje disponíveis no mercado... Porém, o Banco do Brasil foi o pioneiro em disponibilizar esse tipo de integração em sua própria API, assim ao registrar um Título pode ser definido se será gerado também uma chave PIX dinâmica referente aquele título, com isso o controle da forma de pagamento fica com o Banco, independente se for pago via PIX ou Boleto. Isso facilita muito o controle por parte da empresa beneficiária e viabilizou a implementação desse tipo de integração via API também no componente ACBrBoleto.

No componente ACBrBoleto já existia a possibilidade de Registro Online de Boletos para alguns Bancos, inclusive o Banco do Brasil via WebService, mas essa API se trata de um novo Serviço, portanto são configurações e funcionalidades distintas no componente ACBrBoleto.

 

Neste tópico vamos descrever como realizar a homologação e utilizar a API do Banco do Brasil através do componente ACBrBoleto.

1-   Primeiro passo é realizar o Cadastro do seu Aplicativo no ambiente Sandbox BB, com isso será fornecido as credenciais para autenticação da API em ambiente de homologação.

Utilize o Serviço API Cobrança:

https://developers.bb.com.br/home

Documentação da API e como utilizar o ambiente Sandbox para cadastrar a aplicação:

https://apoio.developers.bb.com.br/referency/post/5ffc477c3b02bd0012ecaa1a

 

2-   Após o Cadastro poderá obter o ClientID e ClientSecret que precisará configurar no componente ACBrBoleto, cada emitente terá seu próprio ClientID e ClientSecret.

No componente ACBrBoleto configure em: Banco / TipoCobranca=cobBancoBrasilAPI 

 

No componente ACBrBoleto configure em: Cedente / CedenteWS 

ClientID=Informe o ClientID gerado no Ambiente Sandbox BB

ClientSecret=Informe o ClientSecret gerado no Ambiente Sandbox BB

Scope=cobrancas.boletos-info cobrancas.boletos-requisicao

KeyUser=developer_application_key

IndicadorPix=True   //Para utilização do PIX pela API - Banco do Brasil é necessário que o emitente tenha chave PIX cadastrada no BB, caso for utilizar somente a emissão tradicional pela API enviar False nesse parâmetro. 

 

Em Configurações / WebService - Configure da seguinte Forma:

Na opção de Ambiente escolher de acordo com a operação que esteja fazendo (Homologação ou Produção) necessário coerência com as chaves contratuais junto ao BB.

As operações homologadas para a API BB são de Inclusão e Consulta  [tpInclui, tpConsulta, tpBaixa, tpAltera]

SSLHttpLib utilizar cryOpenSSL

SSLType utilizar LT_TLSv1_2

 

3 - Com essas configurações já é possível realizar o registro de um título no BB via API. O Título deve ser incluso normalmente como no processo tradicional do componente, mas ao invés de gerar uma remessa, utiliza-se o o método "EnviarBoleto" - (botão no Aplicativo ACBrBoleto Demo: [Registrar Boleto On-Line]) . Este botão possui exemplos de como obter o Retorno da API. Se o título foi registrado sem nenhuma rejeição, automaticamente será atualizado a chave PIX junto ao Título.

 

Atenção usuários do Inter :

Uma das informações que deve ser armazenada do retorno da inclusão é a propriedade “NossoNumeroCorrespondente” pois toda operação de alteração, baixa e consulta você vai precisar informar esta propriedade. (é um código UUID de identificação do boleto)

 

Particularidades BB via API:

obs: API possui envio Síncrono

Carteira=17

EspecieDoc=DM

Modalidade=35

CodigoCedente=Informar Código Cedente

Convenio=Informar o Convenio

 

4- Para imprimir o Boleto:

Obs: Quando utilizado PIX, é necessário que além das informações tradicionais, sejam informadas no título o retorno do registro "QrCode" na propriedade "EMV", esse campo corresponde a String de geração do QRCode PIX gerada pelo Banco. ex:

Titulo.qrcode.emv := FRetornoConteudoEMV;

Impressão em FortesReport: Utilize o Layout "PadraoPIX"

Impressão em FastReport: Selecione o arquivo "BoletoPIX.fr3" no diretório "Report" junto ao ACBrBoleto Demo.

Segue o Modelo de Boleto Híbrido Impresso:

 

 

5-   Consulta de Títulos via API

Na aplicação ACBrBoletoDemo temos o botão "Consultar Boleto" com código exemplo de como passar os parâmetros para realizar uma consulta na API, o retorno será gerado em uma lista para posterior validação de cada Título.

 

Obs: A homologação deve ser feita também junto ao Banco, inclusive enviando os modelos das Fichas de Compensação emitidas para validação. 

Todos os testes foram realizados em ambiente de homologação, então é importante a validação completa antes de emitir em ambiente de produção.

 

Atenção usuários do Inter :

Uma das informações que deve ser armazenada do retorno da inclusão é a propriedade “NossoNumeroCorrespondente” pois toda operação de alteração, baixa e consulta você vai precisar informar esta propriedade. (é um código UUID de identificação do boleto)

 

[Victor H. Gonzales - Panda]

Saudações digitais comunidade ACBr!

A API do Banco do Brasil passou por uma evolução, agora possui novos métodos relacionados ao PIX vinculado ao boleto bancário "Boleto Híbrido".

 

tpPIXCriar, Utilizado para Gerar um Pix de Boleto

tpPIXCancelar, Utilizado para Cancelar um Pix de Boleto

tpPIXConsultar, Utilizado para Consultar um Pix de Boleto

[tpConsulta,tpAltera,tpBaixa,tpInclui,tpConsultaDetalhe, tpPIXCriar, tpPIXCancelar, tpPIXConsultar] // utilizado para o tipo de operação

Recursos acima já estão disponíveis no Componente, ACBrLib e MonitorACBr.

Docs OpenApi 3.0 https://api.bb.com.br/cobrancas/v2/swagger?gw-app-key=8f729780c2b401384349005056b91a5b

 

Para quem não trabalha com o fluxo de pooling, a API disponibiliza agora Webhook, então você criar um serviço em uma API sua e parametrizar um callback para facilitar o processo e agilizar os processamentos, a comunicação é feita por mTLS;

Docs Webhook: https://apoio.developers.bb.com.br/referency/post/6125045d8378f10012877468