Tax returns (Webhooks)
Reference information for our Tax returns webhook events.
Historical update
As soon as your fiscal link is created, we asynchronously load the last five years of yearly tax returns as well as the 12 months of monthly tax returns. You will receive a historical_update
notification for each type of tax return (yearly and monthly) whenever the tax return history is available for you to access.
Webhook Code | Description |
---|---|
historical_update | The last 5 years of yearly tax returns. |
historical_update | The last 12 months of monthly tax returns. |
In the webhook payload we include the type of tax returns, total number of tax returns found, as well as the first and last year of the retrieved tax returns.
{
"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 tax returns found
"first_tax_return_year": 2017, // First filed tax return
"last_tax_return_year": 2018 // Last filed tax return
}
}
{
"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 tax returns found
"first_tax_return_year": 2017, // First filed tax return
"last_tax_return_year": 2018 // Last filed tax return
}
}
Once you receive the notification, you can get further details by making the following request:
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-returns/?link=link_id&ejercicio__range=first_tax_return_year,last_tax_return_year'
Query Parameter | Description | Example |
---|---|---|
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
ejercicio__range | The date range that you want to get tax returns for. This should be the first_tax_return_year and last_tax_return_year you received in the webhook notification. | 2017,2020 |
For details about the response body, make sure to check out our List Tax Returns API reference documentation.
New tax returns available
According to your chosen refresh rate, Belvo will asynchronously retrieve data about any new tax returns that have appeared in the SAT system for a given link since the last update.
Webhook Code | Description |
---|---|
new_tax_returns_available | A count of new tax returns since the last update. |
You can receive a new_tax_returns_available
notification whenever new tax returns are available for a fiscal recurrent link. You can receive more than one webhook event for a link at a time, depending on the type of tax returns found. For example, you might receive a webhook event for monthly
tax returns and a separate one for yearly
tax returns.
We define new tax returns as all new tax returns found in the institution for this link since our last update. It could be new tax returns from the last year or also tax returns that were added by the institution for previous years or months.
In the webhook payload we include the the type of tax returns (monthly
or yearly
) as well as the number of tax returns found since the last refresh.
{
"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", // can be either yearly or monthly
"new_tax_returns": 1 // Total number of new tax returns found
}
}
{
"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", // can be either yearly or monthly
"new_tax_returns": 1 // Total number of new tax returns found
}
}
Once you receive the notification, you can get further details by making the following request:
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-returns/?link=link_id&created_at__range=date1,date2'
Query Parameter | Description | Example |
---|---|---|
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
created_at__range | The date range you want to receive tax returns for. We recommend that date1 is the date when you previously received a notification and date2 is the date when you receive the current notification (both in YYYY-MM-DD format). | 2024-05-01,2024-06-01 |
For details about the response body, make sure to check out our List Tax Returns API reference documentation.
Updated about 2 months ago