Xentral-Schnittstelle und API-Integration
Xentral ist ein deutsches Cloud-ERP für produktbezogene kleine und mittlere Unternehmen, und es ist der Ort, an dem ein E-Commerce-Betrieb seine Aufträge, seinen Bestand und seine Bücher an einer Stelle hält. Jedes Produkt, das die Finanzen eines deutschsprachigen Händlers berührt, begegnet ihm früher oder später. Binden Sie es über Maesn an, und Sie erreichen es mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Was eine Xentral-Anbindung kostet
Xentral ist keine schwer aufzurufende API. Ungewöhnlich ist, was es vor der ersten Anfrage verlangt und ein Jahr später wieder: Der Schlüssel, den es ausstellt, verhält sich ganz anders als ein OAuth-Token, die Instanz des Kunden entscheidet die Adresse, und die Version gehört zum Endpunkt und nicht zur API. Maesn nimmt alle drei.
Je Mandant verwahrt, an einer Stelle entzogen
Ein persönliches Zugriffstoken von Xentral trägt kein Ablaufdatum und keinen Berechtigungs-Scope. Es erreicht also alles, was das Konto Ihres Kunden erreicht, und tut das so lange, bis jemand es löscht. Xentral zeigt es genau einmal an und rät davon ab, es in eine externe Anwendung zu geben. Maesn verwahrt es an der Verbindung, es lebt damit an einer Stelle und nicht in jedem Produkt, das es braucht.
Einmal eingesammelt, bei jedem Aufruf geroutet
Jeder Xentral-Kunde antwortet auf einem eigenen Host, und die ID vor xentral.biz ist Teil der Adresse und kein Parameter, den man übergeben kann. Schicken Sie den richtigen Schlüssel an den falschen Host, sagt Ihnen nichts am Fehler, welche Hälfte falsch war. Maesn sammelt die Instanz-ID zusammen mit dem Schlüssel ein, wenn Ihr Kunde sich verbindet, und baut von da an den richtigen Host.
Eine Schnittstelle über drei Generationen
Xentral versioniert jeden Endpunkt für sich und nicht die API als Ganzes, und eine neue Version setzt die vorige auf veraltet. Drei Generationen antworten unter demselben Schlüssel, und die zwei älteren können damit nicht jeden Endpunkt bedienen. Über Maesn rufen Sie stattdessen eine Schnittstelle auf. Eine Abkündigung auf der Seite von Xentral ist damit keine Änderung auf Ihrer.
Auf Ihrer Seite bleibt ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren. Teams sind in Tagen produktiv, statt ein Quartal auf die Eigenheiten eines Herstellers zu verwenden.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Paywise hat manuelle Rechnungsimporte durch Integrationen ersetzt
Paywise treibt unbezahlte Rechnungen für Unternehmen ein, von der ersten Mahnung bis zur gerichtlichen Durchsetzung. Ihre Kunden haben diese Rechnungen früher von Hand hochgeladen, und die Liste der offenen Posten kommt jetzt aus dem System, das jeder von ihnen ohnehin einsetzt. Xentral ist eines der fünf, die sie nennen.
“Unsere Kunden können ihre vorhandenen Werkzeuge sofort anbinden. Das erhöht die Nutzung und macht Maesn zu einem festen Bestandteil unserer Erfolgsstrategie.”
Drei Gründe, die Xentral-Schnittstelle über Maesn anzubinden
Xentral direkt anzubinden ist ein Projekt, das ein Team abschließen kann. Es zu besitzen, und danach das nächste System zu besitzen, entscheidet über eine Roadmap.
Eine Anbindung, und die nächste ist Konfiguration
Kunden, Rechnungen, Rechnungspositionen und Lieferanten kommen hier in derselben Form an wie auf jedem anderen angebundenen System, und was Ihr Anwendungsfall darüber hinaus braucht, ist eine Anfrage und kein Umbau. Das Routing zur Instanz, der dauerhafte Schlüssel und die Versionen je Endpunkt werden einmal gelöst, hier, für jeden Kunden, den Sie anbinden.
Die Verwahrung eines dauerhaften Schlüssels
Nichts an einem Xentral-Token erzwingt eine Rotation, und das ist bequem, bis man die Kopien davon zählt. Zentral verwahrt liegt es in einem System mit einem Weg zum Entzug. Je Produkt verwahrt liegt es dort, wo die letzte Integration es gelassen hat, und Xentral rät selbst dazu, es überhaupt nicht in eine externe Anwendung zu geben.
Das nächste System kostet nichts
Sobald Xentral läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle. Ihre zweite Integration ist ein Konfigurationsschritt, und die Schlüsselverwahrung und das Routing zur Instanz, die Sie hier bezahlt haben, zahlen Sie kein zweites Mal.
Ein Xentral-Schlüssel, eine Instanz je Kunde
Xentral fährt keinen OAuth-Handshake. Ihr Kunde erzeugt in seiner eigenen Instanz ein persönliches Zugriffstoken und übergibt es, und das macht die Verbindung einfacher zu beschreiben und schwerer zu betreuen: Der Schlüssel läuft nicht ab, er ist auf nichts eingegrenzt, und die Instanz, zu der er gehört, ist Teil der Adresse und nicht Teil der Nutzlast.
- Persönliches Zugriffstoken
- Von einem Administrator in der eigenen Instanz des Kunden angelegt
Ein Schlüssel und eine Instanz-ID je Kunde. Maesn verwahrt beide und setzt jeden davon dorthin, wo eine Anfrage ihn braucht.
- Das Token, einmal und je Mandant
- Xentral zeigt den Wert ein einziges Mal und bietet keinen Weg, ihn zurückzulesen. Maesn verwahrt ihn an der Verbindung. Er muss also nie durch Ihre Logs oder Ihren Support-Posteingang laufen, und das Token in Xentral zu löschen bleibt der eine saubere Weg, den Zugriff zu beenden.
- Die Instanz-ID, in den Host aufgelöst
- Die ID entscheidet, welcher xentral.biz-Host antwortet, und sie wird zusammen mit dem Schlüssel eingereicht und nicht aus ihm abgeleitet. Maesn hält das Paar zusammen und baut die Adresse bei jeder Anfrage. Ihr Code sendet für einen Xentral-Kunden also dieselbe URL-Form wie für jedes andere System.
Headless ändert hier, wie Ihr Produkt aussieht, und nicht, was es tut. Xentral gehört zu den Systemen, die sich mit einem Schlüssel statt mit einem Redirect authentifizieren. Die zwei Werte lassen sich also entweder auf einer von Maesn gehosteten Seite einsammeln oder an einen Endpunkt senden, der den Account-Key direkt zurückgibt. Der zweite Weg hält die ganze Verbindung in Ihrer eigenen Oberfläche, und bei einem System, dessen Zugangsdaten ein dauerhafter Schlüssel sind, ist das meist die Fassung, die eine Sicherheitsprüfung vorzieht.
- 1
Ihr Kunde erzeugt das Token
Ein Administrator öffnet Kontoeinstellungen, dann Entwicklereinstellungen, dann Personal Access Tokens, benennt das Token und kopiert es. Dieses Kopieren ist der einzige Moment, in dem der Wert sichtbar ist, und das Administratorrecht ist es, was den Bildschirm überhaupt erreichbar macht.
- 2
Schlüssel und Instanz-ID kommen zusammen an
Beide gehen in die Verbindung, entweder über die Seite, die Maesn hostet, oder direkt über die API. Die Instanz-ID lässt sich von Ihrer Seite vorbelegen. Ein Kunde, der Ihnen seine Xentral-Adresse bereits genannt hat, tippt sie also kein zweites Mal.
- 3
Sie arbeiten mit einem Account-Key
Maesn gibt einen Account-Key zurück und hält das Paar dahinter. Ab da trägt jede Anfrage Ihren API-Schlüssel und diesen Account-Key, dieselben zwei Header, die Sie für jedes andere unterstützte System ohnehin schon senden.
Jedes System im Katalog authentifiziert anders, und bei Xentral gibt es keinen nennenswerten Handshake und die Zugangsdaten sind das ganze Problem: ein Schlüssel, der nie altert, nie enger wird und nur ein einziges Mal erscheint. Dafür ist Unified Authentication da. Die gehostete Seite, der Headless-Weg und die Speicherung hinter beiden werden einmal für alle Systeme erledigt und nicht einmal je System, was Ihr Code hält, ist also ein Account-Key.
Was Xentral zu Events dokumentiert, und was heute freigeschaltet ist
Kein Xentral-Objekt sendet heute ein Event über Maesn. Xentral dokumentiert 152 eigene Event-Typen, von salesOrder.created bis invoice.released, und die Funktion ist in der Beta. Sie wird je Instanz freigeschaltet statt je Integration. Jeder Ihrer Kunden müsste also mit seinem eigenen Konto am Beta-Programm von Xentral teilnehmen, bevor ein einziges Event Sie erreichen könnte.
Einen Katalog von 152 Event-Typen mit einem festgelegten Umschlag für die Nutzlast, zugestellt per HTTP POST an eine Ziel-URL von höchstens 255 Zeichen. Die Funktion ist in der Beta, und die Anmeldung dafür gehört Ihrem Kunden und nicht Ihnen: Seine Instanz tritt dem Programm von Xentral bei, Konto für Konto.
Ein geplanter Lesezugriff, mit demselben lastModifiedAt-Filter und derselben Paginierung, die Sie für jedes andere System schon benutzen. Der Code, der eine Änderung in Xentral bemerkt, ist der Code, den Sie einmal geschrieben haben, nur auf einen anderen Account-Key gerichtet.
Das Intervall ist eine Produktentscheidung mit einer veröffentlichten Obergrenze dahinter. Xentral beantwortet 100 Anfragen pro Minute unabhängig vom Tarif und nennt diese Zahl vorläufig. Ein Delta-Lesezugriff über vier Objekte passt also bequem, während ein erster vollständiger Massenabzug Tempo braucht. Ein Lesezugriff erholt sich außerdem von selbst: Was ein Push während eines Ausfalls verloren hätte, holt der nächste Aufruf durch ein breiteres Fenster nach.
Ein Lesezugriff nach Zeitplan ist die Schleife, die es übersteht, falsch zu liegen. Ein Push, der ankommt, während Ihr Endpunkt nicht erreichbar ist, ist weg, sofern ihn nichts wiederholt, und ein Lesezugriff fragt einfach noch einmal mit einem breiteren Fenster. Was er dafür braucht, sind ein Filter und ein Seitenmodell, denen Sie trauen, und auf einem System, das jeden Endpunkt einzeln versioniert, driften genau diese beiden zuerst. Ein Weg, zu filtern und zu paginieren nimmt diese Fehlerklasse weg, denn der Cursor und der Zeitstempel sind keine Fragen je Endpunkt mehr. Was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei getrennte Wege, und bei Xentral ist nur der zweite eingeschaltet.
Was eine Xentral-Anbindung vorab braucht
Xentral stellt vier Dinge vor eine Integration. Drei sind an einem Nachmittag erledigt, und das zweite entscheidet, ob Sie überhaupt etwas bauen können, bevor Ihr erster Kunde kommt.
- Ein Administrator im Xentral-Konto des Kunden
- Das persönliche Zugriffstoken wird unter Kontoeinstellungen und dann Entwicklereinstellungen erzeugt, und Administratorrechte sind es, die diesen Bildschirm überhaupt erreichbar machen. Der Wert erscheint einmal und lässt sich danach nicht erneut lesen, wer ihn erzeugt, muss ihn also in diesem Moment festhalten. Dem Token den Namen Ihres Produkts zu geben macht den späteren Entzug eindeutig.
- Eine Sandbox, denn Xentral bietet keine kostenlose Testphase
- Ein Xentral-Testkonto, für das man sich selbst anmelden kann, gibt es nicht, und damit bleibt einem Team sonst nur, gegen die Live-Instanz eines Kunden zu bauen. Maesn stellt für jedes unterstützte System eine Sandbox bereit, auch für die ohne Testphase. Die erste Fassung Ihrer Integration läuft also gegen Daten, die kaputtgehen dürfen.
- Ein Budget von 100 Anfragen pro Minute
- Xentral begrenzt seine API auf 100 Anfragen je Minute, unabhängig davon, in welchem Tarif Ihr Kunde ist, und antwortet darüber mit einem 429. Es schreibt außerdem, dass der Wert noch ausgewertet wird und sich höchstwahrscheinlich ändert. Man entwirft einen Abgleich also darum herum, statt dagegen zu rechnen.
- Eine Entscheidung darüber, welche Generation aufgerufen wird
- Ein Token authentifiziert gegen die aktuelle Xentral-API, die ältere REST-API und die Standard-API gleichermaßen, und die zwei älteren können damit nicht jeden Endpunkt bedienen. Xentral führt dreizehn auf, die nicht verfügbar sind, und schreibt, dass die Liste nicht vollständig ist. Maesn ruft die aktuelle API auf. Die Frage folgt Ihnen also nicht in den Produktivbetrieb.
Wir gehen das Token, die Instanz-ID und die Sandbox mit Ihnen durch.
Eine Form für Xentral, und für das nächste System
Xentral routet je Instanz, versioniert je Endpunkt und gibt einen Schlüssel aus, der nie altert. Eine gemeinsame Form hält alle drei aus Ihrem Code heraus.
Die lesbare Seite ist die Hauptbuchseite
Xentral verkauft Auftragsverwaltung, Lagerhaltung und Mehrkanalhandel, und was heute zum Lesen freigeschaltet ist, ist das Forderungsende davon: Kunden, Rechnungen, Rechnungspositionen und Lieferanten. Bestellungen, Wareneingänge und Buchungssätze werden nicht angeboten, Kundenaufträge und Artikel sind auf Anfrage verfügbar. Ein Anwendungsfall aus der Logistik fängt deshalb mit einem anderen Gespräch an als einer aus der Finanzabteilung.
Ein Schreibweg, und nichts lässt sich bearbeiten
Kunden sind das einzige Objekt, das zum Anlegen freigeschaltet ist, und zum Aktualisieren oder Löschen ist überhaupt kein Objekt freigeschaltet. Ein Produkt, das Datensätze an Ort und Stelle korrigiert, statt neue zu buchen, sollte das gegen seinen eigenen Anwendungsfall prüfen, bevor es die Schreibseite entwirft. Die Buchhaltungspraxis erwartet Korrekturen ohnehin als neue Belege.
Auf Anfrage ist eine Anfrage und keine Sackgasse
Objekte mit der Kennzeichnung auf Anfrage fehlen nicht, sie sind nur nicht standardmäßig freigeschaltet. Fünfundfünfzig Kombinationen aus Objekt und Operation stehen dort, darunter die Kundenaufträge, Artikel und Zahlungen, mit denen ein Ablauf vom Auftrag bis zum Zahlungseingang anfängt. Sagen Sie uns, welche Ihr Anwendungsfall braucht, und sie kommen dazu.
Die Zeilen, die ein Leser gefüllt erwartet und leer vorfindet, sind hier keine Grenze von Maesn, sondern eine von Xentral. Xentral wird als ERP für Händler verkauft, Bestellungen, Wareneingänge und Auftragspositionen sind also das, wonach eine Logistikintegration zuerst greift, und Xentrals eigene Schnittstelle liefert sie noch nicht. Der Hersteller veröffentlicht eine Liste von Endpunkten, die nicht verfügbar sind, und sagt dazu, dass die Liste nicht vollständig ist, was eine faire Beschreibung einer API ist, die noch im Aufbau ist.
Das lohnt sich zu wissen, bevor Sie den Umfang festlegen, denn es bewegt sich mit der Zeit und nicht mit Ihrem Aufwand. Verfügbar ist heute das Debitorenende desselben Produkts: Kunden, Rechnungen, Rechnungspositionen und Lieferanten, also die Oberfläche, die ein Finanz-Anwendungsfall tatsächlich braucht. Sobald Xentral den Rest ausliefert, kommen die Objekte hier an, ohne dass auf Ihrer Seite eine zweite Integration nötig wäre.
Das ist der Moment, in dem sich ein gemeinsames Modell bezahlt macht. Ein Kunde aus Xentral kommt in derselben Form an wie ein Kunde aus einem System, das jede Geschäftsbeziehung in einem einzigen Kontaktdatensatz führt, denn das Common Data Model nimmt den Unterschied auf. Der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste System wiederverwenden, und die Objekte, die als auf Anfrage markiert sind, sind eine Anfrage und kein Neubau.
Die Obergrenze gehört von Anfang an in den Entwurf des Abgleichs. Xentral beantwortet 100 Anfragen pro Minute, gleich welchen Tarif Ihr Kunde hat, was ein Delta-Lesezugriff über vier Objekte leicht schafft und ein erster vollständiger Abzug nicht. Xentral ergänzt, dass die Zahl noch geprüft wird, das Tempo baut man also besser ein, bevor sie sich bewegt. Wenn der 429 kommt, verhindert ein Fehlerkontrakt, dass daraus eine Xentral-förmige Verzweigung in Ihrem Code wird.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
