Bexio-Schnittstelle und API-Integration
bexio ist eine Cloud-Buchhaltungsplattform für Schweizer KMU, Freiberufler und die Treuhänder, die mit ihnen arbeiten. Sie deckt Rechnungsstellung, Ausgaben, Mehrwertsteuer, Bankabstimmung und die Buchführung nach Schweizer Vorgaben ab. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Eine bexio-Anbindung in Tagen
bexio ist eine kurze Integration mit einem langen Schatten: Die Entscheidungen, die Sie treffen, bevor sich Ihr erster Kunde verbindet, sind teuer zu revidieren. Hier stehen die drei, auf die es ankommt, und was Maesn davon abnimmt.
Einmal entschieden, mit der Objektliste vor sich
bexio gewährt den Zugriff Objekt für Objekt, und seine Dokumentation sagt ausdrücklich, dass ein Token-Refresh den Satz nie erweitert: Ein neuer Scope heißt, jeden angebundenen Kunden erneut durch den Zustimmungsbildschirm zu schicken. Maesn führt den Ablauf, Ihnen bleibt also die Entscheidung, welche Objekte freigeschaltet werden, und genau die führt die Abdeckungstabelle auf.
Die Ablehnung kommt in einer Form an, die Sie bereits verarbeiten
Der Zugriff braucht zwei Dinge gleichzeitig: den Scope, den Ihre App erhalten hat, und die Rechte des bexio-Nutzers, der diese Verbindung eingerichtet hat. Fehlt es auf einer der beiden Seiten, wird der Aufruf abgelehnt, und von außen sehen beide Fälle gleich aus. Über Maesn kommt diese Ablehnung vereinheitlicht zurück. Ein Rechteproblem auf bexio sieht also aus wie ein Rechteproblem überall sonst und nicht wie ein Fehler in Ihrem Code.
bexio-IDs, in benannte Objekte aufgelöst
Einen Kontakt anzulegen verlangt vier Pflichtfelder, und drei davon sind bexio-interne Ganzzahlen: ein numerischer Typ, der entscheidet, ob das Namensfeld eine Firma oder einen Nachnamen trägt, dazu zwei Verweise auf bexio-Nutzer. Maesn gibt den Typ als COMPANY oder CONTACT_PERSON zurück und löst die Verweise auf, Sie schreiben also Namen statt Zahlen.
Auf Ihrer Seite bleibt ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren. Teams gehen in Tagen live, und niemand muss vorher ein Quartal mit einem Schweizer Hauptbuch verbringen.
Der zweite der drei zeigt ein Symptom, das von seiner Ursache wegführt: Derselbe Aufruf gelingt bei einem Kunden und kommt beim nächsten abgelehnt zurück, ohne Unterschied in Ihrem Code und ohne Unterschied am Objekt. Der Grund ist, dass Bexio zwei Dinge prüft und beide braucht: den Scope, den Ihre App bekommen hat, und die Rechte des Bexio-Nutzers, der die Verbindung eingerichtet hat. Fehlt eine der beiden Seiten, wird der Aufruf abgelehnt, und die Ablehnung sieht in beiden Fällen gleich aus. Über Maesn kommt sie für jedes System in einer Form an: ein Fehlermodell über den ganzen Katalog bedeutet einen Status und einen Body zum Auslesen, der Bexio-Anteil daran gehört also in Ihr Support-Runbook und nicht in eine Verzweigung in Ihrem Client.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
HERO Software erreicht Schweizer Hauptbücher über dieselbe Verbindung
HERO Software digitalisiert das Backoffice für Handwerksbetriebe, vom Angebot bis zur Rechnung, und nennt die Schweiz als einen seiner vier Märkte neben Deutschland, Österreich und den Niederlanden.
“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 bexio-Schnittstelle über Maesn anzubinden
bexio direkt anzubinden ist ein Projekt, das Sie in einem Sprint abschließen können. Es ein Jahr am Leben zu halten, ohne ein einziges Event, auf das Sie reagieren können, und danach das nächste System hinzuzunehmen, entscheidet über Ihre Roadmap.
Die bexio-Arbeit bleibt hier
Der Scope-Satz, der Tausch des Authorization Code, das Refresh-Token, das es nur gibt, wenn Sie Offline-Zugriff angefordert haben, und die Ein-Jahres-Uhr auf dieser Sitzung sind das, was jede bexio-Integration lösen muss. Gelöst wird es einmal, hier, für jeden Kunden, den Sie anbinden.
Eine Zustimmung, und die Objektliste steht
bexio legt den Scope-Satz bei der Zustimmung fest. Die Objekte, die Ihr Produkt anfassen darf, werden also einmal mit der Liste vor sich entschieden, statt eine Ablehnung nach der anderen zu entdecken. Eines später hinzuzunehmen ist eine Zustimmung und keine Migration, und es ist eine Frage, die Sie vor einer Zusage an einen Kunden beantworten können.
Das nächste System kostet nichts
Sobald bexio läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle, mit demselben Datenmodell dahinter und denselben zwei Headern davor. Ihre zweite Integration ist ein Konfigurationsschritt, und ein Schweizer Kunde ist kein Grund mehr, ein zweites Projekt aufzumachen.
Was ein bexio-Marketplace-Eintrag wirklich verlangt
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei bexio liegen die beiden ungewöhnlich weit auseinander: Die API steht allen offen, und im Eintrag liegen die Bedingungen.
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, und der OpenID-Connect-Login, den bexio von seinen Partnern verlangt, gehört dazu.
Unterstützung bei der Partnerschaft
Die Bedingungen von bexio sind zuerst kaufmännisch und dann technisch. Der Eintrag folgt also einem laufenden Produkt, statt es aufzuhalten. Maesn geht Qualifizierung und Eintrag mit Ihnen durch, sobald Ihre Integration läuft und Ihre ersten bexio-Kunden darauf sind.
Die API steht allen offen
bexio sagt es unumwunden: Der API-Zugang ist nicht beschränkt, und jeder kann eine Integration dagegen bauen. Nichts in der Abdeckung wartet auf eine Partnerschaft, und am Ablauf ändert sich an dem Tag nichts, an dem Sie eine bekommen. Die Bedingungen unten regeln den Eintrag und nicht den Bau.
Der Eintrag hat acht Bedingungen
Mindestens 10 bexio-Kunden und 20 aktive Nutzer, eine definierte Zielgruppe, eine bedienbare Integration, Support für bexio-Kunden, die bexio-API mit OpenID-Connect-Login, ein unterschriebener Partnervertrag und eine Sprachregel: die App in zwei von Deutsch, Französisch, Italienisch und Englisch, die Inhalte des Eintrags in allen vieren.
Die Gebühr folgt dem Umsatz
bexio verlangt keine Jahresgebühr, keinen Mitgliedsbeitrag und keine Kosten für den Eintrag. Es nimmt eine Servicegebühr von 25 Prozent auf den Umsatz mit gemeinsamen Nutzern, also mit Kunden, die beide Produkte einsetzen, und 20 Prozent für Partner im obersten Fünftel nach Umsatz. bexio zieht diese Zahlungen direkt ein und verlangt Preisgleichheit mit Ihren anderen Kanälen.
Die Integration läuft unter dem Namen Ihres Produkts, und der Eintrag gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir gehen die Qualifizierung mit Ihnen durch, sobald die Integration läuft.
Ein bexio-Flow, und die Scopes reisen mit
bexio authentifiziert über den Authorization-Code-Grant von OAuth 2.0 gegen seinen eigenen Identity Provider, mit OpenID Connect darüber. bexio dokumentiert einen einzigen Ablauf, und wichtig daran ist, was dieser Ablauf trägt: die Scopes, die Ihre App anfragt, und die Rechte der Person, die sie gewährt.
- OAuth 2.0 Authorization Code
- Mit OpenID Connect darüber
Ein Ablauf, und er erfüllt sowohl die direkte Nutzung als auch die Marketplace-Anforderung.
- Der Scope-Satz
- bexio teilt den Zugriff je Objekt in einen Lese- und einen Schreib-Scope, und wer den Schreib-Scope anfordert, bekommt den Lese-Scope dazu. Der Satz läuft in der Autorisierungsanfrage mit. Er steht also mit der Zustimmung fest und lässt sich durch ein Refresh nicht erweitern.
- Wessen Rechte gelten
- Die Verbindung läuft mit den Rechten des bexio-Nutzers, der sie angelegt hat. Zwei Administratoren derselben Firma können damit zwei Verbindungen erzeugen, die unterschiedliche Daten sehen, und nichts in Ihrem Code wird erklären, warum.
Bexio stellt auch persönliche Zugriffstokens aus, und der Grund, sie hier zu erwähnen, ist, dass Sie nicht danach greifen: Bexio gibt ihnen alle Standard-Scopes, lässt sie nach 60 Tagen ablaufen und sagt, dass sie strikt für den persönlichen Gebrauch sind und nie geteilt werden sollten. Eine Produktintegration gehört auf den Authorization-Code-Ablauf, und der läuft hier.
- 1
Ihr Kunde wird zu bexio geschickt
Maesn baut die Autorisierungsanfrage gegen den Identitätsanbieter von bexio und leitet Ihren Kunden dorthin. Er sieht die Anmeldung von bexio selbst und einen Zustimmungsbildschirm, der genau die Rechte auflistet, die die Anfrage verlangt hat.
- 2
bexio leitet zu Maesn weiter, nicht zu Ihnen
Der Authorization Code kommt an die Redirect-URL zurück, die Sie an der App registriert haben, und das ist der Callback von Maesn für bexio. Maesn tauscht ihn mit Ihrer Client-ID und Ihrem Secret gegen die Tokens. Das Secret läuft also nie durch Ihr Frontend.
- 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, dieselben zwei Header, die Sie für jedes andere System im Katalog ohnehin schon senden.
Jedes System im Katalog authentifiziert anders, und bei Bexio ist der Ablauf gewöhnlich und seine Nutzlast nicht: keine Umgebung zu wählen, kein Firmencode aufzulösen, dafür ein Berechtigungssatz, der in dem Moment festgeschrieben wird, in dem Ihr Kunde auf Zustimmen klickt. Unified Authentication verhindert, dass Ihnen das zweimal zum Problem wird: Der Redirect, der Code-Austausch, das Refresh und der Account-Key funktionieren hier genauso wie bei einem System mit API-Schlüssel oder Firmenauswahl, und die Bexio-eigene Frage, die bleibt, ist, welche Objekte Sie anfragen.
bexio-Daten bleiben aktuell mit einem geplanten Abruf
bexio veröffentlicht keine Webhooks. Kein Objekt in der Abdeckungsmatrix trägt eines, und das Wort kommt in der eigenen API-Referenz von bexio kein einziges Mal vor, über 310 dokumentierte Operationen hinweg. Nichts im Konto eines Kunden wird Ihren Endpunkt aufrufen.
Nichts. Jede Event-Spalte in der Matrix ist entweder eine Anfrage oder leer, und die Referenz von bexio selbst hat keinen Abschnitt zu Webhooks, auf den man ausweichen könnte. Eine Änderung im Konto eines Kunden bleibt also unsichtbar, bis etwas sie liest.
Ein geplanter Lesezugriff, mit der Paginierung, die Sie überall sonst schon benutzen. Bei Kontakten verengt er sich auf einen Filter nach letzter Änderung und fragt nur, was sich geändert hat. Bei den anderen fünf lesbaren Objekten sind die dokumentierten Parameter die Seite und die Seitengröße. Dieser Lesezugriff ist also ein voller Durchlauf.
Weil die Erkennung ein Lesezugriff ist und kein Push, wird die Aktualität zur Frage des Intervalls, und das ist eine Entscheidung mit einem Vorteil: Ein geplanter Lesezugriff holt nach einem Ausfall sauber nach, wo ein verpasster Push schlicht weg ist. Bexio begrenzt Anfragen je Firma und Minute und gibt das verbleibende Budget in einem Antwort-Header zurück. Ihr Intervall kann sich also an der veröffentlichten Obergrenze orientieren.
Praktisch heißt das, dass Bexio nicht einen Zeitplan will. Ein Kontenrahmen und eine Steuersatzliste bewegen sich ein paar Mal im Jahr und lassen sich über Nacht vollständig neu lesen. Kontakte bewegen sich fortlaufend und haben den Filter, der es belegt, sie tragen also den häufigen Lauf. Beide gleich zu dimensionieren heißt entweder, einen vollen Durchlauf zu bezahlen, den Sie nicht gebraucht haben, oder einen Tag später von einem umbenannten Kunden zu erfahren, und keines von beidem ist eine Grenze der Anbindung.
Günstig werden beide dadurch, dass keiner davon Bexio-eigener Code ist, und genau den bekommt eine Integration je System nie: ein Weg, zu filtern und zu paginieren bedeutet, dass die Schleife auf Bexio dieselbe ist wie die auf alles andere, ob ein Filter da ist oder nicht. Und sie funktioniert weiter, sobald das System darunter doch sendet, denn das Event-Modell ist ein eigener Weg und kein Ersatz für diesen. Sie schreiben den Zeitplan einmal und tauschen den Account-Key.
Vier Dinge, die eine bexio-Anbindung zuerst braucht
bexio stellt vier Dinge vor eine Integration, und jedes davon lässt sich günstiger einplanen als auf halber Strecke entdecken.
- Ein bexio-Konto mit Administratorrechten
- Das Konto ist nur dafür da, die App zu halten, die Sie registrieren. Die Dokumentation von bexio sagt genau das: Für etwas anderes brauchen Sie es nicht, und ein kostenloses Testkonto genügt dafür.
- Eine App im Entwicklerportal von bexio
- Sie legen sie auf developer.bexio.com an, mit dem Namen Ihres Produkts, der URL Ihres Unternehmens und der Redirect-URL https://api.maesn.dev/auth/callback/bexio. Client-ID und Client Secret gehen an Ihren Ansprechpartner bei Maesn. Eine App nimmt bis zu zehn Redirect-URLs, und bexio empfiehlt eigene Zugangsdaten für die Produktion, statt die aus dem Test weiterzuverwenden.
- Die Objektliste, bevor sich der erste Kunde verbindet
- Weil ein breiterer Scope eine neue Zustimmung braucht, benennen Sie die Objekte, die Ihr Anwendungsfall braucht, bevor Sie bauen. Alles, was in der Matrix mit auf Anfrage gekennzeichnet ist, lässt sich auf Anfrage freischalten, und diese Anfrage ist ein viel kürzeres Gespräch, bevor Ihre Kunden angebunden sind, als danach.
- Ein Testkonto, und davon gibt es zwei Arten
- bexio bietet einen kostenlosen Test an, für den Sie sich selbst anmelden können, und Maesn stellt eine Sandbox mit Testdaten bereit. Für bexio sind beide aufgeführt, und das gilt nicht für jedes System im Katalog: DATEV, Fortnox und Twinfield haben überhaupt keinen kostenlosen Test.
Wir gehen die App-Registrierung und die Objektliste mit Ihnen durch.
Ein bexio-Kontakt kommt in einer gemeinsamen Form
Bexio führt seine Geschäftspartner an einer Stelle und unterscheidet sie über eine Nummer. Diese Entscheidung reicht bis in Ihr Schema, also treffen Sie die eigene besser bewusst, bevor Sie etwas abbilden.
bexio hat keine Gutschriften und keine getrennten Lieferanten
Zwei Dinge, die eine Hauptbuch-Integration üblicherweise voraussetzt, gibt es in diesem System nicht. Die Dokumentation von bexio beantwortet die Frage nach Gutschriften mit einem klaren Nein, und ein Lieferantenobjekt gibt es dort überhaupt nicht: Jeder Geschäftspartner ist ein Kontakt, auf welcher Seite der Rechnung er auch steht. Das erste ist eine Funktion, die bexio nicht anbietet, das zweite ein anderes Vokabular, und nur das zweite ändert Ihr Modell.
Eine bexio-Buchung wird an zwei Stellen geschrieben und gelesen
bexio nennt einen Buchungssatz eine manuelle Buchung und schreibt ihn auf seine Accounting-Ressource, während der Weg zurück eine Journalauswertung ist, die einen Zeitraum verlangt. Maesn zeigt ein Objekt für beide Richtungen. Die Asymmetrie bleibt also hier und wird nicht zu zwei Codepfaden in Ihrem Produkt.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, ein Kontakt aus Bexio hat also dieselbe Form wie ein Kontakt aus einem zehnmal so großen System, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden. Bei Bexio leistet diese Abbildung mehr als sonst: Ein Kontakt kommt dem Namen nach als Firma oder als Kontaktperson an, wobei das Quellfeld eine Zahl ist, deren Wert zugleich entscheidet, was das Namensfeld daneben bedeutet.
Was bis in Ihr Schema reicht, sind die Rollen. Wenn jeder Geschäftspartner in Bexio ein Kontakt ist, dann sind Käufer und Verkäufer derselbe Datensatz, nur aus zwei Richtungen gelesen, und die Seite, die diese Unterscheidung hält, ist Ihre. Lieferanten und Kunden kommen über denselben Endpunkt, eine Zuordnungsregel, die gegen ein System mit zwei getrennten Objekten geschrieben ist, lässt sich also nicht unverändert übertragen. Zu entscheiden, wo die Rolle liegt, bevor Sie etwas abbilden, kostet jetzt ein Gespräch und später eine Migration.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
