Banco do Brasil

APIs do Banco do Brasil: extratos, cobrança, Pix e mais, pelo Portal Developers BB

Módulo extra: instale pelo Gerenciador de Módulos do A4A Studio.

Guia do módulo

Antes de começar

O módulo usa as APIs oficiais do Banco do Brasil pelo Portal Developers BB (developers.bb.com.br). Cada empresa cria a sua aplicação no portal, escolhe as APIs que o robô vai usar (Cobrança, Pix, Extratos) e recebe três credenciais.

Client ID: identifica a aplicação; pode ficar no campo do comando.
Client Secret: senha da aplicação; guarde no cofre de credenciais do Studio.
Chave da aplicação (developer_application_key): guarde no cofre; o módulo a envia em toda chamada.

Todo robô começa com "Conectar ao Banco do Brasil". A conexão pede o token de acesso, renova sozinha antes de vencer e é usada por todos os comandos do módulo.

Ambientes

O BB tem três ambientes, e as credenciais de um não valem no outro.

Sandbox: só a Cobrança tem.
Homologação: é onde se testa com dados fictícios; a documentação da Cobrança indica a homologação como ambiente de teste, e Pix e Extratos só têm homologação e produção.
Produção: dados e dinheiro reais; exige a aplicação aprovada pelo BB para produção.

Os endereços de cada API vêm das especificações do BB. Se o banco mudar algum, troque em "Hosts das APIs", nos parâmetros avançados da conexão.

Certificado digital (mTLS)

Pix e Extratos exigem certificado digital da empresa também em homologação; a Cobrança não exige.

Use o e-CNPJ A1 (.pfx ou .p12) da empresa dona da conta, com a senha guardada no cofre.
Cadastre o certificado (a cadeia completa) na aplicação do Portal Developers BB e aguarde a liberação.
Certificados de teste de outras autoridades ou de pessoa física (e-CPF) são recusados com a mensagem "O BB não reconheceu o certificado digital".
O módulo converte o .pfx para uma cópia temporária e a apaga ao fim do robô.

Cobrança (boletos): regras do BB

Convênio, carteira e variação vêm do contrato de cobrança da empresa com o BB.
O número do boleto (nosso número) tem 20 dígitos: 000 + convênio com 7 dígitos + sequência com 10. Nos comandos, basta a sequência; o módulo monta o resto. A sequência não pode se repetir.
O "seu número" é obrigatório para o BB; vazio, o módulo usa a sequência do boleto.
Datas aceitam dd/mm/aaaa ou variável de data; valores aceitam 150,00 ou 150.00.
Alterar e baixar só são aceitos 30 minutos depois do registro. Na homologação, o prazo pode passar de 30 minutos; o BB responde "Boleto em processamento" enquanto não libera.
O BB aceita uma alteração por chamada (vencimento, valor ou abatimento): use um comando para cada.
Consultar o mesmo boleto de novo em menos de 30 segundos devolve a resposta anterior.
A listagem traz 300 boletos por vez e o módulo junta as páginas; sem resultado, devolve lista vazia.
Na homologação, use os dados fictícios do portal: convênio 3128557, carteira 17, variação 35, agência 452, conta 123873 e um CPF/CNPJ de teste (ex.: 97965940132).

Pix: regras do BB e do Banco Central

A chave Pix informada precisa estar cadastrada na conta do BB da empresa.
O txid identifica a cobrança: 26 a 35 letras e números. Deixe vazio para o banco ou o módulo gerar.
Cobrança imediata vale pelo tempo de expiração (padrão 1 hora); a com vencimento vale até o vencimento mais os dias de validade.
Situações: ATIVA (aguardando), CONCLUIDA (paga), REMOVIDA_PELO_USUARIO_RECEBEDOR (cancelada) e REMOVIDA_PELO_PSP (removida pelo banco).
As pesquisas (cobranças e Pix recebidos) cobrem menos de 5 dias por vez.
Cobrança paga não se cancela: devolva o Pix pelo endToEndId. A soma das devoluções não passa do valor recebido, e a devolução é processada pelo Banco Central (consulte até DEVOLVIDO).
Na homologação, use a chave de teste hmtestes2@bb.com.br; outra chave é recusada com "Chave Pix não pertence ao cliente gerador da cobrança". Os nomes devolvidos pelo BB são fictícios.

