Daten lesen (GET)

Mit der HTTP-Methode GET rufst du Daten aus deinem Billomat-Account ab – einzelne Datensätze genauso wie gefilterte und sortierte Listen.

Was ist ein GET-Request?

GET ist die einfachste und sicherste Methode in der Billomat API – du kannst damit ausschließlich Daten lesen, niemals verändern oder löschen. Es ist wie ein Blick ins Aktenschrank: Du siehst alles, nimmst aber nichts heraus.

GET-Requests lassen sich sogar direkt im Browser testen – einfach die URL mit API-Schlüssel in die Adressleiste eingeben. Mehr dazu im Artikel Tools & Testing.

Eine Liste abrufen

Um alle Datensätze einer Ressource abzurufen, sprichst du einfach die Ressource ohne ID an:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/invoices

Bei Erfolg antwortet die API mit dem HTTP-Statuscode 200 OK und gibt alle Rechnungen zurück.

Einen einzelnen Datensatz abrufen

Um einen bestimmten Datensatz abzurufen, hängst du die ID des Datensatzes an die URL:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/invoices/12345

Gibt es keinen Datensatz mit dieser ID, antwortet die API mit 404 Not Found.

Paginierung – große Datenmengen aufteilen

Wenn du viele Datensätze hast, gibt die API diese nicht auf einmal zurück, sondern in Seiten – ähnlich wie Suchergebnisse bei Google. Standardmäßig bekommst du 100 Datensätze pro Seite.

Beispiel: Seite 2 abrufen, mit jeweils 50 Datensätzen pro Seite:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/invoices?per_page=50&page=2

Die API-Antwort enthält im Wurzelelement immer drei nützliche Angaben zur Gesamtmenge:

<invoices page="2" per_page="50" total="340">
  ...
</invoices>

Filtern – nur relevante Datensätze abrufen

Du kannst die zurückgegebenen Datensätze über URL-Parameter einschränken. Welche Filter eine Ressource unterstützt, ist in den jeweiligen Ressourcen-Artikeln beschrieben. Einige häufig verwendete Beispiele für Rechnungen:

Mehrere Filter lassen sich mit & kombinieren:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/invoices?status=OPEN&client_id=456

Sortieren – die Reihenfolge bestimmen

Mit dem Parameter order_by kannst du die Reihenfolge der Ergebnisse festlegen. Das Format ist feldname+ASC (aufsteigend) oder feldname+DESC (absteigend). Mehrere Sortierfelder werden per Komma verkettet:

Neueste Rechnungen zuerst:

?order_by=date+DESC

 

Nach Datum absteigend, bei gleichem Datum nach Rechnungsnummer aufsteigend:

?order_by=date+DESC,invoice_number+ASC

Nur die Trefferanzahl abfragen (HEAD)

Manchmal möchtest du nur wissen, wie viele Datensätze ein Filter liefert – ohne die Daten selbst zu laden. Dafür gibt es den HEAD-Request: Er ist deutlich schneller und spart API-Kontingent, weil kein Body übertragen wird.

curl -I -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/invoices?status=OPEN

Im Antwort-Header steht dann:

X-Total-Count: 42

Sprache der Antwort festlegen

Bei bestimmten Ressourcen wie dem Aktivitäten-Feed werden sprachabhängige Texte zurückgegeben. Die gewünschte Sprache kannst du über den HTTP-Header Accept-Language festlegen:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
     -H 'Accept-Language: de-de' \
  https://{deineBillomatID}.billomat.net/api/activity-feed

Nächste Schritte

Daten lesen ist der erste Schritt – jetzt lernst du, wie du Datensätze anlegst, bearbeitest und löschst:

• Daten schreiben (POST / PUT / DELETE)