[API] Basics

RESTful web service

The billomat[API] is designed as a so-called RESTful web service, where each resource is addressed by a unique URI.
What Opertationen be done with the resources is specified using the HTTP verbs:

• GET: read resources
• POST: create resources
• PUT: edit resources
• DELETE: delete resources

General Service URL

https://{billomatID}.billomat.net/api/{ressource}[/{id}][/{methode}]

Data formats

Billomat understands XML and JSON for write requests. Following points should be noted:

• All requests should be in UTF-8
• Boolean values are either 1 (true) or 0 (false)
• Depending on the desired format for the write request the appropriate content type must be set in the HTTP header (application/xml or application/json).

Responses are given in XML or JSON format. Other formats (e.g. PDF) are possible for specifiv resources. You can set the output format by setting the GET parameter format (default: XML):

?format=[xml|json]

Alternatively, the format also be determined via an HTTP header:

Accept: application/json

JSONP

JSONP is also supported. All you have to do, is to provide the param jsonp with an optional name for the callback function. The default callback function is callback.

?format=json&jsonp[=callback]

The Content Type changes to application/javascript.

Authentication

The authentication is done through existing Billomat users.
A user, who wants to use billomat[API], must activate the API access under Settings > employees. Inject a personal API key will be generated.
This API key is the "password" for the use of the API.
API requests are stateless, i.e. that no sessions will be stored. Thus you must send the API key with each request,

The API key can be transmitted in two different ways:

via GET parameter

curl https://{billomatid}.billomat.net/api/clients?api_key={apischluessel}

via HTTP header

curl -H 'X-BillomatApiKey: {apikey}' \
https://{billomatid}.billomat.net/api/clients

Security

Regardless of the rate booked the access to the API can be done encrypted over https or unencrypted over http.
It is generally recommended to work only over an encrypted connection because the data is otherwise transferred in plain text and can potentially be read.

Tools

For reading data via GET a normal browser is sufficient. With Firefox, the XML data can also be clearly displayed as a tree structure.
Simply enter the URL of the resource (including the API key) into the address bar of the browser.
For the testing of the remaining methods (POST, PUT, DELETE), we recommend using either the command line tool curl or the firefox plugin RESTClient as a graphical alternative.

To better illustrate the examples we have outlined on this page using the command line tool curl.
The actual resource descriptions we have given up the deadwood and listed only the most important components of the requests.

Read data

Data are always read with the HTTP GET method either in lists or single resource.
A list will be read on the resource path:

curl -H 'X-BillomatApiKey: {apikey}' \
https://{billomatid}.billomat.net/api/clients

When reading a single resource, the URL consists of of the path and the ID of the resource:

curl -H 'X-BillomatApiKey: {apikey}' \
https://{billomatid}.billomat.net/api/clients/1

If the request was successful, returns the status 200 OK and the requested data in the desired format.

The number of records per request (for a list of a resource) can be specified via the parameter per_page. Through the individual pages can be navigated with the parameter page:

Paging

curl -H 'X-BillomatApiKey: {apikey}' \

https://{billomatid}.billomat.net/api/clients?per_page=50&page=2

shows 50 clients per page and the 2nd page (entries from 51 - 100).

The XML root element of a resource list also provides for better orientation the attributes page (current page), per_page (entries per page) and total (total number over all pages). Default value for page is 1 and for per_page is 100, maximum 1000 entries can be returned per page.

Sorting

You can specify a sort order with the optional paramater order_by. Sortings consist of the name of the field and sort order: ASC for ascending resp. DESC for descending order. If no order is specified, ascending order (ASC) is used.

Nested sort orders are possible. Please separate the sort orders by comma.

Example:
Sort invoices by date descending and ascending by invoice number within the same date:

curl -H 'X-BillomatApiKey: {apikey}' \
https://{billomatid}.billomat.net/api/invoices?order_by=date+DESC,invoice_number+ASC

Write Data

Data is written using the HTTP methods POST, PUT and DELETE.
The default format is XML. Each request should be written in the header "Content-type: application/xml" Please include the actual data and neatly wrapped in XML tags contained in the body:

curl -v -X POST \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/xml' \
-d '<client><name>Musterfirma</name></client>' \\
https://{billomatid}.billomat.net/api/clients

Alternativ kann anstatt XML auch JSON verwendet werden, wenn "Content-Type: application/json" mitgesendet wird:

curl -v -X POST \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/json' \
-d '{"client":{"name":"Sample Company"}}' \
https://{billomatid}.billomat.net/api/clients

This creates a new resource using POST - in this examples a new customer with the name 'Sample Company'.
The answer comes with the status 201 Created and the request body with the entire object.
An already existing resource is modified with the PUT method:

curl -v -X PUT \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/xml' \
-d '<client><name>Musterkunde</name></client>' \
https://{billomatid}.billomat.net/api/clients/1

Was the treatment successful, status 200 OK is returned.
Deleting works very similar with the DELETE method, but without additional parameters in the request body:

curl -v -X DELETE \
-H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients/1

Here too, the status 200 OK is returned after a successful deletion.

Own meta data

You can store your own data at Billomat entities by using the so called "customfield". For example this could be the primary key from your system to synchronize Billomat data with the data in your database.

Read

GET /api/clients/{id}/customfield

<?xml version="1.0" encoding="UTF-8"?>
<client>
    <id type="integer">{id}</id>
    <customfield>foo</customfield>
</client>

Write

PUT /api/clients/{id}/customfield

<client>
    <customfield>bar</customfield>
</client>

<?xml version="1.0" encoding="UTF-8"?>
<client>
    <id type="integer">{id}</id>
    <customfield>bar</customfield>
</client>

Errors

If an error occurs while processing a request a status code in the 400 or 500 range are returned. In addition, a short plain text error message is returned in the response body:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Ressource not found</error>
</errors>