Extratos: regras do BB

Agência e conta sem o dígito verificador e sem zeros à esquerda (0297 vira 297).
Período de até 31 dias; a data inicial pode ser de no máximo 5 anos atrás. Sem datas, vêm os lançamentos mais recentes.
O BB devolve de 30 a 120 lançamentos por página; o módulo junta as páginas.
Cada lançamento traz o sinal em indicadorSinalLancamento (C crédito, D débito); o módulo acrescenta "valor" já negativo nos débitos e "data" em dd/mm/aaaa.
A lista inclui linhas de saldo (ex.: "SALDO ANTERIOR", "S A L D O"), com codigoHistorico 0 e sem número de documento: filtre-as antes de somar os lançamentos.
Exige o certificado digital (mTLS), também na homologação.
Na homologação, informe na conexão o "MCI de teste" de uma das contas fictícias do BB: MCI 704950857 (agência 452, conta 123873), 26968930 (551/5087) ou 178961031 (1505/1348). Em produção esse campo é ignorado.

Erros e boas práticas

Erros do banco param o robô com o status e a mensagem do BB (ex.: "4874915: Convênio inválido"); trate com Tentar/Capturar quando o robô precisar seguir.
Credenciais e chave da aplicação nunca aparecem nos logs nem nas mensagens de erro.
Para um endpoint do BB que ainda não tem comando, use "Chamar API do BB", que já leva o token e a chave.
Comece sempre pela homologação e só depois troque o ambiente para produção.

Conectar ao Banco do Brasil

banco_brasil.connect

Autentica nas APIs do BB (OAuth) e devolve a conexão usada pelos demais comandos

Como usar

Crie uma aplicação em developers.bb.com.br, marque as APIs que o robô vai usar (Extratos, Cobrança, Pix...) e copie o Client ID, o Client Secret e a chave da aplicação (developer_application_key). Guarde o Client Secret e a chave no cofre de credenciais e escolha-os aqui. Comece no ambiente Sandbox; em produção, algumas APIs exigem o certificado digital da empresa (e-CNPJ A1, .pfx). A conexão fica em {bb} e é usada por todos os comandos do módulo.

Exemplo: Conecte no Sandbox com o Client ID da aplicação de testes e as credenciais BB_CLIENT_SECRET e BB_APP_KEY do cofre; depois liste os boletos do convênio.

Campos

Campo	Tipo	Padrão	Detalhes
Ambiente *	Opção	`Sandbox (testes)`	Pix e Extratos não têm Sandbox: teste-os em Homologação, com o certificadoOpções: Sandbox (testes), Homologação, Produção
Client ID *	Texto		Em Credenciais, na aplicação do Portal Developers BB
Client Secret (cofre) *	Credencial do cofre
Chave da aplicação (cofre) *	Credencial do cofre		developer_application_key da aplicação, enviada como gw-dev-app-key
Escopos	Texto		Separados por espaço; vazio usa os escopos liberados para a aplicaçãoEx.: `cobrancas.boletos-info cobrancas.boletos-requisicao`
Variável da conexão *	Variável de saída	`bb`

+ Avançado (8)

Campo	Tipo	Padrão	Detalhes
Certificado digital (mTLS)	Arquivo		e-CNPJ A1 (.pfx/.p12) ou .pem/.crt; exigido pelo Pix e pelos Extratos
Senha do certificado (cofre)	Credencial do cofre		Só para .pfx/.p12
Chave do certificado (.key)	Arquivo		Só para certificado .pem/.crt
Servidor de autorização	Texto		Vazio usa o padrão do ambienteEx.: `https://oauth.sandbox.bb.com.br`
Hosts das APIs	Pares chave e valor		Troca a URL base de uma API (cobranca, pix, extratos); vazio usa a das especificações do BB
Credenciais no corpo do pedido de token	Sim/Não	`Não`	Desligado: envia por Basic (padrão OAuth)
MCI de teste (homologação)	Texto		Extratos na homologação: MCI da conta fictícia indicada pelo BB (header x-br-com-bb-ipa-mciteste). Ignorado em produção.Ex.: `704950857`
Tempo limite	Número	`60 s`

