Invoices (Webhooks)
Reference information for our Incomes webhook events.
Initial updates
As soon as your fiscal recurrent link is created, we asynchronously load the last 30 days of invoice history. You will receive two notifications via a webhook whenever the last 30 days of invoices are available for you to access.
| Webhook Code | Description |
|---|---|
initial_inflow_update | The last 30 days of INFLOW (received) invoices. |
initial_outflow_update | The last 30 days of OUTFLOW (sent) invoices. |
We include the number of invoices found during this period for the invoice type, as well as the dates for the first and last invoice in the range.
{
"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"
}
}
{
"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"
}
}
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/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'
| Query Parameter | Description | Example |
|---|---|---|
type | The type of invoice. Can be either INFLOW or OUTFLOW. If you receive a initial_inflow_update webhook, this should be set to INFLOW. If you receive a initial_outflow_update webhook, this should be set to OUTFLOW. | INFLOW |
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
invoice_date__range | The date range that you want to get invoices for. This should be the first_invoice_date and last_invoice_date you received in the webhook notification. | 2017-07-31,2018-07-31 |
For details about the response body, make sure to check out our List Invoices API reference documentation or Invoices Data Dictionary.
Historical updates
As soon as your fiscal recurrent link is created, we asynchronously load the last three years of INFLOW and OUTFLOW invoice history for SAT. You will receive up to 6 notifications via a webhook whenever the history of invoices is available for you to access. For each year Belvo extracts data for, you will receive the following webhooks:
| Webhook Code | Description |
|---|---|
historical_inflow_update | The last 1 year of INFLOW (received) invoices. |
historical_outflow_update | The last 1 year of OUTFLOW (sent) invoices. |
In the webhook payload we include the number of invoices found during this period for the invoice type, as well as the dates for the first and last invoice in the range.
{
"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, // Total number of invoices found
"first_invoice_date": "2017-07-31", // First inflow invoice found
"last_invoice_date": "2018-07-31" // Last inflow invoice found
}
}
{
"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"
}
}
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/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'
| Query Parameter | Description | Example |
|---|---|---|
type | The type of invoice. Can be either INFLOW or OUTFLOW. If you receive a historical_inflow_update webhook, this should be set to INFLOW. If you receive a historical_outflow_update webhook, this should be set to OUTFLOW. | INFLOW |
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
invoice_date__range | The date range that you want to get invoices for. This should be the first_invoice_date and last_invoice_date you received in the webhook notification. | 2017-07-31,2018-07-31 |
For details about the response body, make sure to check out our List Invoices API reference documentation or Invoices Data Dictionary.
New invoices available
According to your chosen refresh rate, Belvo will asynchronously retrieve data about any new invoices that have appeared in the SAT system for a given link since the last update.
| Webhook Code | Description |
|---|---|
new_invoices_available | A list of new invoices that were retrieved since the last update. |
You can receive a new_invoices_available notification whenever new invoices 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 invoices found. For example, you might receive a webhook event for INFLOW invoices and a separate one for OUTFLOW invoices.
We define new invoices as all new invoices found in the institution for this link since our last update. For example, if you have a daily refresh rate, it could be the new invoices from the last 24 hours or invoices added by the institution in the past 24 hours for previous days.
In the webhook payload we include the number of invoices found since the last refresh, the type of invoices (INFLOW or OUTFLOW), as well as an array of invoice ids.
{
"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": [
// An array of invoice IDs
"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"
]
}
}
Once you receive the notification, you can get further details for the new invoices by making the following request:
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'
| Query Parameter | Description | Example |
|---|---|---|
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
id__in | The list of invoice ids you received in the data.new_invoices of the webhook notification. | 24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509 |
For details about the response body, make sure to check out our List Invoices API reference documentation or Invoices Data Dictionary.
Cancelled invoices
According to your chosen refresh rate, Belvo will asynchronously retrieve data about any cancelled invoices that have appeared in the SAT system for a given link since the last update.
| Webhook Code | Description |
|---|---|
invoices_cancelled | A list of cancelled invoices that were retrieved since the last update. |
We define canceled invoices as all existing invoices with a new "canceled" status in the institution for this link.
In the webhook payload we include the type of cancelled invoices (INFLOW or OUTFLOW) as well as an array of invoice ids.
{
"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": [
// An array of invoice IDs
"0a362860-c92f-4414-a731-a772e88ab54b",
"0a376126-c23r-2131-b745-a876d77cd76c"
]
}
}
Once you receive the notification, you can get further details for the cancelled invoices by making the following request:
curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'
| Query Parameter | Description | Example |
|---|---|---|
link | The link_id you received in the webhook notification. | 2f5d361d-dad6-45d4-a0bf-26d479766067 |
id__in | The list of invoice ids you received in the data.cancelled_invoices of the webhook notification. | 24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509 |
For details about the response body, make sure to check out our List Invoices API reference documentation or Invoices Data Dictionary.
Updated 15 days ago