Fortnox-Schnittstelle und API-Integration
Fortnox ist die meistgenutzte Buchhaltungsplattform für KMU in Schweden und deckt Buchführung, Rechnungsstellung und Lohn für mehr als 600.000 Unternehmen in den nordischen Ländern ab. Binden Sie es über Maesn an, und Sie erreichen es mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System, ohne eigene schwedische Zugangsdaten.
Für Fortnox bauen, ohne schwedische Zugangsdaten
Die meisten Integrationen in diesem Katalog beginnen damit, eine API zu lesen. Diese beginnt früher, an der Tür: Fortnox prüft, wer Sie sind, bevor es Sie bauen lässt. Hier steht, was im Weg steht, und was Maesn davon abnimmt.
Eine Sandbox, die keine verlangt
Fortnox ist fest in schwedische Geschäftsabläufe eingebunden, und wer ein Konto oder eine Testfirma anlegt, muss eine Personen- oder Organisationsnummer bestätigen. Die Dokumentation von Maesn führt Fortnox als System, für das es keinen kostenlosen Test gibt und stattdessen eine Maesn-Sandbox bereitsteht. Ein Team außerhalb Schwedens kann also bauen, bevor es eine schwedische Gesellschaft hat.
Übersicht und Einzelheiten sind zwei Lesezugriffe
Die Listen-Endpunkte von Fortnox liefern von Haus aus eine Auswahl von Feldern. Die vollständigen Einzelheiten bedeuten also einen zweiten Aufruf je Datensatz über dessen ID. Eine Seite mit 100 Ergebnissen ist damit eine Seite mit bis zu 100 Folgeabrufen, und das gegen die Grenze je Token zu planen ist die eigentliche Arbeit. Über Maesn benutzen beide Lesezugriffe dieselbe Schnittstelle, dasselbe Paging und dieselbe Form wie jedes andere System, das Sie anbinden, Sie planen also Aufrufe ein und keinen neuen Client.
Einmal gewählt, dann für Sie verwahrt
Sie legen die Integration im Entwicklerportal von Fortnox an, tragen den Callback von Maesn ein und haken sieben Scopes mit schwedischen Namen an, von Bokföring bis Leverantörsfaktura. Danach übergeben Sie Client-ID und Secret, und der OAuth-Handshake, das Token-Refresh und jeder Zustimmungsbildschirm danach laufen hier.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Teams gehen in Tagen live, und das System nach Fortnox ist ein Konfigurationsschritt und kein zweites Projekt.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Tipalti betritt einen Markt über dessen lokales ERP
Tipalti automatisiert die Kreditorenbuchhaltung, und die Plattform ist so viel wert wie das, worin sie buchen kann. Jeder Markt, in den sie eintreten, hängt an dem Buchhaltungssystem, auf dem dieser Markt läuft, und deshalb behandeln sie diese Systeme nicht mehr als Entwicklungsarbeit.
“Mit Maesn haben wir unsere europäische Expansion beschleunigt, weil komplexe ERP-Integrationen über Benelux und DACH hinweg reibungslos laufen. Für eine AP-Plattform ist verlässlicher Zugang zu den wichtigen lokalen ERP-Systemen entscheidend, und genau den gibt uns Maesn.”
Drei Gründe, die Fortnox-Schnittstelle über Maesn anzubinden
Fortnox anzubinden ist ein kurzer Bau hinter einer langen ersten Woche. Danach kommt dieselbe Pflege, die jedes andere System von Ihnen verlangt, und danach das nächste Land.
Die schwedische Hälfte bleibt hier
Die Sandbox, die Entwicklerregistrierung und der OAuth-Handshake sind das, was jede Fortnox-Integration bezahlt, bevor sie eine einzige Rechnung liest. Gelöst wird es einmal, hier, für jeden Kunden, den Sie anbinden.
Tiefe, die Sie nachprüfen können
Konten, Eingangsrechnungen, Kunden, Lieferanten, Rechnungen, Journale und Buchungssätze lassen sich hier alle lesen, und bis auf die Journale lässt sich jedes davon auch schreiben. Lesen und Schreiben sind auf diesem System zwei verschiedene Listen. Die Frage lautet also, ob die Objekte, die Ihr Anwendungsfall braucht, auf der richtigen stehen, und das beantwortet unsere Dokumentation je Objekt.
Das nächste System kostet nichts
Sobald Fortnox läuft, antwortet jedes andere unterstützte System auf derselben Schnittstelle. Ihre zweite Integration ist ein Konfigurationsschritt, und Ihr zweiter Markt eine kaufmännische Entscheidung statt einer technischen.
Ihre Anbindung, gefunden in Fortnox selbst
Die meisten Anbieter hören bei der API auf. Maesn bereitet auch den Eintrag vor, und bei Fortnox macht der Eintrag einen schwedischen Markt überhaupt erst erreichbar: Über ihn findet ein schwedisches Unternehmen eine Integration überhaupt erst, aus dem Produkt heraus, das es ohnehin nutzt.
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 hilft Ihnen, die technischen und sicherheitsbezogenen Anforderungen zu erfüllen, gegen die Fortnox prüft, und steht danach weiter hinter der Integration. Der Eintrag trägt den Namen Ihres Produkts, nicht unseren.
Bauen und produktionsreif machen
Am Eintrag hängt der Bau selbst nicht. Das ist also Entwicklungszeit und keine Wartezeit. Sie registrieren sich als Entwickler, bauen gegen die Sandbox und bringen die Integration in einen Zustand, auf den Sie einen Kunden setzen würden.
Beim Fortnox-Partnerteam einreichen
Sie bewerben sich, indem Sie das Partnerteam von Fortnox mit den Angaben ansprechen, die es prüft: Name, Beschreibung, Logo und ein Support-Kontakt. Für diesen Schritt ist die technische und sicherheitsbezogene Vorbereitung von Maesn da.
Aus Fortnox heraus gefunden werden
Nach der Freigabe erscheint die Integration im Fortnox Marketplace, wo ein Kunde sie findet und aus dem Konto heraus verbindet, in dem er ohnehin arbeitet. Das ist ein Vertriebskanal und kein Abzeichen.
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 technische und die sicherheitsbezogene Seite der Prüfung mit Ihnen vor.
Sieben schwedische Scopes auf Ihrer eigenen Fortnox-App
Fortnox authentifiziert über OAuth 2.0 gegen Version 3 seiner API, und die Integration, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Es ist der einfache Redirect-Ablauf: Fortnox steht in der Authentifizierungsdokumentation weder auf der interaktiven noch auf der Headless-Liste. Der Zustimmungsdialog ist also eine Seite, die Ihr Kunde besucht, und der Account-Key kommt danach zu Ihnen zurück.
- OAuth 2.0
- Ihre eigene Integration im Entwicklerportal
Eine Integration, jeder Kunde. Maesn verwahrt die Zugangsdaten und führt Handshake und Refresh dahinter aus.
- Ihre Integrations-Zugangsdaten
- Client-ID und Secret werden einmal eingereicht und für jede Verbindung benutzt, die Sie danach herstellen. Der Handshake, der sie verbraucht, läuft also hier statt in Ihrem Backend. Was Ihr Code hält, ist ein Account-Key je Kunde.
- Die Scopes und der Token-Zyklus
- Die sieben Scopes, die Sie bei der Registrierung erteilt haben, bestimmen, was die Verbindung erreichen kann, und das Access-Token dahinter wird hier erneuert, je angebundenem Kunden. Von beidem erreicht nichts den Code, den Sie schreiben.
Bevor das alles gegen eine echte Firma läuft, läuft es gegen eine Sandbox. Fortnox lässt einen registrierten Entwickler bis zu 30 Testfirmen anlegen, jede eine vollständige Firmendatenbank, und wo diese Registrierung die Hürde ist, stellt Maesn die Sandbox stattdessen. So oder so ist die Verbindung ein eigener Account-Key und nicht derselbe mit einem Kennzeichen darauf.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von Fortnox. Er trägt den Namen Ihrer Integration, denn die Integration ist auf Ihr Unternehmen registriert. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
Fortnox kehrt zu Maesn zurück
Die Redirect-URL Ihrer Integration zeigt auf den Callback von Maesn. Der Code-Tausch und das erste Token passieren also hier statt in Ihrem Backend. Ihr Kunde landet in Ihrem Produkt, ohne etwas einfügen zu müssen.
- 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 Fortnox ist das Protokoll gewöhnlich und der Papierkram davor nicht. Unified Authentication macht daraus einen einmaligen Aufwand: Der Zustimmungsdialog, der Code-Austausch, das Refresh und der Account-Key verhalten sich hier genauso wie bei einem System mit API-Schlüssel oder Datenbank-Zugangsdaten, die zweite Integration erbt die Arbeit also, statt sie zu wiederholen.
Die Änderungserkennung läuft über einen Zeitstempel
Fortnox veröffentlicht durchaus Webhooks, für einige Objekte statt für alle, und keines davon ist hier eingeschaltet. Kein Objekt in der Abdeckungsmatrix trägt einen freigeschalteten Webhook: 28 sind als auf Anfrage markiert, die übrigen 9 bietet Fortnox gar nicht an. Was heute läuft, ohne jemanden zu fragen, ist ein geplanter Lesezugriff.
Native Events auf einem Teil seiner Objekte, darunter Kunden und Rechnungen, und auf dem Rest gar nichts. Freigeschaltet ist heute nichts davon in der Abdeckungsmatrix. Eine Änderung im Konto eines Kunden bleibt also unsichtbar, bis etwas sie liest.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code, der Änderungen auf Fortnox erkennt, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet. Braucht Ihr Anwendungsfall die Events eines bestimmten Objekts, ist dafür die Spalte auf Anfrage da.
Vor dem Dimensionieren wissenswert: Fortnox paginiert nativ bis zu 500 Datensätze, die vereinheitlichte Schnittstelle endet bei 100 je Seite. Ein Massenabzug gegen Fortnox macht über Maesn deshalb mehr Umläufe als ein handgeschriebener Client, im Tausch gegen ein Paging-Modell statt eines je System.
Ein System, das Sie abfragen müssen, ist die Stelle, an der die Kosten einer Integration je System am deutlichsten sichtbar werden: Sie schreiben eine Schleife zur Änderungserkennung für Fortnox und dann noch eine für das nächste System, mit eigener Filtersyntax und einer eigenen Vorstellung davon, was eine Seite ist. Ein Weg, zu filtern und zu paginieren nimmt diese Wiederholung weg, und derselbe Mechanismus macht aus der kleineren vereinheitlichten Seitengröße eine Frage der Dimensionierung statt einer Neuschrift. Was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei Wege, und bei Fortnox läuft heute alles über den zweiten.
Was Fortnox verlangt, vor dem ersten Aufruf
Die eigene Voraussetzungsliste von Fortnox ist eine Zeile lang: ein Konto mit Entwicklerrechten. Was daraus folgt, plant man besser vor dem Sprint als während ihm.
- Ein Fortnox-Konto mit Entwicklerrechten
- Das Entwicklerportal hängt an einer Berechtigung und nicht an einer eigenen Anmeldung, und es öffnet sich über das Menü oben links. Fehlt es dort, hat das Konto das Recht nicht, und das sollten Sie zuerst prüfen statt zuletzt.
- Ihre eigene Integration, mit dem Callback von Maesn darauf
- Sie legen die Integration im Portal an und setzen die Redirect-URL auf https://api.maesn.dev/auth/callback/fortnox. Der Code-Tausch passiert damit auf unserer Seite. Fortnox erzeugt in diesem Moment Client-ID und Secret, und beide gehen an Ihren Ansprechpartner bei Maesn statt in Ihr Backend.
- Sieben Scopes, und das Vokabular ist schwedisch
- Bokföring für die Buchhaltung, Faktura für Rechnungen, Leverantörsfaktura für Eingangsrechnungen, Kund und Leverantör für Kunden und Lieferanten, dazu Inbox und Koppla filer für Dateien. Übersehen Sie einen, fehlen die Objekte dahinter in der Verbindung schlicht.
- Ein Zeitplan, denn nichts ist zum Senden eingeschaltet
- Kein Objekt in der Abdeckungsmatrix trägt einen freigeschalteten Webhook. Die Änderungserkennung ist heute also ein Lesezugriff, den Sie in einem Intervall fahren. Das Intervall ist eine Produktentscheidung, und sie ist vor dem Bau billiger als nach der ersten Beschwerde über veraltete Daten.
Wir gehen die Entwicklerregistrierung und die Sandbox mit Ihnen durch.
Zwei Abrufe, und eine Form am Ende
Fortnox antwortet in zwei Schritten und grenzt in einer Dimension ein. Beides ist dokumentiert, keines davon verhandelbar, und zusammen entscheiden sie, was ein Abgleich kostet, bevor Sie einen einzigen Endpunkt wählen.
Journale lassen sich lesen, und nichts schreibt sie
Journale sind das eine Objekt, das Fortnox liest und nicht anlegt. Das ist keine Grenze von Fortnox: Kein System hier kann ein Journal anlegen, und nur fünf können überhaupt eines lesen. Fortnox ist eines der fünf, wenn Ihr Produkt also auf Journalebene lesen muss, ist das ein System, das es kann.
Ein Filter auf einmal, dazu ein Zeitstempel
Fortnox sagt es deutlich: Je Anfrage lässt sich nur ein ressourcenspezifischer Filter benutzen, kombinierbar mit einem globalen Parameter wie lastmodified. Sie bekommen also eine Dimension Ihrer Wahl plus ein Änderungsfenster, und jede weitere Einschränkung passiert in Ihrem eigenen Code, nachdem die Daten über die Leitung sind. Das ist die Randbedingung, um die herum Sie einen Abgleich entwerfen, nicht die Objektliste.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, eine Rechnung hat also dieselbe Form wie eine Rechnung aus einem zehnmal so großen System, und die Übersicht und die Einzelheiten, die Sie dazu holen, kommen in derselben Form an statt in zwei Fortnox-eigenen.
Was Fortnox trägt, fällt auf eine Seite und nicht zufällig. Kontakte sind nicht verfügbar, und Bestellungen, Aufträge, Wareneingänge oder deren Positionen ebenso wenig. Da ist stattdessen das Hauptbuch: Konten, Journale und Buchungssätze, alle lesbar. Das ist Fortnox als Buchhaltung und Rechnungsstellung statt als Auftragssystem, und es ist das Spiegelbild von sevdesk, das weder die Aufträge noch das Hauptbuch trägt. Wenn Ihr Anwendungsfall die Auftragsseite braucht, ist sie über dieselbe Schnittstelle bei einem System erreichbar, das sie hat, und genau das ist das Argument, gegen das Modell zu bauen statt gegen einen Hersteller.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