Resultado: guardado na variável bb (Objeto).

Extratos

Consultar Extrato

banco_brasil.consultar_extrato

Lista os lançamentos da conta corrente num período de até 31 dias

Como usar

Informe a agência e a conta (sem dígito e sem zeros à esquerda) e o período (até 31 dias, com início em no máximo 5 anos atrás). Sem datas, o BB devolve os lançamentos mais recentes. Cada item da lista em {lancamentos} traz os campos do BB (dataLancamento, valorLancamento, indicadorSinalLancamento C/D, textoDescricaoSubHistorico, numeroDocumento, contrapartida...) e mais data (dd/mm/aaaa) e valor (negativo nos débitos). Exige o certificado digital na conexão.

Exemplo: Todo dia às 7h, consulte o extrato do dia anterior e lance cada crédito no contas a receber do ERP.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Agência *	Texto		Sem o dígitoEx.: `452`
Conta *	Texto		Sem o dígitoEx.: `123873`
De	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Até	Texto		No máximo 31 dias depois do início
Variável da lista	Variável de saída	`lancamentos`

+ Avançado (2)

Campo	Tipo	Padrão	Detalhes
Buscar todas as páginas	Sim/Não	`Sim`
Lançamentos por página	Número	`120`	Entre 30 e 120 (regra do BB)

Resultado: guardado na variável lancamentos (Lista).

Cobrança (boletos)

Registrar Boleto

banco_brasil.registrar_boleto

Registra um boleto de cobrança no BB e devolve linha digitável, código de barras e Pix

Como usar

Informe o convênio, a carteira e a variação (dados do contrato de cobrança), o número do boleto, o vencimento, o valor e o pagador. O resultado em {boleto} traz linhaDigitavel, codigoBarraNumerico, numero e, com Pix, qrCode (emv, url, txId). Juros, multa, desconto e outros campos ficam nos parâmetros avançados. Valores aceitam 150,00 ou 150.00; datas aceitam dd/mm/aaaa.

Exemplo: Para cada linha da planilha de cobranças, registre o boleto com o vencimento e o valor da linha e grave a linha digitável na própria planilha.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Convênio *	Texto		Número do convênio de cobrança (7 dígitos)Ex.: `3128557`
Carteira *	Texto	`17`	Ex.: `17`
Variação da carteira *	Texto		Ex.: `35`
Número do boleto *	Texto		Sequência (até 10 dígitos) ou o número completo de 20 dígitos
Vencimento *	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Valor *	Texto		Ex.: `150,00`
CPF/CNPJ do pagador *	Texto
Nome do pagador *	Texto
Endereço	Texto
CEP	Texto
Cidade	Texto
Bairro	Texto
UF	Texto		Ex.: `SP`
Boleto com Pix (QR Code)	Sim/Não	`Não`
Variável do resultado	Variável de saída	`boleto`

+ Avançado (18)

Campo	Tipo	Padrão	Detalhes
E-mail do pagador	Texto
Telefone do pagador	Texto
Seu número	Texto		Número do documento no seu sistema (ex.: nota fiscal)
Data de emissão	Texto		Vazio usa hoje
Mensagem no boleto	Texto (várias linhas)		Até 165 caracteres
Tipo de juros	Opção	`Sem juros`	Opções: Sem juros, Valor por dia de atraso, Taxa mensal (%)
Valor ou % de juros	Texto		Só quando «Tipo de juros» = «Valor por dia de atraso» ou «Taxa mensal (%)»
Tipo de multa	Opção	`Sem multa`	Opções: Sem multa, Valor fixo, Percentual (%)
Valor ou % de multa	Texto		Só quando «Tipo de multa» = «Valor fixo» ou «Percentual (%)»
Data da multa	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de dataSó quando «Tipo de multa» = «Valor fixo» ou «Percentual (%)»
Tipo de desconto	Opção	`Sem desconto`	Opções: Sem desconto, Valor fixo até a data, Percentual até a data
Valor ou % de desconto	Texto		Só quando «Tipo de desconto» = «Valor fixo até a data» ou «Percentual até a data»
Desconto válido até	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de dataSó quando «Tipo de desconto» = «Valor fixo até a data» ou «Percentual até a data»
Dias para receber após o vencimento	Número
Tipo de título	Texto	`2`	Código do BB: 2 duplicata mercantil, 4 duplicata de serviço, 12 nota promissória...
Aceite	Opção	`Não aceite`	Opções: Não aceite, Aceite
Modalidade	Opção	`Simples`	Opções: Simples, Vinculada
Campos extras (JSON)	Código		Outros campos da API, enviados como estão (ex.: beneficiarioFinal)

