Entwicklung – Vollständige API-Referenz

Fach-API für User Exits, Dashboard-Widgets und Report-Vorlagen. Basis ist https://core-backend.reybex.com/api (Staging: https://io-staging-partner.reybex.com/api). Authentifizierung wie im API: --header "authorization: Basic $TOKEN".

Der User Exit hängt an einer Service-Methode der Fachmodule, zum Beispiel Artikel, Auftrag oder FiBu-Beleg. Die Fachdaten stehen auf den jeweiligen API-Seiten.

Der schreibende Weg des User Exit ist POST /api/runnableServiceEvent/. Der des Widgets ist POST /api/widget/. Der Körper ist der Datensatz selbst, ohne Umschlag.

1. Grundlagen

Objekt	Rolle
RunnableServiceEvent	Groovy-Skript vor oder nach einer Service-Methode
Widget	Kachel auf dem Dashboard
WidgetDashboard	Anordnung der Kacheln
WidgetType	Art der Kachel
JasperReport	Druckvorlage

Die Zahlen in den Beispielen sind Beispiel-Ids eines Mandanten. 98001 ist der User Exit.

serviceMethod ist standardmäßig save. isActive false lässt den Exit liegen. sortOrder bestimmt die Reihenfolge mehrerer Exits an derselben Methode.

1.1 Suchschlüssel

User Exit und Widget speichern keine Partner-Referenz über customerNo oder matCode. Rollen am Widget-Typ werden per id gesetzt.

1.2 Antwort- und Fehlerformat

Speichern liefert die id. Lesen kapselt den Datensatz. Ein unbekannter Exit ist nicht gefunden.

Situation	Körper
Exit nicht gefunden	nicht gefunden
Skript bricht beim Fachaufruf ab	die Meldung des Skripts, der Fachaufruf läuft nicht weiter
Fehlende Anmeldung	HTTP 401

2. User Exit

POST /api/runnableServiceEvent/ legt an, wenn keine id im Körper steht.

2.1 Felder

Feld	Bedeutung
serviceClass	Klasse, an der das Skript hängt
serviceMethod	Methode. Standard save
beforeCode	Skript vor der Methode
afterCode	Skript nach der Methode
description	Bezeichnung
isActive	Aktiv. Standard false
sortOrder	Reihenfolge. Standard 0
commitMessage	Kommentar zur Änderung

2.2 Pflichtfelder

Auflösung, wenn ein Pflichtfeld fehlt

Die API setzt die Klasse nicht von selbst. Fehlt ein Feld, in dieser Reihenfolge füllen. Der erste Treffer gilt.

1. Angabe – Wert aus dem Auftrag für dieses Feld.
2. Vorlage – dasselbe Feld aus GET /api/runnableServiceEvent/{id}. id nicht übernehmen. Ist eine Vorlage genannt, diese lesen. Ist keine genannt, keine raten, mit Schritt 3 weiter.
3. Standard – Wert aus der Tabelle.
4. Domäne – erlaubte Klassen über GET /api/runnableServiceEvent/domains und Methoden über GET /api/runnableServiceEvent/runnableServices.
5. Stopp – serviceClass steht nicht in der Liste. Exit nicht anlegen.

Feld	Pflicht	Vorlage	Standard	Domäne
serviceClass	ja	serviceClass	—	runnableServices
serviceMethod	nein	serviceMethod	save	—
beforeCode oder afterCode	ja, eines von beiden	dasselbe Skript	—	—
isActive	nein	isActive	false, bis das Skript geprüft ist	—
sortOrder	nein	sortOrder	0	—

2.3 Exit anlegen

Zuerst GET /api/runnableServiceEvent/domains und GET /api/runnableServiceEvent/runnableServices. serviceClass und serviceMethod müssen aus diesen Listen stammen.

Vor der Methode sind object und inputObject die Argumente. Nach der Methode ist object das Ergebnis, returnObject dasselbe Ergebnis, inputObject bleiben die Argumente. rlog schreibt das Protokoll.

{
  "serviceClass": "MaterialService",
  "serviceMethod": "save",
  "description": "Protokoll vor dem Speichern",
  "isActive": false,
  "sortOrder": 10,
  "beforeCode": "rlog.info(object?.toString())"
}

MaterialService nur verwenden, wenn die Klassenliste ihn enthält. Sonst die Klasse aus der Liste einsetzen.

Response enthält die id. Ein Fehler im Skript beginnt mit USER-EXIT: und nennt Klasse, Methode und Before oder After.

Prüfen, ohne zu speichern: POST /api/runnableServiceEvent/analyzeScript. Beispiele: GET /api/runnableServiceEvent/codeExamples/{id}. Historie: GET /api/runnableServiceEvent/listEventHistory/{id}. Unterschied: GET /api/runnableServiceEvent/getEventDiff/{eventId}/{eventHistoryId}.

Lesen: GET /api/runnableServiceEvent/98001. Löschen: DELETE /api/runnableServiceEvent/98001. Antwort { "success": true }.

isActive erst auf true setzen, wenn analyzeScript das Skript annimmt.

3. Dashboard

