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

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.


```mermaid
sequenceDiagram
    participant App as Application
    participant Belvo as Belvo
    participant Institution as Fiscal Institution

    App->>Belvo: POST /links/
    Note over App,Belvo: fetch_resources=[INVOICES, TAX_RETURNS ...]
    Belvo->>Institution: Conectar e confirmar as credenciais fornecidas
    Belvo-->>App: 201 - Link Criado + Link ID
    
    Belvo->>Institution: A Belvo recupera informações históricas para o Link ID

    Note over App,Institution: Para cada recurso listado em fetch_resources, você irá<br/>receber um webhook historical_update.

    Belvo->>App: WEBHOOK: historical_update (INVOICES)
    App->>Belvo: GET /invoices/?link={id}
    Belvo-->>App: 200 + Detalhes da Fatura

    Note over App,Institution: Se estiver usando links recorrentes, na frequência de atualização agendada<br/>você receberá um webhook new_{resource}_available.

    Belvo->>App: WEBHOOK: new_tax_returns_available
    App->>Belvo: GET /tax-returns/?link={link.id}
    Belvo-->>App: 200 + Detalhes da Declaração de Imposto
```

## Criar um link

O que é um link?
Um link é o termo da Belvo para uma conexão entre seu usuário (RFC) e a instituição fiscal (SAT). Sempre que você quiser extrair informações de um novo usuário, precisará criar um link.

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

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

Produção

```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 | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `institution` | string | sim | A instituição onde você deseja criar o link. Você pode escolher entre:- `tatooine_mx_fiscal` para Sandbox
- `sat_mx_fiscal` para Produção

 | `tatooine_mx_fiscal` |
| `username` | string | sim | O username do indivíduo ou empresa. Se você estiver testando em nosso ambiente Sandbox, pode usar as seguintes credenciais para simular dados:- **indivíduos**:`PFIS010101000`
- **empresas**:`PMO010101000`

 | `PFIS010101000` |
| `password` | string | sim | A senha do indivíduo ou empresa. Se você estiver testando em nosso ambiente Sandbox, pode usar as seguintes credenciais para simular dados:- **indivíduos**: `individual`
- **empresas**: `business`

 | `individual` |
| `access_mode` | string | sim | O tipo de link a ser criado (`single` ou `recurrent`). Para dados fiscais, recomendamos usar links `recurrent` pois você receberá atualizações sobre quaisquer novas faturas ou | `recurrent` |
| `credentials_storage` | string | não | O parâmetro `credentials_storage` permite que você controle por quanto tempo a Belvo armazena as credenciais de login criptografadas. Para mais informações, confira a seção credentials_storage do nosso artigo sobre controles de retenção de dados. | `store` |
| `stale_in` | string | não | O parâmetro `stale_in` permite que você controle por quanto tempo a Belvo armazena dados derivados do usuário. Para mais informações, confira a seção stale_in do nosso artigo sobre controles de retenção de dados. | `300d` |
| `external_id` | string | altamente recomendado | Sua referência interna para este usuário. Isso é extremamente útil, pois você pode os dados que a Belvo recupera para este usuário em seu sistema. | `COHORT_32_User_6790023X5` |
| `fetch_resources` | array | sim | Os recursos que você deseja que a Belvo recupere. Para instituições fiscais, 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"]` |


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


```json Example Link Response
{
  "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"
  ]
}
```

**Feito**! A Belvo agora se conectará à instituição e carregará os dados para os recursos que você solicitou em `fetch_resources` de forma assíncrona. Enviaremos um webhook assim que tivermos recuperado os dados para o link fornecido, e você poderá então extraí-los com uma solicitação **GET**

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

| Recurso | Número de Webhooks | Código do 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` |


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

| Webhook Code | Descrição |
|  --- | --- |
| historical_update | Os últimos três anos de demonstrações financeiras. |


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


```json Exemplo de Atualização Histórica de Demonstrações Financeiras
{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 3
  }
}
```

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


```shell Solicitação Get de Demonstrações Financeiras
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/financial-statements/?link=link_id'
```

| Query Parameter  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |


### Faturas

Devido ao número de faturas que um indivíduo ou empresa pode ter, e para otimizar o processo de extração, você receberá vários tipos diferentes de webhooks de Fatura após criar o link.

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

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


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

Exemplo de Atualização Inicial de Entrada de Faturas

```json Exemplo de Atualização Inicial de Entrada de Faturas
{
  "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"
  }
}
```

Exemplo de Atualização Inicial de Saída de Faturas

```json Exemplo de Atualização Inicial de Saída de Faturas
{
  "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"
  }
}
```

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


```curl Solicitação de Obtenção de Faturas
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'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `type` | O tipo de fatura. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `initial_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `initial_outflow_update`, isso deve ser definido como `OUTFLOW`. | `INFLOW` |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | O intervalo de datas para o qual você deseja obter faturas. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook. | `2017-07-31,2018-07-31` |


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

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_inflow_update` | O último 1 ano de notas fiscais de ENTRADA (recebidas). |
| `historical_outflow_update` | O último 1 ano de notas fiscais de SAÍDA (enviadas). |


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

Exemplo de Atualização Histórica de Entrada de Notas Fiscais

```json Exemplo de Atualização Histórica de Entrada de Notas Fiscais
{
  "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
  }
}
```

Exemplo de Atualização Histórica de Saída de Notas Fiscais

```json Exemplo de Atualização Histórica de Saída de Notas Fiscais
{
  "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"
  }
}
```

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


```curl Solicitação de Obtenção de Notas Fiscais
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'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `type` | O tipo de nota fiscal. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `historical_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `historical_outflow_update`, isso deve ser definido como `OUTFLOW`. | `INFLOW` |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `invoice_date__range` | O intervalo de datas para o qual você deseja obter notas fiscais. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook. | `2017-07-31,2018-07-31` |


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

