List and download invoices

1. List new incoming invoices

To get information of the new incoming invoices in Maventa, start by listing the new incoming invoice id’s and save them locally.

• SOAP:
  • invoice_list_ids To get a list of invoice id’s between selected timestamps. Method is called per company, so it is only possible to list invoices from one company at a time.
  • list_vendor_inbound_invoices To list all inbound invoices of companies. Method lists all inbound invoices of all the companies which are linked to certain vendor_api_key.

• REST:
  • Use GET /v1/invoices with params direction=RECEIVED, received_at_start, and received_at_end to get list of invoices to download.
    • You can see a lot of different information about the invoices e.g. original format (source_format) and all the assosiated attachments (files -array). Each file in the array has its own id, type and href.
    • Note that only files which are ATTACHMENT type are shown in files, therefore there is no invoice image. To download attachment marked as invoice image see the next chapter.

2. Download based on listed invoice id’s

After you have listed and saved the new incoming invoice id’s, download the invoice files and attachments into your system.

• SOAP: Use invoice_download to download the invoice xml and attachments.
• REST:
  • Use GET /v1/invoices/{id} to download the invoice xml file in the specified format, or to download the invoice image.
    To download invoice image you need to use param return_format:
    • ORIGINAL_IMAGE (returns an image only if original exists)
    • GENERATED_IMAGE (returns image we generate)
    • ORIGINAL_OR_GENERATED_IMAGE (returns original if one exists, and if not then we generate an image for you)

To get specific file of the invoice you can use GET /v1/invoices/{id}/files/{file_id}. You need invoice’s id and the file’s id, which were returned when invoices were listed.

Example usage:

1. Invoice’s original format is Peppol BIS3 and you download it as Peppol BIS3.
   - You only need the XML file as it has all original attachments embedded to it. In conversion we do not forcefully embed separate attachments.
2. Invoices’s original format is Teapps 3.0 and there is also invoice image and extra attachment.
   - You download the invoice as Finvoice 3.0 with GET /v1/invoices/{id} by giving return_format as FINVOICE30.
   - Then you can download the possible invoice image with same endpoint but return_format being one of the described above.
   - To get other attachments you can use GET /v1/invoices/{id}/files/{file_id} as described above. Or there is direct href for each file in files array in response of GET /v1/invoices.

Recommended routine and notes

• Incoming invoices should not be polled more often than once per hour, usually a couple of times per day is enough
  • Call methods starting with latest fetch timestamp and ending with current timestamp
  • If the API returns error or something unexpected, do not update timestamp but allow retry of listing at a later time
  • When the API returns a list of invoices, save invoice IDs locally with a status ‘pending download’ or such
  • Use the local ID list to download an invoice, marking it as successfully retrieved only after it has actually been retrieved (e.g. in case of errors, alert/retry download)
  • Timestamp on the server is GMT +2 and differences between client side and server side clocks might create intervals not covered when listing. Therefore, it is recommended that the timestamps have some buffer, for example 1 minute before and after to avoid any gaps in the time
  • Since the IDs of the invoices are listed locally, that list can be used to make sure the same invoice is not downloaded twice
• After listing the invoices, have a separate process to download the actual invoice XML and attachments, and update the status with ‘download completed’ only after completed download. This will help to ensure intermittent errors will not cause any invoices to not be downloaded.