API-Calls

The official documentation for the onOffice API can be found at apidoc.onoffice.de.

Do you have questions about the API or need help? Then please contact the API support at apisupport@onoffice.de.

For specific questions about the Marketplace, please contact us at marketplace-dev@onoffice.de.

API Calls:

Some API Calls are required specifically for the Marketplace:

API User / Parameter extendedClaim:

In each customer version, your API user is present so that you have read and write access to the onOffice Enterprise version of your customers. This is automatically created when the customer activates your service.

The user rights (e.g. which properties or addresses he is allowed to read) of the customer who orders in your store must be observed by your API user. This means that your API user cannot query more data and perform more actions than the customer’s set rights allow.

Therefore, every time the customer calls your service, a parameter “apiClaim” is passed to you. Afterwards you have to return this “apiclaim” as parameter “extendedclaim” for all API calls. This is to ensure that the transfer of the user ID and the customer version is verified. Please use the “apiClaim” from the latest service call of the customer. The validity of “apiClaim” will be limited in time in the future. It is therefore not sufficient to always work with the same “apiClaim”.

The “extendedclaim” during unlock is valid only during unlock and not for the service calls after activation.
Do not use any other calls during the activation except unlockProvider. After activating the service, you can retrieve the required data via API.

This parameter will soon be a mandatory parameter in the context of the Marketplace. Set this parameter if you use API calls in the context of the marketplace. You must set this parameter for all API calls listed on apidoc.onoffice.de. Please include this parameter in your API calls as soon as possible.

API versions:

There are 2 API versions, latest and stable. It is up to you whether you use stable or latest. The stable version is updated monthly on the first Tuesday of the month. The latest-version is updated twice a week, and becomes stable on the first Tuesday of the next month. In the initial phase of the marketplace, when a lot is still changing and you want to test directly, latest makes more sense. Later, stable makes more sense, because errors in the API are less likely to occur.

The request URI for the “latest” API version is
https://api.onoffice.de/api/latest/api.php

The request URI for the “stable” API version, which is updated monthly, is
https://api.onoffice.de/api/stable/api.php

When you use a Live Client, it is automatically redirected to the stable API version, regardless of the API version you set.

If you are using a beta client, it is automatically redirected to the latest API version, regardless of the set API version.

Multilingual real estate::

If you want your service to work with multilingual properties and function correctly, please note the following information when reading and writing multilingual properties: If your customer calls your service from a multilingual property, the parameter language is passed to you in addition to the property ID estateid. With estateid and language, you can use the API call “Read real estate” to read the required values from a multilingual real estate and the API call “Edit real estate” to write the required values back to multilingual real estate. estateid is specified in the API as resourceid, language as estatelanguage. If the estatelanguageparameter is not specified, the system writes to the wrong language version of the real estate.

Advice:

The API calls for the Marketplace may still change sometimes, especially in the early days. In most cases, the changes remain backwards compatible, e.g. new parameters are added. Please be prepared for this and build your interface accordingly flexible and error-tolerant.

This post is also available in: German