Delivery Notes | Billomat Accounting API

List all delivery notes

GET /api/delivery-notes

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;delivery-notes type="array" page="1" per_page="100" total="2"&gt;
&lt;delivery-note&gt;
…
&lt;/delivery-note&gt;
&lt;delivery-note&gt;
…
&lt;/delivery-note&gt;
&lt;/delivery-notes&gt;

You can filter the result by parameters:

GET /api/delivery-notes?delivery_note_number=LS123

Lists all delivery notes with “LS123” in the delivery note number. Upper and lower case are ignored.
The following filter parameters are available:

Parameter	Description
client_id	ID of the client
contact_id	ID of the contact
delivery_note_number	Delivery note number
status	Status (DRAFT, CREATED). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
from	Only show delivery notes since this date (format YYYY-MM-DD)
to	Only show delivery notes up to this date (format YYYY-MM-DD)
label	Free text search in label text
intro	Free text search in introductory text
note	Free text search in explanatory notes
tags	Comma separated list of tags
article_id	ID of an article

Get a single delivery note

GET /api/delivery-notes/{id}

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;delivery-note&gt;
&lt;id type="integer"&gt;1&lt;/id&gt;
&lt;client_id type="integer"&gt;123&lt;/client_id&gt;
&lt;contact_id type="integer"&gt;&lt;/contact_id&gt;
&lt;created type="datetime"&gt;2007-12-13T12:12:00+01:00&lt;/created&gt;
&lt;delivery_note_number&gt;GS123&lt;/delivery_note_number&gt;
&lt;number type="integer"&gt;123&lt;/number&gt;
&lt;number_pre&gt;LS&lt;/number_pre&gt;
&lt;number_length type="integer"&gt;0&lt;/number_length&gt;
&lt;status&gt;CREATED&lt;/status&gt;
&lt;date type="date"&gt;2009-10-14&lt;/date&gt;

&lt;address&gt;Billomat GmbH &amp;amp;amp; Co. KG
Hollertszug 26
57562 Herdorf
Deutschland&lt;/address&gt;    &lt;title&gt;&lt;/title&gt;
&lt;label&gt;project 123&lt;/label&gt;
&lt;intro&gt;Dear sir or madam,…&lt;/intro&gt;
&lt;note&gt;Thank you!&lt;/note&gt;
&lt;customerportal_url&gt;https://mybillomatid.billomat.net/customerportal/deliverynotes/show/entityId/123?hash=123456789aabbcc&lt;/customerportal_url&gt;
&lt;offer_id&gt;&lt;/offer_id&gt;
&lt;confirmation_id&gt;7&lt;/confirmation_id&gt;
&lt;invoice_id&gt;&lt;/invoice_id&gt;
&lt;template_id&gt;&lt;/template_id&gt;
&lt;/delivery-note&gt;

status can have the following values:

DRAFT
CREATED
Delivery note items and comments can be accessed separately.

Create delivery note

POST /api/delivery-notes

XML element	Description	Type	Default value	Mandatory
client_id	ID of the client	INT		yes
contact_id	ID of the contact	INT
address	the delivery address	ALNUM	Address of the customer
number_pre	Prefix	ALNUM	Value taken from the settings.
number	serial number	INT	next free number
number_length	Minimum length of the delivery note number (to be filled with leading zeros)	INT	Value taken from the settings.
date	Date of delivery	DATE	today
title	Title of the document	ALNUM
label	Label text to describe the project	ALNUM
intro	Introductory text	ALNUM	Value taken from the settings.
note	Explanatory notest	ALNUM	Value taken from the settings.
offer_id	The ID of the estimate, if the delivery note was created from an estimate.	INT
confirmation_id	The ID of the confirmation, if the delivery note was created from a confirmation.	INT
invoice_id	The ID of the invoice, if the delivery note was created from an invoice.	INT
free_text_id	The ID of the free text to set title, label, intro and note.	INT
template_id	The ID of the template to be used to complete the delivery note.	INT	ID of the default template

status at creation is always DRAFT.

When initially created in DRAFT state, the delivery_note_number is returned as an empty response. It is only on completion of a delivery note that the delivery note number is calculated and gets a value.

Delivery note items (delivery-note-items) can be specified directly at creation. Please find a documentation of the XML elements at Create delivery note items, but the XML element invoice_id need not be specified with.

&lt;delivery-note&gt;
&lt;client_id&gt;1&lt;/client_id&gt;
&lt;date&gt;2009-11-18&lt;/date&gt;
&lt;note&gt;Dear sir or madam,…:&lt;/note&gt;
&lt;delivery-note-items&gt;
&lt;delivery-note-item&gt;
&lt;unit&gt;Piece&lt;/unit&gt;
&lt;quantity&gt;1.5&lt;/quantity&gt;
&lt;title&gt;Pattern&lt;/title&gt;
&lt;/delivery-note-item&gt;
&lt;delivery-note-item&gt;
&lt;unit&gt;Hour&lt;/unit&gt;
&lt;quantity&gt;8&lt;/quantity&gt;
&lt;title&gt;Working&lt;/title&gt;
&lt;/delivery-note-item&gt;
&lt;/delivery-note-items&gt;
&lt;/delivery-note&gt;

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;delivery-note&gt;
&lt;id type="integer"&gt;1234&lt;/id&gt;
&lt;client_id type="integer"&gt;1&lt;/client_id&gt;
&lt;created type="datetime"&gt;2007-12-13T12:12:00+01:00&lt;/created&gt;
&lt;delivery_note_number&gt;LS124&lt;/delivery_note_number&gt;
&lt;number type="integer"&gt;124&lt;/number&gt;
&lt;number_pre&gt;LS&lt;/number_pre&gt;
&lt;number_length type="integer"&gt;0&lt;/number_length&gt;
&lt;date type="date"&gt;2009-11-18&lt;/date&gt;
…
&lt;/delivery-note&gt;

