Activation process at the customer
The services of the providers are accessed via the menu item “Marketplace” in onOffice enterprise or via the action bar in the individual modules such as properties and addresses. In the menu item “Overview” all providers are listed in a popup. The menu items below list the providers and their services individually.
If the user selects a provider that is not yet activated, a popup for activation opens. The activation is only possible as an administrator.
In this short video you can see the whole activation process. Click on the image on the left to start the video.
In the first step of the activation, the user confirms your general terms and conditions (GTC) and the order processing agreement. After that, the following mask will be displayed to him:
- “To the provider” shows a description of your company and services. Under “Description of rights to be released” , the rights that the user must grant you are described. This makes the user aware of what data is being accessed.
- Under “Activate user right” , the user must deliberately set either “For all users” or “For all administrators” so that the activation can be carried out. Administrators always have access. For Marketplace providers that offer exactly ONE service via webhook, this selection is disabled and “for all users” is preselected. The API key is displayed directly in this case.
- After setting the user rights, the API key appears. This must be copied manually into the second API key field.
The activation requires the following steps:
- Confirm GTC and contract data processing
- Select user right
- Copy API key
- Insert API key into your iframe
- Take note of privacy policy
- Clicking on “Activate now” activates the provider.
Structure of the iframe URL for activation
When the activation URL is called up in the iframe, data is transferred to identify the customer:
- Client name
- WebID of the client
- UserID of the user
- parameterCacheId
- Timestamp
- Signature
Timestamp
To ensure that the iframe is called via onOffice enterprise , the following procedure is used:
- A timestamp parameter is added to each URL generated by onOffice to call a service iframe (…×tamp=1234569). The timestamp ensures that the links cannot be used as often as you like.
Signature
In addition, all calls to a URL are signed by onOffice using the following procedure:
- A signature is created over the complete URL using the hash_hmac function.
- An additional part of this signature is a secret that must be set once by you when you join the Marketplace. In your provider client you can enter and also change the secret in the menu Marketplace >> Change provider secret . The secret is valid immediately after saving. Therefore, make sure you can process it immediately. Frequent secret changes are not recommended, the secret is also used, for example, in the link for recalculations that your customers receive by e-mail. The secret must consist of at least 24 characters and contain upper and lower case letters, numbers and special characters.
- The generated hash is again appended to the URL as a parameter.
For the signature, the URL including all parameters (except parameter signature) is encrypted using hash_hmac, sha256 (see checkSignature in the code examples). The parameters are sorted alphabetically. The validity of the signature can be checked via the time stamp.
Activation at the provider
They authenticate themselves with the entered API key and the passed token . You need to call the API function to unlock the provider (ACTION_ID_DO, ‘unlockProvider’) and pass parameterCacheId parameter to it (see unlockProvider.js in the code samples). The parameterCacheId parameter contains internal information that was stored in the parameter cache.
Note that an extendedclaim parameter must be specified for each API call. Therefore, each time your service is called by the client, an “apiClaim” parameter 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 customer’s latest service call. The apiClaim during activation can only be used for the unlockProvider call.
More detailed information is available at https://www.marketplacedoc.onoffice.de/api-calls.
If successful, your offer is now unlocked. Store the API access data (API key and token) for each customer. As feedback for the user you have to report the result back to the popup via JavaScript .
In case of success “active” should be returned, in case of error an error message should be returned for the user. (see unlockProvider.js in the code examples).
The status changes from “Inactive” to “Active” if successful.
The API key is the secret of your API user at the client. The customer who wants to use your services copies the API key into their iFrame during activation, thereby transmitting it to you and giving you rights to access their onOffice software. Therefore, please save the API key and the token for each customer. Many services in the Marketplace require read or write access to certain resources in onOffice enterprise in order to function. Example floor plan optimization: Customer orders floor plan in the Marketplace for a specific property (provider must have read access to property or floor plan), provider creates floor plan, provider plays back optimized floor plan (provider must have write access to property).
The user has unlocked your offer. Your services can now be booked via the “Marketplace” menu item in onOffice enterprise. When the user calls your service, your iframe with the desired service frontend is displayed to him in the popup.
This post is also available in: German