# Webhooks de Agregação

Um **webhook** é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico. Você precisará configurar webhooks para usar as APIs da Belvo.

## Configurar webhooks

Para configurar um novo webhook:

1. No seu painel do Belvo, vá para a seção de webhooks de dados.
2. Na aba **Webhooks de Dados**, clique em **+Novo webhook**.
3. Preencha o formulário **Novo webhook** com as informações necessárias.
  - **URL**: a URL para receber as notificações do webhook.
  - **Authorization**: um token de autorização opcional para usar se sua URL estiver protegida.
4. Clique em **Criar webhook**.



✳️ Feito! O webhook agora está configurado e seu aplicativo será notificado sobre novos eventos relacionados aos seus links.

Usando Autenticação Adicional
Por razões de segurança, você pode adicionar uma camada adicional de autenticação às suas chamadas de webhook. Quando você cria seu webhook, no campo **Autenticação (Opcional)**, insira:

- `Basic` e uma string `username:password` codificada em base64 (para autenticação Basic)
- `Bearer` e um token (para autenticação Bearer)


## Tipos de Webhook

Todos os eventos de webhook vêm com um payload principal (conforme descrito no exemplo de código).

```json Webhook Payload Core Schema
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {}
}
```

| Parâmetro  | Obrigatório | Tipo | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `webhook_id` | true | string | O ID do webhook da Belvo. | `aadf41a1fc8e4f79a49f7f04027ac999` |
| `webhook_type` | true | string | O recurso ao qual este webhook se refere. | `ACCOUNTS` |
| `process_type` | true | string | O parâmetro `process_type` indica por que o evento de webhook foi acionado. Retornamos um dos seguintes valores:- `historical_update`: O webhook foi acionado quando terminamos uma atualização histórica para a recuperação de dados (para links recorrentes e para links únicos com fetch_resources).
- `historical_update_progress_complete`: O webhook foi acionado quando todos os recursos de um link terminaram de ser processados durante uma atualização histórica (recurso beta opt-in).
- `recurrent_update`: O webhook foi acionado devido à atualização recorrente (cíclica) dos dados.
- `async_post`: O webhook foi acionado quando a recuperação assíncrona de dados de uma chamada POST foi concluída.
- `async_delete`: O webhook foi acionado quando a exclusão assíncrona de um link foi concluída.

 | `ACCOUNTS` |
| `webhook_code` | true | string | O evento que acionou o webhook. | `STATUS_UPDATE` |
| `external_id` | true | string | O identificador único que você forneceu ao criar o objeto. Para cobranças e transações, este campo sempre retornará `null`. | `c3c51aaf-aaa3-400c-926d-87ab62e195fd` |
| `data` | true | object | Um objeto contendo dados específicos sobre o evento. Os campos retornados neste objeto dependem do `webhook_type` e `webhook_code`. Para informações sobre os dados específicos de um determinado webhook, consulte a página dedicada para cada recurso. | `{}` |


## Eventos de erro de webhook

Às vezes, ao recuperar informações de uma instituição, pode ocorrer um erro. Nesse caso, o objeto de dados do evento de webhook conterá as informações do erro que ocorreu. Por exemplo:

```json Exemplo de Evento de Erro de Webhook
{
    "webhook_id": "5b82fdf536da43039c69a4305ecb1ceb",
    "webhook_type": "ACCOUNTS",
    "webhook_code": "historical_update",
    "link_id": "c7ba4551-ed8d-46ee-9b67-c864a77d6381",
    "external_id": "your_external_id",
    "data": {
        "errors": [ // Detalhes do erro que ocorreu
            {
              "code": "service_unavailable",
              "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"
            }
        ]
    }
}
```

### Limites operacionais do OFDA atingidos

Para **Open Finance Data Aggregation (OFDA) no Brasil**, quando a Belvo não consegue recuperar dados para um link porque o limite operacional mensal foi atingido para o CPF/CNPJ do usuário e o recurso solicitado, você recebe um `historical_update` webhook (ou outro webhook de fluxo assíncrono) com `operational_limits_reached` no array `data.errors`. Isso se aplica a fluxos assíncronos—por exemplo, quando você cria um link com `fetch_resources` ou quando uma atualização recorrente de link é executada—e a Belvo tenta recuperar um recurso como `ACCOUNTS`, `OWNERS` ou `TRANSACTIONS`.

O `webhook_type` corresponde ao recurso que não pôde ser recuperado (por exemplo, `TRANSACTIONS`). O `webhook_code` e `process_type` refletem o fluxo de trabalho que acionou o evento (comumente `historical_update` para a carga assíncrona inicial).

```json Exemplo de Webhook de Limites Operacionais do OFDA 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": "Operational Limit Reached"
      }
    ]
  }
}
```

| Parâmetro  | Obrigatório | Tipo | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `data.errors` | false | array | Presente quando a recuperação falhou para este recurso. Cada objeto descreve um erro. | Veja as linhas seguintes. |
| `data.errors[].code` | true | string | O código de erro. Para limites operacionais do OFDA, este é `operational_limits_reached`. | `operational_limits_reached` |
| `data.errors[].message` | true | string | Uma descrição legível do erro. | `Operational Limit Reached` |


Limites operacionais no OFDA
Para entender como os limites mensais funcionam por CPF/CNPJ e recurso, e como planejar sua integração em torno deles, veja Limites de Recuperação de Dados do OFDA Brasil. Você também pode receber um erro HTTP `400` com o mesmo código `operational_limits_reached` em requisições POST síncronas quando os limites já estiverem esgotados.

## Política de Retentativa

Se a Belvo chamar inicialmente o seu servidor e não receber um código de status HTTP `2XX`, tentaremos novamente cinco vezes usando um backoff linear para permitir que o seu servidor se recupere de qualquer mau funcionamento.

## Melhores Práticas de Webhook

#### Responder a webhooks

Assim que você receber um webhook da Belvo, certifique-se de responder com o código de status HTTP `2XX`. Se não recebermos uma resposta `2XX` do seu servidor, tentaremos novamente cinco vezes usando um backoff linear para permitir que seu servidor se recupere de qualquer mau funcionamento.

#### Lista de permissões para endereços IP de saída

Lista de Permissões para Endereços IP
Recomendamos fortemente que você adicione esses endereços IP à lista de permissões para que possa receber eventos de webhook.

Você pode receber eventos de webhook dos seguintes endereços IP:

- `3.130.254.46`
- `18.220.61.186`
- `18.223.45.212`


#### Testando eventos de webhook

Você pode acionar qualquer tipo de evento de webhook (incluindo eventos de link) a partir do seu Dashboard Belvo. Uma vez acionado, você receberá um payload com dados fictícios. Esta é uma excelente maneira de testar se você pode receber webhooks, se configurou corretamente sua autenticação (se necessário) e agir sobre os vários tipos de eventos.

Para acionar um evento:

1. No Environment Switcher no seu dashboard Belvo, selecione o ambiente em que você deseja testar seu webhook.
2. Selecione a aba **Webhooks**.
3. Clique no menu suspenso ao lado da URL do webhook Sandbox que você deseja testar.
4. Selecione o tipo de evento de webhook que você deseja. Isso envia o webhook.
5. Expanda a caixa de status para ver os detalhes do evento de webhook.


## Progresso de Atualização Histórica

Recurso Beta de Adesão
O webhook `historical_update_progress_complete` está atualmente em beta e disponível como um recurso de adesão. Para habilitar este webhook para sua conta, por favor entre em contato com o suporte da Belvo.

### Progresso da atualização histórica completo

Quando você cria um link com o parâmetro `fetch_resources` (seja via API ou ao gerar um token de acesso para o widget), a Belvo recupera automaticamente dados históricos para os recursos solicitados. O webhook `historical_update_progress_complete` é enviado assim que todos os recursos solicitados terminam de ser processados — independentemente de cada recurso ter sido bem-sucedido ou falhado.

