Como emitir PIX pela API do Banco do Brasil

[Pedro.Bravin]

Olá, nessa documentação iremos mostrar o passo a passo de como fazemos para liberar as credenciais de integração no site do BB, e como correlacionar essas credenciais na API do PIX na Tecnospeed.

Essa documentação será separada em duas etapas, a primeira etapa é relacionada nos procedimentos relacionados no lado do Banco do Brasil, onde são descritos o passo a passo para auxiliar você a cadastrar a integração no painel do Banco do Brasil e pegar as suas credenciais de integração de produção.

A segunda parte já entramos na parte de integração dentro da plataforma da Tecnospeed, onde iremos cadastrar os dados da integração que foram entregues pelo banco, e por final iremos entrar no fluxo de emissão do PIX, e como é feito sua conciliação.

Porém antes de entrarmos no passo a passo, o cliente que quer começar a sua emissão usando o BB, deve ter os seguintes requisitos mínimos para conseguir fazer todos os procedimentos na API da Tecnospeed e no BB.

• Conta ativa no Banco do Brasil
• Um contrato ativo com a API do PIX da Tecnospeed
• Acesso ao portal do desenvolvedor do Banco do Brasil (https://developers.bb.com.br/home)

Como todos os requisitos mínimos liberados, você já está apto a começar a sua emissão de PIX dinâmicos e estáticos pelo BB.

Primeira etapa (Texto retirado do manual do banco BB 13-05-2021)

1) Acesse e cadastre-se no Portal BB for Developers

É muito simples. Na landing page do Portal BB for Developers (se preferir, acesse Aqui) acione a transação Cadastre-se e preencha os seguintes dados: CPF, nome da mãe, data de nascimento, endereço de e-mail e número de celular válidos.

Desconsidere acentuação e caracteres especiais.

Será remetido um código de confirmação para o número de telefone cadastrado no Banco. Informe o código recebido e cadastre uma senha conforme instruções indicadas em tela. Caso você tenha recebido um e-mail com convite do BB para primeiro ingresso no Portal BB for Developers, após o primeiro acesso, informe a chave/código indicada na mensagem.

Leia e assine eletronicamente o Termo para Uso da Plataforma. Você aproveitará um ambiente super seguro para desenvolver a sua aplicação.

 

2) Criando sua aplicação

Uma vez cadastrado no Portal BB for Developers será exigida a criação de uma aplicação. Acesse o contêiner (“+ Nova Aplicação”) e atribua as seguintes informações: nome da aplicação, descrição, URL de imagem para ícone da área de desenvolvimento (não obrigatório) e URL de call-back.

Os campos Ícone da aplicação e URL de callback, ambos são opcionais e especialmente a URL de callback não devem ser preenchido, por que a API da Tecnospeed utiliza a autenticação via client_credentials e necessita apenas o client_id e client_secret, a URL de callback pertence a outro fluxo de autenticação que não será utilizado.

Criada a aplicação, clique sobre o contêiner do app para acessar a área do desenvolvedor. As credenciais necessárias para realização dos testes são geradas automaticamente neste momento e poderão ser identificadas na opção Credenciais do menu lateral esquerdo. 
 

3) Pegando suas credenciais 

Ao acessar sua aplicação, será disponibilizado um menu lateral esquerdo, escolha a opção "Credenciais''. Após o cadastro das credenciais, apenas a opção Teste irá se encontrar selecionada em azul.

Em ambiente de Teste, o primeiro item disponibilizado, o “developer_application_key”, deverá ser informado como parâmetro clientKey na API da Tecnospeed e logo abaixo, seguem as credenciais OAuth, que serão cadastrados no client_id e client_secret.

4) Enviando a sua aplicação para Produção
Para utilizar as APIs do BB para a emissão do PIX, é necessário o envio da sua aplicação para Produção para que sejam geradas chaves compatíveis com o ambiente produtivo.

Passo 4.1
Selecione qual aplicação você deseja enviar para produção.
É importante lembrar que a aplicação deverá estar com status "Em desenvolvimento".  

Passo 4.2
No menu lateral, selecione a opção "Produção" e siga os passos:
Informe o CNPJ da empresa responsável.
Revise as informações da sua aplicação.

Caso a sua aplicação tenha a API de Cobrança vinculada, a contratação poderá ser feita de 2 formas: com ou sem o contato do BB.

