Daten lesen

Daten werden immer mit der HTTP-Methode GET entweder in Listen oder als Einzel-Ressource gelesen.

Eine Liste wird über den Ressourcen-Pfad gelesen:

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

Beim Lesen einer Einzel-Ressource setzt sich die URL aus dem Ressourcen-Pfad und der ID der Ressource zusammen:

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

Wenn der Request erfolgreich war, kommt der Status 200 OK und die angeforderten Daten im gewünschten Format zurück.

Paginierung

Die Anzahl der Datensätze per Request (bei einer Ressourcen-Liste) kann über den Parameter per_page angegeben werden, durch die einzelnen Seiten kann mit dem Parameter page navigiert werden:

curl -H 'X-BillomatApiKey: {apischluessel}'
https://{billomatid}.billomat.net/api/clients?per_page=50&amp;page=2

liefert 50 Kunden pro Seite und zeigt die 2. Seite (also Datensätze von 51 – 100) an.
Das XML-Root-Element einer Listen-Ressource liefert zur besseren Orientierung außerdem die 3 Attribute page (aktuelle Seite), per_page (Einträge pro Seite) und total (Gesamtanzahl über alle Seiten) zurück. Standard-Wert für page ist 1 und für per_page ist 100, maximal können 1000 Einträge pro Seite zurückgegeben werden.

Filterung

Die zurückgegebenen Ressourcen in einer Liste lassen sich über Filterparameter einschränken. Die Filter, die dabei zur Verfügung stehen, sind in den Beschreibungen der jeweiligen Ressourcen aufgeführt und beschrieben.

Möchte man nur performant abfragen, wieviele Treffer eine Filterung ergibt, so reicht es aus, einen HEAD Request auf die Listen-Ressource mit den entsprechenden Filtern auszuführen und den Header X-Total-Count auszulesen.

Sortierung

Über den optionalen Parameter order_by kann eine Sortierreihenfolge angegeben werden. Eine Sortierung besteht aus dem Namen des Feldes und der Sortierreihenfolge: ASC für aufstiegende bzw. DESC für absteigende Sortierung. Wird keine Reihenfolge angegeben, wird aufsteigend (ASC) sortiert.

Sortierreihenfolgen können geschachtelt werden, indem mehrere Sortierungen kommasepariert aufgelistet werden.

Beispiel:
Sortierung von Rechnungen absteigend nach Datum und innerhalb des selben Datums aufsteigend nach Rechnungsnummer:

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

Sprache

Einige wenige Werte werden sprachabhängig (genauer: in Abhängigkeit eines Gebietsschemas) zurückgegeben. Das Gebietsschema kann mit dem HTTP-Header Accept-Language angegeben werden.

curl -H 'X-BillomatApiKey: {apischluessel}' -H 'Accept-Language: de-de'
https://{billomatid}.billomat.net/api/activity-feed

curl -H 'X-BillomatApiKey: {apischluessel}' -H 'Accept-Language: en-gb'
https://{billomatid}.billomat.net/api/activity-feed