SnelStart anbinden: Zwei Authentifizierungsflüsse, und ein Konto-Schlüssel

Fast jede Beschreibung dieses Systems, unsere bisherige eingeschlossen, sagt, SnelStart authentifiziere sich mit zwei Schlüsseln, und hört dort auf. Für den Fluss, gegen den Sie bauen, stimmt das. Für den, mit dem Sie ausliefern, nicht. SnelStart betreibt zwei getrennte Authentifizierungsprozesse: Entwicklung und Test, also die zwei Schlüssel weiter unten, und Produktion, ein Redirect mit einem eigenen Abschnitt.

Warum der zweite im öffentlichen Bestand fehlt, sollten Sie wissen, bevor Sie irgendetwas anderem über diese Schnittstelle vertrauen: SnelStarts Referenz liegt hinter einem Login, Beschreibungen werden also aus der sichtbaren Hälfte rekonstruiert.

Für den Entwicklungsfluss sind zwei Zugangsdaten unauffällig. Entscheidend ist, dass keine einzelne Person beide erzeugen kann, und das ändert, was Ihre Onboarding-Maske leisten kann.

Der Verbindungsschlüssel gehört Ihrem Kunden. Er meldet sich in seinem eigenen Konto an, öffnet Koppelingen, wählt Maatwerk, stimmt den Scopes zu und speichert den Wert. Er gilt je Firma, Ihr Kunde kann ihn widerrufen, und er ist die Hälfte, die Sie in Ihrem eigenen Produkt einsammeln können.

Der Abonnementschlüssel gehört Ihnen. Er kommt aus einem Entwicklerkonto, das Sie einmal registrieren, und er identifiziert Ihre Anwendung. Kein Onboarding-Formular kann danach fragen, weil Ihr Kunde keinen hat und nie einen haben wird.

Vor beiden steht eine dritte Bedingung, und sie zeigt sich eher im Vertriebsgespräch als beim Bauen. Der Zugang hängt am Tarif: maesns Connect-Guide hält fest, dass Ihr Kunde das Paket inZicht oder inControle halten muss, um den Zugang überhaupt einzurichten. Das sind die oberen zwei Pakete auf SnelStarts eigener Preisliste.

Im Entwicklungsfluss gibt es keinen Redirect, weshalb dies eines der sieben Systeme ist, die sich während des Bauens ohne gehostete Seite verbinden lassen. Produktiv ändert sich das, und der Abschnitt darunter beschreibt, was daraus wird.

Sobald Sie freigegebener Partner sind, ändert der Handschlag seine Form. SnelStart nennt diesen Fluss OAuth, und das Wort ist weit auszulegen: Er folgt dem Standardmuster nicht, und am klarsten liest er sich als eigener Prozess neben den zwei Schlüsseln.

Aus dem Partnerantrag bekommen Sie einen Anwendungskurznamen, der sich wie eine Client-ID verhält. Ohne ihn beginnt in diesem Fluss nichts. Sie schicken Ihren Kunden an eine daraus gebaute Aktivierungs-URL, die einen Referenzschlüssel und eine Erfolgs-URL für den Abschluss mit sich führt. Der Referenzschlüssel verhält sich wie ein State-Parameter.

Ihr Kunde meldet sich bei SnelStart an und akzeptiert die Scopes, die Ihre Anwendung angefragt hat. Dann folgt der Teil, der Ihr Callback-Design entscheidet: SnelStart gibt den Verbindungsschlüssel nicht über den Browser zurück. Es sendet ihn an eine Callback-Adresse, die Sie bei der Antragstellung registriert haben, zusammen mit dem Referenzschlüssel, den Sie mitgeschickt haben, damit der Callback der Browser-Sitzung zugeordnet werden kann. Ihre Seite bestätigt mit einem 201, und erst dann wird Ihr Kunde weitergeleitet.

Über maesn erreicht nichts davon Ihren Code. Der Aktivierungslink, der Callback, die Zuordnung des State und die Speicherung des Verbindungsschlüssels liegen hinter der Verbindung, und was Sie halten, ist ein Konto-Schlüssel. Unified Authentication lässt ein System mit zwei verschiedenen Handschlägen aussehen wie eines mit einem.

