Qonto anbinden: Drei Lesezugriffe, ein Event und eine App-Prüfung

Qonto ist die einzige Banking-Plattform in unserem Katalog von 30+ Systemen, und das ist keine Fußnote über Kategorien. Es entscheidet, welche drei Dinge Sie lesen können, und es entscheidet, was Ihren Start tatsächlich aufhält.

Fangen Sie damit an, was zurückkommt. Drei Objekttypen sind lesbar: Eingangsrechnungen, Buchungsvorschläge und Rechnungen. Alle drei sind Belege über Geld, das geschuldet wird oder auf seine Buchung wartet.

Was fehlt, ist die Mechanik der Buchhaltung, und Qontos eigenes Berechtigungsvokabular erklärt warum: es gewährt Zugriff auf Begünstigte, Überweisungen, Karten, Salden, IBANs, Kontoauszüge und Mitgliedschaften. Es gibt keine Berechtigung für einen Kontenrahmen, ein Journal oder ein Wirtschaftsjahr, weil eine Bank diese Dinge nicht führt.

Eine kurze Objektliste beschreibt hier also eine vollständige Banking-Anbindung. Die Frage danach ist, wohin diese Belege als Nächstes gehen, und diese Frage gehört zu Ihrem Buchhaltungs-Zielsystem, nicht zu dieser Anbindung.

Welches es auch ist, die Form, die Sie bekommen, bleibt dieselbe, und genau darum geht es beim Common Data Model: eine Rechnung von einer Bank und eine Rechnung aus einem ERP kommen mit denselben Feldnamen an.

Ein Zusammentreffen lohnt sich zu wissen, bevor Sie eine Synchronisation planen. Die drei Objekte, die unsere eigene Schnittstelle am reichhaltigsten sortieren und filtern kann, sind Rechnungen, Eingangsrechnungen und Buchungsvorschläge, und das sind genau die drei, die Qonto bereitstellt. So deckt ein Weg, zu filtern und zu paginieren den gesamten Leseumfang dieses Systems ab.

Zwei weitere strukturelle Tatsachen gehören hierher. Qonto veröffentlicht zwei getrennte Schnittstellen: eine Business API für die Arbeit mit bestehenden Konten und eine Onboarding API, um neue Qonto-Organisationen anzulegen. Alles in diesem Beitrag ist die Business API. Und die vollständige Objektabdeckung, einschließlich der auf Anfrage markierten Kombinationen, steht auf der Seite zur Qonto-Schnittstelle.

Der erste Bildschirm des Qonto-Entwicklerportals fragt, welche Art von Anwendung Sie bauen, und diese Antwort wiegt schwerer, als sie aussieht. Qonto dokumentiert vier Use Cases, und der gewählte entscheidet, welche Scopes Ihnen zur Verfügung stehen und welche Freigabe Sie vor dem Produktivbetrieb brauchen.

Für eine Anbindung wie diese steht die Antwort fest. Maesns Einrichtungsanleitung benennt sie: die Qonto-Konten Ihrer Kunden an Ihre Plattform anbinden. Qonto beschreibt diesen Use Case als Drittplattformen, die sich im Namen ihrer Nutzer verbinden, nennt ERP- und Buchhaltungssoftware als Beispiele und hält fest, dass er ausschließlich über OAuth 2.0 erreichbar ist.

Der einfachere Weg über einen API-Schlüssel gehört zu dem Use Case, in dem ein Qonto-Kunde seine eigenen Abläufe automatisiert, und er steht hier nicht zur Verfügung.

Dann kommt der Satz, der daraus eine Entwurfsentscheidung statt eines Formularfeldes macht. „Der Use Case einer Anwendung lässt sich nach dem Anlegen nicht mehr ändern. Wenn Sie den falschen Use Case gewählt haben, legen Sie eine neue Anwendung an. Sie erhalten eine neue client_id und ein neues client_secret, die Struktur der Anbindung bleibt jedoch identisch.“

In der Praxis ist das behebbar, und die Kosten sind organisatorisch. Der Code, den Sie geschrieben haben, funktioniert weiter, weil sich die Form der Anbindung nicht ändert. Was sich ändert, ist das Paar aus Zugangsdaten, und wenn Sie das Problem erst bemerkt haben, nachdem Ihre Kunden sich verbunden hatten, wurde jede dieser Verbindungen gegen eine Anwendung hergestellt, die Sie nicht mehr verwenden.