A contratação é feita sem a interferência do BB, caso a empresa já possua contratado um convênio de cobrança e este esteja ativo. Caso não tenha, aguarde o Banco do Brasil entrar em contato com você para finalizar a contratação, e sua aplicação ficará com o status de "Aguardando aprovação".  Após o envio da sua aplicação para produção o status será alterado para "Aprovado".

6) Gerando credenciais para produção

A decisão de subir a aplicação para o ambiente de produção é responsabilidade exclusiva da empresa contratante do serviço financeiro integrado pela API, assim recomendamos que os desenvolvedores e os responsáveis administrativos certifiquem-se de que todos os cenários e adequações inerentes ao modelo de negócio ao qual a API será utilizada foram testados suficiente e satisfatoriamente. Os efeitos da integração dos sistemas por API somente ocorrerão a partir da disponibilização da aplicação em produção.

Selecione qual aplicação você deseja enviar para produção. É importante lembrar que a aplicação deve estar com seu status “Em desenvolvimento”. Na área do desenvolvedor, acesse a transação Produção no menu lateral esquerdo, informe o CNPJ da empresa responsável, revise os dados da aplicação e comande a disponibilização.

Neste meio tempo sua aplicação permanecerá com status Aguardando aprovação. Após envio da aplicação para produção e retirada de pendência pelos outorgados, o status será alterado para Aprovado. 

Verifique se o item Produção ficou selecionado em azul.
 

7) Cadastrando suas credenciais na API da Tecnospeed

Com as credenciais geradas no painel do Banco do Brasil e com acesso às suas credenciais de produção, agora iremos cadastrar os dados na API da Tecnospeed, para assim podermos gerar os PIX usando a integração da API do PIX.

Passo 7.1 Cadastro de uma Company (Empresa)

O primeiro passo é o cadastro da Company (Dados da sua empresa), que será onde você vai cadastrar os dados cadastrais da empresa que é titular da conta do BB, e também é a empresa que será usada para emitir as cobranças via PIX.
 

{
         "zipcode": "87045410",
         "name": "Usuario de testes",
         "email": "xxxxx@gmail.com",
         "cpfCnpj": "xxxxxxxxx",
         "city": "Maringa",
         "state": "PR"
}

 

Nessa parte é muito importante cadastrar os dados iguais as que estão no registro do Banco, por que essas informações vai ser usado para registrar o PIX, e também será usado para gerar o EMV do PIX, e qualquer diferença entre os dados cadastros pode gerar rejeição ou falha de leitura do PIX em alguns bancos.

Você consegue consultar o formato da resposta e requisição da rota de cadastro junto com os tipos de dados nesse link da documentação.

Passo 7.2 Cadastro de uma account (Conta BB)

Com a sua company criada, agora iremos cadastrar a conta do BB na plataforma de PIX da Tecnospeed, nessa conta iremos informar o código do banco em formato numérico, no caso do BB é o código 001, e também iremos cadastrar as credenciais geradas no painel BB, seguindo o mapeamento abaixo.

 

{
         "bankCode": "001",
         "clientId": "client_id",
         "clientSecret": "client_secret",
         "clientKey": "developer_application_key"
}

 

Caso tenha alguma dúvida temos a documentação em formato OPENAPI 3 nesse link, exemplificando todos os campos da requisição junto com a resposta que deve ser esperada.

Com esses passos feitos, você já está pronto para começar a emitir PIX dinâmicos e estáticos para o BB usando a API da Tecnospeed de PIX.

Avisos importantes

• Para integrar com o BB no momento é necessário um certificado digital.
• No momento o webservice do PIX não tem suporte para Webhook, por esse motivo a aplicação faz um pooling de 30 minutos com um intervalo de 10 segundos a cada consulta, com isso se o PIX não for pago nas primeiros 30 minutos, será necessário consultar manualmente o PIX na aplicação, para que  a mesma faça uma nova consulta no webservice do BB, e faça a sincronização do status do PIX.
• Documentação foi criada usando trechos da documentação oficial do Banco do Brasil.

Bibliografia

Documento de primeiro passos no BB (https://apoio.developers.bb.com.br/referency/post/5f4f8129b71fb5001268c99d)

Documentação OPENAPI 3 da API do PIX (https://docs.pix.tecnospeed.com.br/)