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

Copiar

• Copiar para LLM

  Copiar página como Markdown para LLMs
• Ver como Markdown

  Abrir esta página como Markdown
• Abrir en ChatGPT

  Obtener información de ChatGPT
• Abrir en Claude

  Obtener información de Claude

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 para 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 el flujo de tus 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.

Crear un enlace

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

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}'

{
  "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"
  ]
}

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

{
  "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"
  ]
}

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:

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:

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

{
  "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:

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/financial-statements/?link=link_id'

Facturas

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

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.

{
  "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:

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'

Ú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 para 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:

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.

{
  "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:

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'

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:

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.

{
  "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:

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-retentions/?link=link_id'

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.

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.

{
  "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
  }
}

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

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'

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:

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.

{
  "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 el estado fiscal fue cambiado por última vez
  }
}

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

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-status/?link=link_id'

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:

En el payload del webhook recibirás el número total de documentos de 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:

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-compliance-status/?link=link_id'

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:

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.

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.

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 ids de 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 realizando la siguiente solicitud:

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'

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.

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

{
  "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:

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'

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.

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.

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.

{
  "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
  }
}

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

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-returns/?link=link_id&created_at__range=date1,date2'

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:

[
  {
    "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.