Edit delivery note

PUT /api/delivery-notes/{id}

A delivery note can basically be edited in draft status (DRAFT) only.
Delivery note items and comments could not be edited at the delivery note. Please use the appropriate resource instead.

&lt;delivery-note&gt;
&lt;date&gt;2009-10-13&lt;/date&gt;
&lt;/delivery-note&gt;

Delete delivery note

DELETE /api/delivery-notes/{id}

Deletes an invoice with all documents (PDFs), items and comments.

Complete delivery note

PUT /api/delivery-notes/{id}/complete

Completes a delivery note in the draft status (DRAFT). Here, the status of created (CREATED) is set and a PDF is generated and stored in the file system.

The optional parameter template_id determines which template is used to create a pdf.

If this parameter is not specified, the template specified at the delivery note or the default template is used.

&lt;complete&gt;
&lt;template_id&gt;123&lt;/template_id&gt;
&lt;/complete&gt;

Open pdf of a delivery note

GET /api/delivery-notes/{id}/pdf

At this point, the parameter format=pdf can also be used to open the PDF directly with MIME type “application/pdf”.
With the optional parameter type=print you can request the PDF without background. Note that the setting print_version must have been activated.

&lt;pdf&gt;
    &lt;id type="integer"&gt;4882&lt;/id&gt;
&lt;created type="datetime"&gt;2009-09-02T12:04:15+02:00&lt;/created&gt;
&lt;delivery_note_id type="integer"&gt;240&lt;/delivery_note_id&gt;
&lt;filename&gt;delivery-note_123.pdf&lt;/filename&gt;
&lt;mimetype&gt;application/pdf&lt;/mimetype&gt;
&lt;filesize&gt;70137&lt;/filesize&gt;
&lt;base64file&gt;{base64 encoded PDF}&lt;/base64file&gt;
&lt;/pdf&gt;

Send delivery note by e-mail

POST /api/delivery-notes/{id}/email

XML element	Description	Type	Default value	Mandatory
email_template_id	ID of the e-mail template	INT
from	Sender	EMAIL	Default email from the settings
recipients	Recipients of the e-mail. There must be at least one xml node for “to”, “cc” and/or “bcc”.	XML node/EMAIL		ja
subject	Subject of the e-mail (may include placeholders)	ALNUM	Value taken from the (default) e-mail template
body	Text of the e-mail (may include placeholders)	ALNUM	Value taken from the (default) e-mail template
filename	Name of the PDF file (without .pdf)	ALNUM	invoice_{id}
attachments	Further files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”.	XML node

&lt;email&gt;
&lt;from&gt;info@billomat.com&lt;/from&gt;
&lt;recipients&gt;
&lt;to&gt;info@billomat.com&lt;/to&gt;
&lt;cc&gt;mail@example.com&lt;/cc&gt;
&lt;/recipients&gt;
&lt;subject&gt;Your invoice&lt;/subject&gt;
&lt;body&gt;Dear sir or madam, ….&lt;/body&gt;
&lt;filename&gt;delivery_note&lt;/filename&gt;
&lt;attachments&gt;
&lt;attachment&gt;
&lt;filename&gt;drawing.pdf&lt;/filename&gt;
&lt;mimetype&gt;application/pdf&lt;/mimetype&gt;
&lt;base64file&gt;{base64 encoded file}&lt;/base64file&gt;
&lt;/attachment&gt;
&lt;/attachments&gt;
&lt;/email&gt;

Send delivery note by mail

POST /api/delivery-notes/{id}/mail

Sends a delivery note by mail. Pixelletter has to be configured as add on for usage.

XML element	Description	Type	Default value
color	Determines whether to use color printing.	BOOL	0
duplex	Determines whether to use duplex printing.	BOOL	1
paper_weight	Determines the paper weight in grams. Possible values are 80 or 90.	INT	90
attachments	Further PDF files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”.	XML node

&lt;mail&gt;
&lt;color&gt;0&lt;/color&gt;
    &lt;duplex&gt;1&lt;/duplex&gt;
    &lt;paper_weight&gt;90&lt;/paper_weight&gt;
    &lt;attachments&gt;
&lt;attachment&gt;
&lt;filename&gt;drawing.pdf&lt;/filename&gt;
&lt;mimetype&gt;application/pdf&lt;/mimetype&gt;
&lt;base64file&gt;{base64 encoded file}&lt;/base64file&gt;
&lt;/attachment&gt;
&lt;/attachments&gt;
&lt;/mail&gt;