Resultado: guardado na variável boleto (Dicionário).

Listar Boletos

banco_brasil.listar_boletos

Lista os boletos da conta, em aberto ou baixados, com filtros de data

Como usar

Informe a agência e a conta (sem dígito) e a situação: em aberto ou baixados/liquidados. Filtre por vencimento, registro ou movimento. O resultado em {boletos} é uma lista; cada item traz numeroBoletoBB, dataVencimento, valorOriginal, codigoEstadoTituloCobranca e outros campos. Use com Para Cada.

Exemplo: Liste os boletos liquidados de ontem (situação B, movimento de ontem até ontem) e dê baixa nas faturas do ERP.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Agência *	Texto		Sem o dígitoEx.: `452`
Conta *	Texto		Sem o dígitoEx.: `123873`
Situação *	Opção	`Em aberto`	Opções: Em aberto, Baixados, liquidados ou protestados
Vencimento de	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Vencimento até	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Variável da lista	Variável de saída	`boletos`

+ Avançado (9)

Campo	Tipo	Padrão	Detalhes
Carteira	Texto
Variação da carteira	Texto
Registro de	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Registro até	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Movimento de	Texto		Para baixados ou liquidados (situação B)
Movimento até	Texto
Vencidos	Opção		Opções: Todos, Só vencidos, Só a vencer
Outros filtros	Pares chave e valor		Parâmetros da API, ex.: cpfPagador, codigoEstadoTituloCobranca
Buscar todas as páginas	Sim/Não	`Sim`	O BB devolve 300 boletos por vez

Resultado: guardado na variável boletos (Lista).

Consultar Boleto

banco_brasil.consultar_boleto

Detalha um boleto: situação, valores, datas e pagamento

Como usar

Informe o convênio e o número do boleto. O resultado em {detalhe} traz a situação (codigoEstadoTituloCobranca), os valores, as datas e, se pago, dataCreditoLiquidacao e valorPagoSacado.

Exemplo: Consulte o boleto antes de enviar a segunda via, para não cobrar quem já pagou.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Convênio *	Texto		Número do convênio de cobrança (7 dígitos)Ex.: `3128557`
Número do boleto *	Texto		Sequência (até 10 dígitos) ou o número completo de 20 dígitos
Variável do resultado	Variável de saída	`detalhe`

Resultado: guardado na variável detalhe (Dicionário).

Alterar Boleto

banco_brasil.alterar_boleto

Muda vencimento, valor, abatimento ou "seu número" de um boleto registrado

Como usar

Informe o convênio, o número do boleto e o que mudar: novo vencimento, novo valor ou abatimento. Outras alterações da API (juros, multa, protesto...) vão em Campos extras, em JSON.

Exemplo: Prorrogue em 10 dias o vencimento dos boletos de clientes que pediram mais prazo.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Convênio *	Texto		Número do convênio de cobrança (7 dígitos)Ex.: `3128557`
Número do boleto *	Texto		Sequência (até 10 dígitos) ou o número completo de 20 dígitos
Novo vencimento	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
Novo valor	Texto
Abatimento	Texto
Variável do resultado	Variável de saída	`alteracao`

+ Avançado (2)

