# Integração Bancária API Banco do Brasil Webhook
Este documento fornece instruções detalhadas sobre a integração e utilização da API do Banco do Brasil, incluindo a configuração do Webhook para notificações em tempo real. A API permite a automação de processos bancários, enquanto o Webhook garante atualizações instantâneas sobre transações e eventos.

> [!NOTE] Requisitos Importantes
> - **Sistema operacional Debian 10**.
> - Para a homologação de uma carteira API o **indicado** é abrir um novo convênio de conta bancária. Caso deseje utilizar um que já esteja em uso no Sistema e/ou que já tenha boletos emitidos por ele, deve estar ciente de que podem ocorrer divergências nos relatórios provenientes de arquivos de retorno.  
Entre as divergências estão: Informação de Título não encontrado nos processamentos de retorno (quem se referem a títulos da carteira de API), liquidações atreladas a boletos divergentes, etc.
> - **Além disso, após a homologação de sua carteira de API, é crucial evitar a geração de novos boletos pela antiga carteira de remessa/retorno, que utiliza o mesmo convênio**.

## Funcionalidades principais

- Geração automática de boletos.  
- Consulta de status de transações.  
- Recebimento de notificações em tempo real por meio do Webhook.  
- Gerenciamento da carteira de cobrança.

## Funcionamento no sistema

A integração da API do Banco do Brasil no sistema ocorre da seguinte forma:

1. **Autenticação**:  
    * O sistema utiliza as credenciais fornecidas pelo Banco do Brasil para se autenticar e acessar a API.  
2. **Sincronização de dados**:  
    - O sistema envia as informações de cobrança para o Banco do Brasil.  
    - Recebe atualizações sobre o status dos boletos e dos pagamentos.  
3. **Processamento automático**:  
    - Os pagamentos são baixados automaticamente no sistema.  
4. **Interface de usuário**:  
    - Os usuários conseguem gerenciar boletos e visualizar as informações diretamente no sistema.

## Processo de integração e homologação

Para realizar a integração e homologação da API do Banco do Brasil no sistema, siga os passos abaixo:

### Homologação
> [!EXAMPLE] Dados bancários necessários para a integração:
>
>**001 - Banco do Brasil (API)**
>
>* 1 - Número da agência com dígito?
>* 2 - Número da conta com dígito?
>* 3 - Número do Convênio / Beneficiário ou Cedente?
>* 4 - Número da carteira?
>* 5 - Variação da carteira?
>* 6 - Client_ID?
>* 7 - Client_Secret?
>* 8 - Developer Aplication Key?
>* 9 - Este convênio bancário é totalmente novo ou já foi usado para emissão?

> [!TIP] Dica!
> Caso tenha dúvida sobre algum dos dados bancários, consulte o(a) Gerente de sua Conta Bancária.

