Xentral

Zweck

Der Xentral Connector bietet eine umfassende Schnittstelle zur Integration mit der Xentral REST-API (v1). Er ermöglicht die Automatisierung einer Vielzahl von ERP-Vorgängen und erlaubt die Verwaltung zentraler Geschäftsentitäten wie Artikel, Kontakte, Aufträge und Projekte direkt aus Workflows.

Mit diesem Connector lassen sich folgende Aufgaben erledigen:

• Artikel verwalten: Artikel erstellen, abrufen, aktualisieren und löschen sowie Lagerbestände, Preise und Bilder verwalten.

• Kontakte handhaben: Kontaktdaten erstellen, aktualisieren, löschen und abrufen – einzeln oder als Liste.

• Aufträge bearbeiten: Auftragsdetails abrufen, neue Aufträge anlegen, bestehende aktualisieren und löschen.

• Projekte und Tickets verwalten: Projekte erstellen und verwalten sowie Ticketinformationen aus dem Xentral-System abrufen.

• Datei-Uploads durchführen: Eine spezielle Aktion ermöglicht das Hochladen von Bildern für Artikel.

Praktische Anwendungshinweise

• Authentifizierung: Ein statischer API-Token wird zur Authentifizierung genutzt und bei jeder Anfrage automatisch als Bearer-Token im Authorization-Header gesendet.

• Paginierung: Listenanfragen (z.B. „Artikel abrufen“) unterstützen die Paginierung über die Parameter page und limit zur effizienten Verarbeitung großer Datenmengen.

• Filterung: Der filter-Parameter akzeptiert JSON-Objekte, um flexible und gezielte Abfragen innerhalb von Listenendpunkten zu ermöglichen.

• Bild-Uploads: Die Aktion „Artikelbild hochladen“ erfordert Dateiinhalt und Dateinamen. Der Connector erstellt automatisch die notwendige multipart/form-data-Anfrage.

Bei Bild-Uploads muss der Dateiinhalt (z. B. Base64-kodiert) und der Dateiname übergeben werden. Der Connector wandelt diese Eingaben in eine multipart/form-data-Anfrage um.

Authentifizierung

• URL: Basis-URL der Xentral-Instanz.

• API Token: Ein in den Xentral-Benutzereinstellungen generierter API-Token vom Typ „Hash“ (kein temporärer JWT).

Erwartungen an Ein- und Ausgabe

Eingabe

• Pfad-Parameter: Für Aktionen auf Einzelressourcen, wie z.B. „Artikel nach ID abrufen“, ist die Ressource-ID (id) erforderlich.

• Query-Parameter: Listenabfragen können optional page, limit und filter enthalten.

• JSON-Body: Beim Erstellen oder Aktualisieren wird ein data-Objekt im JSON-Format mit den relevanten Attributen erwartet.

• Datei-Upload: Die Aktion „Artikelbild hochladen“ benötigt die Artikel-id, den fileContent des Bildes und den fileName.

Ausgabe

• response: Enthält den JSON-Body der API-Antwort.

• header: Enthält die Response-Header, sofern die Option „Header ausgeben“ aktiviert wurde.

• createResponseDataStructure: Unterstützt die Generierung einer Datenstruktur aus der response zur erleichterten Weiterverarbeitung im Workflow.