# Extrair Dados Bancários no Brasil (Widget)

Neste guia, vamos orientá-lo em tudo o que você precisa para extrair dados bancários sobre seus usuários da Rede de Open Finance do Brasil usando nossa API. Isso inclui:

- Uma visão geral do fluxo de dados.
- Configuração do Hosted Widget da Belvo para conectar seus usuários.
- Obtenção dos dados dos seus usuários com base em eventos de webhook enviados pela Belvo.
- Fornecer aos seus usuários uma maneira de gerenciar seus consentimentos.


## Pré-requisitos

Antes de prosseguir com sua integração, certifique-se de que você leu nosso guia de introdução. No guia de introdução, você criará uma conta Belvo, gerará algumas chaves de API sandbox e configurará uma URL de webhook. Para fins de teste e desenvolvimento de sua integração, recomendamos fortemente o uso do ambiente Sandbox sempre que possível.

Além disso, para fins de teste e desenvolvimento da sua integração, recomendamos fortemente o uso do ambiente Sandbox junto com a instituição Mockbank. Você pode encontrar credenciais de exemplo para simular diferentes usuários para a instituição Mockbank aqui.

## Visão geral do fluxo de dados

A Belvo utiliza um *fluxo de trabalho assíncrono* para melhorar a extração de dados e o fluxo de integração. Como você pode ver no diagrama abaixo, uma vez que o usuário conectou sua conta usando o Hosted Widget e o link é criado, a Belvo carrega todos os dados de forma assíncrona e, em seguida, notifica você usando webhooks que os dados estão disponíveis para você recuperar.


```mermaid
sequenceDiagram
    participant Application
    participant Belvo
    participant Institution

    Application->>Belvo: Cria um Link usando o widget
    Belvo->>Institution: Conecta e confirma o consentimento com a instituição
    Belvo-->>Application: 201 - Criado
    Institution-->>Belvo: A Belvo recupera informações históricas para o ID do link.

    Note over Application,Belvo: OWNERS

    Belvo->>Application: WEBHOOK historical_update (OWNERS)
    Application->>Belvo: GET /owners/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Proprietário

    Note over Application,Belvo: ACCOUNTS

    Belvo->>Application: WEBHOOK historical_update (ACCOUNTS)
    Application->>Belvo: GET /accounts/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Conta

    Note over Application,Belvo: TRANSACTIONS

    Belvo->>Application: WEBHOOK historical_update (TRANSACTIONS)
    Application->>Belvo: GET /transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Transação

    Note over Application,Belvo: BILLS

    Belvo->>Application: WEBHOOK historical_update (BILLS)
    Application->>Belvo: GET /bills/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Fatura

    Note over Application,Belvo: INVESTMENTS

    Belvo->>Application: WEBHOOK historical_update (INVESTMENTS)
    Application->>Belvo: GET /br/investments/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Investimento

    Note over Application,Belvo: INVESTMENT TRANSACTIONS

    Belvo->>Application: WEBHOOK historical_update (INVESTMENT_TRANSACTIONS)
    Application->>Belvo: GET /br/investment-transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes das Transações de Investimento
```

## Configurando o Hosted Widget

O Hosted Widget da Belvo é projetado para simplificar seu processo de desenvolvimento e integração, cumprir com as regulamentações de Open Finance, e é constantemente monitorado por uma equipe de especialistas para melhorar a experiência do usuário.

Nosso Hosted Widget pode ser incorporado em seu aplicativo como um *webview* e guiará seu usuário por todas as etapas para conceder seu consentimento para que você acesse seus dados. Isso inclui redirecionar o usuário para sua instituição para fornecer consentimento e, em seguida, de volta para o seu aplicativo. Você pode ver um fluxo simplificado do que acontece durante o processo de conexão do widget no diagrama abaixo:


```mermaid
sequenceDiagram
    autonumber
    participant Application
    participant Belvo
    participant User
    participant Institution

    Application->>Belvo: Gerar um access_token usando o CPF ou CNPJ do usuário
    Belvo-->>Application: 200 + access_token

    Application->>User: Exibir o widget para seu usuário<br>https://widget.belvo.io/?access_token=access...
    User->>Institution: Seu usuário é redirecionado para sua instituição

    Institution->>Belvo: Uma vez que eles concedem seu consentimento,<br>eles são momentaneamente redirecionados para uma tela segura no navegador
    Belvo->>Application: Usuário redirecionado para seu aplicativo<br>para finalizar o fluxo
    Application-->>Belvo: Usuário completou o fluxo (sucesso)

    Belvo-->>Application: Você recebe o link ID para o usuário
```

