Configuração da API V2 — Banco do Brasil
Navegação: BankPlus → Conciliação Bancária → Processamento de Extrato Bancário → Importação via API (Banco do Brasil)
Introdução
Este artigo orienta a configuração e a importação de extratos bancários pela API do Banco do Brasil (versão 2) no BankPlus. A API V2 utiliza autenticação por certificado digital (mTLS) e por token (OAuth), e passou a exigir o envio da App Key (chave de aplicação) em cada consulta — informação que agora é configurável diretamente na tela de Extrato.
Ao final desta configuração, o BankPlus consultará o extrato de cada conta corrente cadastrada e importará os lançamentos para conciliação.
Observação: a versão 1 da API de Extrato do Banco do Brasil tem desativação prevista pelo banco para 20/11/2026. A migração para a V2 é necessária, entre outros motivos, para o correto tratamento do CNPJ alfanumérico exigido pela Receita Federal.
1. Pré-requisitos
Antes de iniciar, tenha em mãos os dados abaixo, obtidos no Portal Developers do Banco do Brasil (ou junto ao gerente/representante da conta):
Item | Descrição |
|---|---|
| Certificado digital (A1 / e-CNPJ) | Certificado da empresa, no arquivo .pfx (contém a chave privada), usado pelo BankPlus para autenticar a comunicação (mTLS). |
| Cadeia pública do certificado | Parte pública do certificado (formato X.509 PEM/Base64), que deve estar internalizada no Portal Developers do BB. |
| Client ID e Client Secret | Credenciais da aplicação, usadas para obter o token de acesso. |
| App Key (chave de aplicação) | Chave da aplicação do portal (também chamada de developer app key). É diferente do Client ID. |
| Agência e conta | Dados de cada conta corrente que terá o extrato importado. |
2. Cadastro do Certificado no BankPlus
Acesso: BankPlus → Configurações → Cadastro de Certificados
Ao acessar, a tela Lista de Certificados é aberta, com os certificados já cadastrados e os botões Novo, Remover e Exportar.
- Clique em Novo e selecione o arquivo do certificado (.pfx).
- A tela Detalhes Certificado será aberta. Informe a Senha e a Confirmação e clique em Validar Senha.
- Com a senha validada, os demais campos (Certificado, Data de Expiração) são preenchidos automaticamente.
- Clique em Atualizar para salvar.
🟦 Observação: só é possível importar certificados no formato PFX. Este é o certificado que o BankPlus apresentará ao Banco do Brasil durante a comunicação — deve ser o mesmo cuja cadeia pública está internalizada no portal.
Para mais informações relacionado ao processo de cadastro de certificado segue artigo do processo:
BankPlus | Configurações | Cadastro de Certificados
3. Configuração da Importação de Extrato (aba API)
Acesso: BankPlus → Conciliação Bancária → (Configuração de Extrato) → aba API
Nesta aba são informadas as credenciais da API do Banco do Brasil.
- Selecione o Banco do Brasil e a configuração de extrato correspondente.
- Preencha os campos da aba API:
Campo | O que informar |
|---|---|
Client ID | Client ID da aplicação (Portal Developers BB). |
Client Secret | Client Secret da aplicação. |
APP KEY | Chave de aplicação (app key) do portal. Campo obrigatório na V2. |
- Confirme em "Atualizar".
Importante — campo APP KEY: na V2, a app key passou a ser enviada em cada consulta e, por isso, tornou-se um campo configurável nesta tela. Sem ela preenchida, a importação não é concluída.
4. Autenticação por conta bancária
O Banco do Brasil valida a comunicação conta a conta — os dados de agência e conta são enviados em cada consulta. Por isso:
- A opção "Autenticar API por conta bancária" deve permanecer ativa.
- A App Key deve estar configurada em todas as contas bancárias da configuração de Extrato, e não apenas na configuração geral.
Observação: cada conta mantém sua própria agência e conta; apenas a App Key (e as credenciais) é replicada entre elas. Em cenários de conta única, essa replicação não é necessária.
Para mais informações acesso o artigo do processo abaixo:
5. Importação do Extrato
Acesso: BankPlus → Conciliação Bancária → Processamento de Extrato Bancário
- Em Configuração, selecione a configuração do Banco do Brasil (API).
- Informe o período desejado em Data do Extrato (data início e data fim).
- Clique em Listar / Processar para importar os lançamentos.
- Os extratos importados aparecem nas abas Em Aberto, Processados e Reconciliados.
Para mais informações sobre o processo, segue o artigo com o processo em anexo:
BankPlus | Conciliação Bancária - Configurações API - Importação de extrato via API Banco do Brasil
6. Mensagens comuns e o que verificar
Caso a importação não seja concluída, as verificações abaixo resolvem a maioria dos casos:
| Situação | O que verificar |
|---|---|
| Mensagem indicando certificado não autorizado / Forbidden | Confirmar que o certificado (.pfx) configurado no BankPlus é o mesmo cuja cadeia pública está internalizada no Portal Developers, e que a aplicação do portal possui a API de Extrato habilitada e aprovada. |
| Mensagem de parâmetros inválidos | Conferir se a App Key está preenchida e se as datas estão corretas; verificar se agência e conta estão informadas na conta bancária. |
| Nenhum lançamento retornado para o período | Pode indicar conta sem movimentação no intervalo consultado. Testar um período anterior com movimento conhecido para confirmar. |
Dica: ao testar pela primeira vez, escolha um período fechado (ex.: um dia útil da semana anterior) com movimento conhecido. Extratos do próprio dia podem ainda não estar consolidados.
7. Referências
- Portal Developers do Banco do Brasil — documentação da API de Extrato de Conta Corrente (V2) e orientações de certificado/mTLS.