Extrair Informações Fiscais no México (API)

Copiar

• Copiar para LLM

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

  Abrir esta página como Markdown
• Abrir no ChatGPT

  Obter insights do ChatGPT
• Abrir no Claude

  Obter insights do Claude

Neste guia, orientamos você em tudo o que precisa para extrair dados fiscais sobre seus usuários usando nossa API. Isso inclui:

• Uma visão geral do fluxo de dados
• Criar um link usando nossa API
• Obter informações fiscais:
  • Atualizações históricas (todos os links)
  • Atualizações recorrentes (apenas links recorrentes)

Pré-requisitos

Antes de prosseguir com sua integração, certifique-se de que você leu nosso guia de introdução. No guia de introdução, você criará uma conta Belvo, gerará algumas chaves de API sandbox e configurará uma URL de webhook. Para fins de teste e desenvolvimento de sua integração, recomendamos fortemente o uso do ambiente Sandbox sempre que possível.

Fluxo geral de dados

A Belvo utiliza fluxos de trabalho assíncronos para melhorar o fluxo de dados (veja o diagrama abaixo).

Sempre que você cria um link, a Belvo automaticamente extrai todos os dados fiscais para você em segundo plano, e assim que temos todos os dados, notificamos você via um webhook que os dados estão prontos para serem recuperados.

Criar um link

Para criar um link, você só precisa fazer a seguinte solicitação POST Register a new link:

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

Uma vez que você cria um link, você precisará salvar o id do link que você recebe na resposta:

{
  "id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // <-- Salve 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"
  ]
}

Aguarde os webhooks para obter dados fiscais históricos

Assim que você criar seu link fiscal, a Below irá recuperar assincronamente os dados históricos para cada recurso que você adicionou no array fetch_resources. Assim que a Belvo recuperar os dados, você receberá um webhook indicando que os dados estão prontos para serem recuperados:

Demonstrações Financeiras

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

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

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

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

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

Faturas

Últimos 30 dias de dados

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

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

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

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

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \

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

# Solicitar Faturas de Saída
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

Últimos 3 anos de dados

Assim que seu link fiscal recorrente for criado, carregamos de forma assíncrona os últimos três anos de histórico de notas fiscais de ENTRADA e SAÍDA do SAT. Após os primeiros 30 dias, para cada um dos últimos três anos, você receberá até duas notificações de webhook: uma para notas fiscais de entrada (historical_inflow_update) e uma para notas fiscais de saída (historical_outflow_update). Isso significa que você pode receber até 6 notificações de webhook adicionais para os dados históricos.

Para cada ano que a Belvo extrai dados, você receberá os seguintes webhooks:

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

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

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

curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \

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

# Solicitar Notas Fiscais de Saída
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

Retenções de Impostos

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

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

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

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

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

Declarações de Imposto

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

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

{
  "webhook_id": "80fa38b7cad34950b210626abd86bfe9",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // either yearly or monthly
    "total_tax_returns": 2, // Total number of yearly tax returns found
    "first_tax_return_year": 2017, // First filed yearly tax return
    "last_tax_return_year": 2018 // Last filed yearly tax return
  }
}

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

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'

Status Fiscal

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

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

{
  "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 status fiscal
    "last_status_change_date": "1995-08-01" // Ano em que o status fiscal foi alterado pela última vez
  }
}

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

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

Status de Conformidade Fiscal

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

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

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

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

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

Atualizações recorrentes

Se você criou um link recorrente (usando access_mode: recurrent), você receberá webhooks para recursos atualizados com base na taxa de atualização que você estabeleceu com a Belvo (veja o diagrama na seção Fluxo geral de dados).

Os seguintes webhooks estão disponíveis para links recorrentes:

Faturas

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

Novas Faturas

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

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

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

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

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

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'

Faturas Canceladas

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

No payload do webhook, incluímos o tipo de faturas canceladas (INFLOW ou OUTFLOW) bem como um array de ids de faturas.

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

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

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'

Declarações de Imposto

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

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

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

{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // pode ser yearly ou monthly
    "new_tax_returns": 1 // Número total de novas declarações de imposto encontradas
  }
}

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

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

Erros ao extrair Demonstrações Financeiras

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

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

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

As possíveis mensagens de erro são:

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

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