REST-/API-Schnittstelle

venabo stellt eine vollständige REST-API bereit, über die Sie Daten auslesen, erstellen und ändern können. Die integrierte Swagger-Oberfläche gibt Ihnen einen übersichtlichen Einstieg in alle verfügbaren Endpunkte.

---

Swagger-Oberfläche aufrufen

Rufen Sie die folgende URL in Ihrem Browser auf, um die Swagger-Dokumentation Ihrer venabo-Installation zu öffnen:

Dort finden Sie alle in Ihrer venabo-Version verfügbaren API-Endpunkte sowie generierte Beispiel-JSON-Strukturen, die Ihnen beim Aufbau eigener Requests helfen.

---

API-Token einrichten

Bevor Sie die REST-API nutzen können, legen Sie in der Benutzerverwaltung einen dedizierten API-Benutzer an. Die Authentifizierung erfolgt anschließend über den generierten Token.

API-Benutzer anlegen

1. Öffnen Sie in venabo den Bereich Verwaltung → Benutzer.
2. Klicken Sie auf Neuer Benutzer.
3. Stellen Sie den Benutzertyp auf API.
4. Weisen Sie dem Benutzer über Rollen oder Einzelrechte die benötigten Berechtigungen zu.
5. Speichern Sie den Benutzer – venabo generiert automatisch den API-Token.

---

Beispielaufrufe und Dokumentation

Ein vollständiges REST-Beispiel mit konkreten Beispielaufrufen steht im venabo-Downloadbereich zur Verfügung:

---

Erweiterte API-Funktionen

Die venabo REST-API umfasst neben den Standardendpunkten auch folgende erweiterte Bereiche:

Erweiterung	Beschreibung
Zulage	Zulagen über die API abrufen und verwalten
Mitarbeiter- und Tätigkeitszuweisungen	Zuweisungen für Aufträge lesen und schreiben
Filter für Adressen	Adressdaten gefiltert abrufen
Einsatzplanung	Einsätze planen und abrufen

Die vollständige API-Beschreibung zu allen Erweiterungen ist über die Swagger-Oberfläche einsehbar.

---

Praxisbeispiel

Szenario: Sie möchten aus einem externen System Mitarbeiterdaten aus venabo abrufen und neue Zeiteinträge automatisch anlegen.

1. Legen Sie in venabo einen API-Benutzer mit den Rechten Mitarbeiter lesen und Zeiten schreiben an (Typ: API, Content-Hash deaktiviert).
2. Öffnen Sie SERVERADRESSE/api/v1/docs und suchen Sie den Endpunkt GET /employees.
3. Tragen Sie Ihren API-Token im Swagger-Interface unter Authorize ein.
4. Führen Sie einen Testaufruf aus – Swagger zeigt Ihnen die Antwortstruktur direkt im Browser.
5. Übernehmen Sie die JSON-Struktur aus dem Downloadbereich und passen Sie Ihren Request entsprechend an.
6. Senden Sie den fertigen Request aus Ihrem externen System an den venabo-Endpunkt.

---

Häufige Fragen

Warum wird mein API-Token abgelehnt?

Prüfen Sie zunächst, ob der Benutzertyp korrekt auf API gesetzt ist und die Option Content-Hash deaktiviert wurde. Außerdem muss der Benutzer die benötigten Rechte für den jeweiligen Endpunkt besitzen.

Wo finde ich alle verfügbaren Endpunkte meiner venabo-Version?

Alle Endpunkte Ihrer Installation sind direkt in der Swagger-Oberfläche unter SERVERADRESSE/api/v1/docs aufgelistet. Da der Funktionsumfang je nach venabo-Version variiert, ist diese Ansicht stets die aktuellste Referenz.

Kann ich die API auch für automatisierte Importe nutzen?

Ja. Die venabo REST-API unterstützt sowohl lesende als auch schreibende Zugriffe. Sie können darüber Daten automatisiert importieren, exportieren oder mit Drittsystemen synchronisieren – sofern der API-Benutzer die entsprechenden Rechte besitzt.

Was ist der Unterschied zwischen Standard- und erweiterter API?

Die Standard-API deckt grundlegende Endpunkte ab. Die erweiterte API ergänzt zusätzliche Bereiche wie Zulagen, Einsatzplanung, Adressfilter und Tätigkeitszuweisungen. Alle verfügbaren Endpunkte – Standard und Erweiterung – sind gemeinsam über Swagger einsehbar.

---

Zusammenfassung

Thema	Details
Swagger-URL	SERVERADRESSE/api/v1/docs
Authentifizierung	API-Token (Benutzertyp: API)
Content-Hash	Muss für API-Benutzer deaktiviert sein
Beispielaufrufe	https://doku.venabo.de/download/
Erweiterte Funktionen	Zulagen, Tätigkeitszuweisungen, Adressfilter, Einsatzplanung
Datenformat	JSON