Es auf dem ersten Bildschirm richtig zu machen kostet eine Minute Lesen. Es falsch zu machen kostet eine erneute Einwilligungskampagne.

Nichts davon erreicht Ihren eigenen Code, und das ist das Argument dafür, es hinter eine Anbindung zu legen, die Sie nur einmal bauen. Was Ihnen einen Authentifizierungsablauf hier gibt: Use Case, Scope-Liste und Token-Austausch sind je System geklärt, nicht je Produkt, und eine Entscheidung wie diese fällt damit an einer Stelle, an der sie einmal fällt.

Maesns Dokumentation sagt, dass es die Prüfung gibt und wie lange sie dauert: „Sobald die App angelegt ist, prüft das Regulatory-Team sie und gibt sie frei. Dieser Vorgang kann einige Tage dauern.“ Was sie nicht sagt, ist warum, und das Warum ist einen Absatz wert, weil es Ihnen sagt, dass die Prüfung keine Formalität ist, durch die man durchgewunken wird.

Qonto stuft fünf Scopes als sensibel ein, mit der Begründung, dass sie unter PSD2 regulierte Vorgänge abdecken. Für jeden benennt es, welche Use Cases eine Prüfung brauchen. Die für diese Anbindung dokumentierte Scope-Liste enthält organization.read, und organization.read ist sensibel und verlangt eine Prüfung für genau den Use Case, den Sie wählen sollten.

Die Prüfung ist damit strukturell. Es gibt keine Variante dieser Anbindung, die sie überspringt, denn der eine Scope, der sie auslöst, ist der, der Salden, IBANs und Transaktionshistorie gewährt, und auf ihm ist diese Verbindung gebaut.

Zwei kleinere Wartezeiten liegen um diese herum, und beide lassen sich leichter verkraften, wenn Sie in Woche eins davon wissen statt in Woche vier. Wenn Sie das Entwicklerkonto mit einer E-Mail-Adresse statt mit einem bestehenden Qonto-Login eröffnen, durchläuft die Organisation selbst eine Prüfung, die Qonto im Schnitt mit rund 48 Stunden angibt. Die Anmeldung mit Qonto überspringt sie, weil sie bereits stattgefunden hat.

Und es gibt eine Anforderung, die eine Minderheit betrifft und laut scheitert, wenn sie Sie betrifft. Qonto hält fest, dass ein lizenzierter Partner sich im Produktivbetrieb mit einem QSeal-Zertifikat an der Business API ausweisen muss und dass Aufrufe ohne dieses Zertifikat mit 401 Unauthorized beantwortet werden. Wenn Sie kein lizenzierter Partner sind, geht Sie diese Zeile nichts an. Wenn doch, ist sie nichts, was man gegen die Produktivumgebung herausfindet.

Das ist der Teil, der einen Nachmittag kostet, und es ist nicht Ihr Fehler. Qontos gesamte Staging-Umgebung ist für das öffentliche Internet geschlossen, und eine Anfrage, die ohne die richtigen Zugangsdaten ankommt, bekommt keinen Fehler. Sie bekommt eine Anmeldeseite für Qontos internes SSO, das die Dokumentation als Qonto-Mitarbeitern vorbehalten und für externe Partner nicht verfügbar beschreibt.

Lesen Sie den Fehlerfall genau, denn eine Hälfte davon hebelt die Prüfung aus, die die meisten schreiben. Die API gibt das Anmelde-HTML zurück statt des erwarteten JSON, „manchmal mit einem Status 200“, und manchmal als Weiterleitung auf den SSO-Host.

Ein Handler, der ein 2xx als Erfolg behandelt und den Rumpf parst, meldet einen Parse-Fehler irgendwo weit entfernt von der Ursache. Ein Statuscode ist keine Antwort auf die Frage, die Sie gestellt haben.

Die Behebung ist ein Header, und die Disziplin besteht darin, dass er auf jede Sandbox-Anfrage gehört. Qonto führt die OAuth-Autorisierungs- und Token-Endpunkte, die Onboarding API, die Endpunkte für Webhook-Abonnements und den Embed-Proxy ausdrücklich auf, der Token-Endpunkt ist also keine Ausnahme.

