Basics

Try out for free

REST­ful web service

The billomat[API] is desi­gned as a so-called REST­ful web ser­vice, where each resource is addres­sed by a uni­que URI.
What Operta­tio­nen be done with the resour­ces is spe­ci­fied using the HTTP verbs:

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

Gene­ral Ser­vice URL

[http|https]://{billomatID}.billomat.net/api/{ressource}[/{id}][/{methode}]
Para­me­ters Mea­ning
{bil­lo­ma­tID} bil­lo­ma­tID of the account
{res­source} res­source to be accessed
{id} ID of the spe­ci­fic ressource
{methode} method of the gene­ral or spe­ci­fic resource

Data for­mats

Bil­lo­mat under­stands XML and JSON for write requests. Fol­lo­wing points should be noted:

  • All requests should be in UTF-8
  • Boo­lean values ​​are eit­her 1 (true) or 0 (false)
  • Depen­ding on the desi­red for­mat for the write request the appro­priate con­tent type must be set in the HTTP hea­der (“application/xml” or “application/json”).

Respon­ses are given in XML or JSON for­mat. Other for­mats (e.g. PDF) are pos­si­ble for spe­ci­fiv resour­ces. You can set the out­put for­mat by set­ting the GET para­me­ter “for­mat” (default: XML):

?format=[ xml | json ]

Alter­na­tively, the for­mat also be deter­mined via an HTTP header:

Accept: application/json

Authen­ti­ca­tion

The authen­ti­ca­tion is done through exis­ting Bil­lo­mat users.
A user, who wants to use billomat[API], must activate the API access under Set­tings > employees. Inject a per­so­nal API key will be gene­ra­ted.
This API key is the “pass­word” for the use of the API.
API requests are sta­te­l­ess, i.e. that no ses­si­ons will be stored. Thus you must send the API key with each request,
The API key can be trans­mit­ted in two dif­fe­rent 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

Secu­rity

Regard­less of the rate booked the access to the API can be done encryp­ted over https or unencryp­ted over http.
It is gene­rally recom­men­ded to work only over an encryp­ted con­nec­tion because the data is other­wise trans­fer­red in plain text and can poten­ti­ally be read.

Tools

For rea­ding data via GET a nor­mal brow­ser is suf­fi­ci­ent. With Fire­fox, the XML data can also be cle­arly dis­played as a tree struc­ture.
Sim­ply enter the URL of the resource (inclu­ding the API key) into the address bar of the brow­ser.
For the tes­ting of the remai­ning methods (POST, PUT, DELETE), we recom­mend using eit­her the com­mand line tool curl or the fire­fox plu­gin REST­Cli­ent as a gra­phi­cal alternative.

To bet­ter illus­trate the exam­ples we have out­lined on this page using the com­mand line tool curl.
The actual resource descrip­ti­ons we have given up the dead­wood and lis­ted only the most import­ant com­ponents of the requests.

Read data

Data are always read with the HTTP GET method eit­her in lists or sin­gle resource.
A list will be read on the resource path:

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

https://{billomatid}.billomat.net/api/clients

When rea­ding a sin­gle resource, the URL con­sists 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 suc­cess­ful, returns the sta­tus 200 OK and the reques­ted data in the desi­red for­mat.
The num­ber of records per request (for a list of a resource) can be spe­ci­fied via the para­me­ter per_page. through the indi­vi­dual pages can be navi­ga­ted with the para­me­ter page:

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

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

shows 50 cli­ents per page and the 2nd page (ent­ries from 51 — 100).
The XML root ele­ment of a resource list also pro­vi­des for bet­ter ori­en­ta­tion the attri­bu­tes page (cur­rent page), per_page (ent­ries per page) and total (total num­ber over all pages).
Default value for page is 1 and for per_page is 100, maxi­mum 1000 ent­ries can be retur­ned per page.

Write Data

Data is writ­ten using the HTTP methods POST, PUT and DELETE.
The default for­mat is XML. Each request should be writ­ten in the hea­der “Content-type: application/xml” Please include the actual data and neatly wrap­ped in XML tags con­tai­ned 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

Alter­na­tiv kann anstatt XML auch JSON ver­wen­det wer­den, wenn “Content-Type: application/json” mit­ge­sen­det 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 crea­tes a new resource using POST — in this exam­ples a new cust­o­mer with the name ‘Sample Com­pany’.
The ans­wer comes with the sta­tus 201 Crea­ted and the request body with the ent­ire object.
An alre­ady exis­ting resource is modi­fied 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 tre­at­ment suc­cess­ful, sta­tus 200 OK is retur­ned.
Dele­ting works very simi­lar with the DELETE method, but wit­hout addi­tio­nal para­me­ters in the request body:

curl -v -X DELETE \
-H 'X-BillomatApiKey: {apischluessel}' \

https://{billomatid}.billomat.net/api/clients/1

Here too, the sta­tus 200 OK is retur­ned after a suc­cess­ful deletion.

Errors

If an error occurs while pro­ces­sing a request a sta­tus code in the 400 or 500 range are retur­ned. In addi­tion, a short plain text error mes­sage is retur­ned in the response body:

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