# Webhooks de Agregación

Un **webhook** es una devolución de llamada web que Belvo utiliza para enviar notificaciones sobre un enlace específico. Necesitarás configurar webhooks para poder usar las APIs de Belvo.

## Configurar webhooks

Para configurar un nuevo webhook:

1. En tu panel de control de Belvo, ve a la sección de webhooks de datos.
2. En la pestaña **Webhooks de Datos**, haz clic en **+Nuevo webhook**.
3. Completa el formulario de **Nuevo webhook** con la información requerida.
  - **URL**: la URL para recibir las notificaciones del webhook.
  - **Authorization**: un token de autorización opcional para usar si tu URL está protegida.
4. Haz clic en **Crear webhook**.



✳️ ¡Listo! El webhook está ahora configurado y tu aplicación será notificada de nuevos eventos relacionados con tus links.

Usando Autenticación Adicional
Por razones de seguridad, puedes agregar una capa adicional de autenticación a tus llamadas de webhook. Cuando crees tu webhook, en el campo **Autenticación (Opcional)**, ingresa ya sea:

- `Basic` y una cadena `username:password` codificada en base64 (para autenticación Básica)
- `Bearer` y un token (para autenticación Bearer)


## Tipos de Webhook

Todos los eventos de webhook vienen con una carga útil principal (como se describe en el ejemplo 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  | Requerido | Tipo | Descripción | Ejemplo |
|  --- | --- | --- | --- | --- |
| `webhook_id` | si | string | El ID del webhook de Belvo. | `aadf41a1fc8e4f79a49f7f04027ac999` |
| `webhook_type` | si | string | El recurso al que se refiere este webhook. | `ACCOUNTS` |
| `process_type` | si | string | El parámetro `process_type` indica por qué se activó el evento del webhook. Devolvemos uno de los siguientes valores:- `historical_update`: El webhook se activó al finalizar una actualización histórica para la recuperación de datos (para enlaces recurrentes y para enlaces únicos con fetch_resources).
- `recurrent_update`: El webhook se activó debido a la actualización recurrente (cíclica) de los datos.
- `async_post`: El webhook se activó al completarse la recuperación asincrónica de datos de una llamada POST.
- `async_delete`: El webhook se activó al completarse la eliminación asincrónica de un enlace.

 | `ACCOUNTS` |
| `webhook_code` | si | string | El evento que activó el webhook. | `STATUS_UPDATE` |
| `external_id` | si | string | El identificador único que proporcionaste al crear el objeto. Para cargos y transacciones, este campo siempre devolverá `null`. | `c3c51aaf-aaa3-400c-926d-87ab62e195fd` |
| `data` | si | object | Un objeto que contiene datos específicos sobre el evento. Los campos devueltos en este objeto dependen del `webhook_type` y `webhook_code`. Para obtener información sobre los datos específicos de un webhook dado, consulta la página dedicada a cada recurso. | `{}` |


## Eventos de error de webhook

A veces, al recuperar información de una institución, puede ocurrir un error. En este caso, el objeto de datos del evento de webhook contendrá la información del error que ocurrió. Por ejemplo:


```json Ejemplo de Evento de Error 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": [ // Detalles del error que ocurrió
            {
              "code": "service_unavailable",
              "message": "Belvo no puede procesar la solicitud debido a un problema interno del sistema o a una respuesta no compatible de una institución"
            }
        ]
    }
}
```

## Política de Reintento

Si Belvo llama inicialmente a tu servidor y no recibe un código de estado HTTP `2XX`, intentaremos nuevamente cinco veces usando un retroceso lineal para permitir que tu servidor se recupere de cualquier mal funcionamiento.

## Mejores Prácticas de Webhook

#### Responder a webhooks

Tan pronto como recibas un webhook de Belvo, asegúrate de responder con un código de estado HTTP `2XX`. Si no recibimos una respuesta `2XX` de tu servidor, intentaremos nuevamente cinco veces usando un retroceso lineal para permitir que tu servidor se recupere de cualquier mal funcionamiento.

#### Lista blanca de direcciones IP salientes

Lista blanca de direcciones IP
Recomendamos encarecidamente que pongas en la lista blanca estas direcciones IP para que puedas recibir eventos de webhook.

Puedes recibir eventos de webhook desde las siguientes direcciones IP:

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


#### Prueba de eventos de webhook

Puedes activar cualquier tipo de evento de webhook (incluidos los eventos de link) desde tu Dashboard de Belvo. Una vez activado, recibirás un payload con datos ficticios. Esta es una excelente manera de probar si puedes recibir webhooks, si has configurado correctamente tu autenticación (si es necesario) y actuar sobre los diversos tipos de eventos.

Para activar un evento:

1. Desde el Cambiador de Entorno en tu dashboard de Belvo, selecciona el entorno en el que deseas probar tu webhook.
2. Selecciona la pestaña **Webhooks**.
3. Haz clic en el menú desplegable junto a la URL del webhook de Sandbox que deseas probar.
4. Selecciona el tipo de evento de webhook que deseas. Esto envía el webhook.
5. Expande el cuadro de estado para ver los detalles del evento de webhook.


## cuentas

### Actualización histórica

Tan pronto como se crea tu enlace bancario, cargamos asincrónicamente las cuentas disponibles para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de cuentas encontradas para el enlace. |


En la carga útil del webhook incluimos el número de cuentas encontradas para el enlace.


```json Ejemplo de Actualización Histórica de Cuentas
{
  "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 cuentas encontradas.
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Cuentas
curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevas cuentas disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nueva cuenta que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_accounts_available` | El número de nuevas cuentas encontradas en la institución desde la última actualización. |


En el payload del webhook incluimos el número de nuevas cuentas encontradas para el enlace.


```json Ejemplo de Nuevas Cuentas Disponibles
{
  "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 nuevas cuentas
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Cuentas
curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## bills

### Actualización histórica

Tan pronto como se crea tu enlace bancario recurrente, cargamos asincrónicamente las facturas disponibles para el enlace y te enviaremos el siguiente webhook:

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de facturas encontradas para el enlace. |


En la carga útil del webhook incluimos el número de facturas encontradas para el enlace.


```json Ejemplo de Actualización Histórica de Facturas
{
  "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 facturas
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


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

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevas facturas disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nueva factura que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_bills_available` | El número de nuevas facturas encontradas en la institución desde la última actualización. |


En el payload del webhook incluimos el número de nuevas facturas encontradas para el enlace.


```json Ejemplo de Nuevas Facturas Disponibles
{
  "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 nuevas facturas
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | El rango de fechas para el que deseas recibir empleos. Recomendamos que `date1` sea la fecha en que recibiste previamente una notificación y `date2` sea la fecha en que recibes la notificación actual (ambas en formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## consents

Solo disponible para enlaces recurrentes
Solo recibirás eventos de `CONSENT` de webhook para enlaces recurrentes.

### Consentimiento a punto de expirar

Opta por recibir webhooks de consentimiento a punto de expirar
Si deseas recibir webhooks para consentimientos que están a punto de expirar, por favor contacta a nuestro equipo de soporte.

Puedes recibir un evento `openfinance_consent_about_to_expire` cuando el consentimiento para uno de tus enlaces OFDA esté a punto de expirar dentro de los siete días posteriores a la actualización recurrente del enlace.

Por ejemplo, si tienes una tasa de actualización mensual para un enlace que se renueva el segundo día de cada mes, y la fecha de expiración del consentimiento del enlace es el sexto de ese mes, recibirás un evento `openfinance_consent_about_to_expire`. Sin embargo, si tienes otro enlace que se renueva el segundo día de cada mes pero la fecha de expiración del consentimiento es el décimo de ese mes, no recibirás un evento.

Solicita a tu usuario que renueve el consentimiento
Una vez que recibas este evento, puedes solicitar a tu usuario que renueve su consentimiento usando el My Belvo Portal.


```json Ejemplo de Payload de Consentimiento a Punto de 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", // El ID del consentimiento.
    "consent_due_date": "2024-12-26T10:45:58.000Z", // Timestamp ISO-8601 de cuándo expirará el consentimiento.
    "action": "renew", // Una indicación de qué acción necesitas tomar. Para los webhooks openfinance_consent_about_to_expire, esto siempre se establece en renew.
    "institution": "ofmockbank_br_retail", // La institución para la cual el usuario proporcionó su consentimiento.
    "institution_display_name": "OF Mockbank", // El nombre para mostrar de la institución.
    "institution_icon_logo": "https://logo.com" // La URL del logo de la institución.
  }
}
```

### Consentimiento expirado

Puedes recibir un evento `consent_expired` cuando el consentimiento para uno de tus enlaces OFDA ha expirado.

Solicita a tu usuario renovar el consentimiento
Una vez que recibas este evento, puedes solicitar a tu usuario que renueve su consentimiento usando el My Belvo Portal.


```json Ejemplo de Payload de Consentimiento Expirado
{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_expired",
  "link_id": "3d3364b7-0175-483d-a58b-b471f251e533", // El ID del enlace asociado con el consentimiento.
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // El ID del consentimiento.
    "action": "renew", // Una indicación de qué acción necesitas tomar. Para los webhooks openfinance_consent_expired, esto siempre se establece en renew.
    "institution": "ofmockbank_br_retail", // La institución para la cual el usuario proporcionó su consentimiento.
    "institution_display_name": "OF Mockbank", // El nombre para mostrar de la institución.
    "institution_icon_logo": "https://logo.com" // La URL del logo de la institución.
  }
}
```

Una vez que recibas la notificación, puedes solicitar a tu usuario que renueve su consentimiento usando el My Belvo Portal.

### Consentimiento revocado

Puedes recibir un evento `openfinance_consent_with_unrecoverable_resources` cuando un consentimiento ha sido revocado debido a que los recursos preexistentes no están disponibles. Un ejemplo de cuándo podrías recibir este evento es cuando un usuario ha otorgado su consentimiento para acceder a varias cuentas y, en una fecha posterior, cerró esas cuentas.


```json Ejemplo de Payload de Open Finance Consent With Unrecoverable Resources
{
  "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", // El ID del consentimiento.
    "institution": "ofmockbank_br_retail", // La institución para la cual el usuario proporcionó su consentimiento.
    "message": "The consent was revoked because it was unrecoverable" // Mensaje de error sobre el consentimiento revocado.
  }
}
```

### Consentimiento temporalmente no disponible

Puedes recibir un evento `openfinance_consent_with_temporarily_unavailable_resources` cuando un consentimiento está temporalmente no disponible debido a que los recursos preexistentes no están disponibles. Un ejemplo de cuándo puede ocurrir esto es cuando el usuario otorgó su consentimiento para acceder a una cuenta determinada, pero no ha utilizado esa cuenta por un tiempo (el número de días hasta que una cuenta se marca como inactiva depende de cada institución).


```json Ejemplo de Payload de Consentimiento de Open Finance con Recursos Temporalmente No Disponibles
{
  "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", // El ID del consentimiento.
    "institution": "ofmockbank_br_retail", // La institución para la cual el usuario proporcionó su consentimiento.
    "message": "The consent is temporarily unusable" // Mensaje de error sobre el consentimiento temporalmente no disponible.
  }
}
```

## current-employments

¡Próximamente Empleos Actuales!
Esta sección menciona actualmente un nuevo recurso que está en desarrollo: **Empleos Actuales**. Este recurso estará disponible en los próximos días, y actualizaremos esta guía una vez que esté listo.

### Actualización histórica

Tan pronto como se crea tu enlace de empleo (para México) y hayas agregado `CURRENT_EMPLOYMENTS` a la lista de recursos en `fetch_resources`, recuperamos asincrónicamente el estado actual de empleo para el enlace y te enviaremos el siguiente webhook:

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de registros de empleo actuales encontrados para el enlace. |


En la carga útil del webhook incluimos el número de registros de empleo actuales encontrados para el enlace.


```json Ejemplo de Actualización Histórica de Empleos Actuales
{
  "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 // El número total de registros de empleo actuales encontrados para el enlace
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Empleos Actuales
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## employment-metrics

### Actualización histórica

Tan pronto como se crea tu enlace de empleo y hayas agregado `EMPLOYMENT_METRICS` a la lista de recursos en `fetch_resources`, calculamos de manera asincrónica las métricas de empleo para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de métricas de empleo generadas para el enlace. |


En la carga útil del webhook incluimos el número de métricas de empleo encontradas para el enlace.


```json Ejemplo de Actualización Histórica de Métricas de Empleo
{
  "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 // El número total de informes de métricas de empleo generados
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Métricas de Empleo
curl --request GET 'https://api.belvo.com/api/employment-metrics/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## registros-de-empleo

### Actualización histórica

Tan pronto como se crea tu enlace de empleo, calculamos de manera asincrónica las métricas de empleo para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de registros de empleo encontrados para el enlace. |


En la carga útil del webhook incluimos el número de facturas encontradas para el enlace.


```json Ejemplo de Actualización Histórica de Registros de Empleo
{
  "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 // El número total de perfiles de registros de empleo encontrados para el enlace
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Registros de Empleo
curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Cambios en el estado de empleo

¿Interesado en acceder a esta nueva función?
Ponte en contacto con nuestro equipo, ¡y te ayudarán a configurarlo!

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nuevo cambio en el empleo que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `employment_changes` | Una lista de cambios de empleo que han ocurrido para el enlace. |


En la carga útil del webhook incluimos los cambios de empleo identificados para el enlace.


```json Ejemplo de Carga Útil de Cambios de Empleo
{
  "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 cambios desde la última verificación
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Registros de Empleo
curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


#### Opciones de cambio de empleo

En tu frecuencia de actualización dada, Belvo extraerá nueva información de empleo para tu enlace y comparará el estado de empleo y la información salarial con la extracción de datos anterior.

Frecuencia de actualización recomendada
Recomendamos una frecuencia de actualización de un mínimo de dos meses. Sin embargo, comunícate con nuestro equipo y podrán asesorarte mejor dependiendo de tu caso de uso.

En el array `data.employment_changes` del webhook, puedes recibir uno o más de los siguientes cambios de empleo:

| Cambio | Descripción |
|  --- | --- |
| `UNEMPLOYED` | El empleado estaba empleado pero fue despedido o renunció a su empleador. |
| `EMPLOYED` | El empleado estaba desempleado en el momento de la última verificación y ahora está empleado. |
| `EMPLOYEE_CHANGED_JOBS` | El empleado cambió de trabajo. |
| `SALARY_INCREASE` | El salario del empleado ha aumentado al menos un 10% desde la última verificación. |
| `SALARY_DECREASE` | El salario del empleado ha disminuido al menos un 10% desde la última verificación. |


Puedes recibir más de un cambio en el array `data.employment_changes`, dependiendo de la situación. Por ejemplo, si una persona cambió de trabajo y ahora recibe un salario más alto, entonces en el array `data.employment_changes` recibirás:


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

#### Escenarios con registros eliminados o faltantes

Belvo envía notificaciones de empleo después de comparar los datos recién recuperados con los datos recuperados anteriormente. Sin embargo, puede haber casos en los que actualicemos un enlace de empleo que **no tenga** ningún dato de registro de empleo en la base de datos de Belvo. En estos casos, aún recibirás un `employment_changes` webhook. Sin embargo, como Belvo verifica los datos recién devueltos contra datos inexistentes en la base de datos de Belvo, en este caso recibirás una de las siguientes combinaciones de cambios de empleo:

| Caso cuando se actualiza | Valores |
|  --- | --- |
| Usuario está empleado | `EMPLOYED`, `EMPLOYEE_CHANGED_JOBS`, `SALARY_INCREASE` |
| Usuario está desempleado | `UNEMPLOYED` |


Esto puede ocurrir debido a cualquiera de las siguientes razones:

#### Al crear un enlace, estableces `stale_in` a un período menor que tu tasa de actualización.

Al crear un enlace, puedes opcionalmente agregar el parámetro `stale_in` para controlar cuánto tiempo Belvo almacena los datos derivados del usuario. El período es **relativo** al timestamp de `last_updated_at` del enlace (la última vez que se accedió a la cuenta del usuario).

Por ejemplo, si estableces `stale_in` a 62 días cuando creaste un enlace el 01.03.2024, los datos se almacenan en la base de datos de Belvo durante 62 días después de esta fecha. Si luego para el mismo enlace accedes a los datos un mes después (01.04.2024), entonces el conteo se reinicia y Belvo eliminará los datos 62 días después del 01.04.2024.

Sin embargo, si estableces un período `stale_in` menor que tu tasa de actualización, Belvo eliminará los datos antes de la próxima actualización. Como resultado, los datos recién devueltos se compararán con datos inexistentes, lo que desencadenará un webhook de `employment_changes` con los estados mencionados anteriormente.

Para evitar esto, ya sea:

- No pases el parámetro `stale_in` (que por defecto es 365 días).
- Establece un valor `stale_in` que sea mayor que tu tasa de actualización. Por ejemplo, si tienes un período de actualización de 60 días, entonces tu parámetro `stale_in` debería establecerse en al menos 62 días.


#### Cuando realices un POST para Recuperar registros de empleo, establece `save_data` en `false`.

Al recuperar datos de registros de empleo utilizando el Recuperar detalles del registro de empleo, establecer `save_data` en `false` evita que Belvo almacene los datos. En consecuencia, cualquier dato recién recuperado se comparará con datos inexistentes, lo que resultará en el `employment_changes` webhook mencionado anteriormente.

Para evitar esto, recomendamos que establezcas `save_data` en `true`.

#### Datos de registro de empleo eliminados

Si eliminas datos de registro de empleo utilizando la solicitud Eliminar un registro de empleo, todos los datos de esa entrada de empleo se eliminan de la base de datos de Belvo. Durante la próxima actualización, Belvo compara los nuevos datos con los datos eliminados (no existentes), lo que resulta en el `employment_changes` webhook mencionado anteriormente.

#### No hubo datos en la extracción inicial de datos del registro de empleo

En el caso de que una recuperación previa del registro de empleo no haya sido exitosa porque no había datos para el usuario en la institución (lo que resultó en que la API devolviera una respuesta vacía) o la institución de empleo no respondiera, durante la siguiente actualización, Belvo compara los nuevos datos con los datos inexistentes, lo que resulta en el webhook `employment_changes` mencionado anteriormente.

## empleos-brasil

### Actualización histórica

Tan pronto como se crea tu enlace bancario recurrente, cargamos de manera asincrónica la información de empleo disponible para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de empleos encontrados para el enlace. |


En la carga útil del webhook incluimos el número de empleos encontrados para el enlace.


```json Ejemplo de Actualización Histórica de Empleos (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 // El número total de perfiles de registros de empleo encontrados para el enlace
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Empleos (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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevos empleos disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nuevo empleo que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_employments_available` | El número de nuevos empleos encontrados desde la última actualización. |


En la carga útil del webhook incluimos el número de nuevos empleos encontrados para el enlace.


```json Ejemplo de Nuevos Empleos (BR) Disponibles
{
  "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 nuevos empleos encontrados desde el último evento
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Empleos (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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | El rango de fechas para el cual deseas recibir empleos. Recomendamos que `date1` sea la fecha en que recibiste previamente una notificación y `date2` sea la fecha en que recibes la notificación actual (ambas en formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## financial-statements-mexico

### Actualización histórica

Tan pronto como se crea tu enlace fiscal, cargamos de manera asincrónica **los últimos tres años de estados financieros** y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | Los últimos tres años de estados financieros. |


En la carga útil del webhook incluimos el número de estados financieros recibidos.


```json Ejemplo de Actualización Histórica de Estados Financieros
{
  "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
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Estados Financieros
curl --request GET 'https://api.belvo.com/api/financial-statements/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevos estados financieros disponibles

Solo aplicable para llamadas POST asincrónicas.

Cuando realizas una solicitud "ad hoc" de estados financieros (con el encabezado `X-Belvo-Request-Mode: async`), Belvo recuperará de manera asincrónica la información del estado financiero y te enviará el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `new_financial_statements_available` | El número de nuevos estados financieros encontrados para el link. |


En el payload del webhook incluimos el número de nuevos estados financieros encontrados para el link.


```json Ejemplo de Nuevos Estados Financieros Disponibles
{
  "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
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles realizando la siguiente solicitud:


```shell Ejemplo de Solicitud de Estados Financieros
curl --request GET 'https://api.belvo.com/api/financial-statements/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


#### Errores al extraer Estados Financieros

Con el fin de proporcionarte una mayor visibilidad respecto a la extracción de datos de Estados Financieros, hemos incluido un nuevo campo `error` en la respuesta de carga útil para cada estado financiero que recibirás.

Si, para un año determinado en el que un estado financiero está disponible, no podemos recuperar los datos debido a que la institución no proporciona la información en el formato correcto, el campo `error` indicará la razón detrás de la extracción fallida:


```json Ejemplo de Error en Estados Financieros
[
  {
    "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
  }
]
```

Los posibles mensajes de error son:

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


Si recibes cargas útiles de estados financieros con estos errores, por favor contacta a nuestro equipo de soporte.

## ingresos

### Actualización histórica

Tan pronto como se crea tu enlace bancario y hayas agregado `INCOMES` a la lista de recursos en `fetch_resources`, calculamos asincrónicamente los datos de ingresos para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de ingresos y flujos de ingresos identificados para el enlace. |


En la carga útil del webhook incluimos el número de ingresos y flujos de ingresos identificados para el enlace.


```json Ejemplo de Actualización Histórica de Ingresos
{
  "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, // Siempre = 1, Indica que el análisis está listo para ser recuperado.
    "number_of_income_streams": 5, // Número total de flujos de ingresos identificados.
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Ingresos
curl --request GET 'https://api.belvo.com/api/incomes/?link=link_id' \
  -u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## investment-transactions

### Actualización histórica

Tan pronto como se crea tu enlace bancario, cargamos de manera asincrónica las transacciones de inversión disponibles para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de transacciones de inversión para el enlace del último año. |


En la carga útil del webhook incluimos el número de transacciones de inversión encontradas para el enlace (incluyendo el número de transacciones de entrada y salida) así como el rango de fechas al que se aplica la información.


```json Ejemplo de Actualización Histórica de Transacciones de Inversión
{
  "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 transacciones encontradas
    "total_inflow_transactions": 10, // Número total de transacciones de entrada
    "total_outflow_transactions": 9, // Número total de transacciones de salida
    "first_transaction_date": "2023-01-03", // Fecha de la primera transacción
    "last_transaction_date": "2024-01-03" // Fecha de la última transacción
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Transacciones
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


Puedes agregar más filtros para reducir los resultados, por ejemplo:


```shell Ejemplo de Solicitud de Transacciones de Inversión
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevas transacciones disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará de manera asincrónica datos sobre cualquier nueva transacción de inversión que haya aparecido para el enlace dado desde la última actualización.

Definimos nuevas transacciones de inversión como transacciones encontradas en la institución para un enlace dado desde la última actualización. Por ejemplo, estas podrían ser nuevas transacciones de inversión de las últimas 24 horas o nuevas transacciones de inversión de hace unos días que solo fueron agregadas recientemente por la institución.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_investment_transactions_available` | El número de nuevas transacciones de inversión encontradas en la institución desde la última actualización. |


En el payload del webhook incluimos el número de nuevas transacciones encontradas para el enlace.


```json Ejemplo de Nuevas Transacciones de Inversión Disponibles
{
  "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 nuevas transacciones de inversión encontradas desde el último evento
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Transacciones de Inversión
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | El rango de fechas para el cual deseas recibir transacciones. Recomendamos que `date1` sea la fecha en que recibiste previamente una notificación y `date2` sea la fecha en que recibes la notificación actual (ambas en formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## inversiones

### Actualización histórica

Tan pronto como se crea tu enlace bancario, cargamos de manera asincrónica las cuentas de inversión disponibles para el enlace y te enviaremos el siguiente webhook:

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de cuentas de inversión encontradas para el enlace. |


En la carga útil del webhook incluimos el número de cuentas de inversión encontradas para el enlace.


```json Ejemplo de Actualización Histórica de Inversiones
{
  "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 cuentas de inversión encontradas.
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Inversiones
curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nueva inversión disponible

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nueva cuenta de inversión que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_investments_available` | El número de nuevas cuentas encontradas en la institución desde la última actualización. |


En el payload del webhook incluimos el número de nuevas cuentas encontradas para el enlace.


```json Ejemplo de Nueva Inversión Disponible
{
  "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 // Nuevas cuentas de inversión encontradas para el enlace
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Inversiones
curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## facturas

### Actualizaciones iniciales

Tan pronto como se crea tu enlace fiscal recurrente, cargamos de manera asincrónica los últimos 30 días de historial de facturas. Recibirás dos notificaciones a través de un webhook cuando los últimos 30 días de facturas estén disponibles para que las accedas.

| Código de Webhook | Descripción |
|  --- | --- |
| `initial_inflow_update` | Los últimos 30 días de facturas de ENTRADA (recibidas). |
| `initial_outflow_update` | Los últimos 30 días de facturas de SALIDA (enviadas). |


Incluimos el número de facturas encontradas durante este período para el tipo de factura, así como las fechas de la primera y última factura en el rango.

Ejemplo de Entrada Inicial

```json Ejemplo 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"
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas 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
```

Ejemplo de Salida Inicial

```json Ejemplo de Salida 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"
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas de Salida 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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `type` | El tipo de factura. Puede ser `INFLOW` o `OUTFLOW`. Si recibes un webhook `initial_inflow_update`, esto debe establecerse en `INFLOW`. Si recibes un webhook `initial_outflow_update`, esto debe establecerse en `OUTFLOW`. | `INFLOW` |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | El rango de fechas para el que deseas obtener facturas. Esto debe ser el `first_invoice_date` y `last_invoice_date` que recibiste en la notificación del webhook. | `2017-07-31,2018-07-31` |


### Actualizaciones históricas

Tan pronto como se crea tu enlace fiscal recurrente, cargamos de manera asincrónica los últimos tres años de historial de facturas de ENTRADA y SALIDA para el SAT. Recibirás hasta 6 notificaciones a través de un webhook cada vez que el historial de facturas esté disponible para que lo accedas. **Por cada año para el cual Belvo extrae datos**, recibirás los siguientes webhooks:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_inflow_update` | El último año de facturas de ENTRADA (recibidas). |
| `historical_outflow_update` | El último año de facturas de SALIDA (enviadas). |


En la carga útil del webhook incluimos el número de facturas encontradas durante este período para el tipo de factura, así como las fechas de la primera y última factura en el rango.

Ejemplo de Entrada Histórica

```json Ejemplo 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 facturas encontradas
    "first_invoice_date": "2017-07-31", // Primera factura de entrada encontrada
    "last_invoice_date": "2018-07-31" // Última factura de entrada encontrada
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas 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
```

Ejemplo de Salida Histórica

```json Ejemplo de Salida 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 facturas encontradas
    "first_invoice_date": "2017-07-31", // Primera factura de salida encontrada
    "last_invoice_date": "2018-07-31" // Última factura de salida encontrada
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas de Salida 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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `type` | El tipo de factura. Puede ser `INFLOW` o `OUTFLOW`. Si recibes un webhook `historical_inflow_update`, esto debe establecerse en `INFLOW`. Si recibes un webhook `historical_outflow_update`, esto debe establecerse en `OUTFLOW`. | `INFLOW` |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | El rango de fechas para el cual deseas obtener facturas. Esto debe ser el `first_invoice_date` y `last_invoice_date` que recibiste en la notificación del webhook. | `2017-07-31,2018-07-31` |


### Nuevas facturas disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará de manera asincrónica datos sobre cualquier nueva factura que haya aparecido en el sistema del SAT para un enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_invoices_available` | Una lista de nuevas facturas que se recuperaron desde la última actualización. |


Puedes recibir una notificación `new_invoices_available` siempre que haya nuevas facturas disponibles para un enlace fiscal recurrente. Puedes recibir más de un evento de webhook para un enlace al mismo tiempo, dependiendo del tipo de facturas encontradas. Por ejemplo, podrías recibir un evento de webhook para facturas de INFLOW y otro separado para facturas de OUTFLOW.

Definimos nuevas facturas como todas las nuevas facturas encontradas en la institución para este enlace desde nuestra última actualización. Por ejemplo, si tienes una frecuencia de actualización diaria, podrían ser las nuevas facturas de las últimas 24 horas o facturas añadidas por la institución en las últimas 24 horas para días anteriores.

En la carga útil del webhook incluimos el número de facturas encontradas desde la última actualización, el tipo de facturas (`INFLOW` o `OUTFLOW`), así como un array de `id`s de facturas.


```json Ejemplo de Nuevas Facturas Disponibles
{
  "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": [
      // Un array de IDs de facturas
      "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"
    ]
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles de las nuevas facturas haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | La lista de `id`s de facturas que recibiste en el `data.new_invoices` de la notificación del webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


### Facturas canceladas

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará de manera asincrónica datos sobre cualquier factura cancelada que haya aparecido en el sistema del SAT para un enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `invoices_cancelled` | Una lista de facturas canceladas que se recuperaron desde la última actualización. |


Definimos facturas canceladas como todas las facturas existentes con un nuevo estado "cancelado" en la institución para este enlace

En la carga útil del webhook incluimos el tipo de facturas canceladas (`INFLOW` o `OUTFLOW`) así como un array de `id`s de facturas.


```json Ejemplo de Facturas 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": [
      // Un array de IDs de facturas
      "0a362860-c92f-4414-a731-a772e88ab54b",
      "0a376126-c23r-2131-b745-a876d77cd76c"
    ]
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles sobre las facturas canceladas haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Facturas 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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | La lista de `id`s de facturas que recibiste en el `data.cancelled_invoices` de la notificación del webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


## enlaces

Modo de Actualización del Widget
Recomendamos encarecidamente que utilices nuestro Connect Widget con Modo de Actualización después de recibir un evento de webhook de Link para manejar la actualización de credenciales o token.

### Credenciales inválidas

Puedes recibir una notificación de `invalid_credentials` siempre que las credenciales de un usuario ya no sean válidas para actualizar un enlace recurrente. Esto puede suceder cuando un usuario cambia sus credenciales bancarias.

Una vez que recibas esta notificación, puedes pedirle a tu usuario que actualice su nueva contraseña utilizando el Connect widget en Modo de Actualización. Tan pronto como las credenciales sean correctas, el enlace recurrente se actualiza.

Si no estás utilizando el Connect Widget, puedes pedirle a tu usuario que te envíe su nueva contraseña y luego realizar una solicitud de Actualización de Enlace para guardar la nueva contraseña. Por ejemplo, si recibes el siguiente webhook:


```json Ejemplo de Credenciales 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", // Error del evento Webhook
    "error_message": "Invalid credentials provided to login to the institution", // Mensaje descriptivo del error
    "status": 400
  }
}
```

Una vez que recibas las credenciales requeridas de tu usuario, realiza una solicitud de Actualizar las credenciales de un enlace con los detalles actualizados.

### Enlace eliminado

Cuando utilizas el encabezado `X-Belvo-Request-Mode: async` de Belvo al solicitar Eliminar un Enlace, Belvo eliminará de manera asincrónica todos los datos asociados a ese enlace (por ejemplo: transacciones, cuentas, facturas, declaraciones de impuestos, empleos, etc.). Una vez que el proceso se complete, recibirás un evento de webhook `link_deleted` indicando que el Enlace y todos los datos asociados se eliminaron con éxito.


```json Ejemplo de Enlace Eliminado
{
  "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
}
```

En caso de que haya un error durante el proceso de eliminación del Enlace, se te notificará utilizando el mismo código de webhook pero con detalles adicionales en el campo `data` indicando que la eliminación del enlace no fue exitosa y que debes reintentar la solicitud:


```json Ejemplo de Error de Eliminación de Enlace
{
  "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."
  }
}
```

Si recibes un error más de dos veces para un enlace dado, contacta a nuestro equipo de soporte con el `request_id`.

### Token requerido

Puedes recibir una notificación `token_required` cada vez que una nueva MFA token sea requerida por la institución para mantener el enlace recurrente funcionando.

Una vez que recibas esta notificación, puedes pedirle a tu usuario que proporcione un nuevo token usando el Connect widget en modo de actualización. Tan pronto como se proporcione el token, el enlace recurrente se actualiza.

Ten en cuenta que hasta que el enlace se actualice, Belvo no enviará ningún webhook relacionado con este enlace.

Si no estás usando el Connect Widget, puedes pedirle a tu usuario que te envíe su nueva contraseña y luego realizar una solicitud de Actualización de Enlace para proporcionar el nuevo MFA token. Por ejemplo, si recibes el siguiente webhook:


```json Ejemplo de Token Requerido
{
  "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", // Error del evento de Webhook
    "error_message": "MFA token fue requerida por la institución", // Mensaje descriptivo del error
    "status": 428,
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "token_generation_data": {
      "instructions": "Usa este código para generar el token",
      "type": "numeric",
      "value": "12345"
    }
  }
}
```

Una vez que recibas las credenciales de token requeridas de tu usuario, realiza una solicitud de Actualizar las credenciales de un enlace con el token actualizado, junto con la `session` y `link_id` que recibiste en la notificación del webhook.

## propietarios

### Actualización histórica

Tan pronto como se crea tu enlace bancario, cargamos de manera asincrónica la información del propietario disponible para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de propietarios encontrados para el enlace. |


En la carga útil del webhook incluimos el número de propietarios encontrados para el enlace.


```json Ejemplo de Actualización Histórica de Propietarios
{
  "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 propietarios
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Propietarios
curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Nuevos propietarios disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará asincrónicamente datos sobre cualquier nueva cuenta que haya aparecido para el enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_owners_available` | El número de nuevos propietarios encontrados desde la última actualización. |


En el payload del webhook incluimos el número de nuevos propietarios encontrados para el enlace.


```json Ejemplo de Nuevos Propietarios Disponibles
{
  "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 nuevos propietarios
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Propietarios
curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## gastos-recurrentes

### Actualización histórica

Tan pronto como se crea tu enlace bancario y hayas agregado `RECURRING_EXPENSES` a la lista de recursos en `fetch_resources`, calculamos de manera asincrónica los datos de gastos recurrentes para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de gastos recurrentes identificados para el enlace. |


En la carga útil del webhook incluimos el número de gastos recurrentes identificados para el enlace.


```json Ejemplo de Actualización Histórica de Gastos Recurrentes
{
  "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 // Conteo de gastos recurrentes identificados.
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Gastos Recurrentes
curl --request GET 'https://api.belvo.com/api/recurring-expenses/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## risk-insights

### Actualización histórica

Tan pronto como se crea tu enlace bancario y hayas agregado `RISK_INSIGHTS` a la lista de recursos en `fetch_resources`, generamos de manera asincrónica los insights de riesgo para el enlace y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de insights de riesgo identificados para el enlace. |


En la carga útil del webhook incluimos el número de insights de riesgo identificados para el enlace.


```json Ejemplo de Actualización Histórica de Insights de Riesgo
{
  "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 // Siempre = 1, Indica que el análisis está listo para ser recuperado.
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Insights de Riesgo
curl --request GET 'https://api.belvo.com/api/risk-insights/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## tax-compliance-status

### Actualización histórica

Tan pronto como se crea tu enlace fiscal, recuperamos de manera asincrónica el documento de Estado de Cumplimiento de Obligaciones Fiscales (*Opinión de Cumplimiento de Obligaciones Fiscales*) y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El Estado de Cumplimiento de Obligaciones Fiscales actual para el usuario. |


En la carga útil del webhook recibirás el número total de documentos de Estado de Cumplimiento de Obligaciones Fiscales.


```json Ejemplo de Actualización Histórica del Estado de Cumplimiento de Obligaciones Fiscales
{
  "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 // El número total de documentos de estado de cumplimiento fiscal
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Estado de Cumplimiento de Obligaciones Fiscales
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## retenciones-impuestos

### Actualización histórica

Tan pronto como se crea tu enlace fiscal, cargamos de manera asincrónica el último año de retenciones fiscales y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | El último año de Retenciones Fiscales. |


En la carga útil del webhook incluimos el número total de retenciones fiscales encontradas para el último año, junto con el rango de fechas para el cual recuperamos datos.


```json Ejemplo de Actualización Histórica de Retenciones Fiscales
{
  "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, // El número total de retenciones fiscales
    "first_tax_retention_date": "2023-06-01", // La fecha de la primera retención fiscal encontrada
    "last_tax_retention_date": "2023-08-20" // La fecha de la última retención fiscal encontrada
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Retenciones Fiscales
curl --request GET 'https://api.belvo.com/api/tax-retentions/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## declaraciones-de-impuestos

### Actualización histórica

Tan pronto como se crea tu enlace fiscal, cargamos de manera asincrónica los últimos cinco años de declaraciones de impuestos **anuales** así como los 12 meses de declaraciones de impuestos **mensuales**. Recibirás una notificación `historical_update` para cada tipo de declaración de impuestos (anual y mensual) cuando el historial de declaraciones de impuestos esté disponible para que lo accedas.

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | Los últimos 5 años de declaraciones de impuestos anuales. |
| `historical_update` | Los últimos 12 meses de declaraciones de impuestos mensuales. |


En la carga útil del webhook incluimos el tipo de declaraciones de impuestos, el número total de declaraciones de impuestos encontradas, así como el primer y último año de las declaraciones de impuestos recuperadas.

Ejemplo Histórico de Declaración de Impuestos (Anual)

```json Ejemplo Histórico de Declaración de Impuestos (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", // ya sea yearly o monthly
    "total_tax_returns": 2, // Número total de declaraciones de impuestos encontradas
    "first_tax_return_year": 2017, // Primera declaración de impuestos presentada
    "last_tax_return_year": 2018 // Última declaración de impuestos presentada
  }
}
```

Ejemplo Histórico de Declaración de Impuestos (Mensual)

```json Ejemplo Histórico de Declaración de Impuestos (Mensual)
{
  "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", // ya sea yearly o monthly
    "total_tax_returns": 7, // Número total de declaraciones de impuestos encontradas
    "first_tax_return_year": 2017, // Primera declaración de impuestos presentada
    "last_tax_return_year": 2018 // Última declaración de impuestos presentada
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `ejercicio__range` | El rango de fechas para el que deseas obtener declaraciones de impuestos. Este debe ser el `first_tax_return_year` y `last_tax_return_year` que recibiste en la notificación del webhook. | `2017,2020` |


### Nuevas declaraciones de impuestos disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará de manera asincrónica datos sobre cualquier nueva declaración de impuestos que haya aparecido en el sistema del SAT para un enlace dado desde la última actualización.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_tax_returns_available` | Un conteo de nuevas declaraciones de impuestos desde la última actualización. |


Puedes recibir una notificación de `new_tax_returns_available` cada vez que haya nuevas declaraciones de impuestos disponibles para un enlace fiscal recurrente. Puedes recibir más de un evento de webhook para un enlace a la vez, dependiendo del tipo de declaraciones de impuestos encontradas. Por ejemplo, podrías recibir un evento de webhook para declaraciones de impuestos `mensuales` y otro separado para declaraciones de impuestos `anuales`.

Definimos nuevas declaraciones de impuestos como todas las nuevas declaraciones de impuestos encontradas en la institución para este enlace desde nuestra última actualización. Podrían ser nuevas declaraciones de impuestos del último año o también declaraciones de impuestos que fueron agregadas por la institución para años o meses anteriores.

En la carga útil del webhook incluimos el tipo de declaraciones de impuestos (`mensuales` o `anuales`) así como el número de declaraciones de impuestos encontradas desde la última actualización.

Ejemplo de Nuevas Declaraciones de Impuestos Disponibles (Anuales)

```json Ejemplo de Nuevas Declaraciones de Impuestos Disponibles (Anuales)
{
  "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", // puede ser anual o mensual
    "new_tax_returns": 1 // Número total de nuevas declaraciones de impuestos encontradas
  }
}
```

Ejemplo de Nuevas Declaraciones de Impuestos Disponibles (Mensuales)

```json Ejemplo de Nuevas Declaraciones de Impuestos Disponibles (Mensuales)
{
  "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", // puede ser anual o mensual
    "new_tax_returns": 1 // Número total de nuevas declaraciones de impuestos encontradas
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Declaraciones de Impuestos
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | El rango de fechas para el cual deseas recibir declaraciones de impuestos. Recomendamos que `date1` sea la fecha en que recibiste una notificación previamente y `date2` sea la fecha en que recibes la notificación actual (ambas en formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


## tax-status

### Actualización histórica

Tan pronto como se crea tu enlace fiscal, recuperamos de manera asincrónica el documento de Situación Fiscal (*Constancia de Situación Fiscal*) y te enviaremos el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `historical_update` | La última Situación Fiscal para el usuario. |


En la carga útil del webhook recibirás el número total de documentos de Situación Fiscal para el usuario junto con la última fecha en que se actualizó la Situación Fiscal.


```json Ejemplo de Actualización Histórica de Situación 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 situaciones fiscales
    "last_status_change_date": "1995-08-01" // Año en que se cambió por última vez la situación fiscal
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Situación 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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


## transacciones

### Actualización histórica

Tan pronto como se crea tu enlace bancario, cargamos asincrónicamente las transacciones disponibles para el enlace y te enviaremos el siguiente webhook:

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | El número total de transacciones para el enlace del último año. |


En la carga útil del webhook incluimos el número de transacciones encontradas para el enlace (incluyendo el número de transacciones de entrada y salida) así como el rango de fechas al que se aplica la información.


```json Ejemplo de Actualización Histórica de Transacciones
{
  "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 transacciones encontradas
    "total_inflow_transactions": 10, // Número total de transacciones de entrada
    "total_outflow_transactions": 9, // Número total de transacciones de salida
    "first_transaction_date": "2023-01-03", // Fecha de la primera transacción
    "last_transaction_date": "2024-01-03" // Fecha de la última transacción
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Transacciones
curl --request GET 'https://api.belvo.com/api/transactions/?link=link_id' \
-u BELVO_SECRET_ID:BELVO_SECRET_PASSWORD
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


Puedes agregar más filtros para reducir los resultados, por ejemplo:


```shell Ejemplo de Solicitud de Transacciones con 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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `type` | El tipo de transacción. Puede ser `INFLOW` o `OUTFLOW`. | `INFLOW` |
| `value_date__range` | El rango de fechas para el que deseas obtener transacciones. Este debe ser el `first_transaction_date` y `last_transaction_date` que recibiste en la notificación del webhook. | `2023-01-03,2024-01-03` |


### Nuevas transacciones disponibles

De acuerdo con la frecuencia de actualización elegida, Belvo recuperará de manera asincrónica datos sobre cualquier nueva transacción que haya aparecido para el enlace dado desde la última actualización.

Definimos nuevas transacciones como transacciones encontradas en la institución para un enlace dado desde la última actualización. Por ejemplo, estas podrían ser nuevas transacciones de las últimas 24 horas o nuevas transacciones de hace unos días que solo fueron agregadas recientemente por la institución.

| Código de Webhook | Descripción |
|  --- | --- |
| `new_transactions_available` | El número de nuevas transacciones encontradas en la institución desde la última actualización. |


En el payload del webhook incluimos el número de nuevas transacciones encontradas para el enlace.


```json Ejemplo de Nuevas Transacciones Disponibles
{
  "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 nuevas transacciones encontradas desde el último evento
  }
}
```

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:


```shell Ejemplo de Solicitud de Transacciones
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | El rango de fechas para el cual deseas recibir transacciones. Recomendamos que `date1` sea la fecha en que recibiste previamente una notificación y `date2` sea la fecha en que recibes la notificación actual (ambas en formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


### Transacción actualizada

Este webhook está disponible para **ambos** enlaces únicos y recurrentes

Cada vez que Belvo identifica que una transacción ha sido actualizada en la institución (por ejemplo, un cambio en el campo de descripción o la fecha de valor), enviará el siguiente webhook:

| Código del Webhook | Descripción |
|  --- | --- |
| `transactions_updated` | El número de transacciones actualizadas junto con la lista de IDs de transacciones. |


En la carga útil del webhook incluimos el número de transacciones que fueron actualizadas junto con una lista de IDs de transacciones de Belvo.


```json Ejemplo de Transacción Actualizada
{
  "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 transacciones actualizadas.
    "updated_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // El ID de la transacción actualizada.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}
```

Una vez que recibas la notificación, puedes obtener la lista completa de transacciones para ese enlace usando la siguiente llamada:


```shell Ejemplo de Solicitud de Transacciones
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  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | La lista de `id`s de transacciones que recibiste en el `data.updated_transactions` de la notificación del webhook. | `7d0afe4c-373d-490c-90e4-06xx4cdd4a17,53759bc-ca02-46f0-b1d5-31xxcd54db41,64ecc7df-f322-4934-82f5-3b3ae675ef4a` |


#### Cambios que activan un `transactions_updated` webhook

Belvo monitorea los siguientes campos para todas las transacciones y cuando detecta un cambio entre la última vez que recuperó datos y ahora, te enviará un `transactions_updated` webhook:

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


### Transacción eliminada

Este webhook está disponible para **ambos** enlaces únicos y recurrentes

Belvo monitorea y limpia regularmente los datos transaccionales en su base de datos para mejorar la consistencia de los datos que recibes. Cuando se identifica que una transacción está duplicada (lo cual puede ocurrir, por ejemplo, debido a llamadas POST realizadas en rápida sucesión a la API para el *mismo* enlace), se elimina de la base de datos. En este caso, recibirás un webhook `transactions_deleted` con una lista de las transacciones que han sido eliminadas.


```json Ejemplo de Transacción Eliminada
{
  "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 transacciones eliminadas.
    "deleted_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // El ID de la transacción eliminada.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}
```

## Webhook de Estado de la Institución (Externo)

### Configurar el webhook

Para suscribirse al webhook de Estado de la Institución:

1. Ve a la página de Estado de la Institución de Belvo.
2. Haz clic en **Subscribe to Updates**.
3. En la navegación superior, haz clic en el icono **<>**.
4. En la pestaña de webhooks, proporciona la información requerida y haz clic en **Subscribe**.
4.1 URL donde deseas recibir el webhook
4.2 Una dirección de correo electrónico para confirmar la URL del webhook.


1. En el diálogo, elige sobre qué instituciones deseas recibir actualizaciones y haz clic en **Save**.


¡Listo! Confirma Tu Dirección de Correo Electrónico
Ahora solo confirma tu dirección de correo electrónico y comenzarás a recibir eventos de estado del webhook para las instituciones que seleccionaste. Pero esperamos que eso no suceda a menudo 😉.

### Carga útil del webhook

En la carga útil del webhook que recibes de statuspage.io, los campos clave que debes analizar son:

| Campo  | Descripción |
|  --- | --- |
| `incident.name` | Indica la naturaleza del problema con la institución. |
| `incident.status` | El estado actual del incidente en el momento del webhook. Puede ser:  investigating  identified  monitoring  resolved |
| `components.status` | La gravedad de la interrupción de la institución. Puede ser:  operational (todo está funcionando)  partial_outage (ciertas funcionalidades no están disponibles)  major_outage (la institución está completamente no disponible) |
| `components.name` | El nombre de la institución que está afectada. |


La carga útil que recibes es bastante grande, como puedes ver en el ejemplo de código a continuación. Sin embargo, si analizas los campos mencionados anteriormente, tendrás toda la información relevante que necesitas sobre el incidente.


```json Ejemplo de Webhook de Estado de la Institución
{
   "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"
         }
      ]
   }
}
```