| Código do Webhook | Descrição |
|  --- | --- |
| `historical_update` | O último ano de Retenções de Impostos. |


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


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

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


```shell Solicitação de Obtenção de Retenções de Impostos
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-retentions/?link=link_id'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


### Declarações de Imposto

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.

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


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.

Atualização Histórica de Declarações de Imposto Anuais

```json Atualização Histórica de Declarações de Imposto Anuais
{
  "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
  }
}
```

Atualização Histórica de Declarações de Imposto Mensais

```json Atualização Histórica de Declarações de Imposto Mensais
{
  "webhook_id": "80fa38b7cad34950b210626abd866549",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // either yearly or monthly
    "total_tax_returns": 7, // Total number of monthly tax returns found
    "first_tax_return_year": 2017, // First filed monthly tax return
    "last_tax_return_year": 2017 // Last filed monthly tax return
  }
}
```

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


```shell Solicitação Get de Declarações de Imposto
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  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `ejercicio__range` | O intervalo de datas para o qual você deseja obter declarações de imposto. Este deve ser o `first_tax_return_year` e `last_tax_return_year` que você recebeu na notificação do webhook. | `2017,2020` |


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

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


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


```json Atualização Histórica do Status Fiscal
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_STATUS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_status": 1, // Número de 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:


```shell Solicitação de Obtenção de Status Fiscal
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-status/?link=link_id'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


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

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


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


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

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


```shell Solicitação de Obtenção do Status de Conformidade Fiscal
curl --request GET \
-u SECRET_ID:SECRET_PASSWORD \
'https://api.belvo.com/api/tax-compliance-status/?link=link_id'
```

| Parâmetro de Consulta  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |


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

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


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

| Código do Webhook | Descrição |
|  --- | --- |
| `new_invoices_available` | Uma lista de novas faturas que foram recuperadas desde a última atualização. |


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

Definimos novas faturas como todas as novas faturas encontradas na instituição para este link desde nossa última atualização. Por exemplo, se você tiver uma taxa de atualização diária, podem ser as novas faturas das últimas 24 horas ou faturas adicionadas pela instituição nas últimas 24 horas para dias anteriores.

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


```json Atualização Recorrente de Novas 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:


```shell Solicitação Get de Faturas
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  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | A lista de `id`s de faturas que você recebeu no `data.new_invoices` da notificação do webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


#### Faturas Canceladas

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

| Código do Webhook | Descrição |
|  --- | --- |
| `invoices_cancelled` | Uma lista de faturas canceladas que foram recuperadas desde a última atualização. |


Definimos faturas canceladas como todas as faturas existentes com um novo status "cancelado" na instituição para este link

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


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

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


```shell Invoices Get Request
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  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `id__in` | A lista de `id`s de faturas que você recebeu no `data.cancelled_invoices` da notificação do webhook. | `24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509` |


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

| Código do Webhook | Descrição |
|  --- | --- |
| `new_tax_returns_available` | Uma contagem de novas declarações de imposto desde a última atualização. |


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

Definimos novas declarações de imposto como todas as novas declarações de imposto encontradas na instituição para este link desde nossa última atualização. Podem ser novas declarações de imposto do último ano ou também declarações de imposto que foram adicionadas pela instituição para anos ou meses anteriores.

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

Atualização de Novas Declarações de Imposto Anuais

```json Atualização de Novas Declarações de Imposto Anuais
{
  "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
  }
}
```

Atualização de Novas Declarações de Imposto Mensais

```json Atualização de Novas Declarações de Imposto Mensais
{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // pode ser 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:


```shell Solicitação de Obtenção de Declarações de Imposto
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  | Descrição | Exemplo |
|  --- | --- | --- |
| `link` | O `link_id` que você recebeu na notificação do webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
| `created_at__range` | O intervalo de datas para o qual você deseja receber declarações de imposto. Recomendamos que `date1` seja a data em que você recebeu uma notificação anteriormente e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`). | `2024-05-01,2024-06-01` |


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


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

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.