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 `id`s 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 `id`s 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.