Campo	Tipo	Padrão	Detalhes
Novo "seu número"	Texto
Campos extras (JSON)	Código		Outras alterações da API (ex.: indicadorCobrarJuros e juros)

Resultado: guardado na variável alteracao (Dicionário).

Baixar Boleto

banco_brasil.baixar_boleto

Baixa (cancela) um boleto em aberto

Como usar

Informe o convênio e o número do boleto. O resultado em {baixa} traz dataBaixa e horarioBaixa.

Exemplo: Baixe os boletos das faturas canceladas no ERP.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Convênio *	Texto		Número do convênio de cobrança (7 dígitos)Ex.: `3128557`
Número do boleto *	Texto		Sequência (até 10 dígitos) ou o número completo de 20 dígitos
Variável do resultado	Variável de saída	`baixa`

Resultado: guardado na variável baixa (Dicionário).

Pix do Boleto

banco_brasil.pix_boleto

Consulta, gera ou cancela o Pix (QR Code) de um boleto

Como usar

Escolha a ação: consultar o Pix do boleto, gerar um Pix para um boleto que não tem, ou cancelar o Pix. O resultado em {pix} traz o qrCode (emv para o copia e cola, url, txId).

Exemplo: Gere o Pix dos boletos em aberto e envie o copia e cola por e-mail aos clientes.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Convênio *	Texto		Número do convênio de cobrança (7 dígitos)Ex.: `3128557`
Número do boleto *	Texto		Sequência (até 10 dígitos) ou o número completo de 20 dígitos
Ação *	Opção	`Consultar`	Opções: Consultar, Gerar, Cancelar
Variável do resultado	Variável de saída	`pix`

Resultado: guardado na variável pix (Dicionário).

Pix

Criar Cobrança Pix Imediata

banco_brasil.criar_cobranca_imediata

Cria uma cobrança Pix com QR Code dinâmico e devolve o copia e cola

Como usar

Informe a chave Pix da conta, o valor e, se quiser, o devedor e uma mensagem. O resultado em {cobranca} traz txid, pixCopiaECola (o código para pagar), location e status ATIVA. Use o pixCopiaECola para gerar a imagem do QR Code ou enviar ao cliente. Para saber se foi pago, use Consultar Cobrança Pix (status CONCLUIDA).

Exemplo: No caixa da loja, crie uma cobrança de R$ 89,90 com expiração de 10 minutos e mostre o QR Code ao cliente.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Chave Pix do recebedor *	Texto		Chave cadastrada na conta do BB (CNPJ, e-mail, telefone ou aleatória)
Valor *	Texto		Ex.: `150,00`
Expiração	Número	`3600 s`
CPF/CNPJ do devedor	Texto
Nome do devedor	Texto		Obrigatório quando houver CPF/CNPJ
Mensagem ao pagador	Texto		Até 140 caracteres, aparece no app do banco
Variável do resultado	Variável de saída	`cobranca`

+ Avançado (3)

Campo	Tipo	Detalhes
txid	Texto	Vazio: o identificador é gerado e volta na resposta
Informações adicionais	Pares chave e valor
Campos extras (JSON)	Código	Outros campos da API, enviados como estão

Resultado: guardado na variável cobranca (Dicionário).

Criar Cobrança Pix com Vencimento

banco_brasil.criar_cobranca_vencimento

Cria uma cobrança Pix com data de vencimento (cobv), como um boleto Pix

Como usar

Informe a chave Pix, o valor, o vencimento e o devedor (CPF/CNPJ e nome). A cobrança pode ser paga até o vencimento mais os dias de validade. O resultado em {cobranca} traz txid e pixCopiaECola. Juros, multa, abatimento e desconto seguem o padrão do Banco Central e vão em Campos extras, no objeto valor.

Exemplo: Gere a cobrança do aluguel com vencimento no dia 10 e validade de 30 dias, e envie o copia e cola ao inquilino.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
Chave Pix do recebedor *	Texto		Chave cadastrada na conta do BB (CNPJ, e-mail, telefone ou aleatória)
Valor *	Texto		Ex.: `150,00`
Vencimento *	Texto		dd/mm/aaaa, aaaa-mm-dd ou uma variável de data
CPF/CNPJ do devedor *	Texto
Nome do devedor *	Texto
Dias para pagar após o vencimento	Número	`30`
Mensagem ao pagador	Texto		Até 140 caracteres, aparece no app do banco
Variável do resultado	Variável de saída	`cobranca`

