GF - Como Fazer - Open Banking para Banco do Brasil

Objetivo

Este manual tem por objetivo instruir alguém que já tenha lido o manual geral do Open Banking CIGAM a realizar todo o processo de parametrização e início do uso das APIs bancárias do Banco do Brasil.

Aqui você será orientado desde a busca e obtenção das credenciais, assistente e parametrizações específicas do Banco do Brasil para o Open Banking. Para dúvidas gerais referentes a funcionalidades gerais do Open Banking consulte o Manual Open Banking - Geral.

APIs disponíveis e serviços atendidos pelo CIGAM

Funcionalidade	Versão
Registro de Cobrança Simples e vinculada	211004.RC
Alteração de Vencimento	211004.RC
Alteração de Juros e multa	211004.RC
Baixa de título	211004.RC
Protesto e Negativação	211004.RC
Retorno de Cobrança	211004.RC
Demais alterações (endereço, desconto por antecipação, abatimentos, etc)	Não tratados.
QR CODE no Boleto	211004.RC
API de PIX avulso (QR Code dinâmico ECF Lojas)	211004.RC

Open Banking Banco do Brasil

Obtenção de credenciais - Banco do Brasil

As credenciais do Banco do Brasil são geradas através do Portal Developers. Também disponibiliza instruções no guia Documentação - Portal Developers. Para maiores informações, entre em contato com o seu gerente de cash (gerente de conta Banco do Brasil).

IMPORTANTE: o usuário criado neste portal deve, obrigatoriamente, ser o responsável pela conta corrente PJ. Caso ele seja criado no CPF de outra pessoa, o processo seguirá normalmente, porém as credenciais de acesso não serão aceitas, ocasionando erros do tipo “500- Forbidden”.

Para parametrizar o Banco do Brasil serão necessárias as informações de Client_id e Client_secret, ambos obtidos no portal developers para os dois ambientes (homologação e produção), também será apresentado o valor chamado developer_application_key, este valor deve ser desprezado, uma vez que o ERP CIGAM possui o seu próprio.

É importante atentar ao ambiente de cada credencial através do botão de ambiente:

Outro ponto importante é que em algumas situações, as próprias credenciais de produção são liberadas em modo “homologação”, para autenticá-las para produção, é preciso entrar na opção “enviar para produção”.

Ainda dentro do portal, na opção APIs, devem ser selecionadas as APIs que se deseja utilizar junto às credenciais geradas. Atualmente o CIGAM atende a API Cobranças (registro de boletos) e a API Pix (PIX no boleto e registro de PIX avulso). A combinação destas APIs irá gerar uma string chamada “Scope” que será necessária para identificar no CIGAM quais os serviços disponíveis.

Uma vez em posse das credenciais, basta seguir o passo a passo no assistente de configuração do Open Banking no cadastro de Portadores e no cadastro de Bancos respectivamente.

Importante: atualmente o Banco do Brasil não utiliza certificados digitais nas APIs disponíveis para o ERP CIGAM.

Assistente Open Banking - Banco do Brasil (versão atual V2)

Abertura do assistente: Ao abrir o assistente serão apresentadas as informações necessárias para a configuração, no caso do Banco do Brasil são Client_id e Client_secret.

Passo 1: Aqui serão solicitados todos os dados relativos a credenciais e serão explicados um a um. Primeiro, na guia homologação, só será necessário informar algo caso você esteja configurando uma base de testes, caso contrário, preencha apenas os dados da guia “Produção”. É importante atentar a guia em que se está posicionado e a credencial que se está informando, existem muitos casos em que, por descuido são informadas credenciais invertidas, gerando erros do tipo “500 – Forbidden”, consulte erros frequentes para maiores detalhes.

• Developer application key: este campo já vem preenchido com a identificação do ERP CIGAM, ele não precisa ser alterado;
• Client_id: cole aqui a informação obtida no portal developers do BB conforme o item Obtenção de credenciais - Banco do Brasil deste manual;
• Client_secret: cole aqui a informação obtida no portal developers do BB conforme o item Obtenção de credenciais - Banco do Brasil deste manual;
• Scope: este campo representa os serviços selecionados pelo cliente no portal developers do Banco do Brasil, o CIGAM já traz o escopo completo com todos os serviços que ele atende. Realize a edição conforme definido no portal developers do BB, abaixo são listados alguns exemplos de como pode ficar a configuração:

Cliente possui apenas API de cobrança:

cobrancas.boletos-requisicao cobrancas.boletos-info

Cliente possui cobrança + PIX:

cobrancas.boletos-requisicao cobrancas.boletos-info cob.write cob.read pix.read pix.write

• Versão da API: versão da API válida para este bloco de credenciais. Atualmente a versão é a v2, não alterar.

• Certificado: Campo para informar o nome do certificado da versão 2 da API do Pix do Banco do Brasil se desejado a utilização dessa nova versão no processo de geração de pix.