Basicamente, sempre que você quiser que seu usuário conecte sua conta de uma instituição financeira no Brasil, você precisará:

### Gerar um token de `access` do widget

Para poder iniciar o widget, você precisará primeiro gerar um token de `access` usando o seguinte payload:

Individual (CPF)

```shell Sandbox Request URL
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'veja o exemplo de payload abaixo'
```


```json Widget Access Token (Individual - OFDA)
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"],
  "widget": {
    "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
    "openfinance_feature": "consent_link_creation",
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-here://error"
    },
    "consent": {
      "terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        }
      ]
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/",
      "overlay_background_color": "#F0F2F4",
      "social_proof": true
    },
    "theme": []
  }
}
```

Empresa (CNPJ)

```shell Sandbox Request URL
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'veja o exemplo de payload abaixo'
```


```json Widget Access Token (Company - OFDA)
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"],
  "widget": {
    "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
    "openfinance_feature": "consent_link_creation",
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-here://error"
    },
    "consent": {
      "terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        },
        {
          "type": "CNPJ",
          "number": "50685362006773",
          "name": "Bragg Mechanics"
        }
      ]
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/",
      "overlay_background_color": "#F0F2F4",
      "social_proof": true
    },
    "theme": []
  }
}
```

| Parâmetro  | Obrigatório | Descrição |
|  --- | --- | --- |
| `id` | sim | Substitua `YOUR_SECRET_ID` pelo ID secreto que você gerou no painel do Belvo. |
| `password` | sim | Substitua `YOUR_SECRET_PASSWORD` pela senha secreta que você gerou no painel do Belvo. |
| `scopes` | sim | O parâmetro `scopes` contém uma lista de permissões que permitem que você crie um link para o usuário. Este é um parâmetro obrigatório e deve ser enviado exatamente como mostrado. |
| `stale_in` | não | O parâmetro `stale_in` permite que você controle por quanto tempo o Belvo armazena dados derivados do usuário. Para mais informações, confira a seção stale_in do nosso artigo sobre controles de retenção de dados. |
| `fetch_resources` | sim | No parâmetro `fetch_resources`, você fornece uma lista de recursos que deseja que o Belvo recupere de forma assíncrona para o usuário. Para OFDA, recomendamos: `["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"]`. |
| `widget.purpose` | sim | No parâmetro `purpose`, você pode personalizar a mensagem que é exibida ao seu usuário sobre para qual caso de uso você está solicitando seus dados. Para mais informações, confira a seção purpose no nosso guia de Hosted Widget (OFDA). |
| `widget.openfinance_feature` | sim | O parâmetro `openfinance_feature` indica que o usuário final passará pelo fluxo OFDA. Deve ser definido como `consent_link_creation`. |
| `widget.callback_urls`
 | sim
 | No objeto `callback_urls`, você **deve** adicionar links para onde seu usuário deve ser redirecionado nos seguintes casos:
- success (seu usuário conectou suas contas com sucesso)
- exit (seu usuário saiu do widget antes de completar o processo)
- event (ocorreu um erro durante o processo de conexão).

Para mais informações, confira a seção callback_urls no nosso guia de Hosted Widget (OFDA). O Belvo enviará informações adicionais com base no evento. Para mais informações, certifique-se de conferir a seção Handling callback events do guia de Hosted Widget (OFDA).
 |
| `widget.consent` | sim | O objeto `consent` é exclusivo do widget OFDA e deve ser fornecido.- No parâmetro `terms_and_conditions_url`, você **deve** fornecer um link para os termos e condições da sua empresa.
- No parâmetro `permissions`, você deve passar o seguinte array de permissões: `["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"]`.
- No array `identification_info`, você precisa fornecer as informações de identificação do usuário para o qual deseja recuperar informações. As informações que você fornecer aqui devem corresponder às informações que a instituição regulada possui para o usuário (por exemplo, para empresas, o CPF e o nome devem ser de um usuário com acesso à conta empresarial). Para indivíduos, você só precisa fornecer o CPF e o nome. Para empresas, você precisa fornecer tanto as informações de CPF quanto de CNPJ. Para mais informações, confira a seção identification_info do nosso guia de Hosted Widget (OFDA).

 |
