Automatisierung
API und Webhooks
Programme, Zapier, Make oder n8n mit einem API-Schlüssel verbinden, Rechte wählen, Änderungen sicher wiederholen und Webhooks einrichten.
Überblick
Mit der SoPasst-API verbinden Sie Ihre eigenen Programme, Ihren Webshop oder Werkzeuge wie Zapier, Make und n8n mit Ihrer Firma in SoPasst. Webhooks melden Ihrer Anwendung sofort, wenn ein Beleg ausgestellt oder gesendet oder eine Zahlung erfasst wurde.
Voraussetzungen
- Paket Planet, Stern oder Galaxie mit aktivem Abonnement (auch in der Testphase). Im Paket Komet ist die API nicht enthalten.
- Sie sind Inhaberin, Inhaber oder Admin der Firma. Andere Rollen sehen die Seite Einstellungen › KI-Assistenten & API › API nicht.
- Für Ausstellen, Senden und Zahlungen: Sie sind Inhaberin oder Inhaber und haben unter Einstellungen › Sicherheit die Zwei-Faktor-Anmeldung eingerichtet.
Schlüssel erstellen

- Öffnen Sie Einstellungen › KI-Assistenten & API › API.
- Geben Sie unter „Neuer Schlüssel“ einen Namen ein, zum Beispiel „Zapier Webshop“, und haken Sie nur die Rechte an, die Ihre Anwendung braucht.
- Wählen Sie „Schlüssel erstellen“ und dann „Kopieren“. Der Schlüssel beginnt mit sop_live_ und wird nur dieses eine Mal angezeigt.
- Tragen Sie den Schlüssel in Ihrer Anwendung als Bearer-Token ein: Kopfzeile Authorization, Wert „Bearer “ und dahinter der Schlüssel.
Wichtig
Rechte eines Schlüssels
- Lesen: Belege samt PDF, Kunden, Produkte und Zahlungen abrufen.
- Entwürfe schreiben: Kunden und Produkte anlegen und ändern sowie Entwürfe von Angeboten, Aufträgen, Lieferscheinen, Rechnungen und Gutschriften anlegen und ändern. Ein Entwurf hat noch keine Rechnungsnummer.
- Ausstellen: einen Entwurf (Rechnung, Angebot, Auftrag, Lieferschein) ausstellen. SoPasst prüft die Pflichtangaben, vergibt die nächste lückenlose Nummer, speichert das PDF und sperrt den Beleg.
- Senden: einen ausgestellten Beleg per E-Mail an eine gespeicherte Adresse des Kunden senden, mit Ihrer Vorlage oder eigenem Text.
- Zahlungen erfassen: Zahlungseingänge zu Rechnungen buchen, mit denselben Regeln wie das Zahlungsformular in der App.
- Ausstellen, Senden und Zahlungen erteilt nur die Inhaberin oder der Inhaber, einmal beim Erstellen des Schlüssels, mit dem Code aus der Authenticator-App. Danach fragt SoPasst nicht bei jedem Aufruf nach. Gutschrift, Storno und Mahnung stellen Sie nur in der App aus.
Die erste Anfrage
- Die Adresse der API ist https://app.sopasst.at/api/v1. Die Beschreibung aller Endpunkte steht unter https://app.sopasst.at/api/v1/openapi.json; Zapier, Make, n8n und Postman lesen sie direkt ein.
- Prüfen Sie den Schlüssel mit GET /api/v1/me. Die Antwort nennt die Rechte des Schlüssels, Ihr Paket und die Nutzung im laufenden Monat und am heutigen Tag.
- Beträge sind immer ganze Cent in Euro, Datumsangaben haben die Form JJJJ-MM-TT. Alle Änderungen sind POST-Anfragen mit JSON.
Änderungen sicher wiederholen
- Jede POST-Anfrage braucht die Kopfzeile Idempotency-Key mit einem eindeutigen Wert, zum Beispiel einer UUID. Ohne sie antwortet die API mit idempotency_key_required.
- Schickt Ihre Anwendung dieselbe Anfrage mit demselben Wert innerhalb von 24 Stunden noch einmal, etwa nach einem Verbindungsabbruch, antwortet SoPasst mit dem gespeicherten Ergebnis und der Kopfzeile idempotent-replayed. Eine Rechnung wird so nie doppelt ausgestellt und eine Zahlung nie doppelt gebucht.
- Derselbe Wert mit einem anderen Inhalt wird mit idempotency_key_reused abgelehnt. Verwenden Sie für jede neue Änderung einen neuen Wert.
- Schlägt eine Anfrage fehl, wird nichts gespeichert und keine Rechnungsnummer verbraucht. Nach der Korrektur können Sie denselben Wert erneut verwenden.
Webhooks einrichten
- Öffnen Sie Einstellungen › KI-Assistenten & API › API und tragen Sie unter Webhooks die Adresse Ihrer Anwendung ein. Erlaubt sind nur https-Adressen auf Port 443 mit einem öffentlichen Hostnamen.
- Wählen Sie die Ereignisse: document.issued (auch Storno und Mahnung), document.sent und payment.recorded. Wählen Sie „Webhook hinzufügen“.
- Kopieren Sie das angezeigte Signatur-Geheimnis (whsec_…). Es wird nur einmal angezeigt.
- Prüfen Sie in Ihrer Anwendung jede Nachricht: Die Kopfzeilen webhook-id, webhook-timestamp und webhook-signature folgen dem Standard „Standard Webhooks“; viele Bibliotheken prüfen die Signatur mit einer Zeile.
Wichtig
Erwartetes Ergebnis
Ihre Anwendung erhält Antworten im JSON-Format: ein angelegter Entwurf erscheint sofort in SoPasst, ein ausgestellter Beleg hat seine endgültige Nummer und sein PDF, und jeder Webhook erreicht Ihre Adresse mit gültiger Signatur. Einstellungen › KI-Assistenten & API › API zeigt die Nutzung im laufenden Monat, wann jeder Schlüssel zuletzt verwendet wurde, und das Zustellprotokoll der letzten 20 Webhooks.
Häufige Probleme
- Monatskontingent: Planet 5.000 Anfragen und 300 über die API angelegte Belege, Stern 50.000 und 3.000, Galaxie 500.000 und 10.000. Jede Anfrage zählt, auch eine fehlerhafte.
- Pro Schlüssel und Minute: Planet 60, Stern 120, Galaxie 300 Anfragen. Für Ausstellen, Senden und Zahlungen gilt zusätzlich ein Tageslimit; GET /api/v1/me zeigt es.
- Ist ein Kontingent erreicht, antwortet die API mit HTTP 429 und nennt in der Kopfzeile Retry-After, wann es weitergeht. Es entstehen nie automatisch Zusatzkosten.
- Jeder Fehler hat einen festen Code, zum Beispiel unauthorized (Schlüssel fehlt oder ist widerrufen), insufficient_scope (Recht fehlt), validation_failed (zum Beispiel fehlende Pflichtangaben) oder quota_exceeded. Geben Sie bei Fragen an den Support den Wert der Kopfzeile x-request-id an, nie den Schlüssel.
Sicher weiterarbeiten
- Öffnen Sie Einstellungen › KI-Assistenten & API › API.
- Wählen Sie beim Schlüssel „Widerrufen“ und dann „Schlüssel widerrufen“, oder beim Webhook „Entfernen“ und dann „Webhook entfernen“.
- Der Zugriff endet sofort und lässt sich nicht wiederherstellen. Erstellen Sie bei Bedarf einen neuen Schlüssel. Widerrufen und Entfernen geht auch, wenn das Abonnement gesperrt ist.