Sage Active anbinden: Elf Objekte lesen, und Korrekturen entstehen als neue Belege

Drei strukturelle Eigenschaften entscheiden den Zuschnitt dieser Anbindung, und keine davon betrifft einen Feldnamen.

Die erste: alles läuft über einen Endpunkt. Sage Active spricht GraphQL, also Queries zum Lesen, Mutations zum Schreiben und eine Antwort in der Form, die Sie angefragt haben. Dazu gilt ein Komplexitätslimit, und Queries darüber werden abgewiesen, tief verschachtelte Daten müssen also manchmal auf mehrere Anfragen verteilt werden.

Die zweite: ein Token benennt keine Firma. Nach der Authentifizierung haben Sie Zugriff und müssen trotzdem bei jedem Aufruf sagen, wessen Bücher Sie meinen. Dieser Wert wird nach Abschluss des Ablaufs geholt und vom Nutzer gewählt, er ist damit ein Schritt nach der Verbindung in Ihrem Onboarding und keine Angabe, die Sie fest eintragen können.

Die dritte: Frankreich, Spanien und Deutschland sind drei eigene Zielsysteme und nicht ein System mit einer Ländereinstellung. Die Anwendung, die Sie in Sage Active registrieren, trägt einen Ländertyp und eine eigene Callback-URL, alle drei Märkte zu bedienen heisst also drei Registrierungen.

Auf Seiten von Sage Active: die Authentifizierung läuft über OAuth 2.0, und das Access-Token lebt acht Stunden. Ein Refresh-Token wird nur ausgestellt, wenn die erste Autorisierung den Scope offline_access angefragt hat. Fragen Sie ihn an, dann läuft eine unbeaufsichtigte Anbindung über die acht Stunden hinaus weiter, ohne dass sich jemand erneut anmeldet.

Zwei weitere Scopes teilen den Zugriff selbst auf, einer zum Lesen und einer zum Schreiben. Nur anzufragen, was Sie brauchen, ist die gewöhnliche Sorgfalt, und hier belegt es zusätzlich Ihre Absicht gegenüber dem Kunden, genau in dem Moment, in dem er die Verbindung bestätigt.

Die Firmenangabe greift dabei an einer Stelle ein, die man kennen sollte. Die Endpunkt-Referenz hält fest: wer den interaktiven Authentifizierungsablauf nicht nutzt, muss den Query-Parameter companyId auf seinen Aufrufen füllen und holt den Wert nach dem Verbinden über einen Companies-Endpunkt. Mit diesem Ablauf fällt die Wahl stattdessen einmal während der Verbindung.

Alle drei Länder-Zielsysteme fahren diesen interaktiven Ablauf über maesn, und deshalb ist Unified Authentication der Unterschied zwischen einem Wahlschritt beim Verbinden und einer Angabe, die Ihr Request-Builder bei jedem Aufruf für jeden Mandanten richtig setzen muss.

Auf Seiten von Sage Active: elf Objekttypen kommen zurück, und die Liste reicht weiter, als es eine Buchhaltungs-API sonst tut. Sie trägt Aufträge, Angebote und deren Positionen neben dem Hauptbuch, die Auftragsseite und die Bücher beantwortet also dieselbe Verbindung.

Wie Sie diese Daten durchlaufen, ist eine GraphQL-Konvention. Die Paginierung läuft über einen Cursor: Sie fragen eine Anzahl von Einträgen an, die Antwort trägt einen Cursor und ein Kennzeichen, ob es weitergeht, und Sie geben den Cursor zurück, um fortzufahren. Eine Seitenzahl gibt es nicht, springen können Sie also nicht.

Für einen ersten Import ändert das den Fehlerfall. Eine Synchronisation, die auf halbem Weg abbricht, kann nicht mit Seite sieben weitermachen, sie setzt an dem Cursor an, den sie gespeichert hat, das Speichern dieses Cursors wird damit Teil des Entwurfs und ist keine Optimierung. Ein Weg, zu filtern und zu paginieren macht daraus wieder dieselbe Seite und dasselbe Limit, die Sie bei Systemen benutzen, die nie von einem Cursor gehört haben.

Auf Seiten von Sage Active: fünf Objekttypen lassen sich anlegen, und ein gebuchter Beleg bleibt so stehen, wie er geschrieben wurde. Einen Änderungs- und einen Löschaufruf gibt es dafür nicht.

