Maxxton help centre

Introduction

API refers to Application Programming Interface that can be used to fetch or create data in the Maxxton system.
Setting up a new REST API connection involves integrating different software systems to communicate seamlessly, enabling data exchange and functionality across applications.

This process typically includes identifying the API endpoints, obtaining authentication credentials, configuring access permissions, and testing connectivity to ensure smooth interaction between systems.

Prerequisites

To connect to the REST API, a new API user must be created in the Integration Manager. For users to modify permissions or access within the Integration Manager module, they must have GDPR Access Level 3.

To create or manage any API user within the Integration Manager, users must have full access to Integration Manager - API users. This access is granted through the Back office manager module.

When creating an API user with linked Distribution Channel (DC) and Reservation Category (RC), the required DC and RC should exist in MXTS.

Initial set up

Access

Navigate to the Integration Manager from Maxxton Software Home.

Select API Users from the left-side panel.

You will be directed to the screen where all API users are managed.

Setup

To create a new REST API user in Maxxton Software, follow these steps:

Once you are on the API users screen , click on the Add Integration button located in the top right corner of the page.

Select Rest API from the list of integration types and click Add integration.

In the next step, you will see a list of products. Choose the type of product that you are going to connect to the Maxxton API.

Product Types

Website/Booking engine : Display or book accommodations for a specific distribution channel on your website.

Touroperator: Connect a partner or sales channel to book your accommodations.

Mobile app : Display information of existing reservations to a guest.

CRM: Connect a CRM system to get insight in customer related data.

Revenue management system: Connect a Revenue management system to optimize your yield.

Access control : Connect doorlocks, barriers, tourniquets and other access control hardware.

Data warehouse: Connect a business intelligence (BI) system.

Other: Setup a custom product on the basis of your own settings.

Once the product is selected, please fill in all the required details.

There are two types of flow to create a new rest API user, express flow and advanced flow.

Express Flow

In the Express flow, the system automatically applies pre-defined configurations based on the selected product type from the previous step, and the API user is created by clicking the Create API user button.

Advanced Flow

In the Advanced flow, you will go through a series of steps to configure everything. Default values based on the selected product type are pre-filled but can be customized as needed. Configuration options include Admin organization, Distribution channel, Reservation category, Release status, and permissions for third-party APIs.

In the subsequent steps, you will proceed through a series of configurations for all necessary settings:

Admin Organizations

Select the admin organization(s) to grant access to the new API user, then click Next step.

You can choose to grant access to all admin organizations or select specific ones.

Distribution Channel

Leave it empty by selecting Define distribution channel in API call to access information from all distribution channels.

Specify a distribution channel for the API key by selecting Use a predefined distribution channel.

Choosing a predefined distribution channel ensures that API operations are limited to data associated with that specific channel. For instance, retrieving reservations will only return those created by the selected distribution channel. Similarly, when creating reservations, only the selected distribution channel can be utilized. This approach is recommended for effective management and clarity in API usage.

Reservation Category

Leave it empty by selecting Define reservation category in API call to control access when creating reservations.

Specify a reservation category for the API key by selecting Use a predefined reservation category.

Selecting a predefined reservation category restricts reservation creation to that specific category. Conversely, leaving it empty allows specifying the reservation category dynamically in the create reservation request, granting access to all the reservation categories linked for selected Distribution Channel.

Release Status

Select which release statuses should be accessible with the specific API key. Lower statuses will return more data.

Permissions

In the next step, specify the permissions for the API key to determine access levels for API endpoints. This allows you to control the scope of data accessible by the API key.

Each permission offers four options:

GET: Used to fetch data from the API.

PUT: Allows updating existing data.

POST: Enables creating new data (example, new reservations).

DELETE: Provides the ability to delete existing information.

You can grant access to all endpoints simultaneously by clicking the icons at the top.

Clicking the Create API user button will generate a new REST API user with all the configurations (such as Admin organization, Distribution channel, Reservation category, release status, and permissions) selected during the creation process.

Once the API user is created, you will receive the Client ID, API key, concern code, and an example authentication call. These credentials can be used to authenticate and access the API.

Managing Third Party API

Updating API User

We can modify/update API users in the following ways:

Link Distribution Channels (DC) and Reservation Categories (RC) to the API user based on requirements. Update existing configurations if DC and RC are already assigned.

Add or remove Admin Organizations and Locations associated with an API user according to specific needs.

Edit or rename API users and their credentials. Modify or delete existing credentials, and add new ones as necessary.

Create multiple API access keys with varying permissions, DCs, and RCs as needed.

Grant credential permissions during or after API user creation. Modify permissions at any time.

Update GDPR levels for API users as required.

Using API Integration

Once the API user is configured, you can authenticate them through Swagger using the following link:
https://api.maxxton.net/maxxton/v1/swagger/index.html#/

Client ID: The unique identifier for accessing the API. You can find this in the Maxxton software Back Office Manager module where API users are configured.

Client Secret: The secret associated with the client ID for accessing the API. You can find this in the Maxxton software back office where API users are configured.

Scopes: The scope is the concern code for the respective clients.

Archiving API User

API users can be archived by updating the Active Till Date from the Integration Manager. Please follow the steps below :

Navigate to Integration Manager.

Go to API Users.

Find and open the desired API user profile.

Click on the three dots or ellipsis icon located on the right-hand side.

Select Edit Profile.

In the settings, locate the Active Till Date field.

Update the date to archive the API user.

Verify your expected outcome

You can verify the creation of an API user using Swagger. Swagger documentation not only lists available endpoints and their descriptions but also enables the execution of API calls. It details the necessary data for request bodies and specifies the format of the response bodies.

Click on Authorize, then fill in the Client_id, Client_secret, and scope, and click Authorize.

Once successfully authorized, a pop-up window will appear with two options: Logout and Close. Click on Close.

Choose any endpoint, click Try it out, input the parameters or request body, and then click Execute.

Please refer to the below data for errors after Executing the Calls:

HTTP Status Code	HTTP Response
200	OK : Successful request.
400	Bad Request : Invalid argument (invalid request payload).
403	Forbidden : Permission denied (e.g. invalid API key).
500	Internal Server Error : Internal server error (retry your request).

Following error codes are available in response of Maxxton APIs, refer to the link : Error Codes

Dependencies & impacts

Dependencies

No additional dependencies.

Impacts

Users need GDPR Access Level 3 to modify permissions and full access to Integration Manager - API users, granted via the Back office manager module. Additionally, the access reach of each API user depends on the permissions enabled for their credentials.

Conclusion

Managing REST API integrations in Maxxton Software involves setting up API users, configuring permissions, and utilizing Swagger for API interaction. By following these steps, users can seamlessly integrate and manage data across various applications.