General Information

The Magicline Device API allows Third Party applications to access our data in a common and standardized manner. You can use this API to get access to devices in Magicline. We use OpenAPI 3.0. specifications for all our endpoints.

Authentication

The Magicline Device API uses persistent token authentication, separate for every device in Magicline. Tokens are generated automatically when a studio owner creates a device in Magicline. To receive the token you will have to

• Get started with Open-API
  • This is necessary in further steps
• Register webhooks
  • Subscribe to websocket event type DEVICE_CREATED which will be executed every time a new device is created in the Magicline
  • Map the Magicline deviceId from the webhook to your corresponding, concrete device. Most likely in cooperation with the studio owner
• Call activate to activate device and receive the token
• If you want to check the state of devices you can call getDevices to get all devices

API requests

All API requests must be made over HTTPS. The https://<tenant_name>.devices.magicline.com/ URL is the request base URL. The complete URL varies depending on the accessed resource.

For example, to identify use on a device, you must make an HTTP POST request to the https://<tenant_name>.devices.magicline.com/open-api/device/cardreader/identification URL.

The <tenant_name> information is already mentioned here.

Access

In Magicline, each device requires configuration, which must be set up by studio operator. There are multiple ways they can configure their devices, and this configuration has an impact on the identification results. The identification process consists of two parts: checks and actions. If there are no issues during the check part, the actions are executed.

Checks

Checks are always executed when you call the identification endpoint. This is the section where we check whether the customer is allowed to access the studio, parking lot, rooms or use equipment. Multiple different checks are performed here and if the customer is not allowed, you will receive an error with the description.

Actions

Actions are executed only when the shouldExecuteAction variable is set to true upon calling the identification endpoint. This is the section where the actual action is performed, for example the member is checked-in, the number of open slots on the parking lot is updated, contingents for access to rooms or equipments is booked, etc.

Vending

In Magicline, each device requires configuration, which must be set up by studio operator. There are multiple ways they can configure their devices, and this configuration has an impact on the vending process. The vending process consists of two parts: checks and actions. If there are no issues during the check part, the actions are executed.

Checks

This is the section where we check whether the customer is allowed to use vending devices in studio. Multiple different checks are performed here and if the customer is not allowed, you will receive an error with the description.

Checks are executed in two steps identification and sale.

Identification

This is the endpoint where we check whether the customer is allowed to use the vending device. Multiple different checks are performed here and if the customer is not allowed, you will receive an error with the description.

Sale

This is the endpoint where we check whether the customer is allowed to buy a specific product if dry-run (shouldExecuteAction is false) is active. Multiple different checks are performed like payment option, product price.

Actions

Actions are executed only when the shouldExecuteAction variable is set to true upon calling the sale endpoint. This is the section where the actual action takes place. For instance, if a milkshake is sold, the customer is subsequently charged.

Timeouts

There are two timeouts in place for vending process which should take care of stopping the transaction if customer does not finish the sale. Both timeouts can be configured in Magicline for every device.

Idle timeout

This timeout commences following identification. For example, a user initiates vending by identifying themselves on the reader and should subsequently proceed with product selection. However, should they walk away without completing the process, the transaction will automatically be canceled after 15(configurable value) seconds. Following this period, the user can then use another device.

Product draw timeout

This timeout begins once the sale endpoint is reached, with the shouldExecuteAction variable set to false. For example, a user initiates vending by identifying themselves on the reader, following which they select a product and confirm their selection. If the time between calling sale endpoint with the shouldExecuteAction variable set to falseand sale endpoint with the shouldExecuteAction variable set to true takes longer than the configured product draw timeout, the user is able to use another device. Once the sale is completed by calling the sale endpoint with shouldExecuteAction set to true, the transaction concludes, enabling the user to use a different device.

Database transaction timeout

A database transaction timeout occurs if there is a long-running database task. In that case, the task will be cancelled, and the request returns an HTTP code 503 (Service Unavailable). If such an event happens, it is safe to retry later. This could arise due to the database processing an excessive amount of data at the moment. An example of this involves tasks that adjust a customer's financial status. If these are in progress, it's often not possible to initiate a new transaction. Therefore, you may sometimes have to wait a few minutes. To avoid waiting and blocking the system with the request, we cancel it, and you can retry later.

Headers

Header Accept-Language

The Accept-Language header can be used to define the language that will be used for any (error-) messages in the responses. Currently these languages are supported by the Magicline:

• cs (Czech)
• de (German)
• en (English)
• es (Spanish)
• fr (French)
• hu (Hungarian)
• it (Italian)
• nb (Norwegian)
• nl (Dutch)
• pl (Polish)
• ro (Romanian)
• ru (Russian)
• sl (Slovenian)
• sv (Swedish)
• tr (Turkish)

Any other language not listed above, that are provided by the client using this header, will fall back to en (English). If this header is not provided it all by the client, the language of the studio configured in the Magicline will be used. For some of the languages mentioned above the Magicline has country specific variants:

• de-CH (Switzerland)
• de-LI (Liechtenstein)
• en-CA (Canada)
• en-GB (United Kingdom)
• en-US (USA)
• fr-LU (Luxembourg)

Any other country specific variants not listed above, that are provided by the client using this header, will fall back to the language. For example de-LU will result in de (German).