We have extended the /invoices-experimental endpoint with a lot of exciting new functionality. It is now possible to book an invoice through /invoices-experimental. 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-experimental/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-experimental/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-experimental/drafts/:draftInvoiceNumber or if based directly on a template then a POST to /invoices-experimental/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-experimental/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-experimental/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-experimental/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-experimental/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-experimental/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-experimental/drafts/:draftInvoiceNumber/templates/booking-instructions
2. Now, to actually book the invoice you have two options:
a. Do a PUT operation to /invoices-experimental/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-experimental/booked
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-experimental.
- GET /invoices-experimental/booked
This endpoint allows you to fetch a collection of booked invoices.
- GET /invoices-experimental/booked/:bookedInvoiceNumber
This endpoint allows you to fetch a specific booked invoices.
- GET /invoices-experimental/booked/: bookedInvoiceNumber/pdf
This endpoint allows you to download a PDF representation of your booked invoice.
- POST /invoices-experimental/booked
This endpoint allows you to book a draft invoice.
- PUT /invoices-experimental/booked/:boookWithNumber
This endpoint allows you to book a draft invoice and give it a specific invoice number.
- GET /invoices-experimental/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-experimental/drafts/: draftInvoiceNumber/templates/booking-instructions
This endpoint gives you a template used for booking an invoice.