Sage Active Schnittstelle und API-Integration
Sage Active ist das Cloud-Buchhaltungs- und ERP-Produkt von Sage für kleine und mittlere Unternehmen, verkauft in Frankreich, Spanien und Deutschland. Es trägt Rechnungsstellung, Umsatzsteuer, Bankabstimmung und das Hauptbuch, und seine API ist GraphQL statt REST. Binden Sie es über Maesn an, und Sie erreichen es mit denselben REST-Aufrufen und demselben Datenmodell wie jedes andere unterstützte System.
Die Sage-Active-API spricht GraphQL, Ihr Code bleibt bei REST
Drei Formen der Sage-Active-API landen am ersten Tag in Ihrer Codebasis, und keine davon hat mit Buchhaltung zu tun.
Gewöhnliche REST-Aufrufe, wieder vorangestellt
Sage Active stellt einen einzigen GraphQL-Endpunkt bereit, auf dem eine Query liest und eine Mutation schreibt, in den Hot-Chocolate-Konventionen, die Sage benutzt. Es erzwingt außerdem eine Komplexitätsgrenze und weist Queries ab, die sie überschreiten. Ein tief verschachtelter Lesezugriff muss also auf mehrere Anfragen aufgeteilt werden. Maesn baut und teilt diese Operationen im Hintergrund, und Ihr Client sendet denselben REST-Aufruf, den er an jedes andere System sendet.
Einmal gewählt, von da an immer dabei
Sage Active weist jeden Aufruf ohne X-OrganizationId ab, die interne Kennung der Firma, deren Bücher Sie anfassen. Am Ende des OAuth-Ablaufs ist sie nicht bekannt: Sie müssen die Liste holen, den Kunden wählen lassen und die Antwort je Mandant verwahren. Maesn führt diese Auswahl als Teil des interaktiven Authentifizierungsablaufs, speichert die Antwort an der Verbindung und setzt den Wert auf jede spätere Anfrage.
Lesbare Werte, darunter aufgelöst
Referenzfelder beim Anlegen nehmen die numerische ID, die Sage Active intern benutzt. Eine unitOfMeasurementId akzeptiert kein KILOGRAM, und dasselbe gilt für Steuerschlüssel, Zahlungsbedingungen und Kontoreferenzen. Diese IDs gelten je Mandant, die Nachschlagetabelle also auch je Kunde. Maesn holt diese Tabellen, hält sie vor und bildet sie ab, Sie senden damit den lesbaren Wert, und die Zuordnung ist kein Code, den Sie pflegen müssen.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. GraphQL, der Firmen-Header und die ID-Auflösung bleiben auf dieser Seite, und das System nach Sage Active ist ein Konfigurationsschritt und kein zweites Projekt.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Paywise hat Buchhaltungssysteme hinzugenommen, die es nie gebaut hat
Paywise automatisiert die Debitorenbuchhaltung für Unternehmen, deren Kunden alle woanders buchen. Die Systeme waren nie das Produkt, und sie einzeln anzubinden war der Teil, der nicht skalierte.
“Seit der Anbindung an Maesn ist die Nutzung unserer Plattform stark gestiegen, weil wir eine große Bandbreite an Buchhaltungssystemen auf einmal unterstützen. 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 Sage Active Schnittstelle über Maesn anzubinden
Eine direkte Sage-Active-Integration sind drei Lernkurven vor der ersten Funktion: eine Abfragesprache, ein Firmenkontext je Mandant und eine Schicht aus Stammdaten. Alle drei fallen hier einmal an, und sie kommen beim nächsten Kunden oder im nächsten Land nicht wieder.
Die Abfragesprache endet hier
Queries, Mutations, Hot-Chocolate-Konventionen und die Komplexitätsgrenze werden im Maesn-Backend erledigt. Teams, die ohnehin REST-Integrationen für Buchhaltung bauen, behalten das Modell, das sie kennen, und das ist der Unterschied zwischen einem System dazunehmen und einen Stack lernen.
Tiefe, die Sie nachprüfen können
Die Leseseite ist hier breiter als auf einem reinen Hauptbuchsystem, denn Sage Active führt die Auftragsseite neben den Büchern: Angebote, Angebotspositionen und Kundenaufträge kommen alle zurück. Alles, was sich lesen lässt, lässt sich auch schreiben, und was heute nicht freigeschaltet ist, ist auf Anfrage verfügbar.
Drei Länder, eine Anbindung
Sage Active läuft in Frankreich, Spanien und Deutschland je Markt als eigenes Zielsystem. Sie registrieren eine App, wählen ihr Land und binden über dieselbe Schnittstelle an. Ein zweiter Sage-Active-Markt ist damit ein Konfigurationsschritt und keine zweite Integration.
Ein Sage-Active-Eintrag ist ein Gespräch, kein Formular
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei Sage hängt der Eintrag an der zweiten: Gelistet zu werden läuft von Hand über das Partnerteam von Sage, einschließlich einer Einschätzung, ob Ihr Produkt zu deren Strategie passt, und nicht über ein Selbstbedienungsformular.
Technische Unterstützung
Eine Integration gegen die Unified API und ein Datenmodell, identisch zu jedem anderen System, das Maesn unterstützt. Ihre Entwickler treffen hier auf dieselbe Schnittstelle wie beim nächsten System.
Unterstützung bei der Partnerschaft
Maesn ist offizieller Sage-Partner und führt das Gespräch über den Eintrag mit Ihnen, von der Einschätzung der Passung bis zur technischen Prüfung, und steht danach weiter hinter der Integration. Der Eintrag trägt den Namen Ihres Produkts, nicht unseren.
Ein konzentriertes Publikum
Sage weist mehr als 2 Millionen Kunden aus, und der Marketplace ist der Ort, an dem ein Sage-Kunde nach angebundener Software sucht. Das ist Vertrieb an Menschen, die das System bereits benutzen, das Sie gerade angebunden haben.
Ein Team entscheidet, kein Formular
Das Partnerteam von Sage prüft die strategische Passung, bevor ein Eintrag online geht. Das ist langsamer als ein Einreichungsformular, und es ist auch der Grund, warum ein Sage-Active-Eintrag nicht etwas ist, das jeder Wettbewerber von Haus aus hat, und das zahlt auf Sie ein, sobald Sie hindurch sind.
Drei Märkte hinter einem Eintrag
Dasselbe Produkt wird in Frankreich, Spanien und Deutschland verkauft. Ein Eintrag, der sitzt, steht vor einer Kundschaft, die alle drei umspannt, und deshalb lohnt es sich, die Länderwahl bei der App-Registrierung früh richtig zu treffen.
Die Integration läuft unter dem Namen Ihres Produkts, und der Eintrag gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir bereiten die Eignungsprüfung und die technische Prüfung mit Ihnen vor.
Eine Sage-Active-Verbindung ist ein Token plus eine Firma
Sage Active authentifiziert über OAuth 2.0 gegen eine App, die Sie selbst registrieren, und der Ablauf hat eine zweite Hälfte, die die meisten Systeme hier nicht haben. Nach der Zustimmung weiß die Verbindung immer noch nicht, für welche Firma sie gilt, deshalb stehen alle drei Sage-Active-Zielsysteme in der Authentifizierungsdokumentation von Maesn auf der interaktiven Liste: Der Kunde wählt auf einer Auswahlseite eine Firma, die Antwort wird gespeichert, und jede spätere Anfrage trägt sie mit.
- OAuth 2.0
- Ihre eigene App, je Sage-Active-Land registriert
Eine App für jeden Kunden in einem Markt. Maesn verwahrt die Zugangsdaten, führt die Firmenauswahl aus und erneuert das 8-Stunden-Token dahinter.
- Ihre App-Zugangsdaten und der Abonnementschlüssel
- Client ID, Client Secret und der Subscription Primary Key werden einmal eingereicht und danach für jede Verbindung benutzt, die Sie in diesem Markt herstellen. Ihr Code hält einen Account-Key je Kunde und sonst nichts.
- Der Firmenkontext und der Token-Zyklus
- Die Firma, die der Kunde gewählt hat, wird an der Verbindung gespeichert und an jeden Aufruf gehängt. Das Access-Token dahinter lebt 8 Stunden und wird hier erneuert, und deshalb wird offline_access gleich zu Beginn angefordert und nicht in der neunten Stunde entdeckt.
Die Sandbox-Dokumentation führt Sage Active als System, für das Maesn eine Umgebung bereitstellt, und das ist hier der Weg, weil Sage keine kostenlose veröffentlicht. Das zählt auf diesem System mehr als anderswo: Die Firmenauswahl, die Scopes und das 8-Stunden-Refresh sind alles Dinge, die Sie funktionieren gesehen haben wollen, bevor ein Kunde sie sieht.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von Sage Active. Er trägt den Namen Ihrer App, denn die App ist auf Ihr Unternehmen registriert. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
Er wählt die Firma
Sage Active kehrt zu Maesn zurück, und der interaktive Ablauf zeigt die Firmen, die dieser Kunde erreichen kann. Die Auswahlseite kann Ihre Farben tragen. Heraus kommt die Firmenkennung, die jede spätere Anfrage braucht.
- 3
Sie arbeiten mit einem Account-Key
Maesn speichert die Verbindung und gibt einen Account-Key zurück. Ab da trägt jede Anfrage Ihren Maesn-API-Schlüssel und diesen Account-Key, dieselben zwei Header, die Sie für jedes andere System im Katalog ohnehin schon senden.
Jedes System im Katalog authentifiziert anders, und bei Sage Active ist die Zustimmung nur die erste Hälfte. Unified Authentication macht daraus einen einmaligen Aufwand: Der Zustimmungsdialog, die Firmenauswahl, das Refresh und der Account-Key verhalten sich hier genauso wie bei einem System, das nichts weiter als einen Schlüssel braucht, die zweite Integration erbt die Arbeit also, statt sie zu wiederholen.
Sage-Active-Daten bleiben frisch mit einem geplanten Abruf
Er läuft, ohne jemanden zu fragen, auf demselben Filter und derselben Paginierung wie bei jedem anderen System, das Sie anbinden. Events sind bei Sage Active eine Frage der Freischaltung und keine Eigenschaft des Systems. Ein Event, auf das Ihr Produkt angewiesen ist, benennt man also besser früh.
Nichts. Jede Event-Spalte in der Matrix ist entweder eine Anfrage oder leer. Eine Änderung in der Firma eines Kunden bleibt also unsichtbar, bis etwas sie liest. Würden die Events eines bestimmten Objekts Ihr Produkt verändern, ist dafür die Spalte auf Anfrage da, und das ist ein Gespräch und kein Punkt auf einer Roadmap.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code zur Änderungserkennung, den Sie auf Sage Active richten, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet, und das Intervall bleibt eine Produktentscheidung und keine Grenze des Systems.
Vor dem Dimensionieren eines Massenabzugs wissenswert: Sage Active paginiert über einen Cursor, was die GraphQL-Norm ist und bedeutet, dass es keine Möglichkeit gibt, nach Seite fünf zu fragen. Den fünfhundertsten Datensatz zu erreichen heißt, jede Seite davor zu durchlaufen. Maesn stellt Offset-Paging bereit und übernimmt das Durchlaufen. Ihr Code bleibt also bei Seite und Limit. Einplanen sollten Sie den ersten vollständigen Ladevorgang, der hier länger dauert als auf einem System, das nativ über Offset paginiert.
Ein System, das Sie nach Zeitplan lesen müssen, ist die Stelle, an der die Kosten einer Integration je System am deutlichsten sichtbar werden, und bei Sage Active zeigen sie sich doppelt, weil das Lesen selbst sequenziell abläuft. Ein Weg, zu filtern und zu paginieren macht aus einem Cursor-Durchlauf dieselbe Seite und dasselbe Limit, die Sie überall sonst benutzen. Was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei Wege, und bei Sage Active läuft heute alles über den zweiten.
Was eine Sage-Active-Anbindung am ersten Tag braucht
Was Sage Active vor dem ersten Aufruf verlangt, ist eine eigene App, und die App trägt ein Land. Der Rest ist eine kurze Liste, und der letzte Punkt ist der, den Teams spät entdecken.
- Ein Sage-Active-Konto mit gültigem Abonnement
- Die ganze Voraussetzungsliste der Dokumentation ist diese eine Zeile. Die Anwendungsschlüssel liegen unter Einstellungen im Konto selbst. Die Entwicklerseite ist also eine Berechtigung auf einem zahlenden Konto und kein eigenes Portal, für das man sich anmeldet.
- Eine App, und ihr Land wird bei der Registrierung gewählt
- Unter Einstellungen, Anwendungsschlüssel und Apps legen Sie eine App mit Namen, URL und Kontakt-E-Mail-Adresse an und wählen dann den Sage-Active-Typ: DE, ES oder FR. Die Callback-URL folgt dieser Wahl, eine von https://api.maesn.dev/auth/callback/sage-active-de, -es oder -fr. Typ und Callback müssen zu dem Markt passen, in dem Ihr Kunde ist. Es ist also eine Entscheidung und kein Detail.
- Drei Werte, einmal übergeben
- Die Solutions-Seite Ihrer App zeigt eine Client ID, ein Client Secret und einen Subscription Primary Key. Alle drei gehen einmal an Ihren Ansprechpartner bei Maesn und nicht je Kunde, und von da an läuft der Handshake, der sie verbraucht, hier.
- Die Scopes entscheiden die Richtung, und das Token lebt 8 Stunden
- RDSA gewährt Lesezugriff und WDSA Schreibzugriff, was eine Verbindung kann, steht also am Zustimmungsbildschirm fest und nicht beim Aufruf. Access-Tokens verfallen nach 8 Stunden, und ein Refresh-Token wird nur ausgestellt, wenn offline_access vorab angefordert wird. Beides wird hier erledigt, und beides sollten Sie kennen, denn genau daran scheitert ein direkter Bau zuerst.
Wir gehen die App-Registrierung, die Länderwahl und die Scopes mit Ihnen durch.
Eine Form für Sage Active, und für das nächste System
Sage Active antwortet in GraphQL und will interne IDs, wo ein Mensch ein Wort schreiben würde. Eine gemeinsame Form hält beides aus Ihrem Code heraus.
Eine breite Leseseite, und eine Auswertung, die fast niemand hat
11 Objekte lassen sich lesen, das ist die viertbreiteste Leseseite der über 30 hier angebundenen Systeme. Zwei davon sind ungewöhnlich und nicht nur zahlreich: Sage Active ist eines von zwei Systemen, die eine Summen- und Saldenliste zurückgeben, und eines von dreien, die Angebote und Angebotspositionen lesen. Auch die Auftragsseite lässt sich lesen, und das ist Sage Active als ERP und nicht als Buchhaltungsprodukt.
Fünf Objekte gehen hinein, und keines davon lässt sich ändern
Konten, Kunden, Rechnungen, Artikel und Lieferanten lassen sich anlegen, und alle fünf lassen sich zurücklesen. Jeder Schreibzugriff macht hier also einen Rundlauf. Was heute kein Objekt kann, ist an Ort und Stelle aktualisieren: 22 dieser Kombinationen sind mit auf Anfrage gekennzeichnet und nicht als unverfügbar, sagen Sie uns also, welche Ihr Anwendungsfall braucht, bevor Sie um ein reines Anlegen herum entwerfen.
Die Auswertung verlangt ein Datum, das dieses System nicht hergibt
Die Summen- und Saldenliste ist die fertige Auswertung, die die API anbietet, und sie verlangt bei jedem Aufruf ein fiscalYearStartDate. Wirtschaftsjahre gibt Sage Active überhaupt nicht zurück. Dieses Datum muss also aus Ihrem Produkt oder vom Kunden kommen. Es ist eine Kleinigkeit, wenn man sie einplant, und teuer, wenn man sie an dem Tag entdeckt, an dem die Auswertung fällig ist und der Kunde schon darauf wartet.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, und bei Sage Active leistet dieses Modell zwei Dinge auf einmal: Es verbirgt die GraphQL-Form der Antwort, und es erlaubt einem Schreibzugriff, einen lesbaren Wert zu tragen, wo die API eine interne ID will.
Die Leseseite ist für eine Buchhaltungsanbindung breit, weil Sage Active nicht nur ein Buchhaltungsprodukt ist. Angebote, Angebotspositionen und Aufträge sind hier lesbar und nur bei sehr wenigen anderen, das ist die Auftragsseite eines ERP neben dem Hauptbuch. Nach dieser Breite hat auch ein veröffentlichter Kunde gesucht: Die Studie von Clockin nennt Sage unter den Systemen, die ihre Kunden einsetzen, und gibt die Vielfalt dieser Systeme als Grund an, warum die Integrationen selbst zu bauen nie realistisch war. Ihre Case Study ist dieses Argument in den Worten eines Kunden statt in einer Tabelle.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
