API-Calls

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

Haben Sie Fragen zur API oder benötigen 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.

API-Calls:

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

API-Benutzer / Parameter extendedClaim:

In jeder Kundenversion ist Ihr API-Benutzer vorhanden, damit Sie lesend und schreibend auf die onOffice enterprise-Version Ihrer Kunden zugreifen können.

Die Benutzerrechte (z.B. welche Immobilien oder Adressen er lesen darf) des Kunden, der in Ihrem Shop bestellt, müssen von Ihrem API-Benutzer beachtet werden. Beim Aufruf Ihres Services durch den Kunden wird deswegen an Sie einen Parameter „apiClaim“ übergeben. Anschliessend müssen Sie diesen bei allen API-Calls wieder als Parameter „extendedclaim“ zurückliefern. Dies dient dazu, dass die Übergabe der Benutzer-ID und der Kundenversion verifiziert ist.

Dieser Parameter wird im Kontext des Marketplace demnächst eine Pflichtangabe sein. Setzen Sie diesen Parameter, wenn Sie API-Calls im Rahmen des Marketplaces benutzen. Der Parameter ist bei allen API-Calls zu setzen, die auf apidoc.onoffice.de aufgelistet sind. Bitte bauen Sie diesen Parameter möglichst bald bei sich in Ihre API-Calls ein.

API-Versionen:

Es gibt 2 API-Versionen, latest und stable. Es liegt in Ihrem Ermessen, ob sie stable oder latest verwenden. Die stable-Version wird monatlich am ersten Dienstag des Monats aktualisiert. Die latest-Version wird 2x wöchentlich aktualisert, und wird am ersten Dienstag des nächsten Monats zum stable. In der Anfangsphase des Marketplaces, wenn sich noch viel verändert und direkt getestet werden soll, ist latest sinnvoller. Später macht stable mehr Sinn, weil dann Fehler in der API unwahrscheinlicher sind.

Die Request-URI für die „latest“-API-Version ist https://api.onoffice.de/api/latest/api.php

Die Request-URI für die „stable“-API-Version, die monatlich aktualisiert wird, ist https://api.onoffice.de/api/stable/api.php

Wenn Sie einen Live-Mandanten verwenden, wird er automatisch auf die stabil API-Version umgeleitet, unabhängig von der eingestellten API-Version.
Wenn Sie einen Beta-Mandanten verwenden, wird er automatisch auf die latest API-Version umgeleitet, unabhängig von der eingestellten API-Version.

Mehrsprachige Immobilien:

Wenn Ihr Service mit mehrsprachigen Immobilien arbeiten und korrekt funktionieren soll, beachten Sie bitte folgende Informationen beim Lesen und Schreiben von mehrsprachigen Immobilien: Wenn Ihr Kunde Ihren Service aus einer mehrsprachigen Immobilie aufgeruft, dann wird zusätzlich zum Immobilien-ID estateid der Parameterlanguage an Sie übergeben. Mit estateid und language können Sie dann über den API-Call „Immobilien lesen“ die benötigten Werte aus einer mehrsprachigen Immobilie auslesen und über den API-Call „Immobilien bearbeiten“ die gewünschten Werte in mehrsprachige Immobilien zurückschreiben. estateid wird in der API als resourceid , language als estatelanguage angegeben. Ohne Angabe des Parameters estatelanguage würde in die falsche Sprachversion der Immobilie geschrieben werden.

Hinweise:

Die API-Calls für den Marketplace können sich, gerade in der Anfangszeit, noch manchmal ändern. In den allermeisten Fällen bleiben die Änderungen abwärtskompatibel, z.B. kommen neue Parameter hinzu. Bitte stellen Sie sich darauf ein und bauen Sie Ihre Schnittstelle dementsprechend flexibel und fehlertolerant.