# Limites de Recuperação de Dados da OFDA Brasil

## Introdução

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 (Owners, Accounts, Transactions, Bills, Balances, Investments ou Investment transactions)
- o certificado da rede Open Finance


Uma vez atingido o limite operacional mensal de chamadas à API, não é possível recuperar mais informações 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.

Os limites estão descritos na tabela abaixo:

| Recurso da API Belvo (chamadas POST) | Limite de Operação do Open Finance |
|  --- | --- |
| Owners | 8 recuperações por CPF/CNPJ |
| Accounts | 8 recuperações por CPF/CNPJ- **Nota**: As informações de limite de cheque especial podem ser atualizadas até 420 vezes por CPF/CNPJ

 |
| Transactions | Dependendo do período solicitado:- Até 365 dias a partir do momento da solicitação: 8 recuperações por CPF/CNPJ
- Menos de 6 dias a partir do momento da solicitação: 240 recuperações por CPF/CNPJ

 |
| Account Balances | 420 recuperações por CPF/CNPJ |
| Bills | 30 recuperações por CPF/CNPJ |
| Investments | 30 recuperações por CPF/CNPJ |
| Investment transactions | 8 recuperações por CPF/CNPJ |


### Fluxo de trabalho assíncrono (links únicos)

> **Necessidade de frequência de dados:** Baixa
Você só precisa recuperar informações históricas uma vez (ou uma vez por semana). Por exemplo, credores de crédito ou verificação de ID.


Quando você cria um link único usando nosso fluxo de trabalho assíncrono (que utiliza nosso parâmetro `fetch_resources`), a Belvo recuperará de forma assíncrona as informações históricas para o seu usuário (até 365 dias). Após receber a notificação do webhook de que os dados históricos estão disponíveis, você pode recuperá-los usando chamadas GET.

Para quaisquer chamadas POST subsequentes que você fizer após a criação do link, a informação que você recupera dependerá do recurso da API (veja a tabela abaixo).

| Recurso da API Belvo | Informação atualizada em cada chamada POST | Frequência recomendada |
|  --- | --- | --- |
| Accounts | Limites de cheque especial, limites de cartão de crédito e saldo | Mensal |
| Owners | Detalhes pessoais do usuário | Mensal |
| Transactions | Transações nos últimos seis dias. | Semanal |
| Saldos de Conta | Saldo de conta atualizado e informações de cheque especial | Diário |
| Faturas | Último extrato de cobrança | Mensal |
| Investimentos | Portfólio de investimentos atual | Mensal |
| Transações de investimento | Transações de investimento recentes | Semanal |


Evite links duplicados
Para cada link que você cria, um novo consentimento é gerado na rede Open Finance do Brasil e a Belvo recupera dados históricos para aquele CPF/CNPJ, consumindo os limites operacionais.

### Fluxo de trabalho assíncrono (links recorrentes)

> **Necessidades de frequência de dados:** Alta
Você precisa de informações de saldo, cheque especial e transações diariamente. Por exemplo, PFMs ou ERPs.


Quando você cria um link recorrente, a Belvo recuperará de forma assíncrona as informações históricas para o seu usuário (até 365 dias). Após receber a notificação do webhook de que os dados históricos estão disponíveis, você pode recuperá-los usando chamadas GET como de costume. Dependendo da sua taxa de atualização, você receberá webhooks indicando se uma nova conta, proprietário, transação ou fatura foi recuperada da instituição, que você também pode recuperar usando chamadas GET.

Qualquer chamada POST individual que você fizer recuperará as seguintes informações:

| Recurso da API Belvo | Informação atualizada em cada chamada POST | Frequência recomendada |
|  --- | --- | --- |
| Contas | Limites de cheque especial, limites de cartão de crédito e saldo | Mensal |
| Proprietários | Detalhes pessoais do usuário | Mensal |
| Transações | Transações dos últimos seis dias. | Semanal |
| Saldos de Conta | Saldo de conta atualizado e informações de cheque especial | Diário |
| Faturas | Último extrato de cobrança | Mensal |
| Investimentos | Portfólio de investimentos atual | Mensal |
| Transações de investimento | Transações de investimento recentes | Semanal |


### Links Únicos

> **Necessidade de frequência de dados:** Muito baixa
Você só precisa recuperar informações históricas uma vez. Por exemplo, análise de crédito pontual.


Quando você cria um link único sem dados históricos, será necessário fazer chamadas POST individuais para recuperar dados para o seu usuário.

