API, Webhooks und Automatisierung

Stellt API-Token, ausgehende Webhooks und eine Automatisierungs-App für Make bereit. Gedacht für kleine Unternehmen und Gründerinnen und Gründer.

Wo das hingehört

Diese Funktion gehört zum Bereich Firmen & Schnittstellen — Fin3000. Dort steht, wie sie mit den übrigen Funktionen zusammenspielt.

Sobald ein Shop, ein CRM und die Buchhaltung nebeneinander laufen, entsteht Übertragungsarbeit: Kunde anlegen, Produkt pflegen, Rechnung nachtragen. Wer diese Buchhaltung automatisieren will, braucht zwei Richtungen — einen Zugang, über den fremde Systeme schreiben dürfen, und ein Signal, wenn in Fin3000 etwas passiert.

Schritt für Schritt

1. Zugangstoken anlegen, einer Firma zuordnen und eine von drei Stufen wählen: nur lesen, lesen und schreiben oder zusätzlich löschen.
2. Den Klartext des Tokens sofort sichern — er wird genau einmal ausgegeben und danach nur noch als Prüfsumme gespeichert.
3. Ziel-Adresse für ausgehende Meldungen hinterlegen, das gemeinsame Geheimnis setzen und die gewünschten Ereignisse anhaken.
4. Im Automatisierungsdienst Make den fertigen Bauplan laden; er bringt zwei Auslöser für neue Verkaufsbelege und neue Kunden sowie zwei Aktionen zum Anlegen von Kunden und Produkten mit.
5. Im Zustellprotokoll prüfen, welche Meldung mit welchem Antwortcode angekommen ist, und einzelne Zustellungen erneut anstoßen.

Ein Token besteht aus 64 Hexadezimalzeichen aus einem kryptografisch sicheren Zufallsgenerator. Gespeichert wird nur ein PBKDF2-SHA256-Hash; die ersten acht Zeichen dienen als Präfix, damit der Server die passende Zeile findet, ohne alle Datensätze durchzurechnen. Ein Token hängt an genau einer Firma, und die erreichbaren Pfade sind bewusst eng gehalten.

Ausgehende Meldungen tragen einen festen Umschlag mit Ereignisname, eigener Ereigniskennung und Zeitstempel. Jede Anfrage ist mit HMAC-SHA256 über Zeitstempel und Rumpf signiert und trägt die Signatur im Kopf X-Fin3000-Signature, dazu Ereignisname, Zeitstempel und eine Zustellkennung. Wer die Kennung auf der Gegenseite auswertet, verarbeitet eine Wiederholung nicht doppelt.

Zugestellt wird mit zehn Sekunden Zeitlimit. Netzfehler und Antworten der 500er-Reihe werden bis zu dreimal wiederholt, mit wachsendem Abstand von 60 bis 600 Sekunden; eine Antwort der 400er-Reihe gilt als endgültig, weil ein abgelehnter Rumpf beim vierten Versuch derselbe bleibt. Das Geheimnis liegt verschlüsselt, und die Ziel-Adresse wird gegen interne Netze geprüft und auf die einmal aufgelöste IP festgenagelt.

Was die Funktion nicht tut

Ausgehende Meldungen gibt es für genau zwei Ereignisse: eine neu erstellte Rechnung und einen erkannten Zahlungseingang. Weitere Ereignisse lassen sich nicht selbst definieren, und eingehende Webhooks nimmt Fin3000 nicht entgegen — der Weg hinein führt über die Schnittstelle mit Token.

Die drei Rechtestufen wirken pauschal; ein Token auf einzelne Endpunkte zu begrenzen, ist nicht vorgesehen. Ein Ablaufdatum gibt es nicht, ein Token wird durch Deaktivieren ungültig. Im Zustellprotokoll lässt sich eine einzelne Zustellung wiederholen, eine Sammelwiederholung über einen Zeitraum nicht.