Holded-Schnittstelle und API-Integration
Holded ist ein Cloud-ERP für spanische kleine und mittlere Unternehmen, und Visma hat es 2021 übernommen. Rechnungsstellung, Buchhaltung, Lager, CRM, Projekte und Personal liegen in einem Produkt. Die Buchhaltungsdaten, die Sie brauchen, sind also ein Abschnitt von etwas deutlich Größerem. Binden Sie es über Maesn an, und Sie erreichen es mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Holded gibt Ihnen einen Schlüssel, keinen Redirect
Drei Dinge an Holded landen bei Ihren Entwicklern, bevor sich der erste Datensatz bewegt: Die Zugangsdaten sind ein statischer Schlüssel, den Ihr Kunde erzeugt, die Berechtigungen sitzen je Endpunkt an diesem Schlüssel, und die Buchhaltungsdaten, die Sie wollen, sind ein Teil eines Produkts, das auch Lager, CRM und Personal betreibt. Hier steht, was jedes davon ist, und was Maesn davon abnimmt.
Die Übergabe läuft über unsere Seite oder über gar keine
Holded authentifiziert mit einem festen API-Schlüssel, den Ihr Kunde in seinem eigenen Konto erzeugt, und Holded zeigt ihn genau einmal an. Maesn nimmt diesen Schlüssel auf einer Seite entgegen, die Sie als Ihre gestalten können, oder Sie sammeln ihn selbst ein und senden ihn an einen Endpunkt, der den Account-Key direkt zurückgibt. Einen OAuth-Redirect gibt es auf beiden Wegen nicht zu bauen.
Eine Ablehnung, die je Aufruf ankommt
Jeder Holded-Schlüssel trägt Berechtigungen mit Scopes, und ein Endpunkt, der einen Scope verlangt, den der Schlüssel nicht hat, antwortet mit 403, statt beim Verbinden zu scheitern. Eine Verbindung kann also gesund aussehen, während ein Aufruf abgelehnt wird. Maesn gibt diese Ablehnung in derselben Fehlerform zurück wie jedes andere System, statt eine Verzweigung in Holded-Form in Ihren Code zu bringen.
Der Buchhaltungsteil, bereits abgebildet
Holded veröffentlicht 338 Endpunkte über elf Bereiche, vom Verkauf und der Lagerhaltung über CRM und Projekte bis zum Personalwesen. Was Maesn bereitstellt, ist der Teil davon, der die Form der Buchhaltung hat, abgebildet auf dieselben Objekte, die Sie aus jedem anderen System schon lesen. Ihr Code erfährt also nie, wo Holded die Dinge ablegt.
Was Ihr Code hält, ist ein API-Schlüssel von uns und ein Account-Key je Kunde. Der Holded-Schlüssel, die Scope-Fehler und die Abbildung aus einem Produkt mit elf Domänen bleiben auf dieser Seite, und das nächste System antwortet auf derselben Schnittstelle.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
HubSpot bringt Stammdaten in das Hauptbuch, das ein Kunde führt
HubSpot gleicht Kundendaten aus dem CRM in das Buchhaltungssystem ab, das jeder ihrer Kunden einsetzt, und das ist genau der Objektsatz, den Holded freigeschaltet hat: Kontakte, Kunden und Lieferanten. Heute erreichen sie auf diesem Weg DATEV und sevdesk.
“Wir binden deutsche Buchhaltungssysteme an und verlassen uns dabei auf Maesn als verlässlichen Partner, der für reibungslosen Datenfluss, vollständige Compliance, stärkere Partnerschaften und effiziente, verlässliche Finanzprozesse sorgt, die unser Wachstum tragen.”
Drei Gründe, die Holded-Schnittstelle über Maesn anzubinden
Holded direkt anzubinden ist günstig im Start und teuer im Unterhalt. Die Übergabe des Schlüssels ist einfach. Alles danach ist Holded-eigen: das Scope-Modell, ein Aufrufbudget, das zum Tarif Ihres Kunden gehört und nicht zu Ihnen, und ein Objektaufbau, der mit dem nächsten System, das Sie hinzunehmen, nichts gemein hat.
Die Holded-eigene Arbeit bleibt hier
Den Schlüssel einsammeln und je Mandant verwahren, die Scope-Ablehnung in einen einheitlichen Fehlervertrag übersetzen und die Buchhaltungsobjekte aus einem Produkt herausbilden, das auch Lager und Personal führt. Keines der drei erreicht den Code, den Sie schreiben.
Was eingeschaltet ist, schriftlich
Lesen und Schreiben sind hier dieselbe Liste. Ein Objekt, das aus Holded kommt, lässt sich also ohne zweite Zuordnung in Holded korrigieren. Alles jenseits dieser Liste ist auf Anfrage verfügbar statt abwesend, die Frage lautet also, welche Objekte Ihr Ablauf braucht, und nicht, ob die Verbindung sie erreichen kann.
Das nächste System kostet nichts
Sobald Holded läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle mit demselben Datenmodell. Ihre zweite Integration ist ein Konfigurationsschritt und kein zweites Schlüsselmodell.
Der Objektumfang macht daraus eine schmale Integration und keine kleine. Kontakte, Kunden und Lieferanten sind die Datensätze, über die zwei Systeme am häufigsten streiten, weil beide Seiten meinen, das Unternehmen zu besitzen, das sie beschreiben, und Kunden- und Lieferantenstammdaten im Gleichstand halten ist ein eigenes Problem, bevor es ein Holded-Problem ist. Was Holded hinzufügt, ist eine Obergrenze dafür, wie oft Sie fragen dürfen.
Ein Holded-API-Key, bei uns verwahrt
Holded ist eines der Systeme ganz ohne OAuth-Redirect. Es authentifiziert mit einem Schlüssel. Die einzige Frage ist also, wie dieses Geheimnis von Ihrem Kunden zu uns kommt, ohne durch Ihr Backend zu laufen. Es gibt zwei Antworten, und beide enden mit einem Account-Key.
- API-Schlüssel
- Ein Schlüssel je Kunde, erzeugt im eigenen Holded-Konto
Eine Integration, jeder Kunde. Maesn verwahrt den Schlüssel je Mandant, und was Ihr Code trägt, ist ein Account-Key.
- Der Schlüssel, je Mandant gespeichert
- Ihr Kunde reicht ihn einmal ein, und Maesn verwahrt ihn an seiner Verbindung. Jeder spätere Aufruf trägt Ihren API-Schlüssel und seinen Account-Key, dieselben zwei Header, die Sie für jedes andere System ohnehin senden, und das Zugangsmerkmal von Holded liegt nie in Ihrer Datenbank.
- Die Seite, oder gar keine Seite
- Maesn stellt die Seite für die Eingabe des Schlüssels bereit, und sie nimmt Ihr Erscheinungsbild an, vom Logo bis zu den Farben für Knöpfe und Fehler. Wenn Sie lieber einen eigenen Bildschirm betreiben, gibt ein POST auf den Accounts-Endpunkt den Account-Key in der Antwort zurück, und die Seite entfällt ganz.
Was einen Entwurf verlangt, ist das Scope-Modell und nicht der Schlüssel selbst. Holded stellt jeden Schlüssel mit begrenzten Berechtigungen aus und dokumentiert die Berechtigung, die jeder Endpunkt verlangt. Ein Schlüssel kann sich also einwandfrei authentifizieren und auf einem einzelnen Aufruf trotzdem mit 403 abgewiesen werden. Dieser Fehlschlag kommt in der Produktion an, auf dem einen Endpunkt, dessen Scope übersehen wurde, und nicht beim Verbinden, wenn jemand zusieht. Maesn vereinheitlicht ihn in denselben Fehlerkontrakt wie bei jedem anderen System, und das ist der Unterschied zwischen einer Verzweigung in Ihrer Fehlerbehandlung und einer je System.
- 1
Er erzeugt den Schlüssel in Holded
Ein Administrator öffnet die Entwicklereinstellungen in seinem Holded-Konto, erzeugt einen Schlüssel mit einer Beschreibung und kopiert ihn. Holded zeigt den Wert einmal und danach nie wieder. Ihr Onboarding-Text muss das also sagen, bevor er den Dialog schließt.
- 2
Er übergibt ihn, oder Sie tun es
Er fügt ihn auf der Maesn-Seite ein, die Ihr Erscheinungsbild trägt, und es gibt einen Abbruchweg für den Fall, dass er sie auf halbem Weg schließt. Haben Sie den Schlüssel schon vorher in Ihrem eigenen Ablauf eingesammelt, senden Sie ihn stattdessen und überspringen die Seite.
- 3
Sie arbeiten mit einem Account-Key
Maesn speichert die Verbindung und gibt einen Account-Key zurück. Ab da sehen die Anfragen aus wie bei jedem anderen System im Katalog, und nichts in Ihrem Code hat die Form von Holded.
Jedes System im Katalog authentifiziert anders, und bei Holded ist der Handshake trivial und die Berechtigung daran nicht. Es gibt kein Token zu erneuern und keine Umgebung zu wählen, die Arbeit verlagert sich also auf eine einzige Frage, die Ihr Onboarding-Text beantworten muss: Welche Scopes braucht dieser Schlüssel vor dem ersten Aufruf. Unified Authentication trägt die Speicherung je Mandant und die Einstiegsseite in Ihrer Marke, einmal für alle Systeme und nicht einmal je System. Fehlt doch ein Scope, kommt der 403 in der Form zurück, die Sie bereits verarbeiten, denn ein Fehlerkontrakt deckt jedes System ab, statt dass jedes seinen eigenen hat.
Holded sendet Events, und Sie fragen trotzdem ab
Holded dokumentiert ein vollständiges eigenes Webhook-System, und nichts davon ist heute über Maesn eingeschaltet. Beide Hälften stimmen gleichzeitig, und die zweite entscheidet, wie Sie bauen: Die Änderungserkennung ist hier etwas, das Sie fahren, und nicht etwas, das ankommt.
Achtzehn Event-Gruppen und 58 Events, von invoice.create bis stock.update, mit HMAC-SHA256 signiert und mit Backoff wiederholt. Abonnements werden in einem Holded-Konto eingerichtet, und über Maesn erreicht Sie heute keines davon.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code, der Änderungen auf Holded erkennt, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet. Nichts an der Schleife hat also die Form von Holded.
Das Intervall ist hier so sehr eine kommerzielle wie eine technische Entscheidung, und das Budget, das es verbraucht, ist nicht Ihres. Holded rechnet API-Aufrufe gegen ein monatliches Kontingent ab, das zum Tarif Ihres Kunden gehört. Es zählt je Account statt je Schlüssel. Einen zweiten Schlüssel auszustellen kauft also keinen zusätzlichen Raum, und der niedrigste Tarif in der veröffentlichten Tabelle erlaubt 500 Aufrufe im Monat. Eine Abfrageschleife verbraucht damit aus einem Budget, das Ihrem Kunden gehört und das er aufbrauchen kann, und darüber spricht man besser beim Dimensionieren des Intervalls als nach dem ersten 429.
In der Unified API gibt es zwei Wege, und bei Holded ist heute nur einer davon verfügbar. Was über das Event-Modell ankommt und was Sie nach Zeitplan holen, bleiben getrennte Belange, und ein System, bei dem nichts eingeschaltet ist, legt das ganze Gewicht auf den zweiten. Genau dort ist eine Integration je System am teuersten: Sie schreiben eine Schleife zur Änderungserkennung für Holded, dann noch eine für das nächste System mit einer eigenen Vorstellung davon, was eine Seite ist, und ein Weg, zu filtern und zu paginieren nimmt den Teil der Arbeit weg, der gar nichts mit Holded zu tun hat.
Was bleibt, ist eine Schleife, deren Frequenz eine betriebliche Vorgabe ist und keine technische, und eine Eigenschaft spricht für sie. Ein Lesezugriff nach Zeitplan holt nach, was er während eines Ausfalls verpasst hat, während ein Event, das nie zugestellt wurde, schlicht weg ist. Sie zu dimensionieren ist also die Frage, wie oft ein Aufruf es wert ist, und die Antwort steht im Tarif Ihrer Kunden und nicht in Ihrem eigenen Code.
Was eine Holded-Anbindung zuerst braucht
Das meiste davon ist geklärt, bevor Code läuft, und zwei der vier sind von der Sorte, die nach dem Livegang auftaucht statt während des Baus. Vier Dinge sollten zuerst entschieden sein.
- API-Zugang auf dem Konto, dazu ein Administrator
- Der Schlüssel wird im Konto Ihres Kunden erzeugt, und ihn anzulegen verlangt Administratorrechte. Holded zeigt ihn einmal an und danach nie wieder, wer ihn erzeugt, muss ihn also auch übergeben. Das ist ein Gespräch beim Onboarding statt eines Support-Tickets eine Woche später.
- Welche Objekte Ihr Anwendungsfall tatsächlich braucht
- Kontakte, Kunden und Lieferanten sind freigeschaltet und gehen in beide Richtungen. Rechnungen, Eingangsrechnungen, Gutschriften, Zahlungen und Ausgaben sind mit auf Anfrage gekennzeichnet, und das heißt eine Anfrage und keinen Schalter, den Sie selbst umlegen. Wenn Ihr Ablauf mit einem Beleg anfängt, sprechen Sie das an, bevor Sie den Aufwand zuschneiden, und nicht danach.
- Die Scopes, die der Schlüssel tragen muss
- Holded dokumentiert, welche Berechtigung jeder Endpunkt braucht, und ein Schlüssel, der ohne sie ausgestellt wurde, wird allein an diesem Endpunkt abgelehnt. Zu entscheiden, welche Scopes die Verbindung anfordert, gehört in den Onboarding-Text, den Ihr Kunde liest, und ist kein Detail der Umsetzung.
- Eine Umgebung, gegen die Sie bauen
- Holded bietet einen kostenlosen Test an, für den Sie sich heute anmelden können, und Maesn stellt auf Anfrage eine Sandbox mit Testdaten bereit. Beides bringt Sie zum Bauen, bevor das Kundengespräch abgeschlossen ist, und der Test ist von beiden der schnellere Start.
Wir gehen den Schlüssel, die Scopes und den Testaccount mit Ihnen durch.
Eine Liste für Lesen und Schreiben, eine Form am Ende
Was Holded zurückgibt und was es entgegennimmt, ist dieselbe Liste. Das ist seltener, als es klingt, und entscheidet darüber, wie ein Abgleich in beide Richtungen arbeitet.
Alles Eingeschaltete geht in beide Richtungen
Kontakte, Kunden und Lieferanten lassen sich lesen, anlegen und aktualisieren, jedes Mal dieselben drei Objekte. Zwei Systeme hier haben diese Form, und ein Belegobjekt ist noch nicht freigeschaltet.
Hier läuft kein Buchungsweg durch
Buchungssätze liegen außerhalb dessen, was Maesn für Holded bereitstellt, in jeder Operation, und sie sind kein Objekt, dessen Freischaltung sich anfragen lässt. Planen Sie das ein, wenn Ihr Produkt Buchungen schreibt.
Standardmäßig löscht kein Objekt
Für kein Objekt ist Löschen freigeschaltet. Die Buchhaltungspraxis erwartet Korrekturen und Stornos ohnehin als neue Belege, planen Sie sie also so und nicht um ein Löschen herum, das Sie erst anfragen müssten.
Was Holded herausgibt, nimmt es auch entgegen: Die Objekte, die Sie lesen können, sind die Objekte, die Sie anlegen und aktualisieren können, eine Firma, die aus Holded kommt, lässt sich also in Holded korrigieren. Das ist der Teil, der gewöhnlich bricht, wenn zwei Systeme beide meinen, ihnen gehöre der Kundendatensatz. Was es nicht gibt, ist irgendein Beleg. Keine Rechnung, Eingangsrechnung oder Gutschrift ist heute freigeschaltet, ein Produkt, das Firmen abgleicht, findet hier also einen vollständigen Rundlauf, und ein Produkt, das Rechnungen bucht, findet ein Gespräch.
Die Partnerobjekte kommen im gemeinsamen Common Data Model zurück, ein Lieferant aus Holded hat also dieselbe Form wie ein Lieferant aus jedem anderen unterstützten System, und der Abbildungscode, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden. Das zählt mehr als sonst bei einem Produkt dieser Breite: Holded betreibt Vertrieb, Lager, CRM, Projekte und Personal neben dem Hauptbuch, und nichts von diesem Aufbau erreicht Sie.
Alles jenseits dieser Liste ist auf Anfrage verfügbar statt nicht verfügbar, es ist also nicht standardmäßig eingeschaltet. Holded gehört seit 2021 zu Visma und behält seine eigene API, sein eigenes Schlüsselmodell und sein eigenes Kontingent, und deshalb hat es hier eine eigene Seite. Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, oder sehen Sie sich jedes System im Katalog an, um zu sehen, wie dieselbe Frage anderswo beantwortet wird.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