| `widget.branding`
 | sim
 | No objeto `branding`, você **deve** adicionar seu:
- company_icon
- company_logo
- company_name
- company_terms_url.

Você também pode opcionalmente adicionar uma cor de fundo personalizada para quando o widget abrir, bem como desativar a mensagem do Belvo sobre quantas contas foram conectadas. Para mais informações sobre as opções de branding e personalização do widget, confira nosso guia dedicado.
 |
| `widget.theme` | não | Você pode opcionalmente adicionar as cores da sua marca ao widget usando o parâmetro `theme`. Para mais informações sobre onde essas cores aparecerão no widget, confira a seção dedicada Add custom colors to the widget do nosso guia de Branding. |


Além disso, confira nossa seção Generating an access token do nosso guia de Hosted Widget (OFDA).


```json Access Token Response Example
{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..." // [!code highlight]
}
```

### Iniciar o widget dentro de uma webview

Em seguida, você precisará redirecionar seu usuário para o widget em uma webview dentro do seu aplicativo:


```shell Hosted Widget URL
https://widget.belvo.io/
  ?access_token={access}
  &mode=webapp
  &locale=pt
  &access_mode=single
  &external_id=HJLSI-897809
```

| Parâmetro  | Obrigatório | Descrição |
|  --- | --- | --- |
| `access_token` | sim | Substitua `access` pelo token de acesso que você recebeu. |
| `mode` | sim | Para que o OFDA Hosted Widget funcione corretamente para seus usuários, você deve definir o parâmetro de consulta mode como `webapp`. |
| `locale` | sim | Para que o OFDA Hosted Widget funcione corretamente para seus usuários, você deve definir o parâmetro de consulta locale como `pt`. |
| `access_mode` | não | Você pode usar o parâmetro `access_mode` para definir qual tipo de link deseja criar (`single` ou `recurrent`). Por padrão, o Belvo cria links `recurrent`. Para mais informações sobre os diferentes tipos de links, consulte a seção Links do nosso guia de Links e Instituições. |
| `external_id`
 | altamente recomendado
 | Você pode adicionar um identificador adicional para ser associado ao link no banco de dados do Belvo. O `external_id` que você fornecer:
- Deve ser um ID único para cada usuário no seu banco de dados.
- Deve ter pelo menos três caracteres.
- Pode ser composto apenas por letras, números, hífens (`-`) e underscores (`_`).
- Não pode conter nenhuma informação pessoalmente identificável sobre o usuário (email, nome, número de telefone, número de cartão de crédito, etc.).

Para mais detalhes, consulte a seção Adicionando seu próprio identificador do nosso guia de melhores práticas para criação de Links.
 |


Além disso, confira nossa seção Iniciando o widget do nosso guia de Hosted Widget (OFDA).

### Ouça o evento de sucesso que incluirá o `id` do link.

Assim que seu usuário terminar o fluxo do widget, enviaremos um evento de `success` para a URL que você forneceu ao gerar o token de `access` do widget. Este evento incluirá o `id` do link que você precisará associar com seu `external_id` no seu banco de dados.

Esta etapa requer algum conhecimento sobre como lidar com redirecionamentos e seus parâmetros de consulta. Para detalhes sobre os eventos que enviamos (e seu formato), consulte a seção Tratando eventos de callback do nosso guia de Hosted Widget (OFDA).

Para ajudar no seu desenvolvimento, criamos guias sobre como configurar deep links e ouvir eventos para as seguintes plataformas:

- iOS (Swift)
- Android (Kotlin)
- React Native


### Aguarde os webhooks e recupere os dados

Como a Belvo utiliza um fluxo de trabalho assíncrono, assim que o link é criado, recuperamos automaticamente os últimos 12 meses de dados históricos para o usuário que acabou de conectar sua conta. Nós notificamos você através de eventos de webhook assim que os dados são extraídos e você pode recuperá-los. Para mais detalhes, veja a seção Obtendo Dados.

## Obtendo Dados

Independentemente de você usar links únicos ou recorrentes, uma vez que seu usuário completa o fluxo do widget com sucesso, a Belvo recupera de forma assíncrona os últimos 12 meses de dados de proprietário, conta, transação, fatura e investimento para o link (atualizações históricas). Assim que extraímos os dados, notificamos você usando um webhook que a informação está pronta para ser recuperada.

