Zum Inhalt springen
Zur Hilfeübersicht

Automatisierung

API und Webhooks

Programme, Zapier, Make oder n8n mit einem API-Schlüssel verbinden, Rechte wählen, Änderungen sicher wiederholen und Webhooks einrichten.

5 Min. LesezeitZuletzt geprüft: 09.10.2026
In SoPasst öffnen

Ü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. Im Paket Komet ist die API nicht enthalten.
  • Sie sind Inhaberin, Inhaber oder Admin der Firma.
  • Für Ausstellen, Senden und Zahlungen: Sie sind Inhaberin oder Inhaber und haben die Zwei-Faktor-Anmeldung eingerichtet.

Schlüssel erstellen

  1. Öffnen Sie Einstellungen › API.
  2. Geben Sie dem Schlüssel einen Namen, zum Beispiel „Zapier Webshop“, und wählen Sie nur die Rechte, die Ihre Anwendung braucht.
  3. Wählen Sie „Schlüssel erstellen“ und kopieren Sie den Schlüssel sofort. Er beginnt mit soplive und wird nur dieses eine Mal angezeigt.
  4. Tragen Sie den Schlüssel in Ihrer Anwendung als Bearer-Token ein: Kopfzeile Authorization mit dem Wert Bearer und dem Schlüssel.

Wichtig

Rechte eines Schlüssels

  • Lesen: Belege samt PDF, Kunden, Produkte und Zahlungen abrufen.
  • Entwürfe schreiben: Kunden, Produkte und 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 und sperrt den Beleg.
  • Senden: einen ausgestellten Beleg an die gespeicherte E-Mail-Adresse des Kunden senden, mit Ihrer Vorlage oder eigenem Text.
  • Zahlungen erfassen: Zahlungseingänge zu Rechnungen buchen, mit denselben Regeln wie in der App.
  • Ausstellen, Senden und Zahlungen erteilt 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. Storno und Gutschrift stellen Sie nur in der App aus.

Die erste Anfrage

  1. Die Adresse der API ist https://app.sopasst.at/api/v1. Die vollständige Beschreibung aller Endpunkte finden Sie unter https://app.sopasst.at/api/v1/openapi.json; Zapier, Make, n8n und Postman können sie direkt einlesen.
  2. 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.
  3. Beträge sind immer ganze Cent in Euro, Datumsangaben haben die Form JJJJ-MM-TT.

Änderungen sicher wiederholen

  • Jede POST-Anfrage braucht die Kopfzeile Idempotency-Key mit einem eindeutigen Wert, zum Beispiel einer UUID.
  • Schickt Ihre Anwendung dieselbe Anfrage mit demselben Schlüssel noch einmal, etwa nach einem Verbindungsabbruch, antwortet SoPasst mit dem gespeicherten Ergebnis. Eine Rechnung wird so nie doppelt ausgestellt, eine Zahlung nie doppelt gebucht und keine Rechnungsnummer verbraucht.
  • Schlägt eine Anfrage fehl, wird nichts gespeichert: Nach der Korrektur können Sie denselben Wert erneut verwenden.

Webhooks einrichten

  1. Öffnen Sie Einstellungen › API und tragen Sie unter Webhooks die Adresse Ihrer Anwendung ein. Erlaubt sind nur https-Adressen auf Port 443 mit einem öffentlichen Hostnamen.
  2. Wählen Sie die Ereignisse: document.issued, document.sent und payment.recorded.
  3. Kopieren Sie das angezeigte Signatur-Geheimnis (whsec…). Es wird nur einmal angezeigt.
  4. 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 unter Dokumente, ein ausgestellter Beleg hat seine endgültige Nummer und sein PDF, und jeder Webhook erreicht Ihre Adresse mit gültiger Signatur. Einstellungen › API zeigt die Nutzung im laufenden Monat und das Zustellprotokoll der Webhooks.

Häufige Probleme

  • Planet: 5.000 Anfragen und 300 über die API angelegte Belege pro Monat. Stern: 50.000 und 3.000. Galaxie: 500.000 Anfragen und 10.000 Belege.
  • Für Ausstellen, Senden und Zahlungen gilt zusätzlich ein Tageslimit; es liegt weit über dem üblichen Bedarf.
  • 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, insufficientscope, validationfailed oder quotaexceeded. Geben Sie bei Fragen an den Support den Wert der Kopfzeile x-request-id an.

Sicher weiterarbeiten

  1. Öffnen Sie Einstellungen › API.
  2. Wählen Sie beim Schlüssel „Widerrufen“ oder beim Webhook „Entfernen“ und bestätigen Sie direkt darunter.
  3. Der Zugriff endet sofort. Erstellen Sie bei Bedarf einen neuen Schlüssel.