# Extraer Información Fiscal en México (API)

En esta guía, te guiamos a través de todo lo que necesitas para extraer datos fiscales sobre tus usuarios utilizando nuestra API. Esto incluye:

- Una visión general del flujo de datos
- Crear un enlace utilizando nuestra API
- Obtener información fiscal:
  - Actualizaciones históricas (todos los enlaces)
  - Actualizaciones recurrentes (solo enlaces recurrentes)


## Requisitos previos

Antes de proceder con tu integración, asegúrate de haber revisado nuestra guía de inicio. En la guía de inicio, crearás una cuenta de Belvo, generarás algunas claves de API de sandbox y configurarás una URL de webhook. Para propósitos de prueba y desarrollo de tu integración, recomendamos encarecidamente usar el entorno de Sandbox siempre que sea posible.

## Flujo general de datos

Belvo utiliza *flujos de trabajo asincrónicos* para mejorar tu flujo de datos (consulta el diagrama a continuación).

Cada vez que creas un link, Belvo extrae automáticamente todos los datos fiscales para ti en segundo plano, y una vez que tenemos todos los datos, te notificamos a través de un webhook que los datos están listos para ser recuperados.


```mermaid
sequenceDiagram
    participant App as Aplicación
    participant Belvo as Belvo
    participant Institution as Institución Fiscal

    App->>Belvo: POST /links/
    Note over App,Belvo: fetch_resources=[INVOICES, TAX_RETURNS ...]
    Belvo->>Institution: Conectar y confirmar las credenciales proporcionadas
    Belvo-->>App: 201 - Link Creado + ID del Link
    
    Belvo->>Institution: Belvo recupera información histórica para el ID del Link

    Note over App,Institution: Para cada recurso listado en fetch_resources, recibirás<br/>un webhook de historical_update.

    Belvo->>App: WEBHOOK: historical_update (INVOICES)
    App->>Belvo: GET /invoices/?link={id}
    Belvo-->>App: 200 + Detalles de la Factura

    Note over App,Institution: Si usas links recurrentes, en la frecuencia de actualización programada<br/>recibirás un webhook de new_{resource}_available.

    Belvo->>App: WEBHOOK: new_tax_returns_available
    App->>Belvo: GET /tax-returns/?link={link.id}
    Belvo-->>App: 200 + Detalles de la Declaración de Impuestos
```

## Crear un enlace

¿Qué es un enlace?
Un enlace es el término de Belvo para una conexión entre tu usuario (RFC) y la institución fiscal (SAT). Cada vez que quieras extraer información de un nuevo usuario, necesitarás crear un enlace.

Para crear un enlace, solo necesitas hacer la siguiente solicitud **POST Registrar un nuevo enlace**:

Sandbox

```curl Sandbox Request URL
curl --location 'https://sandbox.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \
--data '{see_example_below}'
```


```json Sandbox Request Body
{
  "institution": "tatooine_mx_fiscal",
  "username": "PFIS010101000",
  "password": "individual",
  "access_mode": "single",
  "credentials_storage": "store",
  "stale_in": "300d",
  "external_id": "HJLSI-897809",
  "fetch_resources": [
    "FINANCIAL_STATEMENTS",
    "INVOICES",
    "TAX_RETENTIONS",
    "TAX_RETURNS",
    "TAX_STATUS",
    "TAX_COMPLIANCE_STATUS"
  ]
}
```

Production

```curl Production Request URL
curl --location 'https://api.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \
--data '{see_example_below}'
```


```json Production Request Body
{
  "institution": "sat_mx_fiscal",
  "username": "username",
  "password": "password",
  "access_mode": "single",
  "credentials_storage": "store",
  "stale_in": "300d",
  "external_id": "HJLSI-897809",
  "fetch_resources": [
    "FINANCIAL_STATEMENTS",
    "INVOICES",
    "TAX_RETENTIONS",
    "TAX_RETURNS",
    "TAX_STATUS",
    "TAX_COMPLIANCE_STATUS"
  ]
}
```

| Parámetro  | Tipo | Requerido | Descripción | Ejemplo |
|  --- | --- | --- | --- | --- |
| `institution` | string | true | La institución donde deseas crear el enlace. Puedes elegir entre:- `tatooine_mx_fiscal` para Sandbox
- `sat_mx_fiscal` para Producción

 | `tatooine_mx_fiscal` |
| `username` | string | true | El nombre de usuario del individuo o negocio. Si estás probando en nuestro entorno Sandbox, puedes usar las siguientes credenciales para simular datos:- **individuals**:`PFIS010101000`
- **businesses**:`PMO010101000`

 | `PFIS010101000` |
| `password` | string | true | La contraseña del individuo o negocio. Si estás probando en nuestro entorno Sandbox, puedes usar las siguientes credenciales para simular datos:- **individuals**: `individual`
- **businesses**: `business`

 | `individual` |
