Sage Accounting Schnittstelle und API-Integration
Sage Accounting ist die Cloud-Buchhaltungsplattform von Sage für kleine und mittlere Unternehmen, verkauft in UK, Irland und Kanada. Sie deckt Rechnungsstellung, Ausgabenerfassung, Bankabstimmung, Umsatzsteuerauswertungen und die Verwaltung mehrerer Unternehmen ab. Binden Sie sie über Maesn an, und Sie erreichen sie mit denselben REST-Aufrufen und demselben Datenmodell wie jedes andere unterstützte System.
Sage Accounting lässt ein Token alle 5 Minuten verfallen, Ihr Code erneuert es nie
Drei Eigenschaften der Sage-Accounting-API landen am ersten Tag in Ihrer Codebasis, und keine davon hat mit Buchhaltung zu tun. Jede einzelne ist ein Stück Infrastruktur, das Sie sonst über die Lebensdauer der Integration besitzen würden.
Der Token-Zyklus bleibt hier
Access-Tokens von Sage Accounting verfallen nach 5 Minuten, und das Refresh-Token rotiert bei jeder Nutzung. Wenn Ihr eigener Speicher das neue Refresh-Token nach einem Erneuerungsaufruf nicht sichert, gibt es für diese Verbindung keinen Weg zurück außer einer vollständigen erneuten Freigabe durch den Endnutzer. Maesn hält diesen Zyklus für jeden angebundenen Endnutzer. Der Fehlerfall, der Sie eine Kundenverbindung kostet, ist also kein Code, den Sie richtig hinbekommen müssen.
Einmal ermittelt, von da an immer dabei
Jede Anfrage an Sage Accounting trägt einen ausdrücklichen X-Business-Header mit der GUID des Business, und dieser Wert gehört nicht zu dem, was die Authentifizierung zurückgibt. Es braucht danach einen eigenen Aufruf, um überhaupt herauszufinden, welche Businesses der Nutzer erreichen kann. Maesn führt diese Ermittlung beim Onboarding, hält die Antwort an der Verbindung und setzt den Header auf jede spätere Anfrage.
Ein POST, der in einen Timeout läuft, ist keine Antwort
Wenn ein POST gegen Sage Accounting in einen Timeout läuft, wissen Sie nicht, ob der Datensatz geschrieben wurde. Wiederholen Sie ihn, riskieren Sie ein Duplikat, lassen Sie ihn aus, riskieren Sie eine fehlende Rechnung. Sage antwortet darauf mit Idempotenzschlüsseln und einem Fenster von sieben Tagen, in dem derselbe Schlüssel auf denselben Datensatz führt. Die Wiederholungsregel, die Sie entwerfen, hat damit eine dokumentierte Grenze und keine Schätzung.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Token-Rotation, Business-Discovery und gefahrlose Wiederholungen bleiben auf dieser Seite, und das System nach Sage Accounting ist ein Konfigurationsschritt und kein zweites Projekt.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
HERO Software baut gegen eine Dokumentation, der es folgen kann
HERO Software digitalisiert das Backoffice für Handwerksbetriebe, vom Angebot bis zur Rechnung. Was die Entwickler dort nennen, ist keine Funktion, sondern wie schnell die Integration aufgehört hat, ein Forschungsprojekt zu sein.
“Die Unterstützung ist wirklich erstklassig, mit beeindruckend kurzen Reaktionszeiten. Die Dokumentation ist gründlich und leicht nachvollziehbar, und dadurch war die Integration für mich ein reibungsloser Ablauf.”
Drei Gründe, die Sage Accounting Schnittstelle über Maesn anzubinden
Sage Accounting ist keine schwierige API, um sie aufzurufen. Sie ist eine teure im Betrieb, denn drei ihrer Eigenschaften brechen erst in der Produktion, und eine davon bricht jeweils bei einem angebundenen Endnutzer.
Der Token-Zyklus ist jemandes Aufgabe
Bei 5 Minuten Gültigkeit und einem Refresh-Token, das bei jeder Nutzung rotiert, ist das Risiko nicht, dass ein Aufruf fehlschlägt. Es ist, dass das neue Refresh-Token Ihren Speicher nicht erreicht, und das kostet die Verbindung und nicht die Anfrage. Wem die Integration gehört, dem gehört das als Bereitschaftsthema, solange die Verbindung lebt. Hier einmal bezahlt, kommt es beim nächsten Kunden und beim nächsten Markt nicht wieder.
Drei Märkte über eine Anbindung
Sage Accounting wird in drei Ländern über eine Basis-URL verkauft. Ein Kunde in Irland und einer in Kanada kommen also über dieselbe Integration und dieselbe registrierte App an. Was sich je Land unterscheidet, ist der Inhalt der Bücher und nicht die Schnittstelle davor.
Mehrere Systeme tragen den Namen
Sage Accounting ist nicht Sage Active, Sage 50 oder Sage Intacct. Welches davon ein Kunde betreibt, entscheidet über API, Portal und Zugangsdaten: Sage Active registriert Apps im Konto des Kunden selbst und gibt drei Werte aus, wo dieses zwei ausgibt. Maesn hält diese Zuordnung. Das richtige Sage zu wählen ist damit ein Konfigurationsschritt.
Ein Sage-Accounting-Eintrag ist eine Prüfung, kein Formular
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei Sage entscheidet die zweite darüber, wie weit die erste reicht: Es gibt kein Selbstbedienungsformular, der Eintrag läuft von Hand über das Partnerteam von Sage.
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. Der Eintrag trägt den Namen Ihres Produkts, nicht unseren.
Eine Prüfung statt eines Formulars
Der Eintrag läuft über das Partnerteam von Sage und schließt eine Prüfung ein, ob Ihr Produkt zu dessen Strategie passt. Das ist langsamer als ein Absende-Knopf, und es heißt auch, dass ein Eintrag nicht etwas ist, das jeder Wettbewerber von Haus aus hat.
Zuerst eine funktionierende Integration
Die technische Prüfung kommt zusammen mit der kaufmännischen. Die Verbindung muss also bestehen, bevor sich das Gespräch lohnt. Sie über Maesn zu bauen macht aus diesem Schritt eine Vorführung statt eines Projekts.
Drei Märkte, ein Eintrag
Sage Accounting wird im Vereinigten Königreich, in Irland und in Kanada verkauft. Ein Eintrag, der sitzt, steht vor einer Kundschaft, die alle drei umspannt, und deshalb gehört die Frage nach dem Markt früh in den Plan.
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-Accounting-Verbindung ist ein Token plus ein Business
Sage Accounting authentifiziert über OAuth 2.0 gegen eine App, die Sie selbst registrieren, und die Zustimmung ist nur die erste Hälfte. Das Token sagt, wer der Nutzer ist, nicht welche Buchhaltung er meint, und Sage weist jede Anfrage ohne das Business daran ab. Sage Accounting steht deshalb in der Authentifizierungsdokumentation von Maesn auf der interaktiven Liste: Der Kunde wählt im Verbindungsablauf ein Business, die Antwort wird an der Verbindung gespeichert, und der X-Business-Header wird von da an angehängt.
- OAuth 2.0
- Ihre eigene App, eine Registrierung für alle drei Märkte
Eine App für jeden Kunden in jedem Markt. Maesn verwahrt die Zugangsdaten, löst das Business auf und erneuert das 5-Minuten-Token dahinter.
- Ihre App-Zugangsdaten
- Client-ID und Client Secret werden einmal eingereicht und danach für jede Verbindung benutzt, die Sie herstellen, in allen drei Märkten. Ihr Code hält einen Account-Key je Kunde und sonst nichts.
- Der Business-Kontext und der Token-Zyklus
- Sage verlangt den X-Business-Header bei jedem Aufruf, und Maesn klärt ihn, und genau deshalb ist der Parameter companyId an den Endpunkten von Maesn für Sie optional. Senden Sie ihn, wenn Sie eine Anfrage auf ein Business eingrenzen wollen, holen Sie die Werte mit GET /companies, und lassen Sie ihn weg, wenn die Verbindung das richtige bereits trägt.
Gegen welches Business eine Anfrage läuft, entscheidet die Business-GUID, die mit ihr reist. Ein Kunde, der über mehrere Bücher hinweg arbeitet, ist also eine Frage danach, welches Sie nennen. Ein versehentlich gesetzter Parameter erreicht die falschen Bücher, statt fehlzuschlagen, und das ist vor dem Start einen eigenen Test wert.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von Sage Accounting. Er trägt den Namen der App, die Sie registriert haben. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
Er wählt das Business
Sage kehrt zu Maesn zurück, und der interaktive Ablauf zeigt die Businesses, die dieser Kunde erreichen kann. Die Auswahlseite kann Ihre Farben tragen. Heraus kommt die Business-GUID, die jede spätere Anfrage in ihrem X-Business-Header 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.
Dieselbe Form zeigt das Schwesterprodukt: Sage Active fragt nach der Zustimmung ebenfalls nach einer Firma, mit einem anderen Header und einem anderen Portal dahinter, und das Sage-Portfolio teilt sich von dort aus weiter auf. Unified Authentication macht daraus einen einmaligen Aufwand: Der Zustimmungsdialog, die Business-Auswahl, der Refresh-Zyklus und der Account-Key verhalten sich hier genauso wie bei einem System, das nichts weiter als einen Schlüssel braucht.
Sage-Accounting-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. 25 der 37 Objekte sind für Events als auf Anfrage markiert, und die übrigen 12 tragen in der Matrix keine Event-Unterstützung. Ein Event, auf das Ihr Produkt angewiesen ist, ist also eine Frage der Freischaltung.
Nichts, was freigeschaltet wäre. Jede Event-Spalte ist entweder eine Anfrage oder leer. Eine Änderung im Business eines Kunden bleibt also unsichtbar, bis etwas sie liest. Würden Events auf einem bestimmten Objekt Ihr Produkt verändern, ist das ein Gespräch, das man führt, und kein Roadmap-Punkt, auf den man wartet.
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 Accounting 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, die das System Ihnen auferlegt.
Das 5-Minuten-Token sitzt unter diesem Lesezugriff, und es ändert, wie ein langer Lauf sich verhält. Ein Massenabzug, der eine Stunde läuft, überschreitet zwölf Token-Grenzen. Wo der Token-Zyklus liegt, entscheidet also darüber, ob der Lauf durchkommt oder auf halber Strecke stirbt und einen unvollständigen Import hinterlässt.
Ein Lesezugriff nach Zeitplan ist die Stelle, an der die Kosten einer Integration je System gewöhnlich sichtbar werden, denn jedes System filtert und paginiert anders. Ein Weg, zu filtern und zu paginieren hält diese Aufgabe über den ganzen Katalog hinweg gleich, und was Sie sonst über das Event-Modell verarbeiten würden, bleibt ein eigener Weg, den Sage Accounting heute nicht nutzt. Die Wiederholungsversuche unter beiden sind die andere Hälfte desselben Bildes: Was Idempotenz auf POST daraus macht, ist ein fehlgeschlagener Aufruf, den man gefahrlos wiederholt, und das zählt mehr auf einem System, dessen Token mitten im Lauf ablaufen kann.
Was eine Sage-Accounting-Anbindung am ersten Tag braucht
Die Liste der Voraussetzungen in der Dokumentation von Maesn ist eine Zeile lang, und die Arbeit liegt in der App-Registrierung dahinter. Die Callback-URL und die Sandbox sind die beiden, zu denen Teams spät greifen.
- Ein Sage-Accounting-Konto mit gültigem Abonnement
- Das ist die gesamte dokumentierte Voraussetzung. Die Entwicklerseite erreicht man aus einem zahlenden Konto und nicht über eine eigene Anmeldung, wer die App registriert, braucht also ein Konto mit laufendem Abonnement.
- Eine App, im Entwicklerportal von Sage registriert
- Sie legen die App im Selbstbedienungsportal für Entwickler von Sage an, mit dem Namen Ihrer Anwendung, der URL Ihrer Startseite und der Callback-URL https://api.maesn.dev/auth/callback/sageaccounting. Den Namen der App sehen Ihre Kunden auf dem Zustimmungsbildschirm. Er gehört also zu Ihrem Produkt und nicht zu uns.
- Zwei Werte, einmal übergeben
- Die fertige App zeigt eine Client-ID und ein Client Secret. Beide gehen einmal an Ihren Ansprechpartner bei Maesn und nicht je Kunde, und der Handshake, der sie verbraucht, läuft von da an hier. Es gibt keine App je Land und keinen Abonnementschlüssel, und darin ist Sage Accounting einfacher als sein Schwesterprodukt.
- Eine Sandbox, die Sie am ersten Tag haben können
- Sage Accounting hat ein kostenloses Testkonto, für das Sie sich selbst anmelden können, und die Sandbox-Tabelle von Maesn führt ebenfalls eine Umgebung dafür. Die Token-Rotation und das Ermitteln der Businesses sind die zwei Verhaltensweisen, die Sie laufen gesehen haben wollen, bevor ein Kunde am anderen Ende davon hängt.
Wir gehen die App-Registrierung, die Callback-URL und die Sandbox mit Ihnen durch.
Eine Form für Sage Accounting, und für das nächste System
Sage Accounting wird in drei Märkten über eine Basis-URL verkauft, und jede Anfrage muss das Unternehmen nennen, zu dem sie gehört. Eine gemeinsame Form hält beides aus Ihrem Code heraus.
Zwei Objekte machen den vollständigen Rundlauf
Konten, Kunden und Lieferanten lassen sich heute lesen, Kunden und Lieferanten außerdem anlegen und aktualisieren. Diese beiden gehen also hinein und kommen verändert zurück. Der eine Schreibzugriff auf einen Beleg ist der Buchungsvorschlag, der eine Rechnung, die Sie halten, ins Hauptbuch trägt. Genau diese Richtung ist sein Zweck. Einen zurückzulesen ist deshalb eine Anfrage und kein Standard.
Kunden und Lieferanten, keine Kontakte
Geschäftspartnerdaten laufen auf Sage Accounting über Kunden und Lieferanten als getrennte Objekte, und beide sind lesbar und schreibbar. Das allgemeine Kontaktobjekt ist hier nicht der Weg hinein. Ein Datenmodell, das jeden Geschäftspartner als einen Kontaktdatensatz führt, braucht seine Zuordnung also vor dem ersten Abgleich entschieden und nicht danach.
Auf Anfrage heißt ein Gespräch
Objekte, die heute nicht freigeschaltet sind, sind keine Absagen. Benennen Sie die, die Ihr Produkt braucht, bevor Sie die Funktion zuschneiden, und Sie bekommen entweder ein Ja mit einem Zeitplan oder ein klares Nein, und beides ist nützlicher als eine Zahl.
Was hier eingeschaltet ist, deckt die Hauptbuchkonten und beide Seiten des Partnerdatensatzes ab. Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, ein Kundendatensatz aus Sage Accounting hat also dieselbe Form wie einer aus jedem anderen angebundenen System, und die Abbildung, die Sie einmal schreiben, funktioniert weiter, wenn das nächste System dazukommt.
Es ist eine kurze Liste, die zwei Aufgaben vollständig abdeckt statt vieler zur Hälfte. Die beiden Objekte, die Sie lesen, anlegen und aktualisieren können, sind Kunden und Lieferanten, beide Seiten des Partnerdatensatzes, Kunden- und Lieferantenstammdaten synchron halten läuft heute also durchgängig. Die zweite ist der Belegschreibzugriff: Ein Buchungsvorschlag trägt eine Rechnung, Eingangsrechnung oder Gutschrift, die Sie bereits halten, ins Hauptbuch, und das ist die Form, die Kreditorenbuchhaltung automatisieren größtenteils tatsächlich braucht. Ein Auswertungs- oder Abstimmungsablauf ist der Fall, der Objekte bräuchte, nach denen bisher niemand gefragt hat. Den Rest des Katalogs führt das Integrationsverzeichnis, erreichbar über denselben Account-Key und dasselbe Datenmodell.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