Não Disponível para Atualizações Históricas Manuais
Este webhook é enviado apenas durante atualizações históricas automáticas (ao criar links com `fetch_resources`). Ele **não** é acionado ao usar o endpoint Acionar uma atualização histórica para um link.

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update_progress_complete` | Um resumo de todos os recursos que foram processados durante a atualização histórica, indicando quais foram bem-sucedidos e quais falharam. |


A carga útil do webhook inclui um objeto `resource_statuses` que mostra o status de cada tipo de recurso solicitado. Se algum recurso não for concluído dentro de 5 minutos, o webhook de resumo é enviado de qualquer forma com as informações de status disponíveis.

```mermaid
sequenceDiagram
    participant Cliente
    participant Belvo API
    participant Instituição
    participant URL do Webhook

    Cliente->>Belvo API: POST /api/links/ com fetch_resources
    Belvo API->>Cliente: 201 Created (link_id)
    
    Note over Belvo API,Instituição: Belvo recupera dados históricos de forma assíncrona
    
    par Recuperar Contas
        Belvo API->>Instituição: Solicitar contas
        Instituição-->>Belvo API: Dados das contas
        Belvo API->>URL do Webhook: Webhook de atualização histórica de CONTAS
    and Recuperar Transações
        Belvo API->>Instituição: Solicitar transações
        Instituição-->>Belvo API: Dados das transações
        Belvo API->>URL do Webhook: Webhook de atualização histórica de TRANSAÇÕES
    and Recuperar Faturas
        Belvo API->>Instituição: Solicitar faturas
        Instituição-->>Belvo API: Erro ao recuperar faturas
        Belvo API->>URL do Webhook: Webhook de atualização histórica de FATURAS (com erro)
    end
    
    Note over Belvo API: Todos os recursos processados ou tempo limite de 5 minutos atingido
    
    Belvo API->>URL do Webhook: Webhook HISTORICAL_UPDATE_PROGRESS_COMPLETE<br/>(com resumo de resource_statuses)
```

```json Exemplo de Payload de Progresso de Atualização Histórica Completa
{
  "webhook_id": "d27528fa-5649-468c-a0cf-256b92d71b80",
  "webhook_type": "HISTORICAL_UPDATE_PROGRESS_COMPLETE",
  "webhook_code": "historical_update_progress_complete",
  "link_id": "829459cd-c287-491b-975f-661467b7b0e1",
  "request_id": "328dfd48-3918-4b02-8c28-d3df0d33c27b",
  "data": {
    "total_resources": 3, // Número total de recursos que foram solicitados.
    "resource_statuses": { // Objeto contendo o status de cada recurso solicitado.
      "transactions": "success", // O recurso de transações foi recuperado com sucesso.
      "accounts": "failed", // O recurso de contas falhou ao ser recuperado.
      "invoices": "success" // O recurso de faturas foi recuperado com sucesso.
    }
  },
  "process_type": "historical_update",
  "external_id": "test-external-id" // Seu identificador externo para este link (se fornecido).
}
```

## accounts

### Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as contas disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de contas encontradas para o link. |


No payload do webhook, incluímos o número de contas encontradas para o link.

Resumo do Webhook Disponível
Após todos os recursos solicitados terem terminado de processar, você também receberá um webhook Progresso da Atualização Histórica Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Contas
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "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 a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Contas
curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novas contas disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar assincronamente dados sobre quaisquer novas contas que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_accounts_available` | O número de novas contas encontradas na instituição desde a última atualização. |


No payload do webhook, incluímos o número de novas contas encontradas para o link.

```json Exemplo de Novas Contas Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_accounts_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_accounts": 1 // Número de novas contas
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Contas
curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## bills

### Atualização histórica

Assim que seu link bancário recorrente for criado, carregamos assincronamente as contas disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de contas encontradas para o link. |


No payload do webhook, incluímos o número de contas encontradas para o link.

Resumo do Webhook Disponível
Após todos os recursos solicitados terem terminado de processar, você também receberá um webhook Progresso da Atualização Histórica Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Contas
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_bills": 2 // Número total de contas
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell
curl --request GET 'https://api.belvo.com/api/bills/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novas contas disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas contas que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_bills_available` | O número de novas contas encontradas na instituição desde a última atualização. |


No payload do webhook, incluímos o número de novas contas encontradas para o link.

