Technische Dokumentation

onOffice Marketplace

Wir erklären Ihnen, wie die Nutzer von onOffice enterprise Ihren Service über unseren Marketplace freischalten können und wie Sie Ihren Service in den onOffice Marketplace einbinden und welche Daten wir von Ihnen benötigen.

Bei Fragen wenden Sie sich bitte an den Marketplace-Support unter marketplace-dev@onoffice.de. Wir freuen uns über jede Rückmeldung von Ihnen, ob Kritik, Verbesserungsvorschläge oder Lob, um den Marketplace stetig verbessern zu können.

Was ist der onOffice Marketplace?

Der onOffice Marketplace bietet Anbietern von Immobiliendienstleistungen die Möglichkeit, ihre Produkte innerhalb von onOffice enterprise anzubieten.

Sie möchten mit Ihrer Dienstleistung, z.B. Grundriss-Erstellung, Immobilienbewertung oder Drohnenaufnahmen, einen größeren Kundenkreis erreichen? Der onOffice Marketplace ist die ideale Plattform dafür.

Täglich arbeiten zehntausende Immobilienmakler mit onOffice enterprise. Über den Marketplace können Sie sich damit viele interessante Dienstleistungen einfach und unkompliziert dazu buchen, ohne sich bei Ihnen als Anbieter zusätzlich anmelden zu müssen. Auch der Zahlungsprozess wird von onOffice durchgeführt, die Kosten für in Anspruch genommene Leistungen werden monatlich abgerechnet und an Sie weitergeleitet.

Was wir von Ihnen wissen müssen, um Sie als Anbieter aufzunehmen

Gemeinsam legen wir fest, welche Informationen und damit Rechte für Ihren Service nötig sind. Dabei wird auch die Abrechnung geregelt.

Welche URL soll für den Service eingebunden werden? Wie groß soll das Fenster für Ihren Service sein? Die Größe des Popups wird dabei vorgegeben und kann von Ihnen mit onOffice abgesprochen werden. Wie ist die URL zur Freischaltung des API-Users? Dabei wird auch das Secret für die Signatur der Aufrufe ausgetauscht. Benötigt Ihr Service Systemfelder in onOffice enterprise, in die Sie Daten zurückspielen möchten?

Diese und gegebenenfalls weitere Einstellungen werden mit Ihnen zusammen erarbeitet.

Sie stellen uns die rechtlich relevanten Dokumente wie die Datenschutzerklärung, die Auftragsverarbeitungsvereinbarung (AVV) und die allgemeinen Geschäftsbedingungen (AGB) zur Verfügung, damit wir sie im Marketplace den Benutzern zum Download bereitstellen können.

Sie legen die Texte, Beschreibungen und Claims etc. fest, die Ihr Unternehmen und ihre angebotenen Services beschreiben.

Freischaltung eines Anbieters

Die Services der Anbieter lassen sich über den Menüpunkt „Marketplace“ in enterprise aufrufen. Nach Klick auf „Übersicht“ öffnet sich eine Übersicht aller Anbieter. In den darunterliegenden Menüpunkten sind die einzelnen Anbieter mit Ihren Services aufgelistet.

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

Wenn der Benutzer Ihren Service freischalten möchte, wird diesem folgende Maske angezeigt:

Unter „Zum Anbieter“ wird eine Beschreibung Ihres Unternehmens und Ihrer Services angezeigt. Unter „Beschreibung der freizugebenden Rechte“ werden die Rechte beschrieben, die der Benutzer Ihnen als Anbieter 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“ eingestellt werden, damit die Freischaltung durchgeführt werden kann. Administratoren haben immer Zugriff.
Nach Einstellen der Benutzerrechte erscheint der API-Key. Dieser muss händisch in das zweite API-Key-Feld kopiert werden.

Nach dem ersten API-Key-Feld beginnt der iFrame des Anbieters. In der Anlage finden Sie den Programm-Code dafür als Vorlage, den Sie für sich individualisieren können. Bitte nutzen Sie dieses HTML-Grundgerüst für die Darstellung Ihres iFrames.

Zum Freischalten muss der API-Key vom Benutzer in Ihren iFrame kopiert werden. Der Datenschutzerklärung muss vom Benutzer zugestimmt werden.

Der Anbieter kann nun über „Jetzt freischalten“ freigeschaltet werden.

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

Name des Mandanten
WebId des Mandanten
UserID des Benutzers
apiToken
parameterCacheId
Zeitstempel
Signatur