Zwei Einzelheiten lassen es still scheitern, wenn Sie sie fast richtig machen. Der Header-Name ist in der mit Bindestrichen geschriebenen Form abhängig von Groß- und Kleinschreibung, weil Qonto anmerkt, dass Varianten in Klein- oder Mischschreibung nicht von jeder Schicht der Kette normalisiert werden. Und der Header gilt nur für die Sandbox, weil die Produktivumgebung den Staging-Token überhaupt nicht annimmt.

Es gibt eine zweite Sandbox-Regel, die nichts mit Headern zu tun hat, weil es um einen Browser geht. Bevor Sie den Autorisierungsablauf gegen Staging starten, müssen Sie über Ihr Entwicklerportal-Konto in der Sandbox-Weboberfläche angemeldet sein, im selben Browser.

Maesns Dokumentation ist eindeutig in der Reihenfolge: öffnen Sie die Sandbox-Weboberfläche in einem Tab und melden Sie sich mit den Testzugangsdaten an, öffnen Sie dann einen zweiten Tab und starten Sie den Ablauf. Umgekehrt hat der Einwilligungsschritt keine Nutzersitzung, an die er sich hängen kann. Erscheint ein Bestätigungsbildschirm, lautet der Sandbox-Code immer 123456.

Die zwei veröffentlichten Zeitfenster sind großzügig, und der Satz darunter ist der, der Ihre Architektur entscheidet. Tausend Anfragen alle zehn Sekunden und zehntausend alle zehn Minuten, beantwortet mit 429, wenn Sie sie überschreiten. Dann: „Rate Limits werden je IP-Adresse angewendet.“

Nicht je Token, nicht je Anwendung und nicht je verbundenem Kunden. Wenn Ihre Worker sich eine Ausgangsadresse teilen, und das ist der Normalfall, dann schöpft jeder Kunde, den Sie je angebunden haben, aus einem Budget. Ein Erstabzug für einen neuen Mandanten ist nicht von der laufenden Synchronisation der anderen getrennt: er konkurriert mit ihnen.

Es lohnt sich zu sehen, dass dies eine echte Entscheidung ist und keine Selbstverständlichkeit. Fortnox misst fünfundzwanzig Anfragen alle fünf Sekunden je Access-Token, seine Obergrenze folgt also jedem angebundenen Kunden, und ein lauter Mandant kann die übrigen nicht aushungern. Qontos Obergrenze ist geteilt und ihre Zahl deutlich größer. Dasselbe Thema, der umgekehrte Entwurf und nur eines von beiden braucht einen globalen Scheduler.

Die dritte Zeile verdient einen eigenen Gedanken, weil sie überhaupt keine Mengenregel ist. Zweihundert Antworten mit 401 innerhalb einer Stunde bringen Ihnen eine Drosselung ein. Eine Wiederholungsschleife um einen abgelaufenen Token ist auf diesem System nicht bloß nutzlos, sie ist aktiv teuer: sie verbraucht Ihr Kontingent für Fehlschläge und senkt es anschließend.

Ein Client, der bei einem Authentifizierungsfehler anhält, ist hier also der richtige Client, und das ist ein anderer Reflex als der, den ein Timeout verdient.

Beides ist die Art von Sache, die Sie einmal behandelt haben wollen, nicht in jedem Job, den Sie schreiben, und dafür ist ein Fehlermodell da: ein Limit und ein totes Zugangsdatum kommen aus jedem System als dieselbe Form von Problem an, Ihr Code hat also eine Stelle, die den Unterschied zwischen Warten und Anhalten kennt.

Ein Objekt trägt hier ein freigeschaltetes Event, und das sind die Rechnungen. Die übrigen sechsunddreißig Objekte haben nichts, was man abonnieren könnte, ein geplanter Lesezugriff ist für sie also die ganze Geschichte ihrer Aktualität. Es gibt keinen künstlichen Ersatz, nach dem man greifen könnte.

Zwei Eigenschaften prägen das Abonnement. Es wird je Kunde angelegt, eine neue Verbindung ist also ein neues Abonnement und kein Filter auf einem bestehenden. Und Sie abonnieren die Ressource statt eines Event-Typs: Qonto sendet für Rechnungen Events über Anlage und Änderung, beide kommen auf demselben Abonnement an, und es gibt kein Lösch-Event, auf das man warten könnte.