POST /api/widgetType/ speichert die Art. Diagrammtypen: GET /api/widgetType/chartTypes. Rechte: GET /api/widgetType/getRights/{id} und POST /api/widgetType/saveRights.

POST /api/widget/ speichert die Kachel. Alle Kacheln: POST /api/widget/updateAllWidgets. Einschalten: POST /api/widget/activateWidget. Ausschalten: POST /api/widget/deactivateWidget. Daten: GET /api/widget/getData/{widgetName}.

Dashboard: POST /api/widgetDashboard/. Vorlagen: GET /api/widgetDashboard/getWidgetTemplates. Löschen: DELETE /api/widgetDashboard/{id}.

4. Reports

Vorlage speichern: POST /api/jasperReport/. Lesen: GET /api/jasperReport/{id}. Aktiv schalten: GET /api/jasperReport/changeActiveState. Löschen: DELETE /api/jasperReport/{id}.

Vorlagen der Gestaltung: GET /api/reportGenerating/reportTemplates. Typen: GET /api/reportGenerating/reportTypesForEditor. Felder eines Objekts: POST /api/reportGenerating/objectFields.

Ein benannter Report: GET /api/report/reportByName/{reportName}/{id} oder POST /api/report/reportByName/{reportName}.

4.1 Plugin, Tabelle, Agent-Event

Plugin installieren: POST /api/plugin/{pluginMaterialId}/install. Entfernen: POST /api/plugin/{pluginMaterialId}/uninstall. pluginMaterialId ist die Artikel-Id des Plugins.

Eigene Tabelle: POST /api/customTableConfig/. Der Körper ist der Datensatz. relatedDomain ist die Domäne, an der die Tabelle hängt. columnSettings beschreibt die Spalten.

{
  "name": "Seriennummern",
  "relatedDomain": "Material",
  "isActive": true,
  "showAsTab": true
}

Zeile speichern: POST /api/customTableRecord/save mit customTableConfigId. Fehlt die Id: die Tabelle wird nicht gefunden. Liste: GET /api/customTableRecord/list. CSV: POST /api/customTableRecord/importCsv. Schaltfläche: POST /api/customTableButton/.

Agent-Events abonnieren: POST /api/agentEventSubscriptions/sync. Aktive: GET /api/agentEventSubscriptions/enabled. Offene Ereignisse: GET /api/agentEventOutbox/pending. Quittieren: POST /api/agentEventOutbox/ack. Als fehlgeschlagen markieren: POST /api/agentEventOutbox/fail.

Widget-Felder

Feld	Bedeutung
name	Schlüssel der Kachel
type	Art
rowNumber, col	Position
sizex, sizey	Größe
isActive	sichtbar. Standard true
widgetDashboard	Dashboard, über id

5. Weitere Beispiele

5.1 Exit vor der Artikelanlage

1. Klassenliste lesen.
2. Exit mit isActive false anlegen, Abschnitt Exit.
3. POST /api/runnableServiceEvent/analyzeScript.
4. Denselben Exit mit isActive true speichern.
5. Artikel über Artikelstamm-Verwaltung anlegen und die Wirkung lesen.

6. Endpoint-Katalog

Methode	Pfad	Bedeutung
GET	/api/runnableServiceEvent/{id}	Ein User Exit
POST	/api/runnableServiceEvent/	Exit speichern
DELETE	/api/runnableServiceEvent/{id}	Exit löschen
GET	/api/runnableServiceEvent/domains	Klassen
GET	/api/runnableServiceEvent/runnableServices	Methoden
POST	/api/runnableServiceEvent/analyzeScript	Skript prüfen
GET	/api/runnableServiceEvent/listEventHistory/{id}	Historie
POST	/api/widget/	Widget speichern
POST	/api/widget/activateWidget	Einschalten
GET	/api/widget/getData/{widgetName}	Daten
POST	/api/widgetDashboard/	Dashboard speichern
GET	/api/widgetDashboard/getWidgetTemplates	Vorlagen
POST	/api/widgetType/	Widget-Art
POST	/api/jasperReport/	Report-Vorlage
GET	/api/reportGenerating/reportTemplates	Vorlagen der Gestaltung
GET	/api/report/reportByName/{reportName}/{id}	Report ausführen
POST	/api/plugin/{pluginMaterialId}/install	Plugin installieren
POST	/api/customTableConfig/	Eigene Tabelle
POST	/api/customTableRecord/save	Zeile, Feld customTableConfigId
POST	/api/agentEventSubscriptions/sync	Abonnement
GET	/api/agentEventOutbox/pending	Offene Ereignisse
POST	/api/agentEventOutbox/ack	Quittieren

7. Häufige Fehler

Situation	Ursache
Exit läuft nicht	isActive ist false oder serviceClass und serviceMethod treffen die Fachmethode nicht
Skriptprüfung schlägt fehl	beforeCode oder afterCode ist kein gültiges Skript
Fachaufruf mit USER-EXIT:	das Skript hat eine Exception geworfen
Widget ohne Daten	der Name in getData trifft kein aktives Widget
Report fehlt	die Vorlage ist nicht aktiv