| Recurso da API Belvo | Informação atualizada na primeira chamada POST |
|  --- | --- |
| Accounts | Informações históricas da conta |
| Owners | Detalhes históricos do proprietário |
| Transactions | Até 365 dias de dados transacionais |
| Account Balances | Saldo atual da conta e informações de cheque especial |
| Bills | Extratos de cobrança históricos |
| Investments | Portfólio de investimentos atual |
| Investment transactions | Dados históricos de transações de investimento |


Qualquer chamada POST individual subsequente que você fizer irá recuperar as seguintes informações:

| Recurso da API Belvo | Informação atualizada em cada chamada POST | Frequência recomendada |
|  --- | --- | --- |
| Accounts | Limites de cheque especial, limites de cartão de crédito e saldo | Mensal |
| Owners | Detalhes pessoais do usuário | Mensal |
| Transactions | Transações dos últimos seis dias. | Semanal |
| Account Balances | Saldo da conta e informações de cheque especial atualizados | Diário |
| Bills | Último extrato de cobrança | Mensal |
| Investments | Portfólio de investimentos atual | Mensal |
| Investment transactions | Transações de investimento recentes | Semanal |


#### Dado os limites, é possível que os dados de conta e proprietário de um link recorrente não sejam atualizados por um mês inteiro?

Sim, na situação em que o limite operacional foi atingido para um CPF/CNPJ, o link recorrente não será atualizado (e novas contas ou proprietários não serão identificados). Isso pode ocorrer por três razões:

1. O usuário criou um link quatro vezes dentro do mês.
2. Clientes que não utilizam fluxos de trabalho assíncronos esgotaram os limites operacionais para o CPF/CNPJ usando chamadas POST.


Informações sobre saldo de conta e limites de cheque especial têm um limite mais alto (mínimo de 420 chamadas de API). Assim, essas informações serão atualizadas para contas existentes até que o limite para esses recursos seja atingido.

#### Ainda recebo webhooks para atualizações diárias ou semanais?

Sim. Dependendo da sua taxa de atualização, a Belvo envia webhooks quando novas contas, proprietários, transações ou faturas são recuperados da instituição. Como os limites para informações transacionais nos últimos seis dias são maiores (240 requisições), você continuará a receber webhooks para novas transações. Webhooks de conta, proprietário e fatura estão sujeitos aos seus respectivos limites mensais.

#### Que erro de API receberei quando o limite for atingido?

Quando o limite é atingido em uma solicitação síncrona POST, você recebe um erro HTTP `400` (`operational_limits_reached`), indicando que a Belvo não pôde recuperar informações para o link devido aos limites terem sido atingidos.

```json Exemplo de Erro de Limites Operacionais Atingidos
[
  {
    "code": "operational_limits_reached",
    "message": "A instituição atingiu seus limites operacionais",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]
```

#### Que webhook receberei em fluxos assíncronos?

Em fluxos assíncronos (por exemplo, quando você cria um link com `fetch_resources` ou quando um link recorrente é atualizado), a Belvo envia um webhook quando limites operacionais impedem a recuperação de um determinado link e recurso. O payload utiliza o mesmo código de erro `operational_limits_reached` dentro do array `data.errors`, com `webhook_code` e `process_type` definidos de acordo com o fluxo de trabalho (comumente `historical_update` para a carga histórica inicial).

O `webhook_type` indica qual recurso não pôde ser recuperado—por exemplo, `TRANSACTIONS`, `ACCOUNTS`, `OWNERS`, `INVESTMENTS` ou `INVESTMENT_TRANSACTIONS`.

```json Exemplo de Webhook de Limites Operacionais Atingidos
{
  "webhook_id": "4d77a0107c1d4fe9b252bf24f9b9c57c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "74f98fe6-f460-4c3f-8a70-2768bc727f48",
  "request_id": "a47e488b4ee2437cb7757244455170f5",
  "external_id": "a0ea1b54bc2b5559e3dcc4be25163e1b87aa0d53d14201a6825dd79f576a017e_accountChange",
  "data": {
    "errors": [
      {
        "code": "operational_limits_reached",
        "message": "Limite Operacional Atingido"
      }
    ]
  }
}
```

Para o esquema completo do webhook e outros payloads de erro, veja Webhooks de Agregação.

#### Meu usuário saberá que atingiu o limite ao criar seu link?

Como as chamadas da API ocorrem **após** o usuário ter criado seu link, ele não receberá nenhum erro que indique que o aplicativo ao qual está concedendo consentimento não poderá recuperar dados.