SDK:
To use the onOffice API, you can use the onOffice SDK (Software Development Kit) written in PHP. It contains code to generate API requests.
The onOffice SDK is available on GitHub and can be downloaded there.
Please read and follow the license conditions and the readme file. The SDK is under the MIT license and is a generous open source license. It allows reuse of the SDK for both open-source and closed-source software.
The request URL for the latest API version is https://api.onoffice.de/api/latest/api.php.
The request URL for the stable API version, which is updated monthly, is https://api.onoffice.de/api/stable/api.php.
Note that the request URLs for the stable and latest API always remains the same for all requests. The individual endpoints are addressed via parameters actionid and resourcetype in the JSON.
As a template for your API requests the PHP files 02-call.php and 01-call-generic.php is contained in the SDK, which you can customize for your own queries.
If you use the SDK, you can use the method getErrors() from the class onOfficeSDK.php to get the error messages.
In the SDK, you specify an API request in PHP array notation, as shown in the example for reading estate data below.
PHP request example: read estate
<php
include 'Psr4AutoloaderClass.php';
use onOffice\SDK\Psr4AutoloaderClass;
use onOffice\SDK\onOfficeSDK;
$pAutoloader = new Psr4AutoloaderClass();
// register path to our files (namespace onOffice)
$pAutoloader->addNamespace('onOffice', __DIR__);
$pAutoloader->register();
$pSDK = new onOfficeSDK();
// Which API version is used, can be set by setApiVersion
// with the values 'latest', which is the latest
// API version in beta stadium or 'stable', the stable
// version, which is updated monthly.
$pSDK->setApiVersion('latest');
$parametersReadEstate = [
'data' => [
'Id',
'kaufpreis',
'lage',
],
'listlimit' => 10,
'sortby' => [
'kaufpreis' => 'ASC',
'warmmiete' => 'ASC',
],
'filter' => [
'kaufpreis' => [
['op' => '<', 'val' => 300000],
],
'status' => [
['op' => '=', 'val' => 1],
],
],
];
$handleReadEstate = $pSDK->callGeneric
(onOfficeSDK::ACTION_ID_READ, 'estate', $parametersReadEstate);
// Sometimes however, you will have to set the
// `resourceId` parameter. In this case, you have to
// use the call()-method instead the callGeneric()-method.
// ResourceId is the 2nd parameter for the call()-method
// and has the value 'estate' here.
// $handleSearchEstate = $pSDK->call
// (onOfficeSDK::ACTION_ID_GET, 'estate',
// '', 'search', $parametersSearchEstate);
$pSDK->sendRequests('put the token here', 'and secret here');
var_export($pSDK->getResponseArray($handleReadEstate));
This code is converted to regular JSON and executed. The general structure of the JSON request can be found here.
That means if you use our SDK, the JSON API requests must be rewritten to PHP.
JSON request example: read estate
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
"resourceid": "",
"identifier": "",
"resourcetype": "estate",
"parameters": {
"data": [
"Id",
"kaufpreis",
"lage"
],
"filter": {
"status": [
{
"op": "=",
"val": 1
}
],
"kaufpreis": [
{
"op": "<",
"val": 300000
}
]
},
"listlimit": 10,
"sortby": {
"kaufpreis": "ASC",
"warmmiete": "ASC"
}
}
}
Without SDK:
If you do not use the onOffice SDK for your API requests, you must additionally specify a timestamp and an HMAC code for each request. This information are described in more detail in in the action elements overview. When using the onOffice SDK, this information is being generated automatically and does not have to be specified.
Without the SDK, the API can be accessed e.g. via cURL, as shown in the following PHP example below.
cURl request: read estate
<?php
// bitte token und secret ausfüllen
$token = '';
$secret = '';
$apiServer = 'https://api.onoffice.de/api/';
$apiVersion = 'stable';
$apiUri = $apiServer.$apiVersion.'/api.php';
$resourceType = 'estate';
$actionId = 'urn:onoffice-de-ns:smart:2.5:smartml:action:read';
$timestamp = time();
$hmac2 = base64_encode(
hash_hmac(
'sha256',
implode(
'',
[
'timestamp' => $timestamp,
'token' => $token,
'resourcetype' => $resourceType,
'actionid' => $actionId,
]
),
$secret,
true
)
);
$actionParameterData =
[
"timestamp" => $timestamp,
"hmac_version" => 2,
"hmac" => $hmac2,
"actionid" => $actionId,
"resourceid" => "",
"identifier" => "",
"resourcetype" => $resourceType,
"parameters" =>
[
"data" => ["Id", "objektnr_extern"], // hier können weitere Felder ausgegeben werden
"listlimit" => 50, // hier die maximale Anzahl an Immobilien eintragen, die ausgegeben werden sollen
],
];
$request = [
'token' => $token,
'request' => ['actions' => [$actionParameterData]],
];
$curlVersionInfo = curl_version();
$curlVersionNumber = $curlVersionInfo['version_number'];
$curlResource = curl_init($apiUri);
curl_setopt($curlResource, CURLOPT_POST, true);
if (version_compare(PHP_VERSION, '5.5.0', '>=') &&
$curlVersionNumber >= 0x072106) {
// empty string = all supported compressions
curl_setopt($curlResource, CURLOPT_ACCEPT_ENCODING, '');
} elseif (version_compare(PHP_VERSION, '5.5.0', '>=') &&
$curlVersionNumber >= 0x071506) // 7.15.06
{
curl_setopt($curlResource, CURLOPT_ENCODING, '');
}
curl_setopt($curlResource, CURLOPT_POSTFIELDS, json_encode($request));
curl_setopt($curlResource, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($curlResource);
API test tools:
We have two separate PHP tools that can be used to easily test our API and take the first steps.
These can be downloaded from Github as a command line tool or with a graphical interface.
We also have an API client for testing purposes that was programmed in Vue.js. The tool is also available here online.
General hints:
Please be sure not to share your generated secret used for the requests of the API user. If this happens accidentally be sure to generate a new secret immediately and adapt your code accordingly. See the section Generate access token about how to generate a new secret.
If you get a successful response of type 200 but cannot read out any records, then probably the read rights for the API user are not sufficient or there are no matching records for your request in your onOffice version.
The user rights can be set in onOffice enterprise under “Extras >> Settings >> User >> Tab API user >> Select API user >> Tab rights”.
Rights set to “only own” are usually not enough for the API user.
Another tip: In this example request, remove all parameters except for “data”, then you will receive all real estate records from onOffice.