# 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` | sim | string | O ID do webhook da Belvo. | `aadf41a1fc8e4f79a49f7f04027ac999` |
| `webhook_type` | sim | string | O recurso ao qual este webhook se refere. | `ACCOUNTS` |
| `process_type` | sim | string | O parâmetro `process_type` indica por que o evento do 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).
- `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 é concluída.
- `async_delete`: O webhook foi acionado quando a exclusão assíncrona de um link é concluída.

 | `ACCOUNTS` |
| `webhook_code` | sim | string | O evento que acionou o webhook. | `STATUS_UPDATE` |
| `external_id` | sim | 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` | sim | 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"
            }
        ]
    }
}
```

## 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.


## 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.


```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.


```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` |


## consents

Disponível apenas para links recorrentes
Você só receberá eventos de webhook `CONSENT` para links recorrentes.

### Consentimento prestes a expirar

Opt-in para receber webhooks de consentimento prestes a expirar
Se você deseja receber webhooks para consentimentos que estão prestes a expirar, entre em contato com nossa equipe de suporte.

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 recorrente do link.

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, poderá solicitar ao usuário que renove seu 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 logo 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 de 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.
  }
}
```

## 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 atuais encontrados para o link. |


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


```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 atuais 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.


```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 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 registros de emprego encontrados para o link. |


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


```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 no 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 |
|  --- | --- |
| `UNEMPLOYED` | O funcionário estava empregado, mas foi demitido ou se demitiu do empregador. |
| `EMPLOYED` | O funcionário estava desempregado na última verificação e agora está empregado. |
| `EMPLOYEE_CHANGED_JOBS` | O funcionário mudou de emprego. |
| `SALARY_INCREASE` | O salário do funcionário aumentou pelo menos 10% desde a última verificação. |
| `SALARY_DECREASE` | O salário do funcioná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. Por exemplo, se uma pessoa mudou de emprego e agora está recebendo um salário mais alto, então no `data.employment_changes` array você receberá:


```json
{
  "data": {
    "employment_changes": ["EMPLOYEE_CHANGED_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 webhook `employment_changes`. 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_CHANGED_JOBS`, `SALARY_INCREASE` |
| 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 dados recém-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 para Recuperar registros de emprego, você define `save_data` como `false`.

Ao recuperar dados de registros de emprego usando o Recuperar detalhes do registro de emprego, 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 houve dados na extração inicial dos dados de registro de emprego

No caso de uma tentativa anterior de recuperação 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 estava sem resposta, 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 seu link bancário recorrente for 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 dados de forma assíncrona 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 de forma assíncrona 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 formos capazes de 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.

## rendas

### 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` |


## faturas

### Atualizações iniciais

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

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


Incluímos o número de faturas encontradas durante este período para o tipo de fatura, bem como as datas da primeira e última fatura 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 Faturas 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 Faturas 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 fatura. 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 faturas. 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 for 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é 6 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 1 ano de notas fiscais de ENTRADA (recebidas). |
| `historical_outflow_update` | O último 1 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 fiscal, bem como as datas da primeira e última nota fiscal 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

Modo de Atualização do Widget
Recomendamos fortemente que você use nosso Connect 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 `invalid_credentials` sempre que as credenciais de um usuário não forem mais válidas para atualizar um link recorrente. Isso pode acontecer quando um usuário altera suas credenciais bancárias.

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 recorrente é 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 Webhook
    "error_message": "Invalid credentials provided to login to the institution", // 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 de Exclusão de 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 Connect widget em 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, pode 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 de forma assíncrona 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.


```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 ser recuperada.
  }
}
```

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 do 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 impostos **anuais**, bem como os 12 meses de declarações de impostos **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 impostos estiver disponível para você acessar.

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


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

Exemplo Histórico de Declaração de Impostos (Anual)

```json Exemplo Histórico de Declaração de Impostos (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 Impostos (Mensal)

```json Exemplo Histórico de Declaração de Impostos (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 as declarações de impostos. 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`) assim 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` |


## status-fiscal

### Atualização histórica

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

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


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


```json Exemplo de Atualização Histórica de Status 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 status fiscais
    "last_status_change_date": "1995-08-01" // Ano em que o status fiscal foi alterado 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 Status 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 for 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.


```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 em `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 agora, enviará um `transactions_updated` webhook:

- `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 `transactions_deleted` webhook 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 Email
Agora basta confirmar seu endereço de email 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 (a 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 de que precisa sobre o incidente.


```json Exemplo de Webhook de Status da Instituição
{
   "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"
         }
      ]
   }
}
```