Se você estiver usando links recorrentes, a Belvo recuperará as informações atualizadas para o link de acordo com sua taxa de atualização (atualizações recorrentes). Assim como nas atualizações históricas, notificamos você usando um webhook que a nova informação está pronta para ser recuperada.

Criação de Link e Limites de Dados
Ao gerar o consentimento e criar o link, a Belvo já consome um limite operacional de Proprietários, Contas, Transações, Faturas e Investimentos (para recuperar os dados históricos do seu usuário). No entanto, a Belvo implementou certos mecanismos internos para otimizar os limites de recuperação de dados. Para mais informações, por favor veja nosso artigo dedicado Limites da Rede de Open Finance (Brasil).

A Rede de Open Finance do Brasil estabelece limites mensais sobre a frequência com que você pode recuperar dados para uma pessoa ou empresa específica. Esses limites operacionais estão vinculados a uma combinação de:

- o CPF ou CNPJ do usuário
- os dados da API que você deseja obter (Proprietário, Conta, Transação ou Fatura)
- o certificado da Rede de Open Finance


Uma vez que o limite operacional mensal de chamadas de API é atingido, nenhuma informação adicional pode ser recuperada para o CPF/CNPJ até o início do próximo mês do calendário. No entanto, a Belvo implementou otimizações para maximizar a quantidade de dados que você pode recuperar para seus usuários de acordo com suas necessidades de dados. Para mais informações, por favor veja nosso artigo dedicado Limites da Rede de Open Finance (Brasil).

### Atualizações históricas

Abaixo você pode ver o fluxo de dados para links únicos e recorrentes uma vez que um link é criado:


```mermaid
sequenceDiagram
    participant Application
    participant Belvo
    participant Institution

    Application->>Belvo: Crie um Link usando o widget
    Belvo->>Institution: Conecte e confirme o consentimento com a instituição
    Belvo-->>Application: 201 - Criado
    Institution-->>Belvo: Belvo recupera informações históricas para o ID do link.

    Note over Application,Belvo: PROPRIETÁRIOS

    Belvo->>Application: WEBHOOK historical_update (PROPRIETÁRIOS)
    Application->>Belvo: GET /owners/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Proprietário

    Note over Application,Belvo: CONTAS

    Belvo->>Application: WEBHOOK historical_update (CONTAS)
    Application->>Belvo: GET /accounts/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Conta

    Note over Application,Belvo: TRANSAÇÕES

    Belvo->>Application: WEBHOOK historical_update (TRANSAÇÕES)
    Application->>Belvo: GET /transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Transação

    Note over Application,Belvo: CONTAS

    Belvo->>Application: WEBHOOK historical_update (CONTAS)
    Application->>Belvo: GET /bills/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Conta

    Note over Application,Belvo: INVESTIMENTOS

    Belvo->>Application: WEBHOOK historical_update (INVESTIMENTOS)
    Application->>Belvo: GET /br/investments/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Investimento

    Note over Application,Belvo: TRANSAÇÕES DE INVESTIMENTO

    Belvo->>Application: WEBHOOK historical_update (TRANSAÇÕES_DE_INVESTIMENTO)
    Application->>Belvo: GET /br/investment-transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes das Transações de Investimento
```

Cada vez que você receber um webhook para um determinado recurso (proprietários, contas, transações, contas, investimentos ou transações de investimento), você precisará fazer uma chamada GET para esse endpoint, usando o ID do link, para recuperar as informações.

#### Obter informações do Owner

A Belvo irá recuperar de forma assíncrona os dados do **owner** dos últimos 12 meses para o seu link e, em seguida, enviará um webhook quando a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):


```json Owners Historical Update
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS", // [!code highlight]
  "process_type": "historical_update", // [!code highlight]
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_owners": 2 // Número total de owners
  }
}
```

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Owners para recuperar os dados do link fornecido:


```curl GET Owner Information
curl --request GET 'https://api.belvo.com/api/owners/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `id` | string | sim | O `link_id` que você recebe na sua notificação de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


#### Obter informações da Conta

A Belvo irá recuperar de forma assíncrona os últimos 12 meses de dados da **conta** para o seu link e, em seguida, enviará um webhook quando a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):


```json Accounts Historical Update
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS", // [!code highlight]
  "process_type": "historical_update", // [!code highlight]
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_accounts": 5 // Número total de contas encontradas.
  }
}
```

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Accounts para recuperar os dados do link fornecido:


```curl GET Account Information
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `id` | string | sim | O `link_id` que você recebe na sua notificação de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


