SnelStart-Schnittstelle und API-Integration
SnelStart ist eine niederländische Buchhaltungsplattform für Freiberufler, kleine Unternehmen und die Buchhaltungsbüros, die mit ihnen arbeiten, und deckt Rechnungsstellung, Umsatzsteuer und Bankabstimmung ab. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System, dokumentiert auf Englisch.
Zwei SnelStart-Schlüssel und ein stündliches Token, alles hier erledigt
Drei Eigenheiten der SnelStart-API entscheiden, wie lange eine erste Integration dauert: woher die Schlüssel kommen, wie lange ein Token lebt, und wie viel von einem Objekt eine Antwort tatsächlich enthält.
Beide enden hier
Während der Entwicklung kopiert Ihr Kunde einen Verbindungsschlüssel aus seinem eigenen SnelStart-Konto, und Sie halten einen Abonnementschlüssel aus dem Entwicklerportal. In der Produktion kommt derselbe Verbindungsschlüssel auf einem anderen Weg an: SnelStart schickt Ihren Kunden durch eine Anmeldung und sendet den Schlüssel dann an Maesn. Beide Wege enden beim selben Account-Key. Der Wechsel des Ablaufs zum Start ist also keine Änderung in Ihrem Code.
Je Kunde getauscht und erneuert
Jeder Aufruf braucht den Abonnementschlüssel plus ein Access-Token, das aus dem Verbindungsschlüssel getauscht wird, und dieses Token verfällt nach einer Stunde, ohne dass etwas es von selbst erneuert. In einem mandantenfähigen Produkt ist das eine Rotationsschleife je angebundener Firma, dazu die Ablauffehler, die sie im falschen Moment erzeugt. Maesn führt den Tausch und die Erneuerung, und was Ihr Code hält, ist ein Account-Key, der nicht nach der Uhr abläuft.
Referenzen aufgelöst, bevor Sie sie sehen
Eine Antwort von SnelStart trägt oft eine Kennung, wo Sie einen Wert wollten: Ein Kontakt verweist auf ein Land über eine ID statt über den ISO-Code, und der Code liegt hinter einem zweiten Aufruf. Länder lassen sich in SnelStart außerdem anlegen, ändern und löschen. Es ist also keine Tabelle, die Sie einmal zwischenspeichern und vergessen. Maesn löst die Referenz auf und gibt den Kontakt im gemeinsamen Datenmodell zurück, mit dem Code bereits darin.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Die niederländischen Eigenheiten bleiben auf dieser Seite, und das System nach SnelStart ist ein Konfigurationsschritt und kein zweites Projekt.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Clockin hat aus Partnerschaften einen Wachstumskanal gemacht
Clockin digitalisiert die Zeiterfassung für kleine und mittlere Unternehmen. Die Integrationen, die sie gebaut haben, sind kein Supportkosten-Posten mehr, sondern bringen Kunden, und genau diesen Tausch bietet ein SnelStart-Partnereintrag.
“Wir nutzen Maesn, um Integrationen und Partnerschaften erfolgreich als wichtigen Treiber für Leadgenerierung und für den Schritt in neue Märkte und Kundensegmente einzusetzen. Weil Clockin an die Buchhaltungssysteme unserer Kunden angebunden ist, fließen Projektdaten direkt in deren vorhandene Werkzeuge, und der Datenaustausch mit den Systemen, die sie ohnehin nutzen, läuft reibungslos und verlässlich.”
Drei Gründe, die SnelStart-Schnittstelle über Maesn anzubinden
Eine SnelStart-Integration ist ein kurzer Bau mit einem langen Anlauf: ein Abonnement zu kaufen, eine Partnerfreigabe abzuwarten und eine Spezifikation auf Niederländisch zu lesen. Diese Kosten fallen hier einmal an, für jeden Kunden, den Sie danach anbinden.
Die nur niederländische Spezifikation endet hier
SnelStart veröffentlicht seine API-Dokumentation auf Niederländisch und hinter einer Registrierung. Ein Team außerhalb der Niederlande hat also einen Übersetzungs- und Zugangsschritt vor sich, bevor es den Aufwand überhaupt abschätzen kann. Die Referenz von Maesn zu demselben System ist englisch, offen und genauso aufgebaut wie die zu jedem anderen System.
Die Abdeckung bewegt sich, wenn die Dokumentation sich bewegt
Was Maesn für SnelStart bereitstellt, ist aus der Dokumentation erzeugt und nicht von Hand geschrieben. Es kann sich also nicht still von dem entfernen, was das System tatsächlich anbietet. Kontakte machen heute den vollen Rundlauf, und was Ihr Anwendungsfall darüber hinaus braucht, ist eine Anfrage und kein Umbau.
Das nächste System kostet nichts
Sobald SnelStart läuft, antwortet jedes andere unterstützte System auf derselben Schnittstelle, mit demselben Datenmodell dahinter. Ihre zweite Integration ist ein Konfigurationsschritt, und der nächste Markt eine kaufmännische Entscheidung statt einer technischen.
Echte SnelStart-Administrationen öffnen sich mit Partnerstatus
Bei den meisten Systemen in diesem Katalog ist ein Marketplace-Eintrag eine Vertriebsmöglichkeit, die Sie später hinzunehmen können. Hier kommt er zuerst: Die Dokumentation sagt, dass die Nutzung der API in der Produktion voraussetzt, offizieller SnelStart-Partner zu werden, und bis das freigegeben ist, erreicht eine Anwendung die vorgegebene Testfirma und sonst nichts. Der Eintrag danach ist der Gewinn, und die Freigabe davor ist der Grund, früh anzufangen.
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 führt Sie durch die Bewerbung und die Qualifizierung, die das Entwicklerportal fährt, und steht danach weiter hinter der Integration. Der Eintrag trägt den Namen Ihres Produkts, nicht unseren.
Abonnieren und gegen die Testfirma bauen
Ein Entwicklungsabonnement im Entwicklerportal von SnelStart gibt Ihnen 90 Tage und ein begrenztes Aufrufvolumen gegen die voreingestellte Testfirma. Das reicht, um die ganze Integration zu bauen, und nichts davon wartet auf eine Freigabe.
Die Aufnahme als offizieller Partner beantragen
Die Bewerbung verlangt zwei konkrete Dinge: die Liste der Scopes, die Ihr Anwendungsfall wirklich braucht, und eine Callback-Adresse für den Produktionsablauf. Maesn liefert den Callback und hilft Ihnen, die Scope-Liste auf das zu kürzen, was Ihre Endpunkte verlangen. Zurück kommt die Anwendungskennung, aus der der Produktions-Redirect gebaut wird.
Die siebentägige Beobachtungsphase durchlaufen
Wenn die Integration fertig ist, sagen Sie dem Partnermanager von SnelStart Bescheid, und er sieht ihr eine Woche lang zu. In diesem Fenster brauchen Sie mindestens 150 Aufrufe und nicht zu viele Fehler. Es ist also eine geplante Übung und nichts, was von selbst passiert. An dieser Stelle steigt Maesn mit Ihnen ein.
Produktive Administrationen erreichen und darin gefunden werden
Die Freigabe öffnet echte Kundenumgebungen über die Testfirma hinaus, und der Eintrag stellt Ihr Produkt niederländischen Unternehmen und Buchhaltungsbüros vor, und zwar in der Software, die sie ohnehin benutzen.
Die Integration läuft unter dem Namen Ihres Produkts, und der Eintrag gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
SnelStart steht damit nicht allein. QuickBooks sperrt die Produktion über das Intuit App Partner Program auf dieselbe Weise, und beide zusammen sind der Grund, warum die Freigabe am ersten Tag in den Plan gehört und nicht in die Startwoche. Verschieden ist die Grenze darunter: SnelStart lässt Ihnen bis zur Freigabe eine einzige vorgegebene Testfirma, der Pilot lässt sich also nicht verbreitern, während Sie warten.
Wir bringen Antrag und Qualifizierung gemeinsam mit Ihnen durch das Entwicklerportal.
SnelStart braucht zwei Schlüssel und ein stündliches Token
SnelStart authentifiziert auf zwei verschiedene Weisen, und welche Ihnen begegnet, hängt davon ab, wie weit Sie sind. Während der Entwicklung sind es zwei Schlüssel: ein Abonnementschlüssel, der Sie als Integrator ausweist und als Header bei jedem Aufruf mitreist, und ein Verbindungsschlüssel, den Ihr Kunde aus seiner eigenen Administration kopiert. Sobald Sie freigegebener Partner sind, ersetzt die Produktion die zweite Hälfte durch einen Redirect, den SnelStart OAuth nennt und bei dem Ihr Kunde sich anmeldet und die Scopes akzeptiert, und der Schlüssel wird an einen Callback zugestellt, statt von Hand kopiert zu werden. Beide Wege enden in demselben stündlichen Zugriffstoken, und beide enden hier.
- Zwei Schlüssel während der Entwicklung
- Verbindungsschlüssel von Ihrem Kunden, Abonnementschlüssel aus dem Entwicklerportal
- Redirect, sobald Sie Partner sind
- SnelStart nennt seinen Produktionsablauf OAuth, und Maesn betreibt beide Enden davon
Eine Implementierung für beide Abläufe. Maesn verwahrt die Schlüssel, führt den Produktions-Redirect aus und erzeugt das stündliche Token hinter beiden Wegen.
- Ihr Abonnementschlüssel, einmal
- Er wird bei der Einrichtung übergeben und danach bei jedem Aufruf als Header gesendet, für jeden Kunden, den Sie anbinden, und in beiden Abläufen. Ihr Code trägt ihn nie, und ihn zu rotieren ist eine Nachricht an Ihren Ansprechpartner bei Maesn und kein Deploy.
- Der Produktions-Redirect, beide Enden davon
- Maesn erzeugt den Aktivierungslink aus Ihrer Anwendungskennung, nimmt den Verbindungsschlüssel entgegen, den SnelStart zurücksendet, bestätigt ihn und schickt Ihren Kunden mit einem Account-Key zurück in Ihr Produkt. Der State-Parameter, der Callback und die Verwahrung gehören uns.
- Der stündliche Token-Zyklus
- Das Access-Token wird aus dem Verbindungsschlüssel getauscht und hier erneuert, je angebundener Administration. Weil der Verbindungsschlüssel verwahrt wird, ist eine Erneuerung ein Aufruf und nicht noch einmal der ganze Ablauf.
Bevor das alles gegen eine echte Administration läuft, läuft es gegen eine Test-Administration, und es gibt zwei Wege hinein: SnelStart bietet eine kostenlose Testphase, und die Sandbox-Dokumentation von Maesn führt auch für dieses System eine von Maesn bereitgestellte Sandbox. Behalten Sie die 90 Tage Laufzeit eines Entwicklungsabonnements im Blick, denn das ist der Teil, der abläuft, während die Partnerfreigabe noch läuft.
- 1
Während der Entwicklung: Ihr Kunde kopiert den Schlüssel
In seinem eigenen SnelStart-Konto wählt er unter Koppelingen und dann Maatwerk den Punkt Koppeling instellen und stimmt den Scopes zu. Das ist der Entwicklungsablauf, und er erreicht die voreingestellte Testfirma und keine echten Daten.
- 2
In der Produktion: Ihr Kunde meldet sich stattdessen an
SnelStart schickt ihn auf eine Aktivierungsseite, die aus der Anwendungskennung gebaut ist, die Sie bekommen, wenn Ihre Partnerbewerbung angenommen wird. Er meldet sich an, akzeptiert die Scopes, und SnelStart sendet den Verbindungsschlüssel an Maesn, statt ihn jemandem zu zeigen.
- 3
Sie arbeiten mit einem Account-Key
So oder so speichert Maesn die Verbindung und gibt einen Account-Key zurück. Ab da trägt jede Anfrage Ihren Maesn-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 SnelStart teilt die Zugangsdaten auf zwei Parteien auf, ohne irgendeinen Redirect dazwischen. Unified Authentication macht daraus einen einmaligen Aufwand: Die Schlüsselerfassung, der Token-Austausch, das Refresh und der Account-Key verhalten sich hier genauso wie bei einem System mit OAuth-Redirect, die zweite Integration erbt die Arbeit also, statt sie zu wiederholen.
SnelStart-Daten bleiben frisch mit einem geplanten Abruf
Er läuft, ohne jemanden zu fragen, auf demselben Filter und derselben Paginierung wie bei jedem anderen System, das Sie anbinden. Wo Ihr Produkt auf ein Event statt auf einen Zeitplan angewiesen ist, ist das eine Frage der Freischaltung, sagen Sie uns also, um welches Objekt es geht, und wir bestätigen, was möglich ist.
Nichts. Jede Event-Spalte in der Matrix ist entweder eine Anfrage oder leer. Eine Änderung in der Administration eines Kunden bleibt also unsichtbar, bis etwas sie liest. Würden die Events eines bestimmten Objekts Ihr Produkt verändern, ist dafür die Spalte auf Anfrage da.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code zur Änderungserkennung, den Sie auf SnelStart richten, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet, und das Intervall ist eine Produktentscheidung und keine Grenze des Systems.
Es gibt hier einen zweiten Grund, geplant statt hart abzufragen. Jeder Lesezugriff trägt ein Zugriffstoken, das eine Stunde lebt. Eine enge Schleife verbringt also einen Teil ihres Budgets damit, sich neu zu authentifizieren. Maesn fängt den erneuten Austausch ab, und ein sinnvolles Intervall verhindert, dass er häufiger passiert, als sich die Daten ändern.
Ein System, das Sie nach Zeitplan lesen 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 SnelStart 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. Was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei Wege, und bei SnelStart läuft heute alles über den zweiten.
Was zutreffen muss, bevor eine SnelStart-Anbindung live geht
Die Voraussetzungen von SnelStart liegen außerhalb des Codes: ein Paket, auf dem Ihr Kunde sein muss, ein Abonnement, das Sie kaufen müssen, und eine Freigabe, die entscheidet, ob Sie echte Firmen überhaupt erreichen.
- Ein Kunde auf inZicht oder inControle
- Der API-Zugang hängt an dem Paket, das Ihr Kunde bezahlt. In den kleineren Tarifen gibt es nichts zu verbinden. Das gehört also in das Qualifizierungsgespräch und nicht in den Sprint, und man sollte es wissen, bevor ein Abschluss auf der Annahme unterschrieben wird, dass die Verbindung existiert.
- Ihr eigenes Entwicklerabonnement, und es ist nicht kostenlos
- Sie registrieren sich im Entwicklerportal von SnelStart und abonnieren ein Produkt. Ein Entwicklungsabonnement ist 90 Tage gültig und im Aufrufvolumen begrenzt. Ein Produktions-Abonnementschlüssel kostet einmalig 250 €. Das ist die Gebühr von SnelStart und nicht unsere, und sie ist dieselbe, ob Sie einen Kunden anbinden oder tausend.
- Die zwei Schlüssel, aus zwei Quellen
- Ihr Kunde erzeugt den Verbindungsschlüssel unter Koppelingen und Maatwerk und akzeptiert dort die Scopes. Den Abonnementschlüssel nehmen Sie aus Ihrem Entwicklerprofil. Der Verbindungsschlüssel kommt in Maesn Connect, in das Feld API Key, und der Abonnementschlüssel geht einmal an Ihren Ansprechpartner bei Maesn und nicht je Kunde.
- Partnerfreigabe vor der Produktion
- Die Dokumentation von SnelStart sagt ausdrücklich, dass die Nutzung der API in der Produktion den Status als offizieller SnelStart-Partner verlangt, und diese Freigabe ist es, die echte Kundenumgebungen über die voreingestellte Testfirma hinaus öffnet. Alles andere auf dieser Liste ist eine Aufgabe. Dies hier ist eine Vorlaufzeit. Es gehört also an dem Tag in den Plan, an dem der Bau beginnt, und nicht in die Woche, in der Sie starten wollen.
Wir gehen die Paketvoraussetzung, das Abonnement und den Partnerantrag mit Ihnen durch.
Eine Form für SnelStart, und für das nächste System
SnelStart gibt die Steuer zweimal je Buchung an, liefert Bezeichner zurück, wo Sie Werte wollten, und spricht über all das Niederländisch. Eine gemeinsame Form hält alle drei aus Ihrem Code heraus.
Heute geht mehr hinein als heraus
Unter den 30 Systemen in diesem Katalog ist SnelStart das einzige, bei dem Maesn mehr Objekttypen zum Schreiben freigeschaltet hat als zum Lesen: vier, die Sie anlegen können, gegen drei, die Sie lesen können. Buchungsvorschläge, Gutschriften und Dateien gehen hinein, Konten, Kontakte und Steuersätze kommen zurück. Das ist der Stand unserer eigenen Freischaltung und keine Form, die SnelStart vorgibt, und genau deshalb sind die Lesezugriffe als auf Anfrage verfügbar gekennzeichnet.
Nur Kontakte machen den Rundlauf
Kontakte sind das einzige Objekt auf beiden Listen und das einzige, das sich auch an Ort und Stelle aktualisieren lässt. Was Sie als Buchungsvorschlag, Gutschrift oder Datei senden, ist auf Anfrage lesbar und nicht schon heute. Ein Produkt, das dem Nutzer seine eigenen Belege zurückzeigen muss, sollte diese Lesezugriffe also anfragen, bevor es den Bildschirm entwirft.
Die Steuer wird je Vorschlag zweimal angegeben
Ein Buchungsvorschlag trägt die Steuer auf Buchungsebene und noch einmal auf jeder Position, und beide müssen übereinstimmen, sonst scheitert die Anfrage an der Prüfung. Das macht die lesbare Seite nützlich: Konten und Steuersätze sind das, was Sie brauchen, um es gleich beim ersten Mal richtig anzugeben. Maesn bildet beides aus einer einheitlichen Buchungsstruktur ab.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, und bei SnelStart macht sich dieses Modell eher auf dem Hinweg bezahlt als auf dem Rückweg: Aus einer Buchungsstruktur wird Steuer auf Kopfebene und Steuer auf jeder Zeile, und aus einem Kontakt wird ein Datensatz, dessen Länderverweis bereits aufgelöst ist.
Die Schreibseite ist das, was diese Anbindung ungewöhnlich macht. Gutschriften lassen sich auf zwei der 30 Systeme hier anlegen, auf diesem und auf Lexware Office, ein Produkt, das sie ausstellt, hat also weniger Orte dafür als es vielleicht annimmt. Konten und Steuersätze kommen als Kontierungskontext für diese Schreibzugriffe zurück, und die Lesezugriffe, die wir noch nicht eingeschaltet haben, stehen in der Spalte auf Anfrage und nicht außerhalb des Systems.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
