Qonto-Schnittstelle und API-Integration
Qonto ist eine europäische Finanzplattform für Unternehmen und deckt Geschäftskonten, Ausgabenverwaltung und Rechnungsstellung ab. Es ist die einzige Bankplattform in diesem Katalog, während jedes andere System ein Buchhaltungspaket oder ein ERP ist, und das ändert, was eine Anbindung daran bedeutet: Die App, die Sie registrieren, wird nach den Regeln für den Zahlungsverkehr geprüft, bevor sie ein Kundenkonto berühren darf. Binden Sie es über Maesn an, und Sie erreichen es mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Eine Qonto-Anbindung in Tagen, bis auf eine Wartezeit
Qonto ist das System in diesem Katalog, bei dem der schwierige Teil nicht der Code ist. Drei Dinge stehen zwischen einem Prototyp und einem angebundenen Kunden, und nur das erste bleibt bei Ihnen.
Die App-Prüfung bleibt bei Ihnen
Qonto stuft den Organisationszugriff als sensiblen Scope unter PSD2 ein, und der Anwendungsfall, unter dem Sie sich registrieren, die Konten Ihrer Kunden anzubinden, braucht dessen Freigabe. Diese Prüfung dauert ein paar Tage und steht vor der Produktion, nicht vor dem Bau: Die Sandbox steht meist sofort bereit, Sie entwickeln also, während sie läuft. Sie registrieren die App, wir gehen den Scope-Satz und die Einreichung mit Ihnen durch, und alles nach der Freigabe gehört uns.
Die Token-Rotation wird hier erledigt
Ein Access-Token lebt eine Stunde und ein Refresh-Token neunzig Tage, und jede Erneuerung gibt ein neues Refresh-Token zurück, das an die Stelle des alten gehört. Maesn hält das aktuelle Paar für jeden angebundenen Kunden und rotiert es rechtzeitig, kein Teil dieses Zeitplans erreicht also Ihren Code.
Eine Filtersprache über alle Systeme hinweg
Buchungsvorschläge kommen ohne Filter nach Belegart zurück, nur die Rechnungen zu lesen heißt also, alles zu holen und selbst zu sortieren. Über die letzte Seite hinaus zu fragen liefert einen 422 und keine leere Liste. Maesn stellt den Filter bereit und macht aus dem 422 eine leere Antwort. Die Schleife, die Sie auf Qonto richten, ist also die, die Sie ohnehin fahren.
Es bleiben ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren, und eine Prüfung, die Sie in den Release-Plan einplanen können, statt sie im letzten Sprint zu entdecken.
Die Prüfung ist der Punkt, um den herum Sie planen sollten, weil sie als einzige der drei bei Ihnen bleibt. Qonto prüft die App, weil der Scope-Satz an Kontodaten reicht, und nicht, weil der Papierkram langsam wäre. Maesn kann dafür sorgen, dass Sie den richtigen Anwendungsfall und die richtigen Scopes gleich beim ersten Mal beantragen, damit die Tage, die Sie warten, die Prüfung sind und keine zweite Einreichung.
Alles nach dieser Freigabe funktioniert wie der Rest des Katalogs. Ein fehlender Scope kommt über ein Fehlermodell zurück, ein Berechtigungsproblem bei Qonto sieht also aus wie eines bei einem Buchhaltungssystem.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Paywise liest die überfällige Rechnung, wo immer sie liegt
Paywise treibt unbezahlte Rechnungen für Unternehmen ein, von der ersten Mahnung bis zur gerichtlichen Durchsetzung. Rechnungen sind zugleich das eine Qonto-Objekt, das ein natives Event trägt. Eine Plattform, die auf diesem Beleg aufsetzt, erreicht diese Anbindung also über dieselbe Schnittstelle, die sie ohnehin nutzt.
“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 Qonto-Schnittstelle über Maesn anzubinden
Eine Qonto-Integration ist schnell gebaut und bleibt danach reguliert. Was Sie das über die Zeit kostet, ist der Teil, den man besser vor dem Start entscheidet.
Die Qonto-Eigenheiten bleiben hier
Maesn nimmt den Scope-Satz und die Prüfung auf, die er auslöst, das stündliche Token und seine Rotation, die Sandbox, die daneben eine offene Browsersitzung braucht, und den 422, den Qonto hinter der letzten Seite zurückgibt. Jedes davon wird einmal hier gelöst, für jeden Kunden, den Sie anbinden.
Eine kleine Oberfläche, genau benannt
Eingangsrechnungen, Buchungsvorschläge und Rechnungen sind heute lesbar, und was nicht freigeschaltet ist, ist auf Anfrage verfügbar. Darum geht es, das vor dem Zuschnitt einer Funktion zu wissen: Die Liste ist kurz, und sie ist genau.
Das nächste System kostet nichts
Sobald Qonto läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle, mit demselben Datenmodell dahinter und denselben zwei Headern davor. Ein Kunde, der bei Qonto bankt und in einem anderen System bucht, ist eine Integration und nicht zwei.
Was ein Qonto-Eintrag wirklich verlangt
Qonto veröffentlicht seine Integrationen in einem Bereich für Integrationen und Partnerschaften, und die Bedingungen betreffen ein Produkt, das bereits läuft, und keinen Plan. Maesn übernimmt die technische Seite und geht den Eintrag mit Ihnen durch.
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, einschließlich des OAuth-Ablaufs, den Qonto für diesen Anwendungsfall verlangt.
Unterstützung bei der Partnerschaft
Die Bedingungen von Qonto beginnen mit echter Nutzung. Der Eintrag folgt also einer laufenden Integration, statt sie aufzuhalten. Maesn bereitet die Einreichung mit Ihnen vor, sobald Ihre ersten Qonto-Kunden angebunden sind.
Fünfundzwanzig Betatester, die es nutzen
Qonto verlangt, dass die Integration von mindestens 25 Betatestern aktiv genutzt wird, bevor es sich einen Eintrag ansieht. Das ist eine Nutzungsschwelle und keine Gebühr, und deshalb gehört das Gespräch über den Eintrag hinter den Bau und nicht davor.
Eine Einreichung, die Qonto testen kann
Die Einreichung geht per E-Mail an das Partnerteam von Qonto und trägt zwei Dinge: eine Videovorführung dessen, was die Integration tut, und Zugangsdaten, damit Qonto sie selbst öffnen und testen kann. Geprüft wird sie von Menschen und nicht von einem Formular.
Inhalte für die Eintragsseite
Nach der Freigabe liefern Sie alles, was auf der Integrationsseite im Verzeichnis von Qonto erscheint: was die Integration tut, für wen sie ist und wie ein Kunde sie einschaltet. Der Eintrag läuft unter dem Namen Ihres Produkts, und darum geht es dabei.
Die Integration gehört Ihnen und der Eintrag gehört Ihnen. Maesn ist die Schicht dahinter.
Wir bereiten die Einreichung mit Ihnen vor, sobald die Integration läuft.
Ein Qonto-Flow, und ein Scope, der eine Freigabe braucht
Qonto authentifiziert über OAuth 2.0, und die Entscheidung, auf die es ankommt, fällt vor dem ersten Redirect: Der Anwendungsfall, unter dem Sie die App registrieren, bestimmt, welche Scopes Sie anfragen dürfen und ob Qonto Sie freigeben muss.
- OAuth 2.0 Authorization Code
- Der einzige Weg für eine Plattform, die Kundenkonten anbindet
Ein Ablauf, ein Account-Key, und dieselben zwei Header, die Sie für jedes andere System senden.
- Unter welchem Anwendungsfall Sie sich registrieren
- Qonto bietet mehrere an, und sie sind nicht austauschbar. Ein Qonto-Kunde, der sein eigenes Konto automatisiert, braucht keine Freigabe und darf einen API-Schlüssel benutzen. Eine Plattform, die die Konten ihrer Kunden anbindet, ist ein anderer Anwendungsfall, läuft nur über OAuth und ist der, den diese Integration benutzt.
- Welcher Scope die Prüfung auslöst
- Von den neun Scopes in der Einrichtung steht genau einer auf der Liste der sensiblen Scopes von Qonto: der Organisationszugriff. Qonto kennzeichnet ihn als sensibel, weil er Salden, IBANs und die Umsatzhistorie erreicht, und das ist unter PSD2 reguliert und bringt die starke Kundenauthentifizierung mit sich. Dieser eine Eintrag macht aus der Registrierung eine Freigabe.
Qonto dokumentiert durchaus einen API-Schlüssel, und es lohnt sich zu wissen, warum er hier nicht der Weg ist: Qonto bindet ihn an den Anwendungsfall, in dem ein Qonto-Kunde sein eigenes Konto automatisiert. Eine Plattform, die fremde Konten anbindet, registriert sich unter einem anderen Anwendungsfall, und für den dokumentiert Qonto OAuth als Zugangsverfahren. Es gibt für diese Integration also keinen Qonto-API-Schlüssel zu finden, und danach zu suchen ist ein Zeichen dafür, dass die App unter dem falschen Anwendungsfall registriert ist.
- 1
Ihr Kunde wird zu Qonto geschickt
Maesn baut die Autorisierungsanfrage und leitet Ihren Kunden zu Qonto. Er sieht die Anmeldung von Qonto selbst und einen Zustimmungsbildschirm, der genau die Rechte auflistet, die Ihre App verlangt hat, unter dem Namen und dem Logo Ihrer App.
- 2
Qonto leitet zu Maesn weiter, nicht zu Ihnen
Der Authorization Code kommt an die Redirect-URL zurück, die an Ihrer App registriert ist, und das ist der Callback von Maesn. Maesn tauscht ihn mit Ihrer Client-ID und Ihrem Secret gegen die Tokens. Das Secret läuft also nie durch Ihr Frontend. Der Code selbst ist kurzlebig, der Tausch passiert deshalb sofort.
- 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 API-Schlüssel und diesen Account-Key, und die stündliche Rotation dahinter gehört uns. Möglich macht das der Scope für den Offline-Zugriff in der Einrichtung: Ohne ihn gibt es kein Refresh-Token, und die Verbindung endet nach einer Stunde.
Jedes System im Katalog authentifiziert anders, und bei Qonto ist der Ablauf gewöhnlich und seine Bedingungen sind es nicht: ein üblicher Austausch über einen Authorization Code, der aber erst funktioniert, nachdem jemand bei Qonto gelesen hat, was Ihr Produkt tut. Das stündliche Token darunter ist der Teil, den niemand sieht. Jedes Refresh gibt ein neues Refresh-Token zurück, das das alte auf der Stelle ersetzen muss, und das ist ein kleines Stück Buchführung, das für jeden angebundenen Kunden laufen muss, dauerhaft.
Unified Authentication verhindert, dass Ihnen das zweimal zum Problem wird: Der Redirect, der Code-Austausch, die Rotation und der Account-Key funktionieren hier genauso wie bei einem System mit API-Schlüssel oder Firmenauswahl. Die Qonto-eigene Frage, die bleibt, ist, unter welchem Anwendungsfall Sie sich registrieren, und die ist beantwortet, bevor Sie eine Zeile Code schreiben.
Ein Qonto-Objekt sendet ein Event, die anderen zwei lesen Sie
Qonto sendet Events, und eine Ressource ist heute über Maesn verdrahtet. Rechnungen sind das Objekt mit einem nativen Event in der Abdeckungsmatrix, und Eingangsrechnungen und Buchungsvorschläge sind Lesezugriffe, die Sie planen. Maesn abonniert je angebundenem Kunden und vereinheitlicht die Nutzlast. Die Form, die Sie hier verarbeiten, ist also die Form, die Sie überall verarbeiten.
Eine Ressource, und Qonto abonniert je Ressource statt je Event-Typ: Sie registrieren sich für Rechnungen und erhalten jedes Event, das Qonto dafür meldet.
Zwei Typen, und ein Lösch-Event gibt es nicht: Qonto meldet nur angelegt und aktualisiert. Eine entfernte Rechnung findet also erst ein Lesezugriff.
Die Nutzlast ist die Stelle, an der Qonto abweicht, und sie weicht in eine nützliche Richtung ab: Das Event trägt die ID der Rechnung, die sich geändert hat, aber keinen Zeitstempel und keinen Nutzer, beides markiert die Integrationsdokumentation von Qonto als nicht unterstützt. Das Event sagt Ihnen also, welchen Datensatz Sie neu lesen sollen, statt was sich darin geändert hat, und der Lesezugriff danach ist derselbe, den Sie für Eingangsrechnungen und Buchungsvorschläge ohnehin fahren. Business Central ist der umgekehrte Tausch, wo das Event einen Zeitstempel trägt und keine ID.
Ein Event, das eine ID trägt und keinen Zeitstempel, ist nützlicher, als es klingt, denn es nimmt die Frage weg, die ein Abfragelauf nie sauber beantwortet: welcher Datensatz sich bewegt hat. Sie nehmen die ID, lesen diese eine Rechnung, und fertig. Was es Ihnen nicht gibt, ist ein Fenster, nach dem Sie fragen können, es ersetzt also einen Lesezugriff nach Zeitplan für Rechnungen und macht anderswo keinen überflüssig. Eingangsrechnungen und Buchungsvorschläge haben gar kein Event, und diese beiden bleiben auf einem Intervall, das Sie wählen.
Bei den Buchungsvorschlägen endet auch Qontos eigenes Filtern, und es ist das Objekt, bei dem Sie das am wenigsten wollen: Es gibt keine Möglichkeit, nach einem Belegtyp zu fragen, nur die Rechnungen darunter zu lesen heißt also, alle zu holen und clientseitig zu sortieren.
Die zweite Kante ist die Paginierung, und sie beendet eine Leseschleife mit einem Fehler statt mit einem Ergebnis: Eine Anfrage hinter der letzten Seite kommt als 422 zurück und nicht als leere Liste, die Schleife, die darauf wartet, dass nichts mehr zurückkommt, erreicht diesen Punkt also nie. Ein Weg, zu filtern und zu paginieren schließt beide Lücken. Bei uns heißt das Unified Pagination & Filtering, es stellt den Filter bereit, den Qonto nicht anbietet, und antwortet hinter der letzten Seite mit einer leeren Antwort, die Schleife, die Sie auf Qonto richten, ist also die, die Sie ohnehin fahren. Und das Event-Modell ist dasselbe, in das jedes andere System meldet, der Handler, den Sie für eine Qonto-Rechnung schreiben, ist also der, den es schon gibt.
Vier Dinge, die eine Qonto-Anbindung zuerst braucht
Qonto stellt vier Dinge vor eine Integration, und am ersten hängt ein Kalender.
- Ein Entwicklerkonto und eine App, von Ihnen registriert
- Sie melden sich auf developers.qonto.com an, legen eine App unter dem Anwendungsfall für das Anbinden der Konten Ihrer Kunden an, geben ihr einen Namen und ein Logo, das Ihre Nutzer sehen, und tragen die Redirect-URL https://api.maesn.dev/auth/callback/qonto ein. Client-ID und Client Secret gehen danach an Ihren Ansprechpartner bei Maesn.
- Vorlauf für die Prüfung, denn sie ist keine Formalität
- Der Scope-Satz enthält den Organisationszugriff, den Qonto unter PSD2 als sensibel einstuft, weil er Salden, IBANs und die Umsatzhistorie erreicht. Qonto gibt selbst vor, dass dieser Anwendungsfall eine Freigabe braucht, und die Dokumentation sagt, dass die Prüfung ein paar Tage dauert. Sie hält die Produktion auf und nicht die Entwicklung, denn die Sandbox ist meist sofort da. Planen Sie sie in das Release ein, statt um sie herum.
- Eine Sandbox, und ein Schritt, den man leicht übersieht
- Qonto hat kein kostenloses Testkonto, stellt aber eine Sandbox bereit, mit eigenen Zugangsdaten, eigener Redirect-URL und einem X-Qonto-Staging-Token. Der Schritt, über den man stolpert: Melden Sie sich in einem Browser-Tab an der Sandbox-Weboberfläche an und lassen Sie diese Sitzung offen, und starten Sie den OAuth-Ablauf in einem zweiten. Ohne das scheitert der Ablauf an einem CSRF-Fehler oder einer Weiterleitung zur Anmeldung.
- Ein Anwendungsfall, der liest
- Über diese Verbindung ist heute nichts schreibbar. Wenn Ihr Produkt nach Qonto buchen muss, ist das ein Gespräch über die Spalte auf Anfrage und kein Schalter, den man umlegt, und es ist ein viel kürzeres, bevor Sie einem Kunden einen Termin zugesagt haben.
Wir gehen die App-Registrierung und den Scope-Satz mit Ihnen durch.
Eine Form für Qonto, und für das nächste System
Qonto ist die einzige Bankplattform in diesem Katalog. Zurück kommen deshalb die Belege, die über ein Geschäftskonto laufen, und keine Buchungssätze. Eine gemeinsame Form stellt sie neben das Buchhaltungssystem, das Ihr Kunde parallel dazu betreibt.
Freigeschaltet sind hier Belege
Die drei lesbaren Objekte sind Eingangsrechnungen, Buchungsvorschläge und Rechnungen. Kein Kontakt-, Kunden- oder Lieferantenobjekt ist freigeschaltet, was zurückkommt, beschreibt also, was abgerechnet wurde, und nicht, wer abgerechnet hat. Eine Zuordnungsregel, die gegen ein System mit einem Kundendatensatz geschrieben ist, lässt sich nicht übertragen, und die Seite, die die Identität halten muss, ist Ihre.
Die Bankbuchung ist kein lesbares Objekt
Buchungen stehen bei Qonto in der Spalte auf Anfrage, und das ist das Gegenteil dessen, was eine Bankplattform nahelegt. Über alle 30 und mehr Systeme der Matrix hinweg ist das Lesen von Buchungen auf keinem einzigen freigeschaltet. Das ist also die Form des Katalogs und keine Lücke hier. Was Qonto Ihnen heute gibt, ist die Belegseite eines Kontos.
Die übrigen Zellen stehen auf Anfrage
Für kein Objekt ist das Löschen freigeschaltet, und die Buchhaltungspraxis erwartet Korrekturen ohnehin als neue Belege. Wichtiger ist die Spalte auf Anfrage selbst: 62 Kombinationen sind als auf Anfrage verfügbar gekennzeichnet, und das heißt, dass sie für Sie umgesetzt werden können, und nicht, dass sie darauf warten, eingeschaltet zu werden. Fragen Sie nach einer, bevor Sie eine Funktion darauf planen.
Eingangsrechnungen, Buchungsvorschläge und Rechnungen sind das, was eine Qonto-Anbindung heute liest, und was zurückkommt, kommt im gemeinsamen Common Data Model an, eine Rechnung aus einem Geschäftskonto hat also dieselbe Form wie eine Rechnung aus einem Buchhaltungssystem, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden.
Eine Entscheidung lohnt sich, bevor Sie etwas abbilden: wo die Gegenpartei liegt. Eine Qonto-Eingangsrechnung sagt Ihnen, was berechnet wurde, und der Geschäftspartner dahinter kommt aus dem Buchhaltungssystem, das Ihr Kunde neben Qonto betreibt und das über dieselbe Schnittstelle erreichbar ist. Das früh zu klären kostet ein Gespräch, es spät zu klären kostet eine Migration.
Was bleibt, ist eine genaue Oberfläche statt einer breiten: die Belege, die durch ein Geschäftskonto laufen, einer davon mit einem Event darauf. Das genügt, um eine Debitoren- oder Kreditorenfunktion darauf zu bauen, und es genügt nicht, um ein Hauptbuch darauf zu bauen. Welches von beidem Sie brauchen, klärt man besser vor der App-Registrierung, denn die Registrierung ist der Schritt mit der Wartezeit daran.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