| `access_mode` | string | true | El tipo de enlace a crear (`single` o `recurrent`). Para datos fiscales, recomendamos usar enlaces `recurrent` ya que recibirás actualizaciones sobre cualquier nueva factura o | `recurrent` |
| `credentials_storage` | string | false | El parámetro `credentials_storage` te permite controlar por cuánto tiempo Belvo almacena las credenciales de inicio de sesión encriptadas. Para más información, consulta la sección credentials_storage de nuestro artículo sobre controles de retención de datos. | `store` |
| `stale_in` | string | false | El parámetro `stale_in` te permite controlar por cuánto tiempo Belvo almacena los datos derivados del usuario. Para más información, consulta la sección stale_in de nuestro artículo sobre controles de retención de datos. | `300d` |
| `external_id` | string | altamente recomendado | Tu referencia interna para este usuario. Esto es extremadamente útil ya que puedes los datos que Belvo recupera para este usuario en tu sistema. | `COHORT_32_User_6790023X5` |
| `fetch_resources` | array | true | Los recursos que deseas que Belvo recupere. Para instituciones fiscales, recomendamos: `["FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETENTIONS", "TAX_RETURNS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS"]` | `["FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETENTIONS", "TAX_RETURNS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS"]` |


Una vez que crees un enlace, necesitarás guardar el `id` del enlace que recibas en la respuesta:


```json Example Link Response
{
  "id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // <-- Guarda este ID.
  "institution": "tatooine_mx_fiscal",
  "access_mode": "single",
  "status": "valid",
  "refresh_rate": null,
  "created_by": "6e9be884-4781-4143-b673-aca02475ee8c",
  "last_accessed_at": "2024-06-26T16:25:54.344113Z",
  "external_id": "HJLSI-897809",
  "created_at": "2024-06-26T16:25:54.334413Z",
  "institution_user_id": "BidIxnZkKvQx0_F0oSYVx6Jnsh4Zmoat2ot2iOoG018=",
  "credentials_storage": "store",
  "stale_in": null,
  "fetch_resources": [
    "FINANCIAL_STATEMENTS",
    "INVOICES",
    "TAX_RETENTIONS",
    "TAX_RETURNS",
    "TAX_STATUS",
    "TAX_COMPLIANCE_STATUS"
  ]
}
```

**¡Hecho**! Belvo ahora se conectará a la institución y cargará asincrónicamente los datos para los recursos que solicitaste en `fetch_resources`. Te enviaremos un webhook una vez que hayamos recuperado los datos para el enlace dado, y luego podrás extraerlo con una solicitud **GET**

## Esperar webhooks para obtener datos fiscales históricos

Tan pronto como crees tu enlace fiscal, Below recuperará de manera asincrónica los datos históricos para cada recurso que agregaste en el array `fetch_resources`. Tan pronto como Belvo recupere los datos, recibirás un webhook indicando que los datos están listos para ser recuperados:

| Recurso | Número de Webhooks | Código del Webhook |
|  --- | --- | --- |
| `FINANCIAL_STATEMENTS` | 1 | `historical_update` |
| `INVOICES` | 4-8 | `initial_inflow_update`, `initial_outflow_update`, `historical_inflow_update`, `historical_outflow_update` |
| `TAX_RETENTIONS` | 1 | `historical_update` |
| `TAX_RETURNS` | 2 | `historical_update` |
| `TAX_STATUS` | 1 | `historical_update` |
| `TAX_COMPLIANCE_STATUS` | 1 | `historical_update` |


### Estados Financieros

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": {
    "new_financial_statements": 3
  }
}
```

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


```shell Solicitud para Obtener Estados Financieros
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/financial-statements/?link=link_id'
```

| Parámetro de Consulta  | Descripción | Ejemplo |
|  --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


### Facturas

Debido a la cantidad de facturas que un individuo o negocio puede tener, y para optimizar el proceso de extracción, recibirás varios tipos diferentes de webhooks de Factura después de crear el enlace.

#### Últimos 30 días de datos

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 Actualización Inicial de Entrada de Facturas

```json Ejemplo de Actualización Inicial de Entrada de Facturas
{
  "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"
  }
}
```

Ejemplo de Actualización Inicial de Salida de Facturas

```json Ejemplo de Actualización Inicial de Salida de Facturas
{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf578",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "initial_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "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:


```curl Solicitud de Obtención de Facturas
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \

# Solicitar Facturas de Entrada
'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

# Solicitar Facturas de Salida
'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 `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` |


#### Últimos 3 años de datos

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 desde el SAT. Después de los primeros 30 días, para cada uno de los últimos tres años, recibirás hasta dos notificaciones de webhook: una para facturas de entrada (`historical_inflow_update`) y otra para facturas de salida (`historical_outflow_update`). Esto significa que podrías recibir hasta 6 notificaciones adicionales de webhook para los datos históricos.

**Por cada año que 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 Actualización Histórica de Facturas de Entrada

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

Ejemplo de Actualización Histórica de Facturas de Salida

```json Ejemplo de Actualización Histórica de Facturas de Salida
{
  "webhook_id": "1ac2917cb25f4e38af9260c0782d3408",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "historical_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "data": {
    "total_invoices": 1000,
    "first_invoice_date": "2017-07-31",
    "last_invoice_date": "2018-07-31"
  }
}
```

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


```curl Solicitud de Obtención de Facturas
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \

# Solicitar Facturas de Entrada
'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

# Solicitar Facturas de Salida
'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 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` |


### Retenciones de Impuestos

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

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


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


```json Actualización Histórica de Retenciones de Impuestos
{
  "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 de impuestos
    "first_tax_retention_date": "2023-06-01", // La fecha de la primera retención de impuestos encontrada
    "last_tax_retention_date": "2023-08-20" // La fecha de la última retención de impuestos encontrada
  }
}
```

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


```shell Solicitud de Obtención de Retenciones de Impuestos
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-retentions/?link=link_id'
```

| 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

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.

Actualización Histórica de Declaraciones de Impuestos Anuales

```json Actualización Histórica de Declaraciones de Impuestos Anuales
{
  "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 anuales encontradas
    "first_tax_return_year": 2017, // Primera declaración de impuestos anual presentada
    "last_tax_return_year": 2018 // Última declaración de impuestos anual presentada
  }
}
```

Actualización Histórica de Declaraciones de Impuestos Mensuales

```json Actualización Histórica de Declaraciones de Impuestos Mensuales
{
  "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 mensuales encontradas
    "first_tax_return_year": 2017, // Primera declaración de impuestos mensual presentada
    "last_tax_return_year": 2017 // Última declaración de impuestos mensual presentada
  }
}
```

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


```shell Solicitud de Obtención de Declaraciones de Impuestos
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-returns/?link=link_id&ejercicio__range=first_tax_return_year,last_tax_return_year'
```

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


### Estado Fiscal

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

| Código de Webhook | Descripción |
|  --- | --- |
| `historical_update` | El último Estado Fiscal para el usuario. |


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


```json Actualización Histórica del Estado 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 documentos de estado fiscal
    "last_status_change_date": "1995-08-01" // Año en que se cambió por última vez el estado fiscal
  }
}
```

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


```shell Solicitud de Obtención de Estado Fiscal
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-status/?link=link_id'
```

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


### Estado de Cumplimiento Fiscal

Tan pronto como se crea tu enlace fiscal, recuperamos de manera asincrónica el documento de Estado de Cumplimiento Fiscal (*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 Fiscal actual para el usuario. |


En el payload del webhook recibirás el número total de documentos de Estado de Cumplimiento Fiscal.


```json Actualización Histórica del Estado de Cumplimiento 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 // 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 Solicitud para Obtener el Estado de Cumplimiento Fiscal
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-compliance-status/?link=link_id'
```

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


## Actualizaciones recurrentes

Si creaste un enlace recurrente (usando `access_mode: recurrent`), recibirás webhooks para recursos actualizados basados en la frecuencia de actualización que estableciste con Belvo (consulta el diagrama en la sección Flujo general de datos).

Los siguientes webhooks están disponibles para enlaces recurrentes:

| Recurso | Número de Webhooks | Código de Webhook |
|  --- | --- | --- |
| `INVOICES` | 2-4 | `new_invoices_available`, `invoices_cancelled` |
| `TAX_RETURNS` | 2 | `new_tax_returns_available` |


### Facturas

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

#### Nuevas Facturas

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` cada vez 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 Actualización Recurrente de Nuevas Facturas
{
  "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 Solicitud de Obtención de Facturas
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'
```

| 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 Actualización Recurrente 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 de las facturas canceladas haciendo la siguiente solicitud:


```shell Solicitud de Obtención de Facturas
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'
```

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


### Declaraciones de Impuestos

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 al mismo tiempo, 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.

Actualización de Nuevas Declaraciones Anuales

```json Actualización de Nuevas Declaraciones 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 yearly o monthly
    "new_tax_returns": 1 // Número total de nuevas declaraciones de impuestos encontradas
  }
}
```

Actualización de Nuevas Declaraciones Mensuales

```json Actualización de Nuevas Declaraciones 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 yearly o monthly
    "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 Solicitud de Obtención de Declaraciones de Impuestos
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-returns/?link=link_id&created_at__range=date1,date2'
```

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


## 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 aún 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
[
  {
    "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.