+ Avançado (7)

Campo	Tipo	Detalhes
txid	Texto	Vazio: o identificador é gerado e volta na resposta
E-mail do devedor	Texto
Endereço do devedor	Texto
Cidade	Texto
UF	Texto
CEP	Texto
Campos extras (JSON)	Código	Outros campos da API, enviados como estão

Resultado: guardado na variável cobranca (Dicionário).

Consultar Cobrança Pix

banco_brasil.consultar_cobranca_pix

Consulta uma cobrança Pix pelo txid: situação, valor e pagamentos

Como usar

Informe o txid e o tipo (imediata ou com vencimento). O resultado em {cobranca} traz status (ATIVA, CONCLUIDA, REMOVIDA_PELO_USUARIO_RECEBEDOR, REMOVIDA_PELO_PSP), valor, pixCopiaECola e, se paga, a lista pix com endToEndId e horário.

Exemplo: Depois de mostrar o QR Code, consulte a cobrança a cada 5 segundos até o status ser CONCLUIDA e libere o pedido.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
txid *	Texto		Identificador da cobrança (26 a 35 letras e números)
Tipo de cobrança *	Opção	`Imediata (cob)`	Opções: Imediata (cob), Com vencimento (cobv)
Variável do resultado	Variável de saída	`cobranca`

Resultado: guardado na variável cobranca (Dicionário).

Listar Cobranças Pix

banco_brasil.listar_cobrancas_pix

Lista as cobranças Pix criadas num período menor que 5 dias

Como usar

Informe o período (menos de 5 dias, regra do BB) e, se quiser, o tipo, a situação e o CPF/CNPJ do devedor. O resultado em {cobrancas} é uma lista; use com Para Cada.

Exemplo: Liste as cobranças CONCLUIDA de ontem e dê baixa nos pedidos do e-commerce.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
De	Texto		Data ou data e hora; o período deve ser menor que 5 dias (regra do BB)
Até	Texto		Vazio: agora
Tipo de cobrança *	Opção	`Imediata (cob)`	Opções: Imediata (cob), Com vencimento (cobv)
Situação	Opção		Opções: Todas, Ativa, Paga, Cancelada, Removida pelo banco
Variável da lista	Variável de saída	`cobrancas`

+ Avançado (2)

Campo	Tipo	Padrão	Detalhes
CPF/CNPJ do devedor	Texto
Buscar todas as páginas	Sim/Não	`Sim`

Resultado: guardado na variável cobrancas (Lista).

Cancelar Cobrança Pix

banco_brasil.cancelar_cobranca_pix

Cancela uma cobrança Pix ativa; o QR Code deixa de aceitar pagamento

Como usar

Informe o txid e o tipo. A cobrança passa a REMOVIDA_PELO_USUARIO_RECEBEDOR. Uma cobrança já paga não pode ser cancelada: devolva o Pix com Devolver Pix.

Exemplo: Cancele a cobrança quando o cliente desistir da compra antes de pagar.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
txid *	Texto		Identificador da cobrança (26 a 35 letras e números)
Tipo de cobrança *	Opção	`Imediata (cob)`	Opções: Imediata (cob), Com vencimento (cobv)
Variável do resultado	Variável de saída	`cobranca`

Resultado: guardado na variável cobranca (Dicionário).

Listar Pix Recebidos

banco_brasil.listar_pix_recebidos

Lista os Pix recebidos na conta num período menor que 5 dias

Como usar

Informe o período (menos de 5 dias) e, se quiser, o txid ou o CPF/CNPJ do pagador. Cada item da lista em {pix_recebidos} traz endToEndId, txid (se veio de cobrança), valor, horario, pagador e devolucoes.