#### Obter informações de Transação

A Belvo irá recuperar de forma assíncrona os dados de **transação** dos últimos 12 meses para o seu link e, em seguida, enviará um webhook assim que a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):


```json Transactions Historical Update
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS", // [!code highlight]
  "process_type": "historical_update", // [!code highlight]
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Número total de transações encontradas
    "total_inflow_transactions": 10, // Número total de transações de entrada
    "total_outflow_transactions": 9, // Número total de transações de saída
    "first_transaction_date": "2017-01-03", // Data da primeira transação
    "last_transaction_date": "2020-03-25" // Data da última transação
  }
}
```

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Transactions para recuperar os dados para o link fornecido:


```curl GET Transaction Information
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `id` | string | sim | O `link_id` que você recebe na sua notificação de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


#### Obter informações da Fatura

A Belvo irá recuperar de forma assíncrona os dados das **faturas** dos últimos 12 meses para o seu link e, em seguida, enviará um webhook quando a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):


```json Bill Historical Update
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS", // [!code highlight]
  "process_type": "historical_update", // [!code highlight]
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // [!code warning]
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_bills": 2 // Número total de faturas
  }
}
```

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Bills para recuperar os dados do link fornecido:


```curl GET Bill Information
curl --request GET 'https://api.belvo.com/api/bills/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `id` | string | sim | O `link_id` que você recebe na sua notificação de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


### Atualizações recorrentes

Se você estiver usando links recorrentes, receberá eventos de webhook de acordo com a frequência de atualização do Link que você estabeleceu com a Belvo (diária, semanal, mensal, etc.). A Belvo envia os seguintes eventos de webhook para atualizações:

- `new_owners_available`
Você receberá um webhook `new_owners_available` sempre que detectarmos que houve uma mudança nos detalhes dos proprietários das contas.
- `new_accounts_available`
Você receberá um webhook `new_accounts_available` sempre que detectarmos que houve uma mudança nas contas que o link possui.
- `new_transactions_available`
Você receberá um webhook `new_transactions_available` sempre que detectarmos que novas transações ocorreram para qualquer conta que o link possui.
- `new_bills_available`
Você receberá um webhook `new_bills_available` sempre que um novo extrato de fatura de cartão de crédito for gerado para um período de faturamento.
- `new_investments_available`
Você receberá um webhook `new_investments_available` sempre que detectarmos que houve uma mudança nos investimentos que o link possui.
- `new_investment_transactions_available`
Você receberá um webhook `new_investment_transactions_available` sempre que detectarmos que houve novas transações para um investimento.



```mermaid
sequenceDiagram
    participant Application
    participant Belvo
    participant Institution

    Belvo->>Institution: Obter novos dados para o link fornecido
    Institution-->>Belvo: Informações do recurso

    Note over Application,Belvo: PROPRIETÁRIOS

    Belvo->>Application: WEBHOOK new_owners_available
    Application->>Belvo: GET /owners/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Proprietário

    Note over Application,Belvo: CONTAS

    Belvo->>Application: WEBHOOK new_accounts_available
    Application->>Belvo: GET /accounts/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Conta

    Note over Application,Belvo: TRANSAÇÕES

    Belvo->>Application: WEBHOOK new_transactions_available
    Application->>Belvo: GET /transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Transação

    Note over Application,Belvo: FATURAS

    Belvo->>Application: WEBHOOK new_bills_available
    Application->>Belvo: GET /bills/?link={link.id}
    Belvo-->>Application: 200 + Detalhes da Fatura

    Note over Application,Belvo: INVESTIMENTOS

    Belvo->>Application: WEBHOOK new_investments_available
    Application->>Belvo: GET /br/investments/?link={link.id}
    Belvo-->>Application: 200 + Detalhes do Investimento

    Note over Application,Belvo: TRANSAÇÕES DE INVESTIMENTO

    Belvo->>Application: WEBHOOK new_investment_transactions_available
    Application->>Belvo: GET /br/investment-transactions/?link={link.id}
    Belvo-->>Application: 200 + Detalhes das Transações de Investimento
```

Assim que você receber um webhook sobre informações recém-atualizadas, você só precisa fazer a mesma chamada GET que fez para a atualização histórica para receber as informações atualizadas.