Das ist der Teil, der in einen Projektplan gehört, und er fehlt in jeder Beschreibung dieses Systems, die wir bisher veröffentlicht haben. Auf den meisten Plattformen registrieren Sie sich, bekommen Schlüssel, bauen, und ein Marktplatzeintrag ist optionale Distribution, die Sie später ergänzen. Hier ist die Reihenfolge umgekehrt.

SnelStarts Entwicklerportal sagt es unumwunden, auf Niederländisch: „Ben je als ontwikkelaar klaar met het bouwen van de koppeling en gereed om een permanente maatwerk- of productiesleutel te ontvangen? Dan kun je de koppeling aanmelden om door ons te worden gecertificeerd.“ Die Integration fertigstellen, einreichen, und ein dauerhafter Schlüssel folgt auf die Freigabe.

maesns eigene Dokumentation sagt, was das absichert. Um die Schnittstelle produktiv zu nutzen, „müssen Sie offizieller Snelstart-Partner werden. Nach der Freigabe erhält Ihre Anwendung Zugang zu Live-Umgebungen von Kunden (über die voreingestellte Testfirma hinaus).“ Bis zu dieser Freigabe erreicht eine voll funktionsfähige Integration genau eine Firma, und die gehört keinem Kunden.

Auch die Uhr zählt. Ein Entwicklungsabonnement ist kostenlos und 90 Tage gültig, mit begrenzten Aufrufen. Zieht sich Ihr Bau über dieses Fenster hinaus, verfällt der Schlüssel, mit dem Sie getestet haben.

Und zwischen Einreichen und Livegang liegt ein Schritt, den man leicht übersieht, wenn man von einem Starttermin rückwärts plant. Sobald Sie SnelStarts Partner-Manager melden, dass die Integration fertig ist, beginnt eine siebentägige Beobachtungsphase. In dieser Woche muss die Integration mindestens 150 Aufrufe absetzen, ohne zu viele Fehler zu erzeugen.

Das ist eine Anforderung, die Sie aktiv bedienen müssen. Hundertfünfzig Aufrufe in einer Woche sind ein überschaubares Aufkommen, und sie sind trotzdem mehr, als eine ruhende Integration erzeugt, also muss jemand sie gezielt auslösen. An dieser Stelle im Prozess erzeugt maesn diesen Verkehr gemeinsam mit Ihnen.

Über die 30 Systeme dieses Katalogs gezählt, ist SnelStart das einzige, in dem maesn mehr Objekttypen zum Schreiben als zum Lesen freigeschaltet hat: vier Create gegen drei Read. Das klingt nach einem Vorteil und ist überwiegend eine Warnung.

Das ist unser eigener Freischaltstand. Die SnelStart-API schreibt diese Form nicht vor. Buchungsvorschläge, Gutschriften und Dateien sind zum Schreiben freigeschaltet, ihre Lesezugriffe sind als auf Anfrage verfügbar markiert. Kontakte ist heute das einzige Objekt, das auf beiden Seiten freigeschaltet ist. Für drei Ihrer vier Schreibvorgänge gibt es derzeit also keinen Rückweg, und nichts, was Sie senden, lässt sich zurückholen und mit dem vergleichen, was Sie senden wollten, bis diese Lesezugriffe freigeschaltet sind.

Die praktische Folge entscheidet, wohin Ihre Arbeit geht. Auf einem System mit vollem Rückweg können Sie optimistisch schreiben und später abgleichen. Hier ist die Antwort auf die Anfrage die Bestätigung, die Prüfung gehört also vor den Aufruf. Unified Error Handling macht dieses Scheitern in derselben Form lesbar wie bei jedem anderen System. Eine herstellereigene Ablehnung, die Sie erst lesen lernen müssen, bleibt Ihnen erspart.

Das Objekt, das Sie am häufigsten schreiben, trägt auch die strengste Payload-Regel. Ein Buchungsvorschlag führt Steuerinformationen auf Buchungsebene und noch einmal auf jeder einzelnen Zeile, beide sind Pflicht, und die zwei Darstellungen müssen übereinstimmen. Eine Abweichung führt zur Ablehnung; abgeglichen wird nichts.

Das ist interne Buchhaltungslogik, die an der Schnittstelle sichtbar wird. Sie erklärt auch, wofür die lesbare Seite dieses Systems da ist: Konten und Steuersätze sind genau die Referenzdaten, die Sie brauchen, um das Paar korrekt anzugeben. Die drei lesbaren Objekte sind der Kontierungskontext für die vier schreibbaren.

