Freischaltung

Freischaltungsprozess beim Kunden

Um einen Marketplace-Service nutzen zu können, müssen die Kunden diesen freischalten.

Die Services der Anbieter werden über den Menüpunkt „Marketplace“ in onOffice enterprise aufgerufen bzw. über die Aktionenleiste in den einzelnen Modulen wie Immobilien und Adressen. Im Menüpunkt „Übersicht“ sind alle Anbieter in einem Popup aufgeführt. Die darunterliegenden Menüpunkte listen die Anbieter mit Ihren Services einzeln auf.

Wählt der Benutzer einen Anbieter aus, der noch nicht freigeschaltet ist, öffnet sich ein Popup für die Freischaltung. Die Freischaltung ist nur als Administrator möglich.

In diesem kurzem Video ist der gesamte Freischaltungsprozess abgebildet. Klicken Sie auf das Bild links, um das Video zu starten.

Im ersten Schritt der Freischaltung bestätigt der Benutzer Ihre allgemeinen Geschäftsbedingungen (AGB) und die Auftragsverarbeitungsvereinbarung (AVV). Danach wird ihm folgende Maske angezeigt:

„Zum Anbieter“ zeigt eine Beschreibung Ihres Unternehmens und Ihrer Services. Unter „Beschreibung der freizugebenden Rechte“ werden die Rechte beschrieben, die der Benutzer Ihnen einräumen muss. Damit ist dem Benutzer bewusst, auf welche Daten zugegriffen wird.
Unter „Benutzerrecht aktivieren“ muss der Benutzer bewusst entweder „Für alle Benutzer“ oder „Für alle Administratoren“ einstellen, damit die Freischaltung durchgeführt werden kann. Administratoren haben immer Zugriff. Bei Marketplace-Anbietern, die genau EINEN Service per Webhook anbieten, ist diese Auswahl deaktiviert und „für alle Benutzer“ ist vorausgewählt. Der API-Key wird in diesem Fall direkt angezeigt.
Nach Einstellen der Benutzerrechte erscheint der API-Key. Dieser muss händisch in das zweite API-Key-Feld in Ihrem iFrame kopiert werden. Damit erlaubt der Kunde, dass Ihr Service über den API-Benutzer in der Kundenversion lesen und schreiben kann. Den API-Key müssen Sie für jeden Kunden speichern.

Achtung: Das zweite API-Key-Feld ist ein Iframe des Marketplace-Anbieters. D.h. diesen Teil des Freischaltungs-Popups programmieren Sie selbst. Programmieren Sie die Freischaltung am Besten zuerst und danach den eigentlichen Shop. Teilen Sie uns dann die URL für die Freischaltung möglichst frühzeitig mit. Dadurch ist sichergestellt, dass Sie Ihre Shop-Implementierung direkt testen können.

In den Code-Beispielen finden Sie einen Programm-Code als Vorlage für die Gestaltung. Diesen können Sie gerne individualisieren, um z. B. das Aussehen zu verändern oder spezifische Hinweise oder Fehlermeldungen für Ihren Service anzuzeigen. Bitte nutzen Sie dieses HTML-Grundgerüst für die Darstellung Ihres Iframes.

Für die Einbindung muss die Iframe-URL öffentlich zugänglich sein. Solange Sie uns die URL des Iframes nicht mitgeteilt haben, wird folgende Fehlermeldung angezeigt: „Eine Freischaltung des Anbieters ist aktuell nicht möglich. Fehlerhafte URL zur Freischaltung des API-Users.“

Schriftart Open Sans: Möchten Sie die Google-Schriftart „Open Sans“ von unseren Servern benutzen? Binden Sie dazu im Header einer HTML-Datei folgende Zeile ein:

und passen Sie Ihre CSS-Datei folgendermaßen an, um die Schriftart zu verwenden:

font-family: ‚onOffice Open_Sans‘

Die Freischaltung erfordert folgende Schritte:

AGB und AVV bestätigen
Benutzerrecht auswählen
API-Key kopieren
API-Key in Ihren Iframe einfügen
Datenschutzbestimmung zur Kenntnis nehmen
Mit einem Klick auf „Jetzt freischalten“ ist der Anbieter freigeschaltet.

Aufbau der Iframe-URL zur Freischaltung

Beim Aufruf der Freischalt-URL im Iframe werden Daten zur Identifikation des Kunden übertragen:

API-Token: apiToken
Name des Mandanten: customerName. Ein Mandant ist eine Instanz der onOffice-Software, die viele Benutzer haben kann. Oft sind Mandanten Maklerbüros und Benutzer die Makler.
WebID des Mandanten: customerWebId
UserID des Benutzers: userId. Die userId identifiziert zusammen mit der customerWebId eindeutig einen Kunden. Die userId alleine reicht nicht aus.
Parameter-Cache-ID: parameterCacheId
Zeitstempel: timestamp
Signatur: signature

Timestamp

Damit sichergestellt ist, dass der Aufruf des Iframes über onOffice enterprise erfolgt, wird folgendes Verfahren verwendet:

Jeder von onOffice generierten URL zum Aufruf eines Service-Iframes wird ein Timestamp-Parameter hinzugefügt (…timestamp=123456789). Der Timestamp stellt sicher, dass die Links nicht beliebig oft genutzt werden können.

Signatur

Außerdem werden alle Aufrufe einer URL von onOffice nach dem folgenden Verfahren signiert:

Über die komplette URL wird mit der Funktion hash_hmac eine Signatur erzeugt.
Zusätzlicher Teil dieser Signatur ist ein Secret, das einmalig von Ihnen bei der Aufnahme in den Marketplace gesetzt werden muss. In Ihrem Anbieter-Mandant können Sie das Secret im Menü Marketplace >> Anbietersecret ändern eintragen und auch verändern. Das Secret ist nach Speichern direkt gültig. Achten Sie daher darauf, es sofort verarbeiten zu können. Von häufigen Secretänderungen ist abzuraten, das Secret wird z.B. auch beim Link für Nachberechnungen verwendet, den Ihre Kunden per E-Mail zugesendet bekommen. Das Secret muss aus mindestens 24 Zeichen bestehen sowie Groß- und Kleinbuchstaben, Zahlen und Sonderzeichen enthalten.
Der erzeugte Hash wird wieder als Parameter an die URL angehangen.

Für die Signatur wird die URL inklusive aller Parameter (außer Parameter signature) über hash_hmac, sha256 verschlüsselt (siehe checkSignature in den Code-Beispielen). Die Parameter sind alphabetisch sortiert. Über den Zeitstempel kann die Gültigkeit der Signatur geprüft werden.

Tipp: Da Parameter sich ändern, oder neue Parameter hinzukommen können, empfehlen wir, alle Parameter dynamisch auszulesen und sie zu sortieren, statt mit einer statischen, festen Liste von Parametern bei der Signaturberechnung zu arbeiten.

Freischaltung des Anbieters

Damit Ihr Service in den Kundenversionen Daten lesen und schreiben kann, wird bei der Freischaltung Ihres Service automatisch ein API-Benutzer in jeder Kundenversion angelegt. Der API-Key und das Token zum Authentifizieren werden Ihnen bei der Freischaltung übergeben.

Mit dem eingetragenen API-Key und dem übergebenen Token authentifizieren sie sich. Sie müssen die API-Funktion zum Freischalten des Anbieters aufrufen (ACTION_ID_DO, ‘unlockProvider’) und an diese den Parameter parameterCacheId übergeben (siehe unlockProvider.js in den Code-Beispielen). Der Parameter parameterCacheId enthält interne Informationen, die im Parameter-Cache gespeichert wurden.

Im Erfolgsfall ist Ihr Angebot nun freigeschaltet. Speichern Sie die Daten zum API-Zugang (API-Key und Token) für jeden Kunden. Ein Kunde kann eindeutig identifiziert werden über die Kombination von Mandanten-ID (customerWebId) und Benutzer-ID (userId). Als Feedback für den Benutzer müssen Sie per JavaScript das Ergebnis an das Popup zurückmelden.

Im Erfolgsfall soll „active“, im Fehlerfall soll eine Fehlermeldung für den Benutzer zurückgegeben werden. (siehe unlockProvider.js in den Code-Beispielen).

Der Status ändert sich im Erfolgsfall von „Inaktiv“ auf „Aktiv“.

Der API-Key ist das Secret Ihres API-Benutzers beim Kunden. Der Kunde, der Ihre Dienste nutzen möchte, kopiert den API-Key bei der Freischaltung in ihren iFrame, übermittelt es Ihnen dadurch und gibt Ihnen dadurch Rechte auf seine onOffice Software zuzugreifen. Den API-Key und das Token speichern Sie deswegen bitte für jeden Kunden ab. Viele Dienste im Marketplace benötigen lesenden oder schreibenden Zugriff auf bestimmte Ressourcen in onOffice enterprise, um zu funktionieren. Beispiel Grundrissoptimierung: Kunde bestellt Grundriss im Marketplace für eine bestimmte Immobilie (Anbieter muss lesend auf Immobilie bzw. den Grundriss zugreifen), Anbieter erstellt Grundriss, Anbieter spielt optimierten Grundriss zurück (Anbieter muss schreibend auf Immobilie zugreifen).

Beachten Sie: Sie müssen keine eigenen API-Benutzer für Ihren Service erstellen. Die API-Benutzer für Ihren Service in den Kundenversionen werden automatisch angelegt, wenn die Kunden Ihren Dienst aktivieren. Die notwendigen Informationen (API-Key und Token) werden dabei übertragen. Den API-Key kopiert der Kunde aktiv in Ihren Iframe und das Token wird mit dem Aufruf der Freischalt-URL im Iframe übergeben.

Beachten Sie, dass ausserdem bei jedem API-Call ein Parameter „extendedclaim“ angegeben werden muss. Bei jedem Aufruf Ihres Services durch den Kunden wird deswegen an Sie ein Parameter „apiClaim“ übergeben. Anschliessend müssen Sie diesen „apiClaim“ bei allen API-Calls wieder als Parameter „extendedclaim“ zurückliefern. Dies dient dazu, dass die Übergabe der Benutzer-ID und der Kundenversion verifiziert ist. Bitte benutzen Sie den „apiClaim“ aus dem neuesten Serviceaufrufes des Kunden. Der apiClaim bei der Freischaltung kann nur für den unlockProvider-Call genutzt werden.
Genauere Informationen dazu unter https://www.marketplacedoc.onoffice.de/api-calls.

Der Benutzer hat Ihr Angebot freigeschaltet. Ihre Services können nun über den Menüpunkt „Marketplace“ in onOffice enterprise gebucht werden. Ruft der Benutzer Ihren Service auf, wird ihm im Popup Ihr Iframe mit dem gewünschten Service-Frontend angezeigt.

This post is also available in: Englisch