```shell
# Recuperar dados do proprietário
curl --request GET 'https://api.belvo.com/api/owners/?link={id}'

# Recuperar dados da conta
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}'

# Recuperar dados da transação
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}'

# Recuperar dados da fatura
curl --request GET 'https://api.belvo.com/api/bills/?link={id}'

# Recuperar dados do investimento
curl --request GET 'https://api.belvo.com/api/investments/?link={id}'

# Recuperar dados da transação de investimento
curl --request GET 'https://api.belvo.com/api/investment-transactions/?link={id}'
```

### Outros eventos de webhook

A Belvo também notifica você quando há alterações no consentimento do seu link. Você pode receber os seguintes webhooks relacionados a consentimentos:

- `openfinance_consent_expired`
- `openfinance_consent_with_unrecoverable_resources`
- `openfinance_consent_with_temporarily_unavailable_resources`


Para os eventos `openfinance_consent_expired`, você pode solicitar ao seu usuário que renove seu consentimento usando o My Belvo Portal. Para mais informações, consulte nosso artigo dedicado sobre webhook de Consentimento.

## Adicionando um link ao Meu Portal Belvo

Requisito Regulatório
De acordo com as regulamentações do Open Finance, seus usuários devem ter uma maneira de fácil acesso para gerenciar seus consentimentos dentro do seu aplicativo ou site.

A Belvo criou o Meu Portal Belvo (MBP) que permite aos usuários gerenciar seus consentimentos de forma simples e direta, atendendo a todos os requisitos das regulamentações.

No seu aplicativo, você deve incluir um link claramente visível para o MBP para que seus usuários possam gerenciar seus consentimentos.

O MBP pode ser configurado de três maneiras diferentes:

- MBP Público
No site da Belvo, hospedamos uma instância universal do MBP que qualquer usuário pode usar para gerenciar seus consentimentos. Esta instância consolida todos os consentimentos que eles concederam usando o produto OFDA da Belvo. Você simplesmente precisa redirecionar seu usuário para `https://meuportal.belvo.com/?mode=landing`, onde eles podem inserir seus dados. Seu usuário poderá ver **todos** os consentimentos que concederam usando a Belvo (incluindo outras aplicações que usam a Belvo para extrair dados da Rede de Open Finance do Brasil).
- MBP Personalizado
Você pode personalizar o MBP para exibir apenas os consentimentos que seu usuário concedeu à sua aplicação, facilitando o gerenciamento dos consentimentos.
- Modo de Renovação de Consentimento
O MBP também pode ser usado para renovar um consentimento expirado. A Belvo enviará um webhook quando o consentimento de um dos seus usuários expirar.


Guia Dedicado do Meu Portal Belvo
Para detalhes sobre como configurar o Meu Portal Belvo no seu aplicativo,
consulte nosso guia dedicado Meu Portal Belvo (OFDA).

## Recursos adicionais

### Lista de verificação de integração

Criamos uma lista de verificação dedicada a todas as coisas que você deve levar em consideração ao desenvolver sua integração OFDA. Confira aqui: Lista de Verificação de Integração OFDA.

### Erros na Rede de Open Finance

Durante o processo de criação de consentimento, as instituições na Rede de Open Finance realizam verificações para garantir que a conexão seja estável e segura. Se a instituição determinar que a conexão não é estável ou segura, ela redirecionará o usuário para uma página de erro personalizada com o seguinte conteúdo:

*Ocorreu um erro. Por favor, verifique o seu CPF ou CNPJ para ter certeza de que está correto, feche o aplicativo e reinicie o processo para conectar sua conta.*

E na URL de redirecionamento, você verá um fragmento de URL com os seguintes detalhes:


```
api.belvo.com/api/consents/callback/#error_description=risk_analysis_denied...
```

Este erro pode ocorrer pelos seguintes motivos:

- Seu usuário tem uma conexão VPN ativa em seu dispositivo. Recomendamos desligar a VPN e tentar novamente.
- Seu usuário está acessando sua instituição através do aplicativo em seu dispositivo móvel, no entanto, não é a versão mais recente do aplicativo. Algumas instituições exigem que a versão do aplicativo seja a mais recente possível para permitir a autorização de consentimento. Recomendamos atualizar o aplicativo da instituição para a versão mais recente disponível e tentar novamente.
- [**Itaú** **somente**] Seu usuário está acessando sua instituição em seu computador desktop, no entanto, ele não tem o aplicativo Guardião 30 horas do Itaú instalado em seu computador. O Itaú exige que os usuários tenham este aplicativo instalado em seu computador desktop para realizar o processo de consentimento.