Welche Objekte und Operationen tatsächlich freigeschaltet sind und welche der 37 als auf Abruf markiert sind, steht Objekt für Objekt auf der Seite zur SnelStart Schnittstelle.

Objekte sind hier auf eine Weise zerstückelt, die Aufrufe kostet. Ein Kontakt trägt keinen Ländercode, er trägt eine Länderkennung, die auf einen eigenen Datensatz zeigt. Von dieser Kennung zu etwas zu kommen, das Sie anzeigen oder speichern können, bedeutet eine weitere Anfrage.

Aus einem Nachschlagevorgang wird eine Design-Entscheidung, weil die Liste nicht fest ist. Länder können angelegt, geändert und gelöscht werden, eine einmal importierte Zuordnung als Konstante zu behandeln veraltet also. Ein Cache ist die richtige Antwort, und er braucht eine Auffrischungsregel.

Das ist der gewöhnliche Fall für Referenzdaten über Buchhaltungssysteme hinweg, und es ist der Grund, warum es überhaupt eine gemeinsame Form gibt. Über das Common Data Model wird die Kennung aufgelöst, bevor das Objekt Sie erreicht, ein Kontakt kommt also mit derselben Länderdarstellung an wie auf jedem anderen verbundenen System.

Kein Objekt in diesem System trägt ein natives Ereignis. Acht der 30+ verbundenen Systeme senden etwas, dieses gehört nicht dazu, es gibt also kein Abonnement zu registrieren und keine Zustellung zu prüfen. Aktuell zu bleiben ist ein geplanter Lesevorgang über dieselben Filter und dieselbe Seitenaufteilung, die Sie überall sonst verwenden.

Im Ereignismodell erledigt damit die Pull-Hälfte die ganze Arbeit. Ein Pull holt nach einem Ausfall auf, was ein Push nicht tut, und das Intervall legen Sie selbst fest.

Ein Vorbehalt dieses Systems muss genannt werden, bevor Sie irgendetwas einstellen. Solange Sie auf einem Entwicklungsschlüssel arbeiten, lesen Sie die voreingestellte Testfirma, alles also, was Sie an Volumen, Zeitverhalten und Seitengrößen messen, messen Sie gegen Daten, die nicht die Ihres Kunden sind. Nehmen Sie diese Zahlen als Rauchtest und nicht als Ausgangswert.

Was wir von der Liste nehmen:

• Den Token-Lebenszyklus. Der Austausch, die stündliche Erneuerung und die Speicherung beider Schlüssel je Mandant laufen hinter der Verbindung, Ihr Code hält also einen Konto-Schlüssel und keine Zeitgeber.
• Die Auflösung der Referenzen. Länderkennungen und die anderen zerstückelten Nachschlagevorgänge werden aufgelöst, bevor Objekte Sie erreichen, und genau dort entstünde sonst das N+1.
• Die doppelte Steuer. Eine normalisierte Buchungsstruktur geht hinein, und die zwei Darstellungen, die dieses System verlangt, werden daraus erzeugt, konsistent.

Was bei Ihnen bleibt, und die ersten zwei sind keine Entwicklungsaufgaben:

• Die Partnerfreigabe und den Produktivschlüssel. Antrag und Einreichung laufen auf Ihren Namen, und keine Schnittstelle davor verkürzt die Prüfung, die Kalenderzeit gehört also in Ihren Plan. Allein stehen Sie damit aber nicht: Wir liefern die Callback-Adresse, nach der der Antrag fragt, helfen Ihnen, die Scope-Liste auf das zu kürzen, was Ihre Endpunkte wirklich brauchen, und erzeugen den Verkehr, den die Beobachtungswoche verlangt.
• Das Paket Ihres Kunden. Der Zugang braucht inZicht oder inControle. Das ist eine Frage für Ihr Qualifizierungsgespräch.
• Was ein Schreibvorgang bedeutet. Wir können eine abgelehnte Buchung verständlich machen, und wir können ein Objekt, das sich nicht abrufen lässt, nicht abrufbar machen. Wo es keinen Rückweg gibt, ist die Entscheidung darüber, was Sie auf Ihrer Seite festhalten, Ihre.