### Passo a passo para obter as Credenciais da API
> [!info] Informação!
> Para a homologação da carteira de API do Banco do Brasil, você também precisa gerar o **Client-ID**, **Client_Secret** e a **Developer application key**, que são as credenciais da aplicação da API no site Developers do Banco do Brasil:
1. Acesse o [Developers Banco do Brasil](https://www.bb.com.br/site/developers/).  
2. Faça login com sua conta.  
3. Clique em Nova Aplicação.  
4. Insira um nome e uma descrição para a sua aplicação e prossiga.  
5. No tópico chamado **Selecione pelo menos uma API para sua aplicação**, marque os escopos que deseja utilizar.  
6. Neste caso, selecione os escopos:
	   - Cobranças  
	   - PIX  
7. Clique no botão Criar. Você será redirecionado novamente ao menu de Aplicações.  
8. Clique sobre a aplicação que acabou de criar.  
9. No menu lateral esquerdo, clique no botão Produção.  
10. Siga os passos pedidos e insira suas informações para seguir com a contratação das chaves em produção.  
11. Após concluir a contratação, clique em Credenciais no menu lateral esquerdo e localize as seguintes chaves: **Client-ID**, **Client_Secret** e **Developer application key**. Copie essas chaves, pois serão usadas para configurar a carteira.

> [!SUCCESS] Credenciais API Finalizadas!  
> Com essas informações e os demais dados bancários, o atendente da IXC Soft poderá seguir com a homologação da sua carteira de cobrança via API.

### Criando a carteira

1. Acesse o menu **Sistema**.  
2. Vá até a pasta **Financeiro**.  
3. Clique em **Carteira de cobrança**.  
4. Clique em **Novo**.  
5. Na aba chamada **Carteira de cobrança**, realize as seguintes configurações:  
	- **Descrição:** Defina o nome da carteira.  
	- **Conta:** Crie a conta responsável por guardar as informações bancárias.  
	- **Tipo de recebimento:** Escolha a opção **Gateway.**  
	- **Enviar e-mail para cliente ao gerar:** Selecione **Não**, pois exige e-mail cadastrado no cliente e envia a fatura automaticamente para registro no banco (por isso, não é recomendado utilizar).  
	- **Validar filial na venda:** Marque como **Sim.**  
	- **Planejamento analítico:** Utilize **240**, ou cadastre um novo código.

### Criando a conta

- **Conta:** Dê um nome à conta.  
- **Tipo da Conta:** Escolha a opção **Banco.**  
- **Data de abertura:** Indique a data do dia da configuração da conta.  
- **Planejamento analítico:** Para mais informações, acesse: [[formulario planejamento analitico|Formulário Planejamento Analítico]].  
- **Filial:** Escolha o ID da filial para à qual a **Conta** e a **Carteira** serão vinculadas.

Na aba seguinte, **Banco:**

- **Banco:** Selecione o ID da instituição bancária, conforme o cadastro nacional. Para o Banco do Brasil, utilize:  
   - **001 - Banco do Brasil S.A.**  
- **Agência:** Preencha o número da sua agência.  
- **Dígito verificador da agência:** Informe o dígito após o número da agência.  
- **Número da conta:** Informe o número da conta bancária.  
- **Dígito verificador da conta:** Informe o dígito verificador da conta.  
- Caso alguma informação for “x”, preencha com letra maiúscula **X**.

### Configurações gateway

- **Gateway:** Selecione o **Banco do Brasil.**  
- **Importado gateway:** Marque como **Não.**  
- **Ambiente gateway:** Escolha a opção **Produção.**  
- **Client_Id e Client_secret:** Cole os códigos gerados no site Developers Banco do Brasil, conforme os passos anteriores.  
- **Data de crédito Pix e Data de crédito boleto:** Indique, em dias, os prazos para o valor cair na conta após o pagamento. Exemplo: Pix = 0 (crédito no mesmo dia), Boleto = 1 (crédito no dia seguinte).  
- **Envia e-mail Gateways:** Marque como **Não.**  
- **Usar webhook:** Marque como **Sim.**  
- **Webhook URL callback:** Clique no botão para gerar a URL.  
- **Gera pix:** Marque como **Sim.**  
- **Tarifas Gateway:** Defina o lançamento das tarifas manualmente, pois o banco não faz isso automaticamente.  
- **Data de crédito Pix / Data de crédito boleto:** Informe as datas em que a movimentação financeira será registrada no sistema.

### Configurações bancárias

- **Número do convênio:** Informe o número do convênio, beneficiário ou cedente vinculado à sua conta bancária.  
- **Carteira:** Preencha com o número da carteira fornecido pelo banco.  
- **Variação da carteira:** Informe a variação da carteira.  
- **Prazo após vencimento (dias):** Insira o número de dias que o título ficará disponível para pagamento após o vencimento. O valor padrão é 90 dias, mas confirme com o gerente da sua conta.

> [!TIP] Dica!  
> Para a API do Banco do Brasil, não é necessário o uso de **Contador**.

### Juros/Multas/Desconto

- **Juros %:** Valor padrão permitido por lei: 0.033% (acima deste, pode ser considerado abusivo).  
- **Multa %:** Valor padrão permitido por lei: 2%.  
- **Desconto até o vencimento R$:** Informe o valor do desconto em **Reais** caso o pagamento ocorra até o vencimento.  
- **Desconto até o vencimento %:** Informe o desconto em **Porcentagem** para pagamento até o vencimento.

Para mais informações, acesse: [[juros, multas e desconto|Juros, Multas e Desconto]].

### Instruções

> [!INFO] Informação:  
> * A API do Banco do Brasil permite até **165 caracteres** ao todo.  
> * Não há limite de linhas, mas cada linha deve ter até **55 caracteres**.  
> * **Atenção:** não são permitidos caracteres de escape (\r ou \n).

Remova as aspas das hashtags nas instruções abaixo:

- **Instrução 1:**  
```
Após vencimento juros R$ #juro# ao dia.
```

- **Instrução 2:**  
```
Após vencimento multa R$ #multa#.
```

> [!WARNING] Aviso!  
> Se adicionar mais linhas de instrução, insira também as variáveis de leitura correspondentes em **Imprimir instruções quando...**

Para mais informações, acesse: [[instrucoes da carteira de cobranca|Instruções da Carteira de Cobrança]].

### Impressão

- **Layout de impressão:** Utilize o padrão **3 por página.**

Para mais informações, acesse: [[layouts de impressao|Layouts de Impressão]].

### Configurando o Webhook

1. Acesse o [Developers Banco do Brasil](https://www.bb.com.br/site/developers/).  
2. Selecione a aplicação desejada.  
3. No menu lateral esquerdo, clique no botão Webhook.  
4. Clique na aba Eventos e depois em Cadastrar Evento.  
5. Selecione o convênio de cobrança e preencha com os seguintes dados:

> [!tip] Eventos:  
> * **URL:** Cole a URL Webhook gerada na carteira de cobrança do sistema.  
> * **E-mail:** Informe um e-mail para receber informações da API do banco.  
> * **Tipo de evento:** Marque a opção **BAIXA OPERACIONAL**.

6. Após preencher os dados, clique em Salvar.  
7. No menu lateral esquerdo, clique em URLs.  
8. Em **URL de Callback**, insira a mesma URL que foi informada anteriormente.  
9. Finalize clicando no botão Editar.

## Fluxo de funcionamento

```mermaid
sequenceDiagram
    participant S as Sistema
    participant API as API Banco do Brasil
    participant W as Webhook

    S->>API: Envia requisição (ex: gerar boleto)
    API->>S: Responde com dados do boleto
    Note over API,W: Evento ocorre (ex: pagamento)
    W->>S: Notifica sobre o evento
    S->>API: Confirma recebimento da notificação
```

### Ativação

> [!SUCCESS] Finalizado!  
> Com todos os passos anteriores concluídos, a carteira e suas tarefas estão prontas. Você já pode gerar um boleto de teste, realizar o pagamento e validar se a baixa foi feita automaticamente pelo sistema.  
Quando a baixa automática for confirmada, o processo de homologação estará concluído.

## Considerações finais

A integração com a API do Banco do Brasil, junto com a configuração do Webhook, permite uma gestão financeira mais automatizada e eficiente. Mantenha sempre suas credenciais seguras e atualizadas para garantir o bom funcionamento do sistema.

## Etiquetas
#IntegracaoBancaria #ApiBancaria #BancoDoBrasil 

## Leia Também
* [[carteira de cobranca|Carteira de Cobrança]]
* [[integracoes bancarias - carteira de cobranca|Integrações Bancárias - Carteira de Cobrança]]
* [[integracoes bancarias - api|Integrações Bancárias - API]]
* [[api banco do brasil|API Banco do Brasil]]
* [[como solicitar o pix na central do assinante|Como Solicitar o Pix na Central do Assinante]]
* **Manual API Banco do Brasil**: https://apoio.developers.bb.com.br/referency/post/5f4fb7f5b71fb5001268ca44