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:

• Freischaltung eines Anbieters
• CI-Farben und Logo
• Daten des Rechnungsempfängers
• Abonnements kündigen
• Benutzerfotos auslesen
• Transaktion stornieren
• Nachzahlungslink generieren

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. Dieser wird automatisch angelegt, wenn der Kunde ihren Service freischaltet.

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. Ihr API-Benutzer kann also nicht mehr Daten abfragen und mehr Aktionen durchführen als es die eingestellten Rechte des Kunden erlauben.

Beim 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. Die Gültigkeit des „apiClaim“ wird in Zukunft zeitlich beschränkt werden. Daher reicht es nicht aus, immer mit dem gleichen „apiClaim“ zu arbeiten.

Der „extendedclaim“ bei der Freischaltung ist nur bei der Freischaltung gültig und nicht für die Servicecalls nach der Aktivierung.
Benutzen Sie keine anderen Calls während der Freischaltung außer unlockProvider. Nach Aktivierung des Services können Sie die benötigten Daten per API abrufen.

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.

---

Neben den API-Benutzern in den Kundenversionen gibt es auch „normale“ API-Benutzer, mit dem Sie Informationen aus Ihrer Anbieterversion abfragen können. Weitere Informationen zum Anlegen und Einstellen von API-Benutzern finden Sie in der API-Dokumentation und der Onlinehilfe.

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.