Datenformate: XML & JSON

Die Billomat API kommuniziert in zwei Formaten: XML und JSON – du entscheidest, welches du verwenden möchtest.

Was sind XML und JSON?

Wenn du eine Anfrage an die Billomat API schickst, bekommst du die Antwort als strukturierten Text zurück – entweder im Format XML oder JSON. Beide Formate beschreiben dieselben Daten, sehen nur unterschiedlich aus.

Stell dir vor, du bekommst eine Rechnung – einmal als klassischen Geschäftsbrief (XML) und einmal als moderne tabellarische Übersicht (JSON). Der Inhalt ist identisch, nur die Darstellung unterscheidet sich.

XML vs. JSON – Ein direkter Vergleich

Hier dieselbe Rechnung einmal in beiden Formaten:

XML (Standard-Format der Billomat API):

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
  <id>12345</id>
  <invoice_number>RE-2024-001</invoice_number>
  <client_id>456</client_id>
  <status>OPEN</status>
  <total_gross>1190.00</total_gross>
</invoice>

JSON (alternatives Format):

{
  "invoice": {
    "id": "12345",
    "invoice_number": "RE-2024-001",
    "client_id": "456",
    "status": "OPEN",
    "total_gross": "1190.00"
  }
}

Das Antwortformat festlegen

Standardmäßig antwortet die Billomat API immer im XML-Format. JSON kannst du auf zwei Wegen anfordern:

Methode 1: Per GET-Parameter

Hänge einfach ?format=json an die URL an:

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

Methode 2: Per HTTP-Header (empfohlen)

Sende den Accept-Header mit dem gewünschten MIME-Type:

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

Format beim Senden von Daten (POST / PUT)

Wenn du Daten an die API schickst – also beim Erstellen oder Bearbeiten von Datensätzen – musst du Billomat mitteilen, in welchem Format die Daten verpackt sind. Das geschieht über den Content-Type-Header:

Beispiel: Neuen Kunden per POST anlegen – einmal in XML, einmal in JSON:

Mit XML:

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

 

Mit JSON:

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"client":{"name":"Musterfirma GmbH"}}' \
  https://{deineBillomatID}.billomat.net/api/clients

Wichtige Grundregeln für beide Formate

• Zeichenkodierung: Alle Anfragen müssen UTF-8-kodiert sein – das ist heute der Standard und wird von allen gängigen Programmiersprachen und Tools automatisch verwendet.
• Boolesche Werte: Wahr/Falsch-Werte werden nicht als true/false übermittelt, sondern als 1 (wahr) und 0 (falsch).
• Zahlen: Dezimalzahlen verwenden einen Punkt als Trennzeichen, kein Komma – also 1190.00, nicht 1190,00.
• Datumsformat: Datumsangaben immer im Format YYYY-MM-DD, also z.B. 2024-12-31.

JSONP (für spezielle Browser-Anwendungen)

Für bestimmte browserbasierte Anwendungen, die aus Sicherheitsgründen keine direkte JSON-Anfrage stellen können, unterstützt die API auch JSONP. Dabei wird die Antwort in eine JavaScript-Funktion verpackt.

https://{deineBillomatID}.billomat.net/api/invoices?format=json&jsonp=meinCallback

Die Antwort sieht dann so aus:

meinCallback({"invoices": { ... }})

Nächste Schritte

Jetzt wo du weißt, wie Daten formatiert werden, geht es ans Eingemachte:

• Daten lesen (GET) – wie du Datensätze abrufst, filterst und sortierst
• Daten schreiben (POST / PUT / DELETE) – wie du Datensätze anlegst, bearbeitest und löschst