```json Exemplo de Novas Contas Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS",
  "process_type": "recurrent_update",
  "webhook_code": "new_bills_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_bills": 1 // Número de novas contas
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Contas
curl --request GET 'https://api.belvo.com/api/bills/?link=link_id&created_at__range=date1,date2' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber as contas. Recomendamos que `date1` seja a data em que você recebeu uma notificação anteriormente e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## consentimentos

### Consentimento prestes a expirar

Você pode receber um evento `openfinance_consent_about_to_expire` quando o consentimento para um dos seus links OFDA estiver prestes a expirar dentro de sete dias da atualização do link recorrente.

Por exemplo, se você tiver uma taxa de atualização mensal para um link que se renova no segundo dia de cada mês, e a data de expiração do consentimento do link for o sexto dia desse mês, você receberá um evento `openfinance_consent_about_to_expire`. No entanto, se você tiver outro link que se renova no segundo dia de cada mês, mas a data de expiração do consentimento for o décimo dia desse mês, você não receberá um evento.

Solicite ao usuário que renove o consentimento
Assim que você receber este evento, pode solicitar ao seu usuário que renove o consentimento usando o My Belvo Portal.

```json Exemplo de Payload de Consentimento Prestes a Expirar
{
  "webhook_id": "37a084ee0741437fa7a95393b5636f7b",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_about_to_expire",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "9e763d19-15a4-410c-a106-18c0f60ca5eb", // O ID do consentimento.
    "consent_due_date": "2024-12-26T10:45:58.000Z", // Timestamp ISO-8601 de quando o consentimento irá expirar.
    "action": "renew", // Uma indicação da ação que você precisa tomar. Para webhooks openfinance_consent_about_to_expire, isso é sempre definido como renew.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "institution_display_name": "OF Mockbank", // O nome de exibição da instituição.
    "institution_icon_logo": "https://logo.com" // A URL para o logotipo da instituição.
  }
}
```

### Consentimento expirado

Você pode receber um evento `consent_expired` quando o consentimento para um dos seus links OFDA tiver expirado.

Peça ao seu usuário para renovar o consentimento
Assim que você receber este evento, pode solicitar ao seu usuário que renove o consentimento usando o My Belvo Portal.

```json Exemplo de Payload de Consentimento Expirado
{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_expired",
  "link_id": "3d3364b7-0175-483d-a58b-b471f251e533", // O ID do link associado ao consentimento.
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "action": "renew", // Uma indicação da ação que você precisa tomar. Para webhooks openfinance_consent_expired, isso é sempre definido como renew.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "institution_display_name": "OF Mockbank", // O nome de exibição da instituição.
    "institution_icon_logo": "https://logo.com" // A URL para o logotipo da instituição.
  }
}
```

Assim que você receber a notificação, pode solicitar ao seu usuário que renove o consentimento usando o My Belvo Portal.

### Consentimento revogado

Você pode receber um evento `openfinance_consent_with_unrecoverable_resources` quando um consentimento foi revogado devido aos recursos pré-existentes estarem indisponíveis. Um exemplo de quando você pode receber este evento é quando um usuário concedeu seu consentimento para acessar várias contas e, em uma data posterior, fechou essas contas.

```json Exemplo de Payload de Consentimento de Open Finance com Recursos Irrecuperáveis
{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_unrecoverable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "message": "The consent was revoked because it was unrecoverable" // Mensagem de erro sobre o consentimento revogado.
  }
}
```

### Consentimento temporariamente indisponível

Você pode receber um evento `openfinance_consent_with_temporarily_unavailable_resources` quando um consentimento está temporariamente indisponível devido aos recursos pré-existentes estarem indisponíveis. Um exemplo de quando isso pode ocorrer é quando o usuário concedeu seu consentimento para acessar uma determinada conta, mas não usou essa conta por um tempo (o número de dias até que uma conta seja marcada como inativa depende de cada instituição).

```json Exemplo de Payload de Consentimento do Open Finance Com Recursos Temporariamente Indisponíveis
{
  "webhook_id": "745156bbbd0d47b0a33ff995d7b4e5d8",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_temporarily_unavailable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "message": "The consent is temporarily unusable" // Mensagem de erro sobre o consentimento temporariamente indisponível.
  }
}
```

### Consentimento rejeitado

Você pode receber um evento `consent_rejected` quando um usuário revoga seu consentimento. Este evento pode ser acionado tanto para links únicos quanto recorrentes. O momento em que você recebe o webhook depende de onde o usuário revoga seu consentimento:

- **Usuário revoga consentimento via My Belvo Portal**: Você recebe imediatamente os webhooks `consent_rejected` e `invalid_credentials`.
- **Usuário revoga consentimento via app ou site do banco**: Os webhooks são acionados quando você faz uma nova solicitação POST para recuperar dados para aquele link (ou durante o processo de atualização). Neste cenário, você receberá:
  - Um webhook `consent_rejected`
  - Um webhook `invalid_credentials`
  - Um webhook para o endpoint específico que você chamou (por exemplo, transações, contas), contendo `code: login_error`


Peça ao usuário para renovar o consentimento
Assim que você receber este evento, pode solicitar ao seu usuário que forneça um novo consentimento usando o My Belvo Portal.

```json Exemplo de Payload de Consentimento Rejeitado
{
  "webhook_id": "be026113485844d0b373dec5275d86e9",
  "webhook_type": "CONSENT",
  "process_type": null,
  "webhook_code": "consent_rejected",
  "link_id": "a88beae7-3d5b-4a53-bae1-d8fe5f892961",
  "external_id": null,
  "data": {
    "consent_id": "04ad5398-3d1c-49b0-ac1b-0e8555a5c784", // O ID do consentimento.
    "action": "renew", // Uma indicação da ação que você precisa tomar.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "institution_display_name": "Nubank", // O nome de exibição da instituição.
    "institution_icon_logo": "https://stapp.nubank.com.br/open-banking/logo.svg" // A URL para o logo da instituição.
  }
}
```

### Alteração na expiração do consentimento

Você pode receber um evento `openfinance_consent_expiration_changed` quando um usuário altera a data de expiração do seu consentimento no Open Finance.

- **Para links recorrentes:** Este webhook é acionado quando o usuário altera a data de expiração via Portal My Belvo ou através do aplicativo bancário.
- **Para links únicos:** Este webhook é acionado apenas quando o usuário altera a data de expiração via Portal My Belvo.


No Open Finance, os consentimentos são criados com uma data de expiração, com opções disponíveis tipicamente de 3, 6, 9, 12 meses ou indefinido. Quando um usuário altera essa data de expiração, você receberá esta notificação de webhook.

```json Exemplo de Payload de Alteração de Expiração de Consentimento
{
  "webhook_id": "f3a2b1c4-5d6e-7f8g-9h0i-1j2k3l4m5n6o",
  "webhook_type": "CONSENT",
  "webhook_code": "openfinance_consent_expiration_changed",
  "process_type": null,
  "link_id": "a88beae7-3d5b-4a53-bae1-d8fe5f892961",
  "external_id": "your_external_id",
  "data": {
    "consent_id": "9e763d19-15a4-410c-a106-18c0f60ca5eb", // O ID do consentimento.
    "institution": "ofmockbank_br_retail", // O identificador da instituição para a qual o usuário forneceu seu consentimento.
    "previous_expiration": "2024-03-23T10:45:58Z", // A data e hora de expiração anterior do consentimento no formato ISO-8601. Isso pode ser nulo se o consentimento estava previamente definido como indefinido.
    "new_expiration": "2024-06-23T10:45:58Z" // A nova data e hora de expiração do consentimento no formato ISO-8601. Isso pode ser nulo se o consentimento foi alterado para indefinido.
  }
}
```

Tratamento de Consentimentos Indefinidos
Tanto `previous_expiration` quanto `new_expiration` podem ser `null`, o que indica uma duração de consentimento indefinida. Por exemplo, se um usuário altera seu consentimento de uma expiração de 3 meses para indefinido, o `new_expiration` será `null`.

## current-employments

Empregos Atuais Em Breve!
Esta seção menciona atualmente um novo recurso que está em desenvolvimento: **Empregos Atuais**. Este recurso estará disponível nos próximos dias, e atualizaremos este guia assim que estiver pronto.

### Atualização histórica

Assim que seu link de emprego for criado (para o México) e você tiver adicionado `CURRENT_EMPLOYMENTS` à lista de recursos em `fetch_resources`, nós recuperamos assincronamente o status atual de emprego para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de registros de emprego atual encontrados para o link. |


No payload do webhook, incluímos o número de registros de emprego atual encontrados para o link.

Webhook de Resumo Disponível
Após todos os recursos solicitados terem terminado de processar, você também receberá um webhook Progresso da Atualização Histórica Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Empregos Atuais
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "CURRENT_EMPLOYMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_current_employments": 1 // O número total de registros de emprego atual encontrados para o link
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Empregos Atuais
curl --request GET 'https://api.belvo.com/api/mx/current-employments/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## employment-metrics

### Atualização histórica

Assim que seu link de emprego for criado e você tiver adicionado `EMPLOYMENT_METRICS` à lista de recursos em `fetch_resources`, calculamos assincronamente as métricas de emprego para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de métricas de emprego geradas para o link. |


No payload do webhook, incluímos o número de métricas de emprego encontradas para o link.

Webhook de Resumo Disponível
Após todos os recursos solicitados terem terminado o processamento, você também receberá um Webhook de Progresso de Atualização Histórica Completa que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Métricas de Emprego
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_METRICS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employment_metrics": 1 // O número total de relatórios de métricas de emprego gerados
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Métricas de Emprego
curl --request GET 'https://api.belvo.com/api/employment-metrics/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## employment-records

### Atualização histórica

Assim que seu link de emprego for criado, calculamos de forma assíncrona as métricas de emprego para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de registros de emprego encontrados para o link. |


No payload do webhook, incluímos o número de contas encontradas para o link.

Resumo do Webhook Disponível
Após todos os recursos solicitados terem terminado de processar, você também receberá um webhook Progresso da Atualização Histórica Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Registros de Emprego
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employment_record_profiles": 1 // O número total de perfis de registro de emprego encontrados para o link
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Registros de Emprego
curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Alterações no status de emprego

Interessado em acessar este novo recurso?
Entre em contato com nossa equipe, e eles ajudarão você a se configurar!

De acordo com a taxa de atualização escolhida, a Belvo recuperará de forma assíncrona dados sobre quaisquer novas alterações de emprego que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `employment_changes` | Uma lista de alterações de emprego que ocorreram para o link. |


No payload do webhook, incluímos as alterações de emprego identificadas para o link.

```json Exemplo de Payload de Alterações de Emprego
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "recurrent_update",
  "webhook_code": "employment_changes",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "employment_changes": ["EMPLOYED", "SALARY_INCREASED"] // Lista de alterações desde a última verificação
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Registros de Emprego
curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


#### Opções de mudança de emprego

Na sua frequência de atualização definida, a Belvo extrairá novas informações de emprego para o seu link e comparará o status de emprego e as informações salariais com a extração de dados anterior.

Frequência de atualização recomendada
Recomendamos uma frequência de atualização mínima de dois meses. No entanto, entre em contato com nossa equipe e eles poderão aconselhá-lo melhor dependendo do seu caso de uso.

No `data.employment_changes` array do webhook, você pode receber uma ou mais das seguintes mudanças de emprego:

| Mudança | Descrição |
|  --- | --- |
| `EMPLOYED` | O usuário passou de desempregado para empregado (adquiriu um ou mais novos empregos). |
| `UNEMPLOYED` | O usuário passou de empregado para desempregado (não possui mais nenhum emprego ativo). |
| `EMPLOYEE_NEW_JOBS` | O usuário adquiriu um ou mais novos empregos (pode ser combinado com outras mudanças). |
| `EMPLOYEE_LOST_JOBS` | O usuário perdeu um ou mais empregos (pode ser combinado com outras mudanças). |
| `SALARY_INCREASE` | O salário total do usuário aumentou pelo menos 10% desde a última verificação. |
| `SALARY_DECREASE` | O salário total do usuário diminuiu pelo menos 10% desde a última verificação. |


Você pode receber mais de uma mudança no `data.employment_changes` array, dependendo da situação. A tabela a seguir mostra cenários comuns e as notificações que você pode esperar:

