Invoices

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.

  • inital_inflow_update: when the last 30 days of inflow invoices are available
  • inital_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",
   "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. You will receive two notifications via a webhook whenever the history of invoices is available for you to access.

  • historical_inflow_update: when the last five years of inflow invoices are available
  • historical_outflow_update: when the last five years of outflow invoices are available
{
   "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
   "webhook_type": "INVOICES",
   "webhook_code": "historical_inflow_update",
   "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
   "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 details on the invoices by making the following request:

curl --request GET 'https://api.belvo.co/api/invoices/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
client.invoices.list({
  filters: {
    link: "{id}"
  }
})
client.Invoices.list(link="{id}")
client.transaction.list(params: {
  link: "{id}"
})

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

📘

We define new invoices as all new invoices found in the institution for this link since our last update. 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",
   "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:

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

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

# all new OUTFLOW invoices
curl --request GET 'https://api.belvo.co/api/invoices/?link={id}&collected_at__range=date1,date2&type=OUTFLOW' \
-u [Secret Key ID]:[Secret Key PASSWORD]
// all new invoices
client.invoices.list({
  filters: {
    link: "{id}",
    collected_at__range: "{date1},{date2}"
  }
})

// all new INFLOW invoices
client.invoices.list({
  filters: {
    link: "{id}",
    collected_at__range: "{date1},{date2}",
    type: "INFLOW"
  }
})

// all new OUTFLOW invoices
client.invoices.list({
  filters: {
    link: "{id}",
    collected_at__range: "{date1},{date2}",
    type: "OUTFLOW"
  }
})
# all new invoices
client.Invoices.list(link="{id}",collected_at__range="{date1},{date2}")

# all new INFLOW invoices
client.Invoices.list(link="{id}", collected_at__range="{date1},{date2}", type="INFLOW")

# all new OUTFLOW invoices
client.Invoices.list(link="{id}", collected_at__range="{date1},{date2}", type="OUTFLOW")
# all new invoices
client.invoices.list(params: {
  link: "{id}",
  collected_at__range: "{date1},{date2}"
})

# all new INFLOW invoices
client.invoices.list(params: {
  link: "{id}",
  collected_at__range: "{date1},{date2}",
  type: "INFLOW"
})

# all new OUTFLOW invoices
client.invoices.list(params: {
  link: "{id}",
  collected_at__range: "{date1},{date2}",
  type: "OUTFLOW"
})

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",
   "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.co/api/invoices/{invoice_id}/' \
-u [Secret Key ID]:[Secret Key PASSWORD]
client.invoices.detail("{invoice_id}")
client.Invoices.detail("{invoice_id}")
client.invoices.detail id: '{invoice_id}'

Where:

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

Did this page help you?