Exemplo: Todo dia às 8h, liste os Pix recebidos no dia anterior e concilie com as notas emitidas.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
De	Texto		Data ou data e hora; o período deve ser menor que 5 dias (regra do BB)
Até	Texto		Vazio: agora
Variável da lista	Variável de saída	`pix_recebidos`

+ Avançado (3)

Campo	Tipo	Padrão
txid	Texto
CPF/CNPJ do pagador	Texto
Buscar todas as páginas	Sim/Não	`Sim`

Resultado: guardado na variável pix_recebidos (Lista).

Consultar Pix Recebido

banco_brasil.consultar_pix

Consulta um Pix recebido pelo endToEndId, com as devoluções

Como usar

Informe o endToEndId. O resultado em {pix} traz valor, horario, pagador, txid e devolucoes.

Exemplo: Antes de devolver um Pix, consulte-o para conferir o valor já devolvido.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
endToEndId do Pix *	Texto		Identificador do Pix recebido (32 caracteres, começa com E)
Variável do resultado	Variável de saída	`pix`

Resultado: guardado na variável pix (Dicionário).

Devolver Pix

banco_brasil.devolver_pix

Devolve todo ou parte de um Pix recebido

Como usar

Informe o endToEndId do Pix e o valor a devolver. O resultado em {devolucao} traz id, rtrId e status (EM_PROCESSAMENTO, DEVOLVIDO ou NAO_REALIZADO). A devolução é processada pelo Banco Central: consulte depois com Consultar Devolução Pix.

Exemplo: Quando um pedido for cancelado depois de pago, devolva o Pix ao cliente com a mensagem 'Pedido cancelado'.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
endToEndId do Pix *	Texto		Identificador do Pix recebido (32 caracteres, começa com E)
Valor a devolver *	Texto
Mensagem ao pagador	Texto
Variável do resultado	Variável de saída	`devolucao`

+ Avançado (1)

Campo	Tipo	Padrão	Detalhes
Id da devolução	Texto		Vazio: gerado e devolvido na resposta; guarde para consultar depois

Resultado: guardado na variável devolucao (Dicionário).

Consultar Devolução Pix

banco_brasil.consultar_devolucao_pix

Consulta a situação de uma devolução de Pix

Como usar

Informe o endToEndId do Pix e o id da devolução (devolvido por Devolver Pix). O resultado em {devolucao} traz status (EM_PROCESSAMENTO, DEVOLVIDO ou NAO_REALIZADO) e, se não realizada, o motivo.

Exemplo: Consulte a devolução até o status ser DEVOLVIDO e então envie o comprovante ao cliente.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
endToEndId do Pix *	Texto		Identificador do Pix recebido (32 caracteres, começa com E)
Id da devolução *	Texto
Variável do resultado	Variável de saída	`devolucao`

Resultado: guardado na variável devolucao (Dicionário).

Avançado

Chamar API do BB

banco_brasil.call_api

Chamada livre a qualquer API do BB, com a autenticação da conexão

Como usar

Informe o método, o caminho (ex.: /boletos na API Cobrança) e, se precisar, parâmetros de query e o corpo em JSON. A resposta em JSON fica em {resposta} como dicionário ou lista. Erros do banco param o robô com o status e a mensagem do BB, e podem ser tratados com Tentar/Capturar.

Exemplo: API Cobrança, GET /boletos com indicadorSituacao=A e o número do convênio para listar os boletos em aberto.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão *	Variável	`bb`
API *	Opção	`Cobrança`	Opções: Cobrança, Pix, Extratos
Método *	Opção	`GET`	Opções: GET, POST, PUT, PATCH, DELETE
Caminho *	Texto		Relativo à URL base da API (ex.: /boletos na Cobrança, /cob no Pix)Ex.: `/boletos`
Parâmetros (query)	Pares chave e valor
Corpo (JSON)	Código		Só quando «Método» = «POST» ou «PUT» ou «PATCH»
Variável da resposta	Variável de saída	`resposta`

+ Avançado (1)

Campo	Tipo	Padrão	Detalhes
Cabeçalhos extras	Pares chave e valor

Resultado: guardado na variável resposta (Qualquer).