Das ist das Modell eines Hauptbuchs und nicht das einer Datenbank, und so behandeln Buchhaltungssysteme einen gebuchten Beleg gewöhnlich: der Nachweis dessen, was gebucht wurde, muss erhalten bleiben, eine Korrektur wird also daneben ausgestellt statt darüber geschrieben. Planen Sie den Korrekturweg vor dem ersten Schreibzugriff, kostet er nichts; entdecken Sie ihn danach, ist er ein Umbau Ihrer Schreiblogik.

Auf dem Schreibweg steht eine zweite Anforderung, die Aufrufe kostet. Referenzfelder nehmen keine lesbaren Werte an: eine Mengeneinheit muss als interne Kennung angegeben werden, die das System dafür führt, nicht als Wort. Diese Kennungen sind zwischen Mandanten nicht gleich, der Abruf und der Zwischenspeicher liegen also je Kunde.

Genau diese Schicht nimmt das Common Data Model heraus. Sie senden einen lesbaren Wert, die Auflösung geschieht hinter der Verbindung, und derselbe Schreibzugriff sieht aus wie bei einem System, das das Wort von vornherein angenommen hätte.

Auf Seiten von Sage Active: eine Summen- und Saldenliste gibt es als fertigen Bericht, und das lohnt zu wissen, weil die meisten Buchhaltungs-APIs sie aus Buchungssätzen zusammensetzen lassen. Davor steht ein Parameter, der sich beim Entwurf leichter behandeln lässt als zur Laufzeit.

Der Endpunkt verlangt den Beginn des Geschäftsjahres. Die Referenz ist eindeutig: „Der Query-Parameter fiscalYearStartDate ist erforderlich und muss ein gültiges Datum sein.“ So weit gewöhnlich, bis Sie suchen, woher dieses Datum kommt.

Geschäftsjahre sind auf diesem System kein lesbares Objekt. Weder auf Anfrage noch hinter einem Schalter: die Coverage-Zelle ist ein schlichtes Nein. Der Bericht verlangt damit einen Wert, den dasselbe System nicht herausgibt, und es bleiben nur Ihre eigene Konfiguration, Ihr Kunde oder eine Vereinbarung, die Sie einmal treffen und hinterlegen.

Kein Objekt trägt hier ein freigeschaltetes Event. Es gibt kein Abonnement anzulegen, keinen Callback zu prüfen und keine Zustellsemantik zu bedenken, Daten aktuell zu halten ist also ein geplanter Lesezugriff, und damit hat es sich.

Im Event-Modell ist das die Pull-Hälfte, die die ganze Arbeit macht. Sie hat eine Eigenschaft, die zu diesem System besonders passt: ein Pull holt auf. Weil der Durchlauf hier über einen Cursor läuft und wiederaufsetzbar ist, macht ein Worker, der einen Tag ausgefallen war, dort weiter, wo er stehen geblieben ist.

Was das kostet, ist Ihre Wahl des Intervalls, und auf einem System, das nichts ändern kann, fällt die Rechnung einfacher aus als sonst: was Sie einmal gelesen haben, ändert sich nicht mehr an Ort und Stelle. Neue Belege kommen hinzu, und ablösende stehen daneben.

Wie die Objektabdeckung vollständig aussieht, einschliesslich der als auf Anfrage vermerkten Kombinationen, steht auf der Seite Sage Active Schnittstelle.

Was wir Ihnen abnehmen:

• Die Abfragesprache. Queries, Mutations, die Konventionen des Frameworks und das Komplexitätslimit bleiben hinter der Verbindung, und Ihre Seite macht gewöhnliche REST-Aufrufe.
• Die Wahl der Firma. Der interaktive Ablauf sammelt sie einmal ein, und die Kennung wird bei jedem späteren Aufruf mitgegeben, ohne dass Ihr Request-Builder davon weiss.
• Den Cursor und die Kennungen. Aus dem Cursor-Durchlauf werden Seite und Limit, und Referenzfelder nehmen lesbare Werte statt Zahlen je Mandant.

Was bei Ihnen bleibt, und das erste davon ist eine Produktentscheidung und keine Aufgabe:

• Was eine Korrektur in Ihrem Modell bedeutet. Ohne Ändern und ohne Löschen ist das Ablösen eines Belegs ein Begriff, den Ihr Produkt tragen muss. Wir können den Schreibzugriff so aussehen lassen wie bei jedem anderen System; änderbar machen können wir dieses hier nicht.
• Der Beginn des Geschäftsjahres. Der Bericht braucht ihn und das System gibt ihn nicht her, er kommt also aus Ihrer Konfiguration oder von Ihrem Kunden.
• Drei Registrierungen für drei Märkte. Jedes Land ist eine eigene Anwendung mit eigenem Callback, und das einzurichten ist Ihre Sache.