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.

initial_inflow_update: when the last 30 days of inflow invoices are available
initial_outflow_update: when the last 30 days of outflow invoices are available

{
   "webhook_id":"ccc9c589bfcb44bc99ce749229ccf142",
   "webhook_type":"INVOICES",
   "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",
   "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"
   }
}

Historical updates

As soon as your fiscal recurrent link is created, we asynchronously load the last five years of invoice history for SAT and the last one year for DIAN. You will receive up to 10 notifications via a webhook whenever the history of invoices is available for you to access.

Webhook type	Institution	# of webhooks
`historical_inflow_update`	DIAN	1
`historical_outflow_update`	DIAN	1
`historical_inflow_update`	SAT	5
`historical_outflow_update`	SAT	5

📘
SAT historical notifcations
In order to improve performance, each webhook that we send will contain one year of data. As we load up to five years of data, we will send one webhook for each year that we are able to retrieve historical data for.

{
   "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
   "webhook_type": "INVOICES",
   "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": "2020-07-28" // Last inflow invoice found
   }
}

{
   "webhook_id": "1ac2917cb25f4e38af9260c0782d3408",
   "webhook_type": "INVOICES",
   "webhook_code": "historical_outflow_update",
   "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
   "data":{
      "total_invoices": 1000,
      "first_invoice_date": "2015-07-31",
      "last_invoice_date": "2019-10-30"
   }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/invoices/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{id} is the link_id your receive in the webhook notification.

New invoices available

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.

Once you receive the notification, you can query the Invoices endpoint to pull the details of these new invoices. For example, if you receive the following webhook:

{
   "webhook_id":"28364bef400f4374a80872b61ba204289",
   "webhook_type":"INVOICES",
   "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":[
         "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"
      ]
   }

You can request more information about the invoices with one of the following queries to the Invoices endpoint using the created_at filter:

# all new invoices
curl --request GET 'https://api.belvo.com/api/invoices/?link={id}3&created_at__range=date1,date2' \
-u [Secret Key ID]:[Secret Key PASSWORD]

# all new INFLOW invoices
curl --request GET 'https://api.belvo.com/api/invoices/?link={id}&created_at__range=date1,date2&type=INFLOW' \
-u [Secret Key ID]:[Secret Key PASSWORD]

# all new OUTFLOW invoices
curl --request GET 'https://api.belvo.com/api/invoices/?link={id}&created_at__range=date1,date2&type=OUTFLOW' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{id} is the link_id you received in the notification.
{date1} is the date when you previously received a notification, in YYYY-MM-DD format.
{date2} is the date you received the latest notification, in YYYY-MM-DD format.

Cancelled invoices

You can receive notifications via a webhook whenever existing invoices are canceled for a fiscal recurrent link.

📘
We define canceled invoices as all existing invoices with a new "canceled" status in the institution for this link.

Once you receive the invoices_cancelled notification, you can get specifics about the invoices by using the Details endpoint. For example, if you receive the following webhook:

{
   "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
   "webhook_type": "INVOICES",
   "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"
      ]
   }
}

You can request more information about the canceled invoiced with a call to the Invoices endpoint:

# cancelled invoice
curl --request GET 'https://api.belvo.com/api/invoices/{invoice_id}/' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{invoice_id} is the ID of one of the cancelled invoices you receive in your notification.

Initial updates

Historical updates

📘SAT historical notifcations

New invoices available

📘

Cancelled invoices

📘

📘
SAT historical notifcations