Como funciona o conteúdo do Banco do Brasil para quem precisa extrair dados
A maior parte das pessoas que procuram conteudo banco do brasil quer alguma coisa prática: extrair extratos, consultar saldos, automatizar cobranças ou integrar a conta PJ de alguma forma. O problema é que o BB não é um banco que facilita isso pra quem tá de fora. A infraestrutura deles existe, mas seguir o caminho errado te dá horas de erro 403 e suporte que não resolve nada. Eu passei uns dois anos lidando com integração via API do BB, principalmente para PJ. Aprendi na marra porque a documentação oficial é generosa em diagrams mas tacanha em detalhes de produção.
conteudo banco do brasil: por onde começar de verdade
O ponto de partida é o Banco do Brasil para Desenvolvedores, o portal deles. Você cria uma conta, solicita acesso ao sandbox e depois à produção. O ciclo de aprovação varia entre três dias úteis para testes e cerca de duas semanas para produção, dependendo do tipo de contrato que você tem com a instituição. Se sua empresa já movimenta mais de 50 mil por mês na conta PJ, o processo costuma ser mais rápido porque eles já te conhecem. As APIs mais usadas são as de cobranças (pix e boletos), extrato e transferências. Todo o tráfego passa por OAuth 2.0 com client_credentials. O token tem validade de quinze minutos e precisa ser renovado antes de expirar. Se você deixar o token morrer no meio de uma requisição, a operação falha e você perde o rastro do que foi ou não enviado. Implementei um sistema de renovação automática com um timer de doze minutos que nunca deu problema.
O que ninguém explica sobre a integração
A coisa mais contraintuitiva é que o sandbox do BB não espelha a produção direito. Eu tinha uma validação que passava no sandbox e derrubava em produção porque o campo dataPagamento exige o formato ISO 8601 completo com timezone, e o sandbox aceitava qualquer string que parecesse data. Perdi quatro horas caçando esse bug. A lição é: teste sempre em produção com valores mínimos antes de confiar no sandbox como referência. Outro ponto que pega muita gente é o rate limit. O BB permite sessenta requisições por minuto por cliente para a maioria dos endpoints. Se você está processando um lote grande de cobranças, precisa batchear. Eu uso lotes de vinte e cinco itens com pausa de quatro segundos entre cada chamada. Isso respeita o limite sem travar o processamento.
A autenticação também funciona com certificado digital A1 ou A3. Se sua empresa já tem certificado para eSocial eNota, o mesmo arquivo serve. Mas o certificado precisa estar instalado no servidor que vai fazer as requisições, não só no computador do desenvolvedor. Configurei o ambiente uma vez em Ubuntu 22.04 usando o pacote libssl e o certificado .p12, e depois precisei refazer porque o repositório de chaves do sistema operacional foi atualizado e o OpenSSL perdeu o path do certificado. Aprendi a verificar com um script simples de healthcheck toda vez que o servidor reinicia.
Extrato e movimentação: a parte que mais dá trabalho
O endpoint de extrato retorna os últimos noventa dias por padrão. Você pode estender até um ano inteiro com um parâmetro opcional, mas aí a resposta vem paginada. Cada página traz cinco mil lançamentos. Se você pede um ano completo de uma conta com movimento intenso, vai receber cerca de quarenta e duas páginas. Eu fiz um script que processa tudo de uma vez, salva em CSV e gera um resumo com débitos e créditos separados por dia. O processo leva cerca de oito minutos para uma conta movimentada. O problema é que o extrato não inclui descrição detalhada de todas as operações. Transações pix vêm apenas com o tipo e o identificador da operação. Para saber o que foi realmente, você precisa cruzar com o extrato bancario exportado pelo internet banking tradicional, que tem o campo historico completo. Eu desenvolvi um mapeamento por data e valor que combina os dois arquivos e identifica cada lançamento. O acerto fica em torno de noventa e cinco por cento. Os cinco por cento restantes são lançamentos idênticos no mesmo dia que exigem verificação manual.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Tem uma particularidade que quase ninguém menciona: o BB separa extrato do agente de pagamento do extrato da conta corrente em endpoints diferentes. Se você pede só o movimento da conta, não vê as cobranças que passaram pelo sistema de boletos. Sempre chame os dois e Some no final.
Transferências e TED/DOC: o que funciona em produção
Para TED, o endpoint pede os dados completos do beneficiário: nome, CPF ou CNPJ, agência, conta, tipo de conta e código do banco. Qualquer campo errado gera erro 422 e a transferência nunca sai. Eu fiz uma camada de validação antes de enviar que checa o dígito verificador da agência e da conta usando o algoritmo mod 11. Isso elimina erros de digitação e evita que você perca dia útil inteiro esperando uma transferência que nunca saiu. Já para DOC, a coisa é mais lenta. O DOC via API só é processado em dias úteis até as onze horas da manhã. Se você dispara depois disso, vira para o próximo dia útil. Pix resolve isso porque é disponível vinte e quatro horas, sete dias por semana. Pra transferência urgente, eu recomendo usar pix mesmo que o destinador prefira DOC. A taxa é zero e a confirmação sai em segundos.
Cuidados que eu aprendi na prática
O BB exige que todo payload seja assinado digitalmente com o certificado. Se a assinatura não bater, o retorno é um erro genérico que não diz nada útil. Eu configuro o log para gravar o payload, o header de assinatura e o response completo. Quando algo falha, eu consigo identificar em dois minutos se o problema é no certificado, no payload ou no endpoint. Sem esse log, você fica mandando e recebendo erro sem entender nada. Outro detalhe: o tempo de resposta do BB é instável. Em horários de pico, como último dia de vencimento de boletos, a resposta pode levar de três a oito segundos. Coloquei um timeout de quinze segundos nas chamadas e um retry automático com backoff exponencial. Duas tentativas resolvem noventa e nove por cento dos casos. Só em ocasiões muito raras eu preciso interv ir manualmente.
Se você não tem contrato PJ ativo com o banco, não adianta insistir. O BB não libera acesso à API para pessoa física e o processo de credenciamento exige contrato de prestação de serviços ou conta ativa há pelo menos seis meses. Minha sugestão é entrar em contato com o gerente da conta e pedir o acesso ao programa de APIs. Se seu movimento for alto, o gerente costuma facilitar porque ganha comissão com o aumento do uso dos serviços digitais da instituição. O download dos manuais técnicos e da documentação completa fica disponível no portal do desenvolvedor do Banco do Brasil. O link direto muda de tempos em tempos, então o melhor é buscar por "BB Open Finance desenvolvedor" e entrar pelo link oficial. Lá você encontra o postman collection, os schemas JSON e os exemplos de código em Python, Java e Node.js.
Resumindo o que funciona: sandbox para prototipar, produção com certificado instalado no servidor, renovação de token automática, validação de dados antes de enviar, logs completos de tudo e paciência porque a infraestrutura deles não é das mais rápidas mas é estável quando bem configurada.
