14. Integrationen

Zwei Wege, dieses Konto mit einem anderen System zu verbinden. API-Schlüssel lassen ein fremdes System hier lesen und schreiben; Webhooks lassen uns dem fremden System melden, dass etwas passiert ist. Beide finden Sie unter Integrationen; beide setzen die Berechtigung „API-Schlüssel verwalten" voraus, die nur Inhaber und Administratoren haben.

API-Schlüssel

Ein Schlüssel meldet sich genauso an wie ein Mensch — über dieselben Adressen, mit denselben Berechtigungen. Das ist Absicht: es gibt keine zweite, abweichende Schnittstelle, die irgendwann anders funktioniert als das Portal.

curl https://rechnung.tatwelletech.de/api/v1/portal/customers \
  -H "X-API-Key: twt_..."

Authorization: Bearer twt_... funktioniert genauso.

Drei Regeln, die Sie kennen sollten:

Der Schlüssel wird genau einmal angezeigt. Es gibt keine Schaltfläche, ihn später noch einmal zu sehen — ein Schlüssel, den man nachlesen kann, liegt irgendwann in einem Screenshot und in einem Support-Ticket. Verloren heißt ersetzen.

Ein Schlüssel kann nie mehr als die Person, die ihn erstellt hat. Sie wählen beim Anlegen Berechtigungen aus, und angeboten werden nur die, die Sie selbst besitzen. Wählen Sie so wenige wie möglich: ein Schlüssel für die Warenwirtschaft braucht meist nur Kunden lesen und Rechnungen anlegen.

Ein Schlüssel gehört zu genau einem Unternehmen. Der Kopfzeilen-Wert, mit dem ein Mensch das Unternehmen wechselt, verschiebt ihn nicht.

Gesperrt wird ein Schlüssel sofort und endgültig; die Zeile bleibt sichtbar, weil ein Schlüssel, mit dem gearbeitet wurde, zur Nachvollziehbarkeit gehört.

Webhooks

Statt regelmäßig nachzufragen, ob etwas passiert ist, hinterlegen Sie eine Adresse, und wir melden uns.

Veröffentlicht werden derzeit: invoice.finalized, invoice.paid, incoming.received, incoming.approved, incoming.booked, customer.created.

Nur https, und die Adresse darf nicht im internen Netz liegen — das wird beim Speichern geprüft und noch einmal bei jeder Zustellung, weil sich ein DNS-Eintrag nachträglich ändern kann.

Zustellung und Wiederholung

Zugestellt wird im Hintergrund, nie während Sie arbeiten: Ob Ihr Server gerade antwortet, darf nicht darüber entscheiden, wie lange das Abschließen einer Rechnung dauert.

Antwortet Ihr Server nicht mit 2xx, versuchen wir es erneut — nach einer Minute, dann zwei, vier, acht, bis maximal sechs Stunden Abstand, insgesamt achtmal. Das überbrückt einen nächtlichen Ausfall, ohne jemanden zu überrennen. Danach gilt die Zustellung als fehlgeschlagen, verschwindet aber nicht: Sie sehen sie im Protokoll mit dem letzten Fehler und können sie mit Erneut senden noch einmal auf die Reise schicken, sobald Ihr System wieder läuft.

Signatur prüfen

Jede Meldung trägt den Kopf X-TWT-Signature: t=<Zeitstempel>,v1=<Signatur>. Die Signatur ist HMAC-SHA256 über <Zeitstempel>.<Rumpf>, mit dem Signaturschlüssel, den Sie beim Anlegen einmalig gesehen haben.

mac = hmac.new(secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()

Prüfen Sie immer die Signatur, und verwerfen Sie Meldungen, deren Zeitstempel deutlich in der Vergangenheit liegt — sonst könnte eine einmal abgefangene Meldung beliebig oft wiederholt werden. Weiterleitungen folgen wir nicht.

Der Kopf X-TWT-Delivery enthält eine eindeutige Kennung. Nutzen Sie sie, um doppelte Verarbeitung zu vermeiden: Wir wiederholen bei Fehlern, und eine Meldung, die Sie zwar verarbeitet, aber nicht bestätigt haben, kommt noch einmal.