Jetzt der Teil, der entscheidet, was Ihr Handler zu tun hat. Qontos eigenes Event für eine Kundenrechnung trägt den ganzen Beleg: Nummer, Status, Summen, Steuer, die Daten und die Positionen mit ihren Einzelpreisen und Sätzen.

Das Event, das über eine vereinheitlichte Schnittstelle ankommt, trägt einen Event-Typ, eine Ressource und eine Kennung. Zwei Felder kommen leer an, weil Qonto sie nicht sendet, und das ist nicht nur bei diesem System so: dieselben zwei sind bei Lexware Office aus demselben Grund leer.

Das Event ist also eine Türklingel und keine Lieferung, und die Schleife, die es startet, ist dieselbe Schleife, die ein Zeitplan starten würde. Das ist ein Entwurf, auf den Sie sich verlassen können: ein Codepfad liest eine Rechnung, und entweder eine Uhr oder ein Event entscheidet, wann er läuft.

In das Event-Modell übersetzt heißt das, dass Push und Pull sich ein Ziel teilen, und genau das wollen Sie auf einem System, auf dem ein Objekt pusht und sechsunddreißig es nicht tun.

Drei Zustellregeln von Qonto gehören in den Handler selbst. Bestätigen Sie innerhalb einer Sekunde mit einem 2xx und erledigen Sie die Arbeit danach, was in der Praxis heißt: Kennung in die Warteschlange und zurück.

Machen Sie den Handler idempotent, denn Wiederholungen folgen auch auf vorübergehende Fehler, und dasselbe Event kann zweimal ankommen. Und kennen Sie den Aufgabepunkt: fehlgeschlagene Zustellungen werden mit exponentiellem Backoff einige Tage wiederholt und dann aufgegeben, ein längerer Ausfall braucht also einen nachholenden Lesezugriff statt einer Wiedereinspielung.

Was wir von der Liste nehmen:

• Den OAuth-Austausch und die Scope-Liste. Use Case, Scopes und die Token-Behandlung sind für dieses System geklärt, und Ihre Seite bekommt einen angebundenen Kunden statt eines Einwilligungsablaufs, den sie bauen muss.
• Zwei Umgebungen, die sich unterschiedlich verhalten. Die getrennten Staging-Hosts und der Staging-Token bleiben hinter der Anbindung, Ihre Anfragen tragen also keinen Header, den es in der einen Umgebung gibt und den die andere ablehnt.
• Die Event-Verrohrung. Ein Abonnement-Aufruf je Kunde, eine geprüfte Zustellung und eine Nutzlast in derselben Form, die jedes andere System erzeugt, statt eines herstellereigenen Umschlags je Anbindung.

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

• Eine rein lesende Fläche in Ihrem Modell. Drei Objekte kommen zurück und nichts wird heute geschrieben. Wenn Ihr Feature davon abhängt, einen Beleg in die Bank zu schieben, ist das ein Gespräch, das vor dem Entwurf stattfindet, und kein Schalter, den man umlegt.
• Der zweite Aufruf nach jedem Event. Das Event benennt die Rechnung und Sie holen sie. Wir können den Abruf genauso aussehen lassen wie bei jedem anderen System; wir können nicht in das Event legen, was Qonto nicht gesendet hat.
• Die Planung gegen eine geteilte Obergrenze. Weil das Limit je IP-Adresse gilt, ist es eine Entscheidung in Ihrer eigenen Infrastruktur, wie Sie einen Erstabzug über Mandanten hinweg staffeln.
• Die Freigaben. Der Use Case, die Prüfung für den sensiblen Scope und, wenn Sie ein lizenzierter Partner sind, das Zertifikat. Sie anzustoßen ist Ihre Sache, und je früher sie anlaufen, desto weniger kosten sie.

Ein letztes Stück Abgrenzung, weil es jemandem einen Sprint spart. Wenn Ihr Kunde eigentlich seine Bankdaten im System seines Steuerberaters haben will, liefert Qonto das bereits als Produktfunktion: das Konto wird über Bankdatenservice, Belegbilderservice und Rechnungsdatenservice 1.0 an DATEV Unternehmen Online angebunden, eingeschaltet vom Kunden in der Qonto-App.

Eine Anbindung zu bauen, die das nachbildet, wäre Arbeit, nach der niemand gefragt hat. Eine zu bauen, die dieselben Daten in Ihr Produkt bringt, ist eine andere Aufgabe, und um die geht es in diesem Beitrag.