| Estado | Cenário | Notificações possíveis |
|  --- | --- | --- |
| Empregado | Salário do usuário aumentou ≥10% | `[SALARY_INCREASE]` |
| Empregado | Salário do usuário diminuiu ≥10% | `[SALARY_DECREASE]` |
| Empregado | Usuário adquiriu um ou mais empregos (com mudança salarial) mas manteve empregos anteriores | `[EMPLOYEE_NEW_JOBS]` ou `[EMPLOYEE_NEW_JOBS, SALARY_INCREASE]` ou `[EMPLOYEE_NEW_JOBS, SALARY_DECREASE]` |
| Empregado | Usuário perdeu um ou mais empregos (pode ser combinado com outras mudanças). | `[EMPLOYEE_LOST_JOBS]` ou `[EMPLOYEE_LOST_JOBS, SALARY_INCREASE]` ou `[EMPLOYEE_LOST_JOBS, SALARY_DECREASE]` |
| Empregado | Usuário mudou de emprego (mesmo número total de empregos) | `[EMPLOYEE_LOST_JOBS, EMPLOYEE_NEW_JOBS]` com `SALARY_INCREASE` ou `SALARY_DECREASE` opcionais |
| Empregado | Usuário adquiriu um ou mais empregos após estar `UNEMPLOYED`. | `[EMPLOYED, EMPLOYEE_NEW_JOBS]` |
| Desempregado | Usuário perdeu todos os empregos | `[UNEMPLOYED, EMPLOYEE_LOST_JOBS]` |
| Desempregado | Usuário teve empregos entre as verificações, mas os perdeu | `[EMPLOYEE_NEW_JOBS, EMPLOYEE_LOST_JOBS]` |


Notificações de mudança salarial
- Ao passar de **empregado para desempregado**, você **não** receberá `SALARY_DECREASE` já que o usuário não possui mais um salário para comparar.
- Ao passar de **desempregado para empregado**, você **não** receberá `SALARY_INCREASE` já que não havia um salário anterior para comparar.


```json
{
  "data": {
    "employment_changes": ["EMPLOYEE_LOST_JOBS", "EMPLOYEE_NEW_JOBS", "SALARY_INCREASE"]
  }
}
```

#### Cenários com registros excluídos ou ausentes

A Belvo envia notificações de emprego após comparar os dados recém-obtidos com os dados obtidos anteriormente. No entanto, pode haver casos em que atualizamos um link de emprego que **não possui** nenhum dado de registro de emprego no banco de dados da Belvo. Nesses casos, você ainda receberá um `employment_changes` webhook. No entanto, como a Belvo verifica os dados recém-retornados em relação aos dados inexistentes no banco de dados da Belvo, neste caso, você receberá uma das seguintes combinações de alterações de emprego:

| Caso quando atualizado | Valores |
|  --- | --- |
| Usuário está empregado | `EMPLOYED`, `EMPLOYEE_NEW_JOBS` |
| Usuário está desempregado | `UNEMPLOYED` |


Isso pode ocorrer devido a qualquer um dos seguintes motivos:

#### Ao criar um link, você define `stale_in` para um período menor que sua taxa de atualização.

Ao criar um link, você pode opcionalmente adicionar o parâmetro `stale_in` para controlar por quanto tempo a Belvo armazena dados derivados do usuário. O período é **relativo** ao timestamp `last_updated_at` do link (a última vez que a conta do usuário foi acessada).

Por exemplo, se você definir `stale_in` para 62 dias ao criar um link em 01.03.2024, os dados serão armazenados no banco de dados da Belvo por 62 dias após essa data. Se então, para o mesmo link, você acessar os dados um mês depois (01.04.2024), a contagem é reiniciada e a Belvo excluirá os dados 62 dias após 01.04.2024.

No entanto, se você definir um período `stale_in` menor que sua taxa de atualização, a Belvo excluirá os dados antes da próxima atualização. Como resultado, os novos dados retornados serão comparados com dados inexistentes, acionando um webhook `employment_changes` com os status mencionados acima.

Para evitar isso, você pode:

- Não passar o parâmetro `stale_in` (que por padrão é 365 dias).
- Definir um valor `stale_in` que seja maior que sua taxa de atualização. Por exemplo, se você tiver um período de atualização de 60 dias, então seu parâmetro `stale_in` deve ser definido para pelo menos 62 dias.


#### Ao fazer um POST Retrieve employment records, você define `save_data` como `false`.

Ao recuperar dados de registros de emprego usando o Retrieve employment record details, definir `save_data` como `false` impede que a Belvo armazene os dados. Consequentemente, quaisquer dados recém-recuperados serão comparados com dados inexistentes, resultando no `employment_changes` webhook mencionado acima.

Para evitar isso, recomendamos que você defina `save_data` como `true`.

#### Dados de registro de emprego excluídos

Se você excluir dados de registro de emprego usando a solicitação Excluir um registro de emprego, todos os dados dessa entrada de emprego serão removidos do banco de dados da Belvo. Durante a próxima atualização, a Belvo compara os novos dados com os dados excluídos (inexistentes), resultando no `employment_changes` webhook mencionado acima.

#### Não havia dados na extração inicial dos dados de registro de emprego

No caso de uma recuperação anterior de registro de emprego não ter sido bem-sucedida, pois não havia dados para o usuário na instituição (resultando na API retornando uma resposta vazia) ou a instituição de emprego não estava respondendo, durante a próxima atualização, a Belvo compara os novos dados com os dados inexistentes, resultando no `employment_changes` webhook mencionado acima.

## employments-brazil

### Atualização histórica

Assim que o seu link bancário recorrente é criado, carregamos assincronamente as informações de emprego disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de empregos encontrados para o link. |


No payload do webhook, incluímos o número de empregos encontrados para o link.

```json Exemplo de Atualização Histórica de Empregos (BR)
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employments": 1 // O número total de perfis de registro de emprego encontrados para o link
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Empregos (BR)
curl --request GET 'https://api.belvo.com/api/br/employments/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novos empregos disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novos empregos que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_employments_available` | O número de novos empregos encontrados desde a última atualização. |


No payload do webhook, incluímos o número de novos empregos encontrados para o link.

```json Exemplo de Novos Empregos (BR) Disponíveis
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_employments_available",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_employments": 1 // Número de novos empregos encontrados desde o último evento
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Empregos (BR)
curl --request GET 'https://api.belvo.com/api/br/employments/?link=link_id&created_at__range=date1,date2' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber os empregos. Recomendamos que `date1` seja a data em que você recebeu uma notificação anteriormente e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## financial-statements-mexico

### Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente **os últimos três anos de demonstrações financeiras** e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | Os últimos três anos de demonstrações financeiras. |


No payload do webhook, incluímos o número de demonstrações financeiras recebidas.

```json Exemplo de Atualização Histórica de Demonstrações Financeiras
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "total_financial_statements": 3
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Demonstrações Financeiras
curl --request GET 'https://api.belvo.com/api/financial-statements/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novos demonstrativos financeiros disponíveis

Aplicável apenas para chamadas POST assíncronas.

Quando você faz uma solicitação "ad hoc" para demonstrativos financeiros (com o cabeçalho `X-Belvo-Request-Mode: async`), a Belvo irá recuperar assincronamente as informações do demonstrativo financeiro e enviar o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `new_financial_statements_available` | O número de novos demonstrativos financeiros encontrados para o link. |


No payload do webhook, incluímos o número de novos demonstrativos financeiros encontrados para o link.