Für die Einbindung muss die iFrame-URL öffentlich zugänglich sein.

Damit sichergestellt ist, dass der Aufruf des iFrames über onOffice enterprise erfolgt, soll folgendes Verfahren verwendet werden:

Jeder von onOffice generierten URL zum Aufruf eines Service-iFrames wird ein Timestamp-Parameter hinzugefügt (…×tamp=1234569). Über den Timestamp ist die Möglichkeit vorhanden, dass die Links nicht beliebig oft genutzt werden können.

Alle Aufrufe einer URL werden außerdem 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 bei der Aufnahme in den Marketplace mit dem Anbieter ausgetauscht werden muss.
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 im Anhang). Die Parameter sind alphabetisch sortiert. Über den Zeitstempel kann die Gültigkeit der Signatur geprüft werden.

Weitere Parameter können von Ihnen als Anbieter frei festgelegt werden.

Sind alle nötigen Schritte zur Freischaltung auf Ihrer Seite durchgeführt, müssen Sie mit dem eingetragenen API-Key und dem übergebenen Token die API-Funktion zum Freischalten des Anbieters aufrufen (ACTION_ID_DO, ‘unlockProvider’) und an diese den Parameter parameterCacheId übergeben (siehe unlockProvider.js im Anhang).

Im Erfolgsfall ist Ihr Angebot nun freigeschaltet und Sie sollten die Daten zum API-Zugang (secret und token) speichern. 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 im Anhang).

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

Der Benutzer hat Ihr Angebot freigeschaltet. Ihre Services können nun über den Menüpunkt „Marketplace“ in enterprise genutzt werden. Der Benutzer sieht dann das gewünschte Service-Frontend.

Sperren eines Anbieters / Aktualisieren des API-Keys

In der Marketplace-Übersicht (Marketplace → Übersicht -> Anbieter auswählen) kann ein freigeschalteter Anbieter über den Button „Anbieter sperren“ wieder gesperrt werden.

Ihr Angebot wird dadurch deaktiviert und Ihre Services lassen sich nicht mehr aufrufen. Dadurch wird auch der API-Benutzer zum zugehörigen Anbieter deaktiviert. Sie als Anbieter bekommen dies nicht mitgeteilt.

Wenn der Kunde sich entschließt, Ihr Angebot wieder zu aktivieren, wird Ihr iFrame für den Freischaltungsprozess aufgerufen. Der Kunde ist Ihnen bereits bekannt, sie haben die Mandanten-ID schon bei sich gespeichert. In diesem Fall müssten Sie dann das API-Token bei sich aktualisieren und per onOffice-API den Anbieter erneut freischalten.

Aufruf der Services / Einbindung des iFrames mit dem Service

Nach der Freischaltung wird Ihr Service per iFrame in enterprise eingebunden.

Für die Einbindung muss die iFrame-URL für den Service öffentlich zugänglich sein. Diese URL für Ihren Service teilen Sie uns einmalig mit, wenn wir Sie als Anbieter für den Marketplace aufnehmen.

Damit eine signierte URL vorhanden ist, die für den iFrame des Services verwendet werden kann, wird dasselbe Verfahren für die Signatur wie bei der Freischaltung eines Anbieters verwendet.

Ihre Aufgabe als Anbieter ist es, die URL selber gegen die Signatur zu prüfen.

Folgende Angaben werden beim Aufruf über die URL signiert übergeben:

Mandantenname: customerName
User-Web-ID: customerWebId
Benutzer-ID: userId
Wenn Gruppen verwendet werden: Gruppen-ID: groupId
Zeitstempel: timestamp (Format: Unix-Zeitstempel in Sekunden, die vergangenen Sekunden seit Donnerstag, dem 1. Januar 1970, 00:00 Uhr UTC)
Parameter, die durch Makros definiert wurden (z.B. ID einer Immobilie oder Adresse)

Manche Services wie z.B. eine Grundriss-Optimierung können einen Immobilien- oder Adressbezug benötigen. Der Kunde muss sich in diesem Fall bei Zeitpunkt des Aufrufs in einer Immobilie bzw. einer Adresse befinden. Die benötigten Informationen zum Kontext wie z.B. die Immobilien-ID oder die Adress-ID werden dann an Sie mit übertragen.

Falls er sich an einer Stelle befindet, die den Bezug nicht herstellen kann, erscheint eine Meldung:

