First Steps

SDK:

To use the onOfficeAPI, you can use the onOffice SDK (Software Development Kit). 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.

As a template for your API requests the PHP file “example.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 in the example example.php for reading estate data.

<?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.
That means if you use our SDK, the JSON API requests must be rewritten to PHP.

{
    "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.

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.