PIX: Banco do Brasil API V2
- Former user (Deleted)
- Editores Confluence
Índice
O MK erp possui integração com a API do Pix Banco do Brasil V2. Nesta modalidade os valores Pix pagos pelos clientes são depositados diretamente na conta corrente do provedor. O processo de uso da API Pix V2 do BB exige que o provedor gere certificados específicos que devem ser utilizado no internet banking e no mk erp. Nesta documentação vamos passar sugestões para que faça a geração destes certificados e como ativar a configuração da profile de pagamento.
Pré Requisitos
- Sistema na versão 109.64.5 ou superior
- Profile V2 homologada do BB
- Certificado digital .PFX
- Cadeia completa do certificado (pois será necessário utilizar as certificações)
- Extração da chave privada .PEM do certificado
- Extração da chave pública .PEM do certificado
Os certificados autorizados pelo BB para a autenticação mútua são do tipo A1, em formato .pem, com a cadeia inteira (Certificado > Intermediarias > Raiz), emitidos por uma CA válida.
Extraindo as chaves do certificado digital
- Acesse o disco local C em seu computador e crie uma pasta chamada OpenSSL, dentro desta pasta crie uma nova chamada SSL. O diretório deve ser exatamente este: C:\OpenSSL\SSL
- Faça o download do OpenSSL clicando neste link, a versão é a 1.1 Portable. Extraia da pasta compactada e salve no seu computador no diretório de sua preferência. No exemplo abaixo foi salvo dentro da pasta Documentos:
Na mesma pasta onde salvou o OpenSSL (a pasta vai ficar com o nome OpenSSL-1.1.1h_win32) coloque o seu certificado digital (caso o nome do certificado tenha espaçamentos na descrição é recomendado que renomeie ele e retire os espaços):
Abra o terminal openssl como administrador:
Extraindo a chave pública
Execute no terminal:
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePublica.pem - substitua pelo nome que deseja utilizar para a chave pública
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave publica vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32.
Extraindo a chave privada
Execute no terminal:
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePrivada.pem - substitua pelo nome que deseja utilizar para a chave privada
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave pública vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32:
Abra o arquivo (pode utilizar o Bloco de Notas, Notepad++ ou qualquer programa que leia arquivos .txt) e remova o cabeçalho: linhas 1,2 e 3, conforme exemplos abaixo:
Salve desta forma:
No exemplo abaixo vamos iniciar pela raiz do certificado:
- selecione e clique na opção Exibir Certificado
- acesse então a aba Detalhes > Copiar para Arquivo...
No assistente para copiar o arquivo selecione a opção X.509 codificado na base 64 (*.cer)
Avance e salve o arquivo. Repita o processo com os certificados intermediários.
Salve os arquivos no seu computador com descrições que encontre facilmente pois eles serão utilizados no portal do BB!
Montando o conteúdo para o portal do BB
Abra os arquivos certificados raiz e intermediários com um leitor de .txt (como Bloco de Notas, ou Notepad++). Você deve visualizá-los dessa forma:
Caso o conteúdo esteja criptografado é porque não foi copiado no formato X.509 codificado na base 64 (*.cer), neste caso faça novamente conforme orientações acima!
O certificado raiz está pronto para ser utilizado. Já os certificados intermediários precisam ser unificados em um único arquivo. O processo é bem simples, basta copiar e colar o conteúdo no programa leitor de txt (um abaixo do outro) e salvar o registro. Exemplo:
Configurações do Pix BB
PROFILE BB
Atenção! Caso não tenha nenhuma profile do Banco do Brasil no layout v2 homologada em seu sistema entre em contato com a equipe de suporte a homologação bancária para iniciar o processo.
Cadastro PIX BB em Produção
Deve ser utilizada uma conta (profile BB v2) já cadastrada no sistema, só é necessário solicitar o Client ID, Client Secret e Developer Api Key da conta. A solicitação é feita pelo Portal Developers BB . Ao acessar o portal faça a criação da conta de testes preenchendo as seguintes informações:
- Nome da aplicação: descrição identificativa (texto livre);
- Descrição: descrição identificativa (texto livre);
Selecione a opção APIs com contratação online pelo Portal Developers BB e após marque a opção PIX:
Para avançar clique em CRIAR.
No menu Produção preencha os dados e confirme a API escolhida:
Ao finalizar clique em SOLICITAR PRODUÇÃO, aceite os termos do contrato (ou solicite ao representante da empresa). No canal do YouTube do BB também está disponível um vídeo que explica o processo: Como colocar uma aplicação em produção.
Credenciais de produção
No menu lateral acesse a opção Credenciais para copiar as informações conforme exemplo abaixo:
Veja que na imagem estão selecionadas as credencias de Teste, no seu caso deve estar selecionada a opção Produção. No ERP vão ser utilizados:
- client_id
- client_secret
- developer_application_key
Upload dos certificados
No menu lateral acesse a Certificados e informe o CNPJ do provedor:
Acesse então a opção ENVIAR CERTIFICADO:
A empresa será identificada pelo nome e as áreas para inserção dos conteúdos dos certificados vão ficar disponíveis. Atenção: em cada campo o conteúdo dos certificados deve ser copiado e colado.
Abra os arquivos dos certificados com um leitor de .txt como Bloco de Notas, ou Notepad++ e então copie todo o conteúdo do certificado. É este conteúdo que deve ser utilizado nos campos abaixo.
- Certificado da empresa - conteúdo da chave pública (extraída do certificado digital);
- Certificado do intermediário - conteúdos copiados dos certificados intermediários;
- Raiz do certificado - conteúdo copiado da raiz do certificado
Abaixo exemplo do portal do BB das informações preenchidas:
Após clicar em SALVAR o portal do BB vai verificar se os dados estão corretos. Caso exista alguma inconsistência uma mensagem vai informar qual dos certificados deve ser ajustado.
Se estiver tudo certo com os dados a tela vai ser atualizada:
E quando os certificados forem aceitos a situação vai ser alterada:
Configuração da profile de pagamento
Após a configuração da conta em produção os dados na profile de pagamento BB v2 deve ser atualizados.
ACESSO: Configurações → Menu Financeiro → Submenu Profile de Pagamento → Boleto MK Ver. 2 - Edição, localize a profile do Banco do Brasil e então vai estar disponível a área PIX para inserir a configuração:
Importante
O cadastro dos dados de homologação e de produção é de responsabilidade exclusiva do provedor!
Preencha os seguintes campos:
- Chave PIX: chave da conta do Banco do Brasil adquirida no site do BB (pode ser o CNPJ, um e-mail, telefone, chave aleatória...).
- Credenciais: seleção da credencial utilizada na conta/profile de pagamento. Clique em Cadastrar credenciais PIX para inserir os dados de produção;
- Status: selecione a opção:
- Produção
- Hab. testes:
- Sim: pode utilizar esta opção para realizar um teste de pagamento, dessa forma a geração do QRcode vai ser permitida somente para um cadastro selecionado como Cliente Homologação;
- Não: liberado para todos os clientes;
- Cliente Homologação: selecione o cadastro do cliente que deseja utilizar para o teste de pagamento;
- Testar comunicação: teste de comunicação com o Sicoob para confirmar se a chave e credenciais estão corretas (clique para executar somente após inserir os dados conforme instruções abaixo);
- Versão API: selecione a opção 'Versão 2'
- Cadastrar credenciais PIX: ao clicar neste botão será aberta nova janela onde deve ser inserida a configuração com as chaves de produção;
- client_id - chave adquirida no site do BB;
- client_secret - chave adquirida no site do BB;
- developer_application_key - chave adquirida no site do BB;
- path_cert_client - chave pública .PEM extraída do certificado digital do provedor;
- path_key_client - chave privada .PEM extraída do certificado digital do provedor
Testar comunicação
Para confirmar que as credenciais estão corretas utilize a ferramenta Testar comunicação:
Este teste verifica se as chaves informadas na credencial estão certas e se os certificados tiveram o upload feito corretamente!