We have extended the /invoices endpoint with a lot of exciting new functionality. It is now possible to book an invoice through /invoices. To make this easier we have introduced template functionality to help you generate a draft invoice and book it.

Templates in our API are not like your typical Office templates. Our templates do not have anything to do with making things look a certain way – instead we supply the data that is necessary to accomplish a task. That way you don’t have to spend a lot of time setting properties, you only have to set the properties you want changed from our templates and hopefully not even that in most cases.

With that said, let us jump right into how the templates are used, by showing you how to create a draft invoice and book it.

 

Create a draft invoice using templates

In this use case we will use the template found here: /customers/:customerNumber/templates/invoice

This template is based on one of your customers and will give you a draft invoice without any lines. The data supplied will contain the following:

customer, paymentTerms, layout, recipient, references, exchangeRate, currency, delivery, deliveryLocation, date, dueDate

1. Get the draft invoice (without any lines) by doing a GET operation on /customers/:customerNumber/templates/invoice

2. Step 1 gives you a draft invoice template ready to be used. You are able to change it if you want.

3. To save the draft invoice, all you need to do is POST it to /invoices/drafts

 

Add lines to a draft invoice using templates

In this use case we will use the template found here: /customers/:customerNumber/templates/invoiceline/:productNumber

This template is based on an existing customer and an existing product and will give you a draft invoice line that is populated with all the data necessary to add it to a draft invoice. The data supplied may contain the following:

unitNetPrice, quantity, discountPercentage, description, product, unitCostPrice, unit

By default, quantity on a draft invoice line template is set to 1 and currency set to the customer’s base currency.

To set a different quantity, you need to set a query string parameter, “quantity=XX” on your call to this endpoint. Setting the quantity as a query string parameter as opposed to just editing the returned document is necessary for the template to apply bulk discounts.

To set a different currency you need to set the query string parameter, “currency=XXX” on your call to this endpoint. Again, this is necessary for the template to be able to apply the correct prices.

1. Fetch a draft invoice using a GET operation on /invoices/drafts or by invoking the invoice template.

2. Get a draft invoice line by doing a GET operation on /customers/:customerNumber/templates/invoiceline/:productNumber

The :customerNumber parameter is the customerNumber in the draft invoice you fetched in step 1. The :productNumber is the product you want the draft invoice line to be referring to. If you want to create the line with a quantity greater than 1 (in the example below the quantity is 11), then you do your GET operation on /customers/:customerNumber/templates/invoiceline/:productNumber?quantity=11

3. Step 2 gives you a draft invoice line template ready to be used, but as with the draft invoice template you are able to change it if you want. Now, if you want more than one line you just re-run step 2 to generate another line.

4. When you have generated the lines you want it’s time to add them to your draft invoice. Your draft invoice has a property called lines. This is an array of draft invoice lines and you need to add your generated lines there.

5. You now have a complete draft invoice and are ready to save it. To do that you do a PUT operation to /invoices/drafts/:draftInvoiceNumber or if based directly on a template then a POST to /invoices/drafts

The :draftInvoiceNumber parameter should be the draftInvoiceNumber of the draft invoice you fetched in step 1 if you have already saved it.

 

Book an existing draft invoice

To book a draft invoice, you can use the template found here: /invoices/drafts/:draftInvoiceNumber/templates/booking-instructions

This template is a bit different than the other two we have talked about. With the booking instructions template our intent is to add more functionality to it in the future. At the time of this blog post, we support booking with automatic numbering and manual numbering.

Book with automatic numbering

1. So you have a draft invoice and are ready to book it. To do that you do a GET operation to /invoices/drafts/:draftInvoiceNumber/templates/booking-instructions

2. This will give you a book request template that we will use to do the actual booking.

3. Now, to actually book the invoice you do a POST operation to /invoices/booked using the response body from step 1. This will book the invoice and make e-conomic generate the identifier of the booked invoice. The response from this request is the newly booked invoice.

 

Book with a specific invoice number (manual numbering)

We still use the template found here: /invoices/drafts/:draftInvoiceNumber/templates/booking-instructions

To specify an invoice number in the booking-instruction template set the property bookWithNumber.

The bookWithNumber property is optional and if not set the invoice will be booked with the next available invoice number in the sequence. bookWithNumber will allow you to use a POST operation to /invoices/booked and have us use the parameter bookWithNumber as the actual identifier of the booked invoice instead of getting an identifier from e-conomic.

1. First get booking instructions by doing a GET operation to /invoices/drafts/:draftInvoiceNumber/templates/booking-instructions

2. Now, to actually book the invoice you have two options:

a. Do a PUT operation to /invoices/booked/:bookWithNumber using the response body from step 1. This is the standard RESTful way.

b. Update the book request template from step 1 and add a bookWithNumber property. Once done you POST the book request to /invoices/booked

 

New endpoints

To facilitate booking of invoices we have added a number of new endpoints. You can get a quick overview of all the new endpoints that relate to booking below, along with a short description of what they do. For further details, visit http://restdocs.e-conomic.com/#invoices.

  • GET /invoices/booked

This endpoint allows you to fetch a collection of booked invoices.

  • GET /invoices/booked/:bookedInvoiceNumber

This endpoint allows you to fetch a specific booked invoices.

  • GET /invoices/booked/: bookedInvoiceNumber/pdf

This endpoint allows you to download a PDF representation of your booked invoice.

  • POST /invoices/booked

This endpoint allows you to book a draft invoice.

  • PUT /invoices/booked/:boookWithNumber

This endpoint allows you to book a draft invoice and give it a specific invoice number.

  • GET /invoices/drafts/:draftInvoiceNumber/templates

This endpoint will list the available templates.

  • GET /customers/:customerNumber/templates/invoiceline

This endpoint will give you a collection of the available draft invoice line templates.

  • GET /customers/:customerNumber/templates/invoiceline/:productNumber

This endpoint allows you to get a template for a draft invoice line.

  • GET /invoices/drafts/: draftInvoiceNumber/templates/booking-instructions

This endpoint gives you a template used for booking an invoice.