Einfach erklärt – für den API Einsteiger
1. Was ist eine API überhaupt?
Stell dir vor, du sitzt in einem Restaurant. Du weißt genau, was du möchtest – aber du gehst nicht selbst in die Küche. Stattdessen kommt eine Kellnerin. Sie nimmt deine Bestellung auf, geht damit in die Küche, und bringt dir das fertige Gericht zurück. Du bekommst, was du willst – ohne zu wissen, wie genau es zubereitet wurde.
Die Abkürzung API steht für Application Programming Interface – auf Deutsch: Programmierschnittstelle. Klingt kompliziert, bedeutet aber nur: Ein standardisierter Weg, über den zwei Programme miteinander kommunizieren können.
2. Wie funktioniert die Billomat API?
2.1 Die Basis-Adresse (URL)
Jeder Billomat-Account hat eine eigene Adresse, über die er angesprochen werden kann.
Bei dir lautet sie:
https://BILLOMATID.billomat.net/api/
Hinter dem /api/ kommt dann die gewünschte Ressource – also das, worüber man sprechen möchte:
| Was ich möchte | URL-Endung | Vollständige URL |
|---|---|---|
Alle Kunden sehen |
/api/clients |
|
Alle Rechnungen sehen |
/api/invoices |
BILLOMATID.billomat.net/api/invoices |
| Alle Angebote sehen | /api/offers |
BILLOMATID.billomat.net/api/offers |
Alle Artikel sehen |
/api/articles |
BILLOMATID.billomat.net/api/articles |
Alle Mahnungen sehen |
/api/reminders |
2.2 Die vier Grundbefehle
Die API versteht vier verschiedene Arten von Anfragen. Man nennt sie auch HTTP-Methoden:
| Befehl | Was er bewirk | Beispiel im Alltag | Gefährlich? |
|---|---|---|---|
| GET | Daten lesen/abrufen | "Zeig mir alle offenen Rechnungen" | ❌ Nein – nur lesen |
| POST | Etwas Neues erstellen | "Erstelle eine neue Rechnung" | ⚠️ Vorsicht – erstellt Daten |
| PUT | Etwas verändern | "Ändere die Adresse von Kunde 5" | ⚠️ Vorsicht – ändert Daten |
| DELETE | Etwas löschen | "Lösch diesen Rechnungsentwurf" | 🚨 Achtung – löscht dauerhaft |
💡Tipp: Mit GET kann absolut nichts schiefgehen – es werden nur Daten gelesen, nie verändert. Ideal zum Ausprobieren!
2.3 Der API-Schlüssel – dein persönlicher Ausweis
Damit nicht jeder einfach auf die Daten eines Billomat-Accounts zugreifen kann, braucht jede Anfrage einen API-Schlüssel. Stell dir das vor wie einen Hausausweis: Nur wer einen gültigen Ausweis vorzeigt, kommt rein.
Wo findet man ihn?
| Schritt 1: In Billomat einloggen | Den gewünschten Billomat-Account öffnen. |
| Schritt 2: Zu den Einstellungen navigieren | Auf Benutzereinstellungen klicken |
| Schritt 3: Nutzer auswählen | Den eigenen Nutzer anklicken und auf 'Bearbeiten' gehen. |
| Schritt 4: API-Zugriff aktivieren |
Den Haken bei 'API Zugriff → aktivieren?' setzen.
→ Dann auf 'API-Schlüssel anzeigen' klicken
→ Schlüssel kopieren
→ Nicht vergessen: 'Speichern' klicken!
|
💡 Wichtig: Den API-Schlüssel geheim halten!
Der API-Schlüssel ist wie ein Passwort. Wer ihn hat, kann auf alle Daten des Accounts zugreifen. Er sollte niemals per E-Mail oder Chat weitergegeben werden.
2.4 Wie sieht eine Antwort aus? (JSON)
Wenn die API antwortet, schickt sie Daten in einem Format namens JSON zurück. Das klingt technisch, ist aber eigentlich sehr gut lesbar:
{
"invoice": {
"id": "12345",
"invoice_number": "RE-2024-001",
"client_name": "Musterfirma GmbH",
"total_gross": "1190.00",
"currency": "EUR",
"status": "OPEN",
"due_date": "2024-02-28"
}
}
Man liest das einfach von oben nach unten, wie eine beschriftete Liste:
| Feld | Bedeutung | Wert im Beispiel |
|---|---|---|
| id | Interne Billomat-Nummer der Rechnung |
12345 |
| invoice_number | Die Rechnungsnummer, die der Kunde sieht |
RE-2024-001 |
| client_name | Name des Kunden |
Musterfirma GmbH |
| total_gross | Bruttobetrag in Euro |
1.190,00 € |
| status | Aktueller Status der Rechnung |
OPEN (offen) |
| due_date | Fälligkeitsdatum |
28.02.2024 |
2.5 Die wichtigsten Fehlermeldungen
Wenn etwas nicht funktioniert, antwortet die API mit einem Fehlercode. Diese Codes sind international standardisiert:
| Code | Name | Was es bedeutet | Mögliche Ursache |
|---|---|---|---|
| 200 | OK | Alles hat funktioniert ✅ |
- |
| 400 | Bad Request | Die Anfrage war fehlerhaft |
Falsche Daten mitgeschickt |
| 401 | Unauthorized |
Nicht angemeldet / kein Zugriff |
Falscher oder fehlender API-Key |
| 403 | Forbidden |
Zugriff verweigert |
Keine Berechtigung für diese Aktion |
| 404 | Not Found |
Nicht gefunden |
Falsche URL oder ID existiert nicht |
| 429 | Too Many Requests |
Zu viele Anfragen |
API-Limit erreicht |
| 500 | Server Error |
Interner Billomat-Fehler |
Problem auf Billomat-Seite |
💡 Eselsbrücke für die Fehlercodes 4xx = Das Problem liegt beim Fragesteller (falsche Daten, kein Schlüssel). 5xx = Das Problem liegt beim Server (Billomat selbst hat ein Problem).
3. Die API testen – ohne Programmierung!
Das Beste: Man braucht keinerlei Programmierkenntnisse, um die Billomat API auszuprobieren. Es gibt ein kostenloses Tool namens Postman, das wie ein "Test-Telefon" für APIs funktioniert – einfach die gewünschte Anfrage zusammenklicken, auf Senden drücken, und die Antwort erscheint.
3.1 Postman installieren
| Schritt 1: Postman herunterladen |
Die Webseite http://www.postman.com öffnen und auf 'Download' klicken. → Kostenlosen Account erstellen (mit E-Mail-Adresse) → Postman herunterladen und installieren |
| Schritt 2: Postman öffnen und einloggen | Postman starten und mit dem gerade erstellten Account anmelden. |
3.2 Erste Anfrage: Alle Kunden abrufen (GET)
Ziel: Wir rufen alle Kunden aus Marions Billomat-Account ab. Das ist absolut sicher – nur lesen, nichts verändern.
| Schritt 1: Neue Anfrage erstellen | In Postman oben auf das '+' klicken, um eine neue Anfrage zu öffnen. |
| Schritt 2: Methode wählen | Links neben der URL-Leiste steht standardmäßig 'GET'. Das ist genau richtig – so lassen. |
| Schritt 3: URL eingeben |
In die URL-Leiste folgendes eintippen: |
| Schritt 4: API-Key eintragen |
Auf den Reiter 'Headers' (Kopfzeilen) klicken und zwei Zeilen ausfüllen: → Key: X-BillomatApiKey | Value: (hier den API-Key eintragen) → Key: Accept | Value: application/json |
| Schritt 5: Anfrage senden |
Auf den blauen Button 'Send' klicken. → Im unteren Bereich erscheint die Antwort von Billomat → Dort sind alle Kunden des Accounts aufgelistet! |
3.3 Weitere nützliche Test-Anfragen
Diese Anfragen sind alle sicher (GET) und können gefahrlos ausprobiert werden:
| Was ich testen möchte | Methode | URL |
|---|---|---|
| Alle Kunden anzeigen | GET | BILLOMATID.billomat.net/api/clients |
| Einen bestimmten Kunden (ID 123) | GET | BILLOMATID.billomat.net/api/clients/123 |
| Alle Rechnungen anzeigen | GET | BILLOMATID.billomat.net/api/invoices |
| Nur offene Rechnungen | GET | BILLOMATID.billomat.net/api/invoices?status=OPEN |
| Alle Angebote anzeigen | GET | BILLOMATID.billomat.net/api/offers |
| Alle Artikel anzeigen | GET | BILLOMATID.billomat.net/api/articles |
| Eigene Account-Infos | GET | BILLOMATID.billomat.net/api/clients/myself |
💡 Was bedeutet das '?' in der URL? Das Fragezeichen leitet einen 'Filter' ein. Mit ?status=OPEN bekommt man nur die offenen Rechnungen, statt alle. Man kann mehrere Filter mit '&' verknüpfen, z.B.: ?status=OPEN&client_id=456
3.4 Postman-Übersicht (Benutzeroberfläche)
| Bereich in Postmen | Was ich dort tue |
|---|---|
Methode (links oben) |
GET / POST / PUT / DELETE auswählen |
URL-Leiste (Mitte oben) |
Die vollständige Adresse der Anfrage eingeben |
Headers (Reiter) |
API-Key und Accept-Format eintragen |
Body (Reiter) |
Nur bei POST/PUT: Hier kommen die Daten rein, die man schicken möchte |
Send (blauer Button) |
Die Anfrage abschicken |
Response (unterer Bereich) |
Hier erscheint die Antwort von Billomat (Status-Code + Daten) |
Status (grün/rot) |
200 = OK, Alles gut. 4xx/5xx = Fehler aufgetreten |
Kommentare
0 Kommentare
Zu diesem Beitrag können keine Kommentare hinterlassen werden.