Items from the “deliveries” domain represent a delivery note.
Structure of URL’s:
https://api.simplybooks.be/api/v1/deliveries: Delivery note details
https://api.simplybooks.be/api/v1/deliveries/4004: Delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/items: Items from delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/items/5004: Item with ID 5004 from delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/remarks: Notes of delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/remarks/5010: Notes with ID 5010 of delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/events: Events of delivery note with ID 4004
https://api.simplybooks.be/api/v1/deliveries/4004/events/5030: Event with ID 5030 of delivery note with ID 4004
Domain : deliveries
| Field name | Type | Description | Example |
|---|---|---|---|
| delivery_id | int | Unique ID of the delivery note. Generated by the system. Required to be specified in URL (except for creation). | 4004 |
| uri | text | URL to the delivery note. Generated by the system. To be used when addressing the delivery note via the API. | – |
| external_delivery_id | text | (Unique) ID of the delivery note that can be set by a third party. Maximum 50 characters long. Uniqueness of the value is not enforced. | delivery-548984 |
| client_id | int | Unique ID of the customer. Required to specify. | 1001 |
| client_uri | text | URL to the customer. Generated by the system. To be used when addressing the customer via the API. | – |
| client_name | text | Name of the customer. Is automatically taken from the customer data if not specified. | IT Services BVBA |
| client_attention | text | Attn of the customer. Is automatically taken from the customer data if not specified. | Dienst administratie |
| type | text | Type of the document. Always contains the value: 'delivery'. It is determined by the system and cannot be passed on by itself. | delivery |
| number | text | Unique delivery note number as shown on the delivery note. Generated if not provided. Maximum 255 characters long. | 00000001 |
| layout_id | int | Unique ID of the layout. If not specified, the default layout is determined automatically. Can be empty if no layout has been set for the account. | 8001 |
| reference | text | Self-specified reference of the delivery note. Not required. Maximum 250 characters long. | REF123456789 |
| date | date | Date of creation of the delivery note. Generated if not provided. Format YYYY-MM-DD. | 2018-02-15 |
| status | text | Delivery note status. Possible values: 'open' (=Open), 'completed' (=Completed). Default status is 'open'. | open |
| billing_address | Address | Customer billing address. Is automatically taken from the customer data if not specified. | – |
| delivery_address | Address | Customer's shipping address. Is automatically taken from the customer data if not specified. | – |
| site_address | Address | Customer site address. Is automatically taken from the customer data if not specified. | – |
| language | text | The language in which the delivery note is drawn up. This value can contain 'dutch', 'french', 'english' or 'german' but can also be empty. If empty (= default value), the default language (dutch) is used. | dutch |
| items | list | List of delivery note items. | – |
| note | text | Note shown at the bottom of the delivery note. Optional to give. Maximum 2000 characters long. | Warranty condtions apllicable |
| note_html | html | Note shown at the bottom of the delivery note in HTML format. Optional to give. Maximum 2000 characters long. | <p>Warranty conditions applicable</p> |
| last_activity | datetime | Time with the last activity of the delivery note. Cannot be specified, automatically determined by the system. | 2018-05-03 11:33:45 |
| custom_values | list | List of standard fields that can be added to the delivery note. The available standard fields can be set via “Settings” > “Advanced”. | – |
| tags | list | List of tags indicating which actions have already been performed for the delivery note. | – |
| remarks | list | List of personal notes on the delivery note. | – |
| events | list | List of delivery note events. | – |
Subdomain : items ( < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| item_id | int | Unique ID of the delivery note item. Generated by the system. Required to be specified in URL (except for creation). | 4004 |
| delivery_id | int | Unique ID of the delivery note. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to delivery note item. Generated by the system. To be used when addressing delivery note item via the API. | – |
| quantity | float | Number of units of the delivery note item. Can be specified to 2 decimal places. If not specified, '1' is used by default. The maximum amount is 99,999.99. | 2 |
| unit | text | Unit of the item. Not required. Maximum 10 characters long and must start with a letter. Must not contain spaces. | stuk |
| stockitem_code | text | Artikelcode gekoppeld aan het item. Niet verplicht. Maximum 20 karakters lang. Toevoegen van een artikelcode heeft geen invloed op het aantal items in voorraad op de artikelenlijst. | A0000001 |
| stockitem_id | int | Item code linked to the item. Not required. Maximum 20 characters long. Adding an item code does not affect the number of items in stock on the item list. | 2002 |
| quantity_with_unit | text | Quantity and unit of the item separated by a space. Can only be used during creation or editing. Cannot be used in combination with field 'quantity' or 'unit'. The same restrictions as 'quantity' and 'unit' fields apply. | 2 stuk |
| description | text | Description of the delivery note item. Mandatory at creation (alternatively, field description_html can be used). | product description |
| description_html | html | Description of the delivery note item in HTML format. Mandatory to be specified at creation (alternatively, field description can be used). | <p>product description</p> |
| custom_values | list | List of standard fields. The available fields are added via “Settings” > “Advanced”. | – |
Subdomain : custom_values ( < deliveries + items < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| name | text | Internal name of the default field. Determined when the default field is created and can be used as a unique identifier for the default field. Mandatory when adding or changing the value of this field. | myreference |
| description | text | Name or description of the default field as it appears when used. Returned for informational purposes only and cannot be modified via the API. | Our reference |
| value | text | Value of the default field. Maximum 75 characters long. | 123456 |
Subdomain : tags ( < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| tag_id | number | Unique ID of the tag. | 3 |
| name | text | Tag name or code. Possible values: 'printed' (tag_id=3), 'sent' (tag_id=6), 'accountant' (tag_id=9). | printed |
Note: The 'tags' subdomain is not a full-fledged subdomain and cannot be addressed separately from domain 'deliveries'. It is not possible to adjust values in tags via the API. This data is automatically added based on actions performed.
Subdomain : remarks ( < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| remark_id | int | Unique ID of the comment. Generated by the system. Required to be specified in URL (except for creation). | 5020 |
| delivery_id | int | Unique ID of the delivery note. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to comment. Generated by the system. To be used when addressing comment via the API. | – |
| date | date | Date the comment was added. If not specified, the current date is used. Format is YYYY-MM-DD. | 2012-02-15 |
| description | text | Description of the comment. Mandatory to be specified when creating or modifying (alternatively, field description_html can be used). | Customer insists on prompt delivery |
| description_html | html | Description of the comment in HTML format. Mandatory to be specified when creating or modifying (alternatively, field description can be used). | <p>Customer insists on prompt delivery</p> |
Subdomain : events ( < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| event_id | int | Unique ID of the event. Generated by the system. Required to be specified in URL. | 5030 |
| delivery_id | int | Unique ID of the delivery note. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to event. Generated by the system. To be used when calling event via the API. | – |
| date | date | Date when the event occurred. Format YYYY-MM-DD. | 2012-02-15 |
| type | text | Event type. Currently only 'email sent' possible. | email sent |
| content | text | Content or description of the event. With type 'email sent' the content of the email will be sent here. | attached your delivery note |
| recipients | list | List of event recipients. | – |
Note: An element of the 'events' subdomain cannot be changed or created by yourself. Only the system can create an 'event'.
Subdomein : recipients ( < events < deliveries )
| Field name | Type | Description | Example |
|---|---|---|---|
| name | text | Name (first name + last name) of the recipient. | Bart Decouster |
| email_address | text | Email address of the recipient. | [email protected] |
| external_event_recipient_id | text | External unique reference to this record. | 17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6 |
| status | text | Status that returns whether the event has already arrived at the recipient. Possible statuses are: sending, sent, open, failed. | sending |
| information | text | Additional information about the status. An error message will appear here if status is set to 'failed'. | – |
Note: The 'recipients' subdomain is not a full-fledged subdomain and cannot be accessed separately from the 'events' subdomain.
Example in XML of a delivery note:
<delivery>
<delivery_id>5005</delivery_id>
<uri>https://eenvoudigfactureren.be/api/v1/deliveries/5005</uri>
<external_delivery_id>delivery-0983984</external_delivery_id>
<client_id>1001</client_id>
<client_uri>https://eenvoudigfactureren/api/v1/clients/1001</client_uri>
<client_name>IT Services BVBA</client_name>
<client_attention>Dienst administratie</client_attention>
<type>delivery</type>
<number>00000001</number>
<layout_id>8001</layout_id>
<reference>ID123456789</reference>
<date>2018-02-15</date>
<status>open</status>
<billing_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</billing_address>
<delivery_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</delivery_address>
<site_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</site_address>
<language>dutch</language>
<items>
<item>
<item_id>4004</item_id>
<uri>https://eenvoudigfactureren.be/api/v1/deliveries/5005/items/4004</uri>
<description>product omschrijving</description>
<description_html><![CDATA[<p>product omschrijving</p>]]></description_html>
<quantity>2</quantity>
<unit>stuk</unit>
<stockitem_code>A000001</stockitem_code>
<custom_values>
<custom_value>
<name>ean</name>
<description>EAN</description>
<value>100000000000001</value>
</custom_value>
</custom_values>
</item>
</items>
<note>Garantievoorwaarden zijn van toepassing.</note>
<note_html><![CDATA[<p>Garantievoorwaarden zijn van toepassing.</p>]]></note_html>
<last_activity>2018-05-03 11:33:45</last_activity>
<custom_values>
<custom_value>
<name>myreference</name>
<description>Onze referentie</description>
<value>123456</value>
</custom_value>
</custom_values>
<tags>
<tag>
<tag_id>3</tag_id>
<name>printed</name>
</tag>
</tags>
<remarks>
<remark>
<remark_id>5020</remark_id>
<uri>https://eenvoudigfactureren.be/api/v1/deliveries/5005/remarks/5020</uri>
<date>2012-02-15</date>
<description>Klant dringt aan op spoedige levering</description>
<description_html><![CDATA[<p>Klant dringt aan op spoedige levering</p>]]></description_html>
</remark>
</remarks>
<events>
<event>
<event_id>5030</event_id>
<uri>https://eenvoudigfactureren.be/api/v1/deliveries/5005/events/5030</uri>
<date>2012-02-16</date>
<type>email sent</type>
<content>In bijlage uw leveringsbon</content>
<recipients>
<recipient>
<name>Bart Decouster</name>
<email_address>[email protected]</email_address>
<external_event_recipient_id>17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6</external_event_recipient_id>
<status>sending</status>
<information>-</information>
</recipient>
</recipients>
</event>
</events>
</delivery> More infiormation about the API? Read the useful articles below