Procountor-Schnittstelle und API-Integration
Procountor ist eine Plattform für das Finanzmanagement von Unternehmen in Finnland, Schweden, Norwegen und Dänemark und deckt Rechnungsstellung, Buchführung, Zahlungen und Lohn nach lokalen 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 Procountor-Anbindung in Tagen
Procountor ist eine gut dokumentierte API mit drei Eigenheiten, die bei Ihren Entwicklern landen, bevor etwas Nützliches passiert. Hier stehen sie, und hier steht, was Maesn davon abnimmt.
Eine Liste statt zwei
Procountor beantwortet eine Anfrage nach Steuersätzen mit zwei getrennten Listen, einer mit Prozentsätzen und einer mit Schlüsseln, und veröffentlicht nichts darüber, welcher Schlüssel zu welchem Satz gehört. Maesn gibt sie als eine Liste in der gemeinsamen Form zurück, und jeder Eintrag trägt den Satz oder den Schlüssel, mit dem er kam. Die Beziehung ist nicht veröffentlicht, und wir erfinden sie nicht.
Beide Endpunkte, eine Kontaktform
Unternehmen kommen aus business partners und Einzelpersonen aus persons, und business partners führt außerdem einen Personentyp, den Procountor nach eigener Aussage abschaffen wird. Maesn liest beide Endpunkte und gibt eine Kontaktform zurück. Die Aufteilung ist also erledigt, bevor Ihr Code sie sieht, und die Abschaffung erreicht Ihr Produkt nicht.
Für Sie verwahrt, auf einem Account-Key
Ein Access-Token lebt eine Stunde, und das Refresh-Token dahinter lebt sechs Monate, ohne zu rotieren. Maesn verwahrt und erneuert beide, von diesem Zyklus erreicht also nichts Ihren Code. Wo Procountor eine Verbindung früher beendet, verbindet sich Ihr Kunde einmal neu, und Ihr Account-Key bleibt derselbe.
Auf Ihrer Seite bleibt ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren. Teams gehen in Tagen live, und ein Kunde aus Nordeuropa ist kein Grund mehr, ein zweites Projekt zu eröffnen.
Der erste der drei ist der, der Leute überrascht, weil nichts daran nach einem Problem aussieht, bis Sie die Antwort benutzen wollen. Procountor gibt seine Steuersätze und seine Steuerschlüssel als zwei getrennte Listen zurück, und es gibt keinen veröffentlichten Schlüssel, der sie einander zuordnet. Über Maesn kommt das als eine Liste in der gemeinsamen Form an, und die Zuordnung bleibt offen, weil Procountor sie nicht veröffentlicht. Das zu wissen, bevor Sie Ihr Steuermodell entwerfen, macht den Unterschied. Wenn später doch etwas schiefgeht, bedeutet ein Fehlermodell über den ganzen Katalog einen Status und einen Body zum Auslesen, Procountor 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.
Drei Gründe, die Procountor-Schnittstelle über Maesn anzubinden
Procountor direkt anzubinden ist ein Projekt, das ein guter Entwickler abschließen kann. Seinen Token-Lebenszyklus ein Jahr lang zu besitzen, sein Steuermodell abzufangen und dann dasselbe für das nächste System noch einmal zu tun, entscheidet über Ihre Roadmap.
Die Procountor-Arbeit bleibt hier
Der Autorisierungsablauf, der Sechs-Monats-Zyklus der Erneuerung und die zwei Kontakt-Endpunkte sind das, was jede Procountor-Integration lösen muss. Gelöst wird es einmal, hier, für jeden Kunden, den Sie anbinden.
Heute live, Lesen und Schreiben
Konten, Kontakte und Steuersätze sind seit Juli lesbar, und das Buchen kam im August mit Buchungsvorschlägen und Ausgaben dazu. Zum Schreiben müssen zuerst die Konten und die Steuersätze stehen, und beide stehen bereits. Der Schreibweg steht also auf der Verbindung bereit, die Sie schon haben.
Das nächste System kostet nichts
Sobald Procountor 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 Ihre Entwickler verwenden wieder, was sie hier gelernt haben.
Ein Procountor-Login, und die Firma kommt mit
Procountor authentifiziert über einen OAuth-2.0-Authorization-Code-Ablauf und klärt von sich aus etwas, das die meisten Systeme Ihnen überlassen. Ihr Kunde wählt die Firma, während er sich verbindet, auf einer Seite, die Procountor selbst ausliefert. Jede Verbindung gehört damit zu genau einer Firma, und es gibt keine Firmenkennung, die Ihr Produkt verwalten müsste.
- OAuth 2.0 Authorization Code
- Eine Verbindung je Firma
Eine Implementierung, und die Firmenauswahl von Procountor gehört dazu.
- Die Firma
- Ein Procountor-Nutzer kann zu mehreren Firmen gehören, und Procountor klärt das bei der Anmeldung auf einer eigenen Auswahlseite. Die Verbindung, die zurückkommt, ist an die Firma gebunden, die Ihr Kunde gewählt hat. In Ihren Anfragen muss davon also nichts mitlaufen.
- Die Session
- Das Access-Token lebt eine Stunde, und das Refresh-Token dahinter bleibt sechs Monate gültig, ohne zu rotieren, und Maesn erneuert in diesem Takt. Vier Dinge beenden es früher: eine Passwortänderung, eine Abmeldung, der Austritt des Nutzers aus der Firma oder mehr als 100 Anmeldungen. Das verwahrte Token ist dann ungültig, und Ihr Kunde authentifiziert sich noch einmal, denn Procountor hält in diesem Schritt an einer Person fest.
Procountor hält für diesen Schritt einen Menschen im Ablauf. Eine Verbindung wird also von Ihrem Kunden im Browser angelegt und nicht aus einem Script. Sobald sie besteht, läuft sie unbeaufsichtigt, und alles nach dem Redirect wird hier erledigt.
- 1
Ihr Kunde wird zu Procountor geschickt
Maesn baut die Autorisierungsanfrage und leitet Ihren Kunden zu Procountor. Er sieht die Anmeldung von Procountor selbst, schließt sie mit seinem zweiten Faktor ab und wählt die Firma, für die diese Verbindung gilt.
- 2
Procountor leitet zu Maesn weiter, nicht zu Ihnen
Der Authorization Code kommt an die Redirect-URL zurück, die an der Anwendung registriert ist, und das ist der Callback von Maesn für Procountor. Maesn tauscht ihn mit Ihren Client-Zugangsdaten 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.
Bei den meisten Systemen im Katalog müssen Sie die Firmenfrage selbst lösen, über einen Discovery-Aufruf oder einen Bezeichner, der durch jede Anfrage mitläuft. Procountor klärt sie während der Anmeldung und gibt eine Verbindung zurück, die bereits weiß, zu welcher Firma sie gehört. Unified Authentication sorgt dafür, dass Ihnen dieser Vorteil erhalten bleibt: Der Redirect, der Token-Austausch, der Refresh-Zyklus über sechs Monate und der Account-Key verhalten sich hier genauso wie bei einem System mit API-Schlüssel oder einer Firmenauswahl von uns, Ihr Produkt sieht also über jedes System hinweg, das es erreicht, dieselbe Anbindung.
Was Procountor sendet, und was Sie selbst abrufen
Die eigene Event-Liste von Procountor deckt Zahlungen und Nutzer ab. Für die Konten, Kontakte und Steuersätze, die eine Buchhaltungsintegration liest, ist die Änderungserkennung ein geplanter Lesezugriff, und Maesn gibt Ihnen einen Weg, ihn zu fahren.
Drei Events, zwei davon zu einer Zahlung und eines zu einem Nutzer, zugestellt über HMAC mit einem einzigen Abonnement je Event-Typ. Nichts an den Objekten, die Sie hier lesen, meldet sich selbst. Eine Änderung im Konto eines Kunden wartet also, bis etwas nachsieht.
Ein geplanter Lesezugriff mit der Paginierung, die Sie überall sonst schon benutzen. Die Schleife, die auf Procountor zeigt, ist die Schleife, die auf jedes andere System zeigt. Der Zeitplan wird also einmal geschrieben, und Sie wechseln den Account-Key. Was sich zwischen den Systemen ändert, ist das Intervall.
Ein geplanter Lesezugriff holt außerdem nach einem Ausfall sauber nach, wo ein verpasster Push schlicht weg ist. Procountor erlaubt in der Produktion 60 Anfragen pro Sekunde je Client, und das ist eine großzügige Obergrenze für einen Lauf, der einen Kontenrahmen und eine Steuerliste in einem Intervall liest, das Sie wählen.
Praktisch heißt das, dass Procountor nicht einen Zeitplan für alles braucht. Ein Kontenrahmen und eine Steuersatzliste liegen monatelang still und lassen sich über Nacht vollständig neu lesen. Kontakte bewegen sich fortlaufend und verdienen ein kürzeres Intervall. Beide gleich zu dimensionieren heißt, einen vollen Durchlauf zu bezahlen, den Sie nicht gebraucht haben, oder einen Tag später von einem umbenannten Kunden zu hören, und keines von beidem ist eine Eigenschaft der Anbindung.
Günstig werden beide dadurch, dass keiner davon Procountor-eigener Code ist. Denn ein Weg, zu filtern und zu paginieren bedeutet, dass die Schleife auf Procountor dieselbe ist wie die auf alles andere. Und sie funktioniert weiter an dem Tag, an dem ein 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.
Was eine Procountor-Verbindung vorab verlangt
Procountor stellt drei Dinge vor eine Integration. Beim ersten gibt es eine Wartezeit, fangen Sie also damit an, bevor Sie Code schreiben.
- Eine Procountor-Testumgebung, früh beantragt
- Sie beantragen sie bei Procountor mit einem kurzen Formular, das Ihre Integration und die Daten beschreibt, die sie nutzen wird. Procountor antwortet innerhalb von drei bis vier Tagen und schickt die Client-Zugangsdaten per E-Mail und per SMS. Unser eigener Entwickler hat während des Wartens gegen die API gebaut und konnte erst testen, als die Antwort da war, mit diesem Schritt fängt man also an.
- Ein zweiter Antrag für die Produktion
- Produktive Zugangsdaten kommen aus einem eigenen Antrag mit denselben Angaben und einer eigenen Wartezeit von drei bis vier Tagen, und das Testkonto geht nicht über. Beide Anträge gleich zu Beginn einzuplanen hält die Wartezeit von Ihrem Liefertermin fern.
- Die Objekte, die Ihr Anwendungsfall braucht
- Konten und Steuersätze sind die Grundlage, auf der die Buchungs-Endpunkte aufbauen, und beide sind heute lesbar. Sagen Sie uns, welche Objekte Ihr Produkt braucht, und wir bestätigen, was verfügbar ist, bevor Sie sich auf einen Zeitplan festlegen.
Wir gehen den Antrag und die Objektliste mit Ihnen durch, bevor Sie mit dem Bauen anfangen.
Ein Procountor-Kontakt kommt in einer gemeinsamen Form
Procountor führt Unternehmen und Privatpersonen an zwei verschiedenen Stellen und beschreibt Steuer in zwei Teilen. Beide Entscheidungen reichen bis in Ihr Schema, es hilft also, sie zu kennen, bevor Sie etwas abbilden.
Ein Procountor-Steuersatz und sein Schlüssel kommen getrennt an
Die Steuerantwort trägt eine Liste mit Prozentsätzen und eine mit Schlüsseln, ohne eine veröffentlichte Verbindung dazwischen, ein Wert und der Schlüssel, zu dem er gehört, lassen sich aus der Antwort allein also nicht paaren. Maesn gibt eine Liste in der gemeinsamen Form zurück statt zweier, und jeder Eintrag bleibt, wie er ankam. Wo ein Anwendungsfall die Paarung braucht, ist es an Ihnen, sie herzustellen.
Procountor sortiert Kontakte nach Unternehmen und Person
business partners hält Unternehmen und trägt an ihnen einen Typ für Kunde oder Lieferant. persons hält Einzelpersonen und trägt keinen solchen Typ. Maesn ruft beide auf und gibt eine Kontaktliste zurück, bei den Unternehmen ist die Rolle durchgereicht und bei den Einzelpersonen offen gelassen, und das ist die ehrliche Form dessen, was Procountor veröffentlicht.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, ein Kontakt aus Procountor 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 Procountor leistet diese Abbildung mehr als sonst bei den Kontakten, die aus zwei Endpunkten kommen und als eine Form herausgehen.
Was bis in Ihr Schema reicht, ist der Ort der Rollen. Procountor führt seine Unternehmen in einem Endpunkt und seine Privatpersonen in einem anderen, und nur das Unternehmen trägt einen Kunden- oder Lieferantentyp. Maesn reicht diesen Typ durch und belässt die Privatpersonen als Kontaktpersonen ohne einen, was ankommt, ist also die Unterscheidung, die Procountor tatsächlich veröffentlicht. Welche Ihrer Kontakte mit einer Rolle zurückkommen und welche nicht, ist das, was vor dem Abbilden zu klären ist.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