• Status do Certificado: Campo preenchido automaticamente pelo CIGAM ao localizar um certificado nomeado com o informado no campo "Certificado".

• Usuário para Alerta: Informe o usuário que receberá o alerta de vencimento do certificado para o processo de alerta descrito na seção Usuário de Alerta (alerta de vencimento de certificado digital) do manual geral do Open Banking.

Ao final, a tela do passo 1 estará preenchida desta forma:

Clique em “avançar” para ir para o passo 2.

Passo 2: Este passo diz respeito à seleção de convênios, ela é uma característica do Banco do Brasil e serve para que possa ser apontado o convênio para o qual as credenciais geradas serão válidas. O CIGAM irá apresentar todos os códigos de convênios localizados dentre os portadores cujo código de banco é “001”. Porém aqui cabe uma ressalva: a não ser que esteja discriminado nas suas credenciais, sugerimos que você clique em “pular” nesta tela, assim as suas credenciais valerão para qualquer convenio que a empresa possua.

O resultado de clicar em “pular” neste passo resultará em uma parametrização de convênio “Geral” na tela de parâmetros open banking. Depois disso, caso você deseje adicionar uma parametrização adicional, será obrigatório informar um convênio para as credenciais que se deseja adicionar (o botão pular estará desabilitado). Caso a parametrização atual possua um convênio especificado, será possível tanto configurar um novo convênio quanto pular a seleção, desta forma, as novas credenciais utilizarão um convênio “Geral”.

Passo 3: Neste passo você irá informar os portadores de remessa e retorno que serão utilizados para esta parametrização do Open Banking, aqui você pode informar mais de um portador, por exemplo, o de carteira SIMPLES e o de carteira DESCONTADA e ambos utilizarão a mesma instância de credenciais. A informação do portador de retorno é para auxiliar na sugestão da rotina de retorno.

Importante: mesmo com a utilização da opção de convênio “Geral”, os portadores de remessa e retorno devem obrigatoriamente possuir o mesmo convênio, isso é importante para que a rotina de retorno funcione corretamente.

A opção “Direto” está detalhada no manual de funcionalidades Open Banking, já a opção PIX será detalhada mais a frente neste manual.

Importante 2: O Banco do Brasil possui a funcionalidade de registro de operações PIX em seu escopo no CIGAM. Esta funcionalidade utiliza as mesmas credenciais da API de cobrança, porém tem um escopo e manual de utilização separados deste documento.

Passo 4: o passo 4 serve para realizar o apontamento do relatório de remessa que servirá como padrão tanto para a rotina de registro quanto para retorno do Open Banking. O CIGAM irá sugerir o caminho padrão para o modelo de relatório (RF00071), mas caso os seus modelos sejam salvos em algum outro local, basta alterá-lo neste momento, após, clique em “avançar”.

Pronto! Caso tenha dado tudo certo com as suas credenciais, o CIGAM irá emitir uma mensagem de sucesso para cada um dos ambientes para o qual você informou as credenciais.

Após clicar em “concluir” você será apresentado à tela “Parâmetros” Open Banking (conforme abaixo), você encontrará o descritivo de cada área dela no no item Tela de parâmetros Open Banking do manual Open Banking.

A partir daqui o seu CIGAM já está parametrizado para utilizar o Open Banking do Banco do Brasil, os serviços disponíveis para ele estão na tabela apresentada no item APIs disponíveis e serviços atendidos pelo CIGAM. Nas sessões a seguir estarão descritas apenas as características específicas do Banco do Brasil. Demais instruções de uso do open banking estão no Manual Open Banking.

Ambiente de testes Banco do Brasil

O Banco do Brasil possui ambiente de testes bastante completo, porém ele exige algumas particularidades. São necessários dados de CNPJ e CPFs específicos conforme descrito na sua documentação disponível em Dados fictícios para Testes no Portal Developers.

Registro de cobrança - Banco do Brasil

O registro do Banco do Brasil é, de maneira geral realizado como todos os outros bancos, abaixo seguem algumas explicações exclusivas.

Particularidades do cadastro de Portador – Banco do Brasil

O Escopo do Banco do Brasil prevê apenas o uso das carteiras Simples e Vinculada, esta parametrização é feita através do campo Identificação do Serviço do cadastro do portador, onde “branco” ou “1” indicam a carteira Simples e “4” indicam a carteira vinculada.

- Agência: o preenchimento da Conta deve ser sem caracteres especiais, somente números e deve possuir caracteres (completar com zeros à esquerda caso necessário).
IMPORTANTE: a rotina de retorno exige que a agência possua no mínimo 4 caracteres, caso contrário acusará erro.

- Conta: o preenchimento da Conta deve ser sem caracteres especiais, somente números.