```json Exemplo de Novos Demonstrativos Financeiros Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "new_financial_statements_available",
  "process_type": "async_post",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 1
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Demonstrativos Financeiros
curl --request GET 'https://api.belvo.com/api/financial-statements/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


#### Erros ao extrair Demonstrações Financeiras

Para fornecer maior visibilidade sobre a extração de dados de Demonstrações Financeiras, incluímos um novo campo `error` no payload de resposta para cada demonstração financeira que você receberá.

Se, para um determinado ano em que uma demonstração financeira está disponível, não conseguirmos recuperar os dados devido à instituição não fornecer as informações no formato correto, o campo `error` indicará o motivo da extração malsucedida:

```json Exemplo de Erro em Demonstrações Financeiras
[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "error": "Unable to validate if the user has an available financial statement for the specified year.",
    "year": 2020,
    "currency": "MXN",
    "balance_sheet": null,
    "income_statement": null
  }
]
```

As possíveis mensagens de erro são:

- `Unable to validate if the user has an available financial statement for the specified year.  `
- `No available financial statement found for the user for the specified year, preventing data extraction.`
- `Unable to verify if the user has _conceptos vigentes_ for the specified year.  `
- `The fiscal institution provided the financial statement in an unrecognized format.`


Se você receber payloads de demonstrações financeiras com esses erros, entre em contato com nossa equipe de suporte.

## incomes

## Descrição

A API de **incomes** permite que você consulte e gerencie as receitas de um usuário. Com essa API, você pode obter informações detalhadas sobre as receitas, incluindo a fonte, o valor e a data de recebimento.

## Endpoints

### GET /incomes

Retorna uma lista de receitas para o usuário autenticado.

#### Parâmetros de Consulta

- `start_date` (opcional): A data de início para filtrar as receitas.
- `end_date` (opcional): A data de término para filtrar as receitas.
- `source` (opcional): Filtra as receitas por fonte específica.


#### Exemplo de Requisição

```http
GET /incomes?start_date=2023-01-01&end_date=2023-12-31&source=salary HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer {token}
```

#### Exemplo de Resposta

```json
{
  "incomes": [
    {
      "id": "1",
      "source": "salary",
      "amount": 5000,
      "received_date": "2023-01-31"
    },
    {
      "id": "2",
      "source": "freelance",
      "amount": 1500,
      "received_date": "2023-02-15"
    }
  ]
}
```

### POST /incomes

Cria uma nova receita para o usuário autenticado.

#### Corpo da Requisição

- `source` (obrigatório): A fonte da receita.
- `amount` (obrigatório): O valor da receita.
- `received_date` (obrigatório): A data em que a receita foi recebida.


#### Exemplo de Requisição

```http
POST /incomes HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "source": "investment",
  "amount": 2000,
  "received_date": "2023-03-10"
}
```

#### Exemplo de Resposta

```json
{
  "id": "3",
  "source": "investment",
  "amount": 2000,
  "received_date": "2023-03-10"
}
```

### DELETE /incomes/{id}

Remove uma receita específica do usuário autenticado.

#### Exemplo de Requisição

```http
DELETE /incomes/3 HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer {token}
```

#### Exemplo de Resposta

```json
{
  "message": "Income deleted successfully."
}
```

## Autenticação

A API de **incomes** requer autenticação via token. Certifique-se de incluir o token de autenticação no cabeçalho de todas as requisições.

## Erros Comuns

- **401 Unauthorized**: O token de autenticação está ausente ou inválido.
- **404 Not Found**: A receita especificada não foi encontrada.
- **400 Bad Request**: Os parâmetros fornecidos são inválidos ou estão faltando.


### Atualização histórica

Assim que seu link bancário for criado e você tiver adicionado `INCOMES` à lista de recursos em `fetch_resources`, calculamos assincronamente os dados de renda para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de rendas e fluxos de renda identificados para o link. |


No payload do webhook, incluímos o número de rendas e fluxos de renda identificados para o link.

```json Exemplo de Atualização Histórica de Rendas
{
  "webhook_id": "75f0c2ca92e64f228da04cc7f5039c03",
  "webhook_type": "INCOMES",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_incomes": 1, // Sempre = 1, Indica que a análise está pronta para recuperação.
    "number_of_income_streams": 5, // Número total de fluxos de renda identificados.
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Rendas
curl --request GET 'https://api.belvo.com/api/incomes/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## investment-transactions

### Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as transações de investimento disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de transações de investimento para o link no último ano. |


No payload do webhook, incluímos o número de transações de investimento encontradas para o link (incluindo o número de transações de entrada e saída), bem como o intervalo de datas ao qual a informação se aplica.

```json Exemplo de Atualização Histórica de Transações de Investimento
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENT_TRANSACTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "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": "2023-01-03", // Data da primeira transação
    "last_transaction_date": "2024-01-03" // Data da última transação
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Transações
curl --request GET 'https://api.belvo.com/api/br/investment-transactions/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


Você pode adicionar mais filtros para restringir os resultados, por exemplo:

```shell Exemplo de Solicitação de Transações de Investimento
curl --request GET 'https://api.belvo.com/api/br/investment-transactions/?link=link_id'\
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novas transações disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas transações de investimento que tenham aparecido para o link fornecido desde a última atualização.

Definimos novas transações de investimento como transações encontradas na instituição para um determinado link desde a última atualização. Por exemplo, estas podem ser novas transações de investimento das últimas 24 horas ou novas transações de investimento de alguns dias atrás que foram apenas recentemente adicionadas pela instituição.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_investment_transactions_available` | O número de novas transações de investimento encontradas na instituição desde a última atualização. |


No payload do webhook, incluímos o número de novas transações encontradas para o link.

```json Exemplo de Novas Transações de Investimento Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENT_TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "new_investment_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_investment_transactions": 19 // Número de novas transações de investimento encontradas desde o último evento
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Transações de Investimento
curl --request GET 'https://api.belvo.com/api/br/investment-transactions/?link=link_id&type&created_at__range=date1,date2' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber transações. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## investimentos

### Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as contas de investimento disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de contas de investimento encontradas para o link. |


No payload do webhook, incluímos o número de contas de investimento encontradas para o link.

```json Exemplo de Atualização Histórica de Investimentos
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_investments": 5 // Número total de contas de investimento encontradas.
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Investimentos
curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novo investimento disponível

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar dados de forma assíncrona sobre quaisquer novas contas de investimento que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_investments_available` | O número de novas contas encontradas na instituição desde a última atualização. |


No payload do webhook, incluímos o número de novas contas encontradas para o link.

```json Exemplo de Novo Investimento Disponível
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_investments_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_investments": 1 // Novas contas de investimento encontradas para o link
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Investimentos
curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## invoices

### Atualizações iniciais

Assim que seu link fiscal recorrente é criado, carregamos de forma assíncrona os últimos 30 dias de histórico de notas fiscais. Você receberá duas notificações via um webhook sempre que os últimos 30 dias de notas fiscais estiverem disponíveis para você acessar.

| Código do Webhook | Descrição |
|  --- | --- |
| `initial_inflow_update` | Os últimos 30 dias de notas fiscais de ENTRADA (recebidas). |
| `initial_outflow_update` | Os últimos 30 dias de notas fiscais de SAÍDA (enviadas). |


Incluímos o número de notas fiscais encontradas durante este período para o tipo de nota fiscal, bem como as datas da primeira e última nota fiscal no intervalo.

Exemplo de Entrada Inicial
```json Exemplo de Entrada Inicial
{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "initial_inflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 3456,
    "first_invoice_date": "2021-04-05",
    "last_invoice_date": "2021-05-05"
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Notas Fiscais de Entrada Inicial
curl --request GET 'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

Exemplo de Saída Inicial
```json Exemplo de Saída Inicial
{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf578",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "initial_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 3456,
    "first_invoice_date": "2021-04-05",
    "last_invoice_date": "2021-05-05"
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Notas Fiscais de Saída Inicial
curl --request GET 'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `type` | O tipo de nota fiscal. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `initial_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `initial_outflow_update`, isso deve ser definido como `OUTFLOW`. | `INFLOW` |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | O intervalo de datas para o qual você deseja obter notas fiscais. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook. | `2017-07-31,2018-07-31` |


### Atualizações Históricas

Assim que seu link fiscal recorrente é criado, carregamos de forma assíncrona os últimos três anos de histórico de notas fiscais de ENTRADA e SAÍDA para o SAT. Você receberá até 8 notificações via um webhook sempre que o histórico de notas fiscais estiver disponível para você acessar. **Para cada ano que a Belvo extrai dados**, você receberá os seguintes webhooks:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_inflow_update` | O último ano de notas fiscais de ENTRADA (recebidas). |
| `historical_outflow_update` | O último ano de notas fiscais de SAÍDA (enviadas). |


No payload do webhook, incluímos o número de notas fiscais encontradas durante este período para o tipo de nota, bem como as datas da primeira e da última nota no intervalo.

Exemplo de Entrada Histórica
```json Exemplo de Entrada Histórica
{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "historical_inflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 5333, // Número total de notas fiscais encontradas
    "first_invoice_date": "2017-07-31", // Primeira nota fiscal de entrada encontrada
    "last_invoice_date": "2018-07-31" // Última nota fiscal de entrada encontrada
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Notas Fiscais de Entrada Histórica
curl --request GET 'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'\
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

Exemplo de Saída Histórica
```json Exemplo de Saída Histórica
{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf578",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "historical_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 1000, // Número total de notas fiscais encontradas
    "first_invoice_date": "2017-07-31", // Primeira nota fiscal de saída encontrada
    "last_invoice_date": "2018-07-31" // Última nota fiscal de saída encontrada
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Notas Fiscais de Saída Histórica
curl --request GET \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `type` | O tipo de nota fiscal. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `historical_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `historical_outflow_update`, isso deve ser definido como `OUTFLOW`. | `INFLOW` |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | O intervalo de datas para o qual você deseja obter notas fiscais. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook. | `2017-07-31,2018-07-31` |


### Novas faturas disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas faturas que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_invoices_available` | Uma lista de novas faturas que foram recuperadas desde a última atualização. |


Você pode receber uma notificação `new_invoices_available` sempre que novas faturas estiverem disponíveis para um link fiscal recorrente. Você pode receber mais de um evento de webhook para um link ao mesmo tempo, dependendo do tipo de faturas encontradas. Por exemplo, você pode receber um evento de webhook para faturas de ENTRADA e outro separado para faturas de SAÍDA.

Definimos novas faturas como todas as novas faturas encontradas na instituição para este link desde nossa última atualização. Por exemplo, se você tiver uma taxa de atualização diária, podem ser as novas faturas das últimas 24 horas ou faturas adicionadas pela instituição nas últimas 24 horas para dias anteriores.

No payload do webhook, incluímos o número de faturas encontradas desde a última atualização, o tipo de faturas (`INFLOW` ou `OUTFLOW`), bem como um array de `id`s de faturas.

```json Exemplo de Novas Faturas Disponíveis
{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "INVOICES",
  "process_type": "recurrent_update",
  "webhook_code": "new_invoices_available",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5,
    "type": "INFLOW",
    "new_invoices": [
      // Um array de IDs de faturas
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17",
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes sobre as novas faturas fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Faturas
curl --request GET 'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | A lista de `id`s de faturas que você recebeu no `data.new_invoices` da notificação do webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


### Faturas canceladas

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer faturas canceladas que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `invoices_cancelled` | Uma lista de faturas canceladas que foram recuperadas desde a última atualização. |


Definimos faturas canceladas como todas as faturas existentes com um novo status "cancelado" na instituição para este link

No payload do webhook, incluímos o tipo de faturas canceladas (`INFLOW` ou `OUTFLOW`) assim como um array de `id`s de faturas.

```json Exemplo de Faturas Canceladas
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVOICES",
  "process_type": "recurrent_update",
  "webhook_code": "invoices_cancelled",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "INFLOW",
    "cancelled_invoices": [
      // Um array de IDs de faturas
      "0a362860-c92f-4414-a731-a772e88ab54b",
      "0a376126-c23r-2131-b745-a876d77cd76c"
    ]
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes sobre as faturas canceladas fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Faturas Canceladas
curl --request GET 'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | A lista de `id`s de faturas que você recebeu no `data.cancelled_invoices` da notificação do webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


## links

Widget Update Mode
Recomendamos fortemente que você use nosso Hosted Widget com Modo de Atualização após receber um evento de webhook de Link para lidar com a atualização de credenciais ou token.

### Credenciais inválidas

Você pode receber uma notificação de `invalid_credentials` sempre que as credenciais de um usuário não forem mais válidas. Isso pode acontecer quando:

- Um usuário altera suas credenciais da instituição.
- Um usuário revoga seu consentimento (seja via My Belvo Portal ou através do aplicativo/site do banco).
- Você tenta atualizar um link (seja recorrente ou único) usando o endpoint de atualização histórica e as credenciais armazenadas não são mais válidas.


Assim que você receber essa notificação, pode pedir ao seu usuário para atualizar sua nova senha usando o Hosted Widget no Modo de Atualização. Assim que as credenciais estiverem corretas, o link é atualizado.

Se você não estiver usando o Connect Widget, pode pedir ao seu usuário para enviar a nova senha e, em seguida, realizar uma solicitação de Atualização de Link para salvar a nova senha. Por exemplo, se você receber o seguinte webhook:

```json Exemplo de Credenciais Inválidas
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "invalid_credentials",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "login_error", // Erro do evento de webhook
    "error_message": "Credenciais inválidas fornecidas para login na instituição", // Mensagem descritiva do erro
    "status": 400
  }
}
```

Assim que você receber as credenciais necessárias do seu usuário, faça uma solicitação de Atualização das credenciais de um link com os detalhes atualizados.

### Link deletado

Quando você usa o cabeçalho `X-Belvo-Request-Mode: async` da Belvo ao solicitar a Exclusão de um Link, a Belvo excluirá de forma assíncrona todos os dados associados a esse link (por exemplo: transações, contas, faturas, declarações de impostos, empregos, e assim por diante). Uma vez que o processo esteja completo, você receberá um evento de webhook `link_deleted` indicando que o Link e todos os dados associados foram excluídos com sucesso.

```json Exemplo de Link Deletado
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "async_delete",
  "webhook_code": "link_deleted",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": null
}
```

No caso de haver um erro durante o processo de exclusão do Link, você será notificado usando o mesmo código de webhook, mas com detalhes adicionais no campo `data` indicando que a exclusão do link não foi bem-sucedida e para tentar novamente a solicitação:

```json Exemplo de Erro na Exclusão do Link
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "async_delete",
  "webhook_code": "link_deleted",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "link_deletion_failed",
    "error_message": "Link deletion failed. Please retry the request."
  }
}
```

Se você receber um erro mais de duas vezes para um determinado link, entre em contato com nossa equipe de suporte com o `request_id`.

### Token necessário

Você pode receber uma notificação `token_required` sempre que um novo token MFA for necessário pela instituição para manter o link recorrente funcionando.

Assim que você receber essa notificação, pode pedir ao seu usuário para fornecer um novo token usando o Hosted Widget no modo de atualização. Assim que o token for fornecido, o link recorrente é atualizado.

Observe que, até que o link seja atualizado, a Belvo não enviará nenhum webhook relacionado a esse link.

Se você não estiver usando o Connect Widget, pode pedir ao seu usuário para enviar sua nova senha e, em seguida, realizar uma solicitação de Atualização de Link para fornecer o novo token MFA. Por exemplo, se você receber o seguinte webhook:

```json Exemplo de Token Necessário
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "token_required",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "token_required", // Erro do evento Webhook
    "error_message": "MFA token was required by the institution", // Mensagem descritiva do erro
    "status": 428,
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "token_generation_data": {
      "instructions": "Use este código para gerar o token",
      "type": "numeric",
      "value": "12345"
    }
  }
}
```

Assim que você receber as credenciais de token necessárias do seu usuário, faça uma solicitação de Atualização das credenciais de um link com o token atualizado, juntamente com a `session` e `link_id` que você recebeu na notificação do webhook.

## proprietários

### Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as informações do proprietário disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de proprietários encontrados para o link. |


No payload do webhook, incluímos o número de proprietários encontrados para o link.

```json Exemplo de Atualização Histórica de Proprietários
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_owners": 2 // Número total de proprietários
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Proprietários
curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Novos proprietários disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar assincronamente dados sobre quaisquer novas contas que tenham aparecido para o link fornecido desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_owners_available` | O número de novos proprietários encontrados desde a última atualização. |


No payload do webhook, incluímos o número de novos proprietários encontrados para o link.

```json Exemplo de Novos Proprietários Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "recurrent_update",
  "webhook_code": "new_owners_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_owners": 1 // Número de novos proprietários
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Proprietários
curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## despesas-recorrentes

### Atualização histórica

Assim que seu link bancário for criado e você tiver adicionado `RECURRING_EXPENSES` à lista de recursos em `fetch_resources`, calculamos assincronamente os dados de despesas recorrentes para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de despesas recorrentes identificadas para o link. |


No payload do webhook, incluímos o número de despesas recorrentes identificadas para o link.

```json Exemplo de Atualização Histórica de Despesas Recorrentes
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "RECURRING_EXPENSES",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_recurring_expenses": 23 // Contagem de despesas recorrentes identificadas.
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Despesas Recorrentes
curl --request GET 'https://api.belvo.com/api/recurring-expenses/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## risk-insights

### Atualização Histórica

Assim que seu link bancário for criado e você tiver adicionado `RISK_INSIGHTS` à lista de recursos em `fetch_resources`, geramos de forma assíncrona as análises de risco para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de análises de risco identificadas para o link. |


No payload do webhook, incluímos o número de análises de risco identificadas para o link.

Webhook de Resumo Disponível
Após todos os recursos solicitados terem terminado o processamento, você também receberá um webhook Atualização Histórica Progresso Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

```json Exemplo de Atualização Histórica de Análises de Risco
{
  "webhook_id": "58577409546a4247848055e1e11bbc71",
  "webhook_type": "RISK_INSIGHTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_risk_insights": 1 // Sempre = 1, Indica que a análise está pronta para recuperação.
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Análises de Risco
curl --request GET 'https://api.belvo.com/api/risk-insights/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## tax-compliance-status

### Atualização histórica

Assim que seu link fiscal for criado, recuperamos de forma assíncrona o documento de Status de Conformidade Fiscal (*Opinión de Cumplimiento de Obligaciones Fiscales*) e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O Status de Conformidade Fiscal atual para o usuário. |


No payload do webhook, você receberá o número total de documentos de Status de Conformidade Fiscal.

```json Exemplo de Atualização Histórica de Status de Conformidade Fiscal
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_COMPLIANCE_STATUS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_compliance_status": 1 // O número total de documentos de declaração de conformidade fiscal
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Status de Conformidade Fiscal
curl --request GET 'https://api.belvo.com/api/tax-compliance-status/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## tax-retentions

### Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente o último ano de retenções de impostos e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O último ano de Retenções de Impostos. |


No payload do webhook, incluímos o número total de retenções de impostos encontradas no último ano, juntamente com o intervalo de datas para o qual recuperamos os dados.

```json Exemplo de Atualização Histórica de Retenções de Impostos
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_RETENTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_retentions": 1, // O número total de retenções de impostos
    "first_tax_retention_date": "2023-06-01", // A data da primeira retenção de imposto encontrada
    "last_tax_retention_date": "2023-08-20" // A data da última retenção de imposto encontrada
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Retenções de Impostos
curl --request GET 'https://api.belvo.com/api/tax-retentions/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## declarações-de-imposto

### Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente os últimos cinco anos de declarações de imposto **anuais**, bem como os 12 meses de declarações de imposto **mensais**. Você receberá uma notificação `historical_update` para cada tipo de declaração de imposto (anual e mensal) sempre que o histórico de declarações de imposto estiver disponível para você acessar.

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | Os últimos 5 anos de declarações de imposto anuais. |
| `historical_update` | Os últimos 12 meses de declarações de imposto mensais. |


No payload do webhook, incluímos o tipo de declarações de imposto, o número total de declarações de imposto encontradas, bem como o primeiro e o último ano das declarações de imposto recuperadas.

Exemplo Histórico de Declaração de Imposto (Anual)
```json Exemplo Histórico de Declaração de Imposto (Anual)
{
  "webhook_id": "80fa38b7cad34950b210626abd86bfe9",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // either yearly or monthly
    "total_tax_returns": 2, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}
```

Exemplo Histórico de Declaração de Imposto (Mensal)
```json Exemplo Histórico de Declaração de Imposto (Mensal)
{
  "webhook_id": "80fa38b7cad34950b210626abd866549",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // either yearly or monthly
    "total_tax_returns": 7, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell
curl --request GET 'https://api.belvo.com/api/tax-returns/?link=link_id&ejercicio__range=first_tax_return_year,last_tax_return_year' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `ejercicio__range` | O intervalo de datas para o qual você deseja obter declarações de imposto. Este deve ser o `first_tax_return_year` e `last_tax_return_year` que você recebeu na notificação do webhook. | `2017,2020` |


### Novas declarações de imposto disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas declarações de imposto que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_tax_returns_available` | Uma contagem de novas declarações de imposto desde a última atualização. |


Você pode receber uma notificação `new_tax_returns_available` sempre que novas declarações de imposto estiverem disponíveis para um link fiscal recorrente. Você pode receber mais de um evento de webhook para um link ao mesmo tempo, dependendo do tipo de declarações de imposto encontradas. Por exemplo, você pode receber um evento de webhook para declarações de imposto `mensais` e outro separado para declarações de imposto `anuais`.

Definimos novas declarações de imposto como todas as novas declarações de imposto encontradas na instituição para este link desde nossa última atualização. Podem ser novas declarações de imposto do último ano ou também declarações de imposto que foram adicionadas pela instituição para anos ou meses anteriores.

No payload do webhook, incluímos o tipo de declarações de imposto (`mensal` ou `anual`) bem como o número de declarações de imposto encontradas desde a última atualização.

Exemplo de Novas Declarações de Imposto Disponíveis (Anual)
```json Exemplo de Novas Declarações de Imposto Disponíveis (Anual)
{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // pode ser anual ou mensal
    "new_tax_returns": 1 // Número total de novas declarações de imposto encontradas
  }
}
```

Exemplo de Novas Declarações de Imposto Disponíveis (Mensal)
```json Exemplo de Novas Declarações de Imposto Disponíveis (Mensal)
{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // pode ser anual ou mensal
    "new_tax_returns": 1 // Número total de novas declarações de imposto encontradas
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Declarações de Imposto
curl --request GET 'https://api.belvo.com/api/tax-returns/?link=link_id&created_at__range=date1,date2' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber declarações de imposto. Recomendamos que `date1` seja a data em que você recebeu uma notificação anteriormente e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## tax-status

### Atualização histórica

Assim que seu link fiscal for criado, recuperamos de forma assíncrona o documento de Situação Fiscal (*Constancia de Situación Fiscal*) e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | A Situação Fiscal mais recente para o usuário. |


No payload do webhook, você receberá o número total de documentos de Situação Fiscal para o usuário, juntamente com a última data em que a Situação Fiscal foi atualizada.

```json Exemplo de Atualização Histórica de Situação Fiscal
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_STATUS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_status": 1, // Número de situações fiscais
    "last_status_change_date": "1995-08-01" // Ano em que a situação fiscal foi alterada pela última vez
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Situação Fiscal
curl --request GET 'https://api.belvo.com/api/tax-status/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## transações

### Atualização histórica

Assim que seu link bancário é criado, carregamos assincronamente as transações disponíveis para o link e enviaremos o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O número total de transações para o link no último ano. |


No payload do webhook, incluímos o número de transações encontradas para o link (incluindo o número de transações de entrada e saída), bem como o intervalo de datas ao qual a informação se aplica.

Resumo do Webhook Disponível
Após todos os recursos solicitados terem terminado de processar, você também receberá um webhook Progresso da Atualização Histórica Completo que fornece um resumo de quais recursos foram bem-sucedidos ou falharam. Este é um recurso beta opcional.

Limites operacionais atingidos
Se os limites operacionais mensais do OFDA forem esgotados para este link e recurso, o webhook `historical_update` incluirá `data.errors` com `code` `operational_limits_reached` em vez de contagens de transações. Veja limites operacionais do OFDA atingidos.

```json Exemplo de Atualização Histórica de Transações
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "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": "2023-01-03", // Data da primeira transação
    "last_transaction_date": "2024-01-03" // Data da última transação
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Transações
curl --request GET 'https://api.belvo.com/api/transactions/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


Você pode adicionar mais filtros para restringir os resultados, por exemplo:

```shell Exemplo de Solicitação de Transações com Filtros
curl --request GET 'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&value_date__range=first_transaction_date,last_transaction_date' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `type` | O tipo de transação. Pode ser `INFLOW` ou `OUTFLOW`. | `INFLOW` |
| `value_date__range` | O intervalo de datas para o qual você deseja obter transações. Este deve ser o `first_transaction_date` e `last_transaction_date` que você recebeu na notificação do webhook. | `2023-01-03,2024-01-03` |


### Novas transações disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas transações que tenham aparecido para o link fornecido desde a última atualização.

Definimos novas transações como transações encontradas na instituição para um determinado link desde a última atualização. Por exemplo, estas podem ser novas transações das últimas 24 horas ou novas transações de alguns dias atrás que foram apenas recentemente adicionadas pela instituição.

| Código do Webhook | Descrição |
|  --- | --- |
| `new_transactions_available` | O número de novas transações encontradas na instituição desde a última atualização. |


No payload do webhook, incluímos o número de novas transações encontradas para o link.

```json Exemplo de Novas Transações Disponíveis
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "new_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_transactions": 19 // Número de novas transações encontradas desde o último evento
  }
}
```

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

```shell Exemplo de Solicitação de Transações
curl --request GET 'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&created_at__range=date1,date2' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber transações. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


### Transação atualizada

Este webhook está disponível para **ambos** os links únicos e recorrentes

Sempre que a Belvo identifica que uma transação foi atualizada na instituição (por exemplo, uma alteração no campo de descrição ou na data de valor), enviará o seguinte webhook:

| Código do Webhook | Descrição |
|  --- | --- |
| `transactions_updated` | O número de transações atualizadas junto com a lista de IDs de transação. |


No payload do webhook, incluímos o número de transações que foram atualizadas junto com uma lista de IDs de transação da Belvo.

```json Exemplo de Transação Atualizada
{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_updated",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Número total de transações atualizadas.
    "updated_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // O ID da transação atualizada.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}
```

Assim que você receber a notificação, poderá obter a lista completa de transações para aquele link usando a seguinte chamada:

```shell Exemplo de Requisição de Transações
curl --request GET 'https://api.belvo.com/api/transactions/?link=link_id&id__in=transaction1,transaction2,transaction3' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | A lista de `id`s de transação que você recebeu no `data.updated_transactions` da notificação do webhook. | `7d0afe4c-373d-490c-90e4-06xx4cdd4a17,53759bc-ca02-46f0-b1d5-31xxcd54db41,64ecc7df-f322-4934-82f5-3b3ae675ef4a` |


#### Alterações que acionam um `transactions_updated` webhook

A Belvo monitora os seguintes campos para todas as transações e, quando detecta uma alteração entre a última vez que os dados foram recuperados e o momento atual, enviará um `transactions_updated` webhook para você:

- `amount`
- `currency`
- `description`
- `value_date`
- `internal_identification`
- `type`
- `status`
- `credit_card_data.bill_internal_identification` (somente OFDA)
- `credit_card_data.credit_card_bill.id` (somente OFDA)


### Transação excluída

Este webhook está disponível para **ambos** os links únicos e recorrentes

A Belvo monitora e limpa regularmente os dados transacionais em seu banco de dados para melhorar a consistência dos dados que você recebe. Quando uma transação é identificada como duplicada (o que pode ocorrer, por exemplo, devido a chamadas POST feitas em rápida sucessão para a API para o *mesmo* link), ela é removida do banco de dados. Nesse caso, você receberá um webhook `transactions_deleted` com uma lista das transações que foram excluídas.

```json Exemplo de Transação Excluída
{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_deleted",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Número total de transações excluídas.
    "deleted_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // O ID da transação excluída.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}
```

## Webhook de Status da Instituição (Externo)

### Configure o webhook

Para assinar o webhook de Status da Instituição:

1. Acesse a página Status da Instituição Belvo.
2. Clique em **Subscribe to Updates**.
3. Na navegação superior, clique no ícone **<>**.
4. Na aba de webhooks, forneça as informações necessárias e clique em **Subscribe**.
4.1 URL onde você deseja receber o webhook
4.2 Um endereço de e-mail para confirmar o URL do webhook.


1. Na caixa de diálogo, escolha sobre quais instituições você deseja receber atualizações e clique em **Save**.


Feito! Confirme Seu Endereço de E-mail
Agora basta confirmar seu endereço de e-mail e você começará a receber eventos de status de webhook para as instituições que selecionou. Mas esperamos que isso não aconteça com frequência 😉.

### Payload do webhook

No payload do webhook que você recebe de statuspage.io, os campos-chave que você deve analisar são:

| Campo  | Descrição |
|  --- | --- |
| `incident.name` | Indica a natureza do problema com a instituição. |
| `incident.status` | O status atual do incidente no momento do webhook. Pode ser:  investigating  identified  monitoring  resolved |
| `components.status` | A gravidade da interrupção da instituição. Pode ser:  operational (tudo está funcionando)  partial_outage (certas funcionalidades estão indisponíveis)  major_outage (instituição está completamente indisponível) |
| `components.name` | O nome da instituição afetada. |


O payload que você recebe é bastante grande, como você pode ver no exemplo de código abaixo. No entanto, se você analisar os campos mencionados acima, terá todas as informações relevantes necessárias sobre o incidente.

```json Institution Status Webhook Example
{
   "meta":{
      "unsubscribe":"http://institutions.belvo.com/?unsubscribe=73cj0w1mm121",
      "documentation":"https://help.statuspage.io/knowledge_base/topics/webhook-notifications",
      "generated_at":"2021-04-19T14:46:37.135Z"
   },
   "page":{
      "id":"3h4nklhdf7jr",
      "status_indicator":"major",
      "status_description":"Partial System Outage"
   },
   "incident":{
      "name":"bancoppel_mx_retail: Link creation and existing links operations are showing high error rates", // importante
      "status":"investigating", // importante
      "created_at":"2021-04-19T14:46:34.737Z",
      "updated_at":"2021-04-19T14:46:34.844Z",
      "monitoring_at":"None",
      "resolved_at":"None",
      "impact":"critical",
      "shortlink":"https://stspg.io/74hxzgnrmjnt",
      "scheduled_for":"None",
      "scheduled_until":"None",
      "scheduled_remind_prior":false,
      "scheduled_reminded_at":"None",
      "impact_override":"None",
      "scheduled_auto_in_progress":false,
      "scheduled_auto_completed":false,
      "metadata":{
      },
      "started_at":"2021-04-19T14:46:34.731Z",
      "id":"p3b3zhn5p0pz",
      "page_id":"3h4nklhdf7jr",
      "incident_updates":[
         {
            "status":"investigating",
            "body":"We are currently investigating this issue related to both link creation and POST calls.",
            "created_at":"2021-04-19T14:46:34.841Z",
            "wants_twitter_update":false,
            "twitter_updated_at":"None",
            "updated_at":"2021-04-19T14:46:34.841Z",
            "display_at":"2021-04-19T14:46:34.841Z",
            "deliver_notifications":true,
            "tweet_id":"None",
            "id":"m9dcv76z7jwf",
            "incident_id":"p3b3zhn5p0pz",
            "custom_tweet":"None",
            "affected_components":[
               {
                  "code":"1f4dxgqr6pkg",
                  "name":"🇲🇽 Retail banking - bancoppel_mx_retail",
                  "old_status":"operational",
                  "new_status":"major_outage"
               }
            ]
         }
      ],
      "postmortem_body":"None",
      "postmortem_body_last_updated_at":"None",
      "postmortem_ignored":false,
      "postmortem_published_at":"None",
      "postmortem_notified_subscribers":false,
      "postmortem_notified_twitter":false,
      "components":[
         {
            "status":"major_outage", // importante
            "name":"bancoppel_mx_retail", // importante
            "created_at":"2021-04-13T09:50:24.288Z",
            "updated_at":"2021-04-19T14:46:34.768Z",
            "position":5,
            "description":"None",
            "showcase":true,
            "start_date":"2021-04-13T00:00:00.000Z",
            "id":"1f4dxgqr6pkg",
            "page_id":"3h4nklhdf7jr",
            "group_id":"bqcwjbwjhvjt"
         }
      ]
   }
}
```