„Dieser Service kann nur aus einer Immobilie / Adresse aufgerufen werden.“

Beispielansicht eines freigeschalteten Service:

Hier präsentieren Sie ihre Produkte und zeigen Ihre Preise an. Der Kunde kann Ihre Produkte direkt bestellen. Im nächsten Schritt öffnet sich dann das Popup für die Zahlungsbestätigung und -abwicklung.

Zahlungsabwicklung

In Progress (Fertigstellung in Kürze)

Systemfelder

Manche Services, die Sie anbieten möchten, benötigen evtl. Systemfelder in onOffice enterprise, in die Sie Daten schreiben können. Ein Anbieter für Immobilienbewertungen könnte z.B. ein Feld „Immobilienbewertung“ benötigen, in das er nach Durchführung der Immobilienbewertung das Resultat schreibt.

Falls Ihre Services Systemfelder benötigen, sprechen Sie uns bitte dazu bei der Aufnahme Ihres Angebots in den Marketplace an und wir richten die gewünschten Systemfelder ein.

API-Calls

Die offizielle Dokumentation zur onOffice-API finden Sie unter apidoc.onoffice.de.

Haben Sie Fragen zur API oder benötigen Sie Hilfe? Dann wenden Sie sich bitte an den API-Support unter apisupport@onoffice.de.

Bei speziellen Fragen zum Marketplace kontaktieren Sie uns bitte unter marketplace-dev@onoffice.de.

Einige API-Calls werden speziell für den Marketplace benötigt:

Anhang

Demo-php-Datei für den iFrame zur Freischaltung eines Anbieters:

