Die Schnittstelle: erster Aufruf in fünf Minuten

Über die Schnittstelle tauscht ein anderes Programm Daten mit PetWorkers aus. Hier richtest du den Zugang ein und fragst seine Berechtigungen ab.

Wofür man das braucht:

• Kontakte mit dem Newsletter-Werkzeug oder dem Buchhaltungsprogramm abgleichen
• Buchungen aus einem Onlineshop oder einem eigenen Formular übernehmen
• Auswertungen in Excel, Power BI oder Google Sheets ziehen
• Abläufe automatisieren, etwa mit n8n, Make oder Zapier
• eine eigene App oder ein Kassensystem anbinden

Die API ist die Schnittstelle für andere Programme. Ein Endpunkt ist die Adresse einer bestimmten Abfrage oder Aktion. JSON ist das Textformat für die übergebenen Daten.

So legst du einen API-Schlüssel an

Ein API-Schlüssel ist der Zugang für ein anderes Programm. Seine Einstellungen bestimmen, was dieses Programm darf.

1. Melde dich als Administrator an.
2. Gehe auf System → API-Schlüssel.
3. Klicke auf Schlüssel anlegen.
4. Gib eine Bezeichnung ein, an der du den Zugang später wiedererkennst — zum Beispiel „Buchhaltung DATEV“ oder „Website-Formular“.
5. Wähle die Berechtigungsstufe. Nimm die niedrigste, die reicht. Wer nur Kontakte lesen soll, braucht keine Administratorrechte.
6. Schalte Schreiben erlauben aus, wenn das Programm nur lesen soll. Das ist die wirksamste einzelne Sicherheitsmaßnahme überhaupt.
7. Trage die Gültigkeit (Tage) ein. 365 ist ein guter Wert. 0 bedeutet unbegrenzt.
8. Klicke auf Speichern.

Die Meldung lautet „API-Schlüssel angelegt. Der Wert steht in der Liste und lässt sich dort kopieren.“ Der Schlüssel steht danach in der Liste. Über das Symbol daneben kopierst du ihn in die Zwischenablage. Er sieht zum Beispiel so aus:

Was macht das? Das ist ein erfundener Beispielschlüssel. Er gibt keinen Zugriff auf deine Instanz.

3f7c9a2e-4b81-4d6f-9a03-7c5e12f8ab44

So prüfst du deinen Zugang

Der Schlüssel gehört in den Kopf jeder Anfrage. Öffne dafür ein Terminal, also das Fenster für Befehle. Ersetze Adresse und Beispielschlüssel durch deine Werte:

Was macht das? Dieser Terminalbefehl fragt die Berechtigungen deines Schlüssels ab. Er ändert keine Fachdaten.

curl -H "Authorization: Bearer 3f7c9a2e-4b81-4d6f-9a03-7c5e12f8ab44" \
     https://deine-adresse.de/api/v1/me

Die Antwort sagt dir, was dieser Schlüssel darf:

Was macht das? Dieser gekürzte Antwortausschnitt zeigt Rechte, Laufzeit und erkannte Absender-Adresse.

{
  "data": {
    "key": { "label": "Buchhaltung DATEV", "masked": "3f7c9a2e…ab44" },
    "permissions": {
      "securitygroup_label": "Buchhaltung",
      "can_write": false,
      "accessible_resources": ["invoices", "lineitems", "payments"]
    },
    "validity": { "days_remaining": 365, "unlimited": false },
    "firewall": { "rate_limit": 120, "your_ip": "203.0.113.7" }
  }
}

Kommt eine Antwort mit data.permissions, funktioniert der Schlüssel. Die erlaubten Bereiche stehen unter accessible_resources. Kommt stattdessen ein Fehler, hilft die Seite Wenn etwas nicht geht in diesem Kapitel weiter.

Was es sonst noch gibt

Die Schnittstelle beschreibt sich selbst. Du musst nichts abtippen und nichts raten:

/api/v1/	Welche Bereiche gibt es, und was darf mein Schlüssel damit?
/api/v1/me	Angaben zum Schlüssel: Stufe, Restlaufzeit, Tempo, erkannte Absender-Adresse
/api/v1/health	Kurze Statusmeldung — eignet sich für eine Überwachung
/api/v1/<bereich>/_schema	Welche Felder hat ein Bereich, welche sind Pflicht, wonach kann ich sortieren?
/api/v1/openapi.json	Die vollständige Beschreibung zum Einlesen in Postman, Insomnia, n8n und andere Werkzeuge

Ruf einmal /api/v1/ auf. Du bekommst eine Liste aller Bereiche mit ihren deutschen Bezeichnungen — das ist die beste Übersicht, die es gibt, weil sie genau deine Instanz beschreibt.

Fertige Beispiele

Unter https://deine-adresse.de/api/beispiele/ liegen lauffähige Beispiele in fünf Sprachen: PHP, Python, JavaScript (Node), PowerShell und curl. Dazu eine Postman-Sammlung mit über 1800 vorbereiteten Anfragen.

Alles zusammen gibt es auch als ZIP-Paket. Die Beispiele zeigen jeweils denselben Ablauf: anmelden, lesen, blättern, filtern, anlegen, ändern, löschen, Fehler behandeln.

Ein Wort zur Sicherheit

Ein API-Schlüssel ist wie ein Kennwort. Drei Dinge sind wichtig:

• Niedrigste ausreichende Stufe wählen. Ein Schlüssel für eine Auswertung braucht keine Schreibrechte.
• Gültigkeit begrenzen. Ein Schlüssel, der nach einem Jahr abläuft, kann nicht ewig herumliegen.
• Absender einschränken, wenn möglich. Läuft das aufrufende Programm auf einem festen Server, trage dessen Adresse in die IP-Freigabeliste ein. Dann ist der Schlüssel woanders wertlos.

Mehr dazu auf der Seite Berechtigungen und Firewall.