API-Zugänge und Webhooks
Fremdsystemen wie ERP oder Leitstelle Zugriff über die API geben, Berechtigungen und Ablauf festlegen und per Webhook über neue Aufträge, Berichte und Störungen informieren.
Stand:
Über die Schnittstelle (API) tauschen Fremdsysteme Daten mit Revisio aus – etwa ein ERP-System, eine Leitstelle oder ein Auswertungswerkzeug. Mit Webhooks benachrichtigt Revisio diese Systeme, sobald etwas passiert, zum Beispiel ein Auftrag abgeschlossen wurde. Beides richten Sie unter Verwaltung → API & Webhooks ein; die Seite erfordert das Recht Einstellungen verwalten.
Unten im Abschnitt Schnittstelle stehen die Adresse der API, der Link zur technischen Beschreibung (OpenAPI 3.1), die Art der Anmeldung, das Rate-Limit und die Webhook-Signatur. Geben Sie diese Angaben an die Entwickler des Fremdsystems weiter.
API-Zugang anlegen#
- Klicken Sie bei API-Zugänge auf Zugang anlegen. Revisio fragt gegebenenfalls Ihr Passwort ab.
- Geben Sie eine Bezeichnung ein, die sagt, wofür der Zugang dient, z. B. „ERP-Anbindung“.
- Wählen Sie die Berechtigungen.
- Legen Sie unter Gültig bis ein Ablaufdatum fest (höchstens zwei Jahre; leer = unbegrenzt).
- Klicken Sie auf Zugang anlegen.
| Berechtigung | erlaubt |
|---|---|
| Stammdaten lesen | Kunden, Objekte, Anlagen mit SW-Nummer, Auftragstypen |
| Aufträge lesen | Auftragsliste und -details mit Anlagen und Technikern |
| Aufträge anlegen und Status ändern | neue Aufträge, Statuswechsel im erlaubten Ablauf |
| Berichte lesen und herunterladen | Berichtsdaten mit Prüfcode und Adresse der Prüfseite, zeitlich begrenzte PDF-Links |
| Störungen lesen | Störungsliste und Störungskategorien |
| Störungen anlegen | Störungen an Anlagen melden |
Achtung
Der Token (beginnt mit rvs_) erscheint nur ein einziges Mal oben auf der Seite. Kopieren Sie ihn sofort und
hinterlegen Sie ihn im Fremdsystem. Danach erkennen Sie den Zugang nur noch an den letzten vier Zeichen.
Vergeben Sie nur so viele Berechtigungen wie nötig. Abschluss, Prüfprotokoll, Berichtsversand und Abrechnung sind über die API nicht möglich.
Zugänge im Blick behalten#
- Zuletzt genutzt zeigt Zeitpunkt und IP-Adresse des letzten Aufrufs.
- Widerrufen sperrt den Zugang sofort, auch bereits ausgegebene PDF-Links. Das lässt sich nicht rückgängig machen; legen Sie bei Bedarf einen neuen Zugang an.
- Änderungen über die API stehen im Protokoll mit dem Namen des Zugangs.
Webhook anlegen#
- Klicken Sie bei Webhooks auf Webhook anlegen.
- Geben Sie eine Bezeichnung und die Empfänger-Adresse ein. Erlaubt sind nur öffentlich erreichbare HTTPS-Adressen.
- Wählen Sie die Ereignisse: Auftrag angelegt, Auftrag abgeschlossen, Bericht erzeugt, Störung angelegt, Anlage geändert.
- Speichern Sie.
Nach dem Anlegen erscheint einmal das Signaturgeheimnis (beginnt mit whsec_). Hinterlegen Sie es beim Empfänger,
damit er die Echtheit jeder Nachricht prüfen kann. Die Nachrichten enthalten nur Nummern, Kennungen und Status, keine
Namen oder Adressen; Einzelheiten holt das Fremdsystem über die API.
Webhook prüfen und pflegen#
Ein Klick auf den Webhook öffnet seine Seite mit dem Zustellprotokoll.
| Schaltfläche | Wirkung |
|---|---|
| Test senden | schickt sofort eine signierte Testnachricht und zeigt HTTP-Status und Dauer |
| Bearbeiten | Adresse und Ereignisse ändern; ohne Haken Aktiv pausiert der Webhook |
| Geheimnis erneuern | erzeugt ein neues Signaturgeheimnis; das alte gilt danach nicht mehr |
| Löschen | entfernt den Webhook |
| Erneut senden | wiederholt eine fehlgeschlagene Zustellung mit derselben Ereignis-ID |
Das Zustellprotokoll zeigt Status, Versuche, die Antwort des Empfängers und den gesendeten Inhalt; die Einträge bleiben 30 Tage. Scheitert eine Zustellung, versucht Revisio es bis zu fünfmal mit wachsendem Abstand.
Hinweis
Nach fünf endgültig gescheiterten Zustellungen in Folge deaktiviert Revisio den Webhook automatisch; der Systemstatus zeigt dann eine Warnung. Prüfen Sie den Empfänger, senden Sie einen Test und aktivieren Sie den Webhook wieder.
Häufige Fragen#
Das Fremdsystem bekommt „nicht berechtigt“. Der Token ist falsch, widerrufen oder abgelaufen, oder die Berechtigung fehlt. Legen Sie bei Bedarf einen neuen Zugang an.
Die Empfänger-Adresse wird abgelehnt. Adressen im eigenen Netz (z. B. 192.168.x.x oder localhost) sind aus Sicherheitsgründen nicht erlaubt. Der Empfänger muss über HTTPS öffentlich erreichbar sein.