_getParameterToken =
      $_REQUEST( self ::GET_PARAMETER_TOKEN);
      $this ->_getParameterCacheId =
      $_REQUEST( self ::GET_PARAMETER_CACHE_ID);
    }
    /**
    *
    */
    public function createHtmlCode ()
    {
      if ( $this ->checkSignature())
        {
        $this ->printHtml();
        }
      else
        {
        $this ->printErrorMessage();
        }
    }
    /**
    *
    * Just a demo function for checking the signature - contains
    pseudo code
    * @return bool
    *
    */
    private function checkSignature ()
    {
      $signature =
      getRequestVariable( self ::GET_PARAMETER_SIGNATURE);
      $uriToCheck = 
      $ checkSignature = hash_hmac ( 'sha256' , $uriToCheck, 'hier
      Anbietersecret einsetzen' );
      return ( 0 === strcmp($checkSignature, $signature));
    }
    /**
    *
    */
    private function printErrorMessage ()
    {
      $html = '
      
        
        attr( 'style' , 'margin: 0;' ). '>
          Signatur nicht korrekt
        
      ' ;
      echo $html;
    }
    /**
    *
    */
    private function printHtml ()
    {
      $cssUri =
      $this ->getUriPath( '/gui/smart/resources/css/layout/smart/themes/mar
      ketplace/marketplaceUnlockIFrame.css' );
      $jsUri = '/mypathToJs/unlockProvider.js' );
      $unlockProviderData = $this ->createUnlockProviderData();
      $unlockLabelText = $this ->getUnlockLabelText();
      $html = '
      
        
          attr( 'rel' , 'stylesheet' ).
          $this ->attr( 'type' , 'text/css' ).
          $this ->attr( 'href' , $cssUri). '>
        
        attr( 'style' , 'margin: 0;' ). '>
          attr( 'class' ,
          'data-privacy-statement-label' ). '>Datenschutzerklärung
          attr( 'class' , 'data-privacy-statement' ).
          $this ->attr( 'id' , 'dataPrivacyStatement' ).
          $this ->attr( 'type' , 'checkbox' ).
          $this ->attr( 'onchange' , 'checkboxChanged(this)' ).
          '>
          attr( 'class' ,
          'data-privacy-link-prefix-label' ). '>Ich akzeptiere die
            attr( 'href' , 'https://de.onoffice.com/' ).
            $this ->attr( 'target' , '_blank' ). '>
            Datenschutzerklärung von *Hier Anbieter
            einsetzen*
            
          
          attr( 'class' ,
          'api-key-label' ). '>API-Key
          attr( 'class' , 'api-key-input-outer' ).
          $this ->attr( 'id' , 'secretDiv' ). '>
          attr( 'class' , 'api-key-input' ).
          $this ->attr( 'name' , 'secret' ).
          $this ->attr( 'type' , 'text' ).
          $this ->attr( 'placeholder' , 'API-key hier
          reinkopieren' ).
          $this ->attr( 'id' , 'secret' ). '>
          
          attr( 'class' , 'unlock-now-button' ).
          $this ->attr( 'id' , 'unlockButton' ).
          $this ->attr( 'type' , 'button' ).
          $this ->attr( 'value' , $unlockLabelText).
          $this ->attr( 'title' , 'Bitte zuerst der
          Datenschutzerklärung zustimmen' ).
          $this ->attr( 'alt' , 'Bitte zuerst der
          Datenschutzerklärung zustimmen' ).
          $this ->attr( 'onclick' ,
          'unlockProvider(' . $this ->json($unlockProviderData). ')' ). '
          disabled>
          attr( 'id' , 'successMessage' ).
          $this ->attr( 'class' , 'active-label' ). '>Aktiv
          attr( 'id' , 'spinner' ).
          $this ->attr( 'class' , 'unlock-load-spinner' ). '>
        
        ' ;
      echo $html;
    }
    /**
    *
    * @return array
    *
    */
    private function createUnlockProviderData ()
    {
      $unlockProviderData = [
      'getParameterToken' => $this ->_getParameterToken,
      'getParameterCacheId' => $this ->_getParameterCacheId,
      ];
      return $unlockProviderData;
    }
    /**
    *
    * @param string $name
    * @param string $value
    * @return string
    *
    */
    private function attr ($name, $value)
    {
      $attr = ($value !== null ? '
      ' .$name. '="' .htmlspecialchars($value, ENT_QUOTES). '"' : '' );
      return $attr;
    }
    /**
    *
    * @param string $path
    * @return string
    *
    */
    private function getUriPath ($path)
    {
      return 'https://smart.onoffice.de/smart' .$path;
    }
    /**
    *
    * @param mixed $variable
    * @return string
    *
    */
    private function json ($variable)
    {
      return json_encode($variable,
      JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_LINE_TERMINATORS);
    }
    /**
    *
    * @return string
    *
    */
    private function getUnlockLabelText ()
    {
      return 'Jetzt Freischalten' ;
    }
  }
?>

Demo-javascript-Datei (unlockProvider.js) für den iFrame zur Freischaltung eines Anbieters:

function unlockProvider (arguments){
  var spinner = document.getElementById( 'spinner' ),
  button = document.getElementById( 'unlockButton' ),
  successMessage =
  document.getElementById( 'successMessage' ),
  secretTextInput =
  document.getElementById( 'secret' ),
  secretDiv = document.getElementById( 'secretDiv' ),
  secret = secretTextInput.value;
  var token = arguments.getParameterToken,
  parameterCacheId = arguments.getParameterCacheId;
  spinner.style.visibility = 'visible' ;
  button.style.visibility = 'hidden' ;

  var data = new FormData();
  data.append( 'token' , token);
  data.append( 'secret' , secret);
  data.append( 'parameterCacheId' , parameterCacheId);
  var httpRequest = new XMLHttpRequest();

  //Here a PHP script is called, which executes the
  //unlockProvider API call (see below: Beispiel zum
  //Freischalten der API). The javascript waits for the
  //answer of the API call and returns the answer to
  //the unlock popup.

  var url = '---->insert url to unlock by API call
  here
  include ' Psr4AutoloaderClass.php ';
  use onOfficeSDKPsr4AutoloaderClass;
  use onOfficeSDKonOfficeSDK;
  $pAutoloader = new Psr4AutoloaderClass();
  // register path to our files (namespace onOffice)
  $pAutoloader->addNamespace(' onOffice ', __DIR__);
  $pAutoloader->register();
  $pSDK = new onOfficeSDK();
  $pSDK->setApiVersion(' latest ');
  $parameterUnlockProvider = [ ' parameterCacheId '=>
  $parameteCacheId];;
  $handleUnlockProvider = $pSDK->callGeneric
  (onOfficeSDK::ACTION_ID_DO, ' unlockProvider ',
  $parameterUnlockProvider);
  $pSDK->sendRequests(' put the token here ', ' and secret here ');
  var_export($pSDK->getResponseArray($handleUnlockProvider));
?>

Dieser Beispielcode ist vorläufig und kann sich im Rahmen der Entwicklung des Marketplace noch ändern.

Autor: Robert Igelmund, 12.07.2019

This post is also available in: German