- Convênio:
"Cada Conta Corrente é um Convênio" - (7 posições). "Uma Conta Corrente pode ter vários Convênios". "Quando tenho mais de um Convênio, muda o Código do Convênio e a variação da Carteira conforme a tabela abaixo:" Variação da Carteira (caso tenha mais de um Convênio):
019 (Código de 2 + DV)
027
035
043...

- Carteira (Serviço):
011 - (Cobrança simples Boleto por correio)
031 - (Cobrança simples Vinculada)
017 - (Cobrança simples Imprime Boleto - considerado como Única)
051 - (Carteira Descontada), modalidade utilizada é 04. Demais são considerados atributos.

- Modalidades de Serviço do Banco do Brasil consideradas:
01 - Simples
04 - Vinculada (esta Modalidade está atrelada somente a Carteira 051, logo não deve ser utilizada para outras Carteiras)

- Regra do Sistema para Banco do Brasil Open Banking:
Identificador do Serviço: as opções para este campo são:
01 - Simples
04 - Vinculado
Valores diferentes destes serão tratados = 01 - Simples

- Espécie: este campo para Open Banking é considerado para identificar o Tipo de Boleto de Cobrança. Quando este campo estiver em Branco o Sistema irá considerar sempre 04 - DUPLICATA SERVICO.
01 - CHEQUE
02 - DUPLICATA MERCANTIL
03 - DUPLICATA MTIL POR INDICACAO
04 - DUPLICATA SERVICO
05 - DUPLICATA SRVC P/INDICAO
06 - DUPLICATA RURAL
07 - LETRA DE CAMBIO
08 - NOTA DE CRÉDITO COMERCIAL
09 - NOTA DE CREDITO A EXPORTACAO
10 - NOTA DE CREDITO INDULTRIAL
11 - NOTA DE CREDITO RURAL
12 - NOTA PROMISSORIA
13 - NOTA PROMISSORIA RURAL
14 - TRIPLICATA MERCANTIL
15 - TRIPLICATA DE SERVICO
16 - NOTA DE SEGURO
17 - RECIBO
18 - FATURA
19 - NOTA DE DEBITO
20 - APOLICE DE SEGURO
21 - MENSALIDADE ESCOLAR
22 - PARCELA DE CONSORCIO
23 - DIVIDA ATIVA DA UNIAO
24 - DIVIDA ATIVA DE ESTADO
25 - DIVIDA ATIVA DE MUNICIPIO
31 - CARTAO DE CREDITO
32 - BOLETO PROPOSTA
33 - BOLETO APORTE
99 - OUTROS

IMPORTANTE: Quando este campo está divergente do esperado, normalmente é apresentado o erro "4678420 - Campo tipo do título preenchido com dados inválidos".

- Recebimentos divergentes da cobrança: Para portadores do Banco do Brasil (001) disponibilizamos o campo "Aceita recebimento divergente da cobrança". Se o checkbox for marcado, a tag "indicadorPermissaoRecebimentoParcial" do envio para registro no banco será enviada com o dado "S", permitindo que o título aceite recebimentos divergentes, caso contrário, a tag será enviada como "N" e o título não permitirá este tipo de recebimento.

Impressão de QR Code no Boleto - Banco do Brasil

O Banco do Brasil possui a funcionalidade de QR Code na impressão do boleto, para que seja possível utilizá-la existem algumas regras a serem seguidas, sendo elas:

IMPORTANTE: A chave pix utilizada no registro não é enviada pelo CIGAM, o Banco do Brasil utiliza automaticamente a chave PIX vinculada à conta corrente do boleto.

A opção “PIX” dos parâmetros open banking para a linha do portador utilizado deve estar marcada. Para que o QR Code seja impresso é imperativo que o título já esteja registrado no banco, essa situação se dá, pois, a operação PIX do boleto é gerada pela própria instituição, de modo que o CIGAM só a obtém após o registro.

O arquivo JSON de remessa terá a opção “indicadorPix” = “S” e no retorno serão trazidos os dados de URL, txid e demais informações necessárias para a impressão do QR Code no boleto:

Para realizar a impressão do boleto, deve ser utilizado o modelo “0098_brasil_PIX.rtf” disponível na pasta de modelos do CIGAM salva na pasta: “CIGAM_INSTAL\Modelos_Relatorios\Gestão Financeira\Bloquetos Merge\” do seu CIGAM ou adicionar a TAG qrcode_pix ao seu modelo existente.

Retorno de cobrança - Banco do Brasil

O Banco do Brasil separa a execução da rotina de retorno em dois blocos, conforme a explicação contida no seu botão informativo:

Documentos Relacionados

• Manual Open Banking Geral
• FAQ Em qual tabela fica gravado o registro do campo "Situação Open Banking" do lançamento financeiro
• FAQ Erro "4678420 - Campo tipo do título preenchido com dados inválidos"

Documentação Banco do Brasil

• Portal Developers Banco do Brasil
• Canais de Atendimento Banco do Brasil