GPTE API TECHNICAL DOCUMENTATION

This document presents description of GP Travel Enterprise API and includes both implementation guide and reference materials. For all enquiries regarding this API please contact GP Support Team.

See detailed descriptions of methods here: https://admin.softwaretravel.net/gptp//stat/swagger/index.html

Access to back-office:

https://admin.softwaretravel.net/
company alias: common
login: demo1 (demo2, demo3, demo4)
password: demo

API-Keys for demo installation of Swagger:

B2C through API: Hfzi07ynN1uwWRBV2uU8x7fIoDn0IktQI0Xk1ExmkNk=
B2B (tour operator of 1st level): b4VA4l6zuYM0lqNs4zSySIUbPDgowX
B2B (tour agency): tZE2IwvX0bMW0UPtke9tM590tgwb3P

GP Travel Enterprise API is a collection of software modules that enable interaction with GP Travel Enterprise via API from any external sources.

This is designed to solve several needs:

• To create custom WEB sites (widgets) for online sales without using standard templates offered by the system. This will allow to create a unique design and layout, and thus get exactly the site that you want.

• To create mobile applications for Iphone, Android, Windows Mobile, etc.

• To exchange information between GP Travel Enterprise and accounting and/or CRM systems.

• To connect from any external software (e.g. Back Office system or ERP system) to functionality of GP Travel Enterprise.

In the current documentation you will learn about capabilities of API and get detailed reference to all its parameters.

Access

From the technical perspective GP Travel Enterprise API is a simple REST service exposed via JSON-interface, that allows maximizing performance and usability of API for various platforms.

Here is the example of the simpliest API request:

GET /companies HTTP/1.1
Content-Type: application/json
Host: admin.software.travel/gptour/api

Header

The header of each request should contain the following parameters.

Methods

To compose a request you have to use HTTPS POST, GET or PUT methods for corresponding actions as presented in the following table.

URL

The general form of the URL for all interfaces is a follows: <application>/api/<method>?<parameters> (some methods can use nesting, e.g. <application>/api/<method>/<submethod>?<parameters> or <application>/api/<method>/<id>?<parameters>, so pay attention to documentation)

demo.software.travel/gptour/api/companies?type=TOUR_OPERATOR

Security

It is important to keep information secure. For this purpose all interaction with external applications should:

• be performed via SSL channel (HTTPS)

• contain specific API-Key for identification of organization or sales channel

• contain token for authorization of user

How to obtain API-KEY (for B2C)

1. Ensure that you have API module switched on (contact your account manager for that).

2. Log into GP Travel Enterprise back-office system.

3. Go to menu My Company -> B2C Settings -> open the required B2C - > General Settings -> Generated Client API key:

How to obtain API-KEY (for B2B)

1. Ensure that you have API module switched on (contact your account manager for that).

2. Log into GP Travel Enterprise back-office system.

3. Go to menu My Company -> Settings -> API

How to obtain token

1. Сall Authorization, where provide your api-key, login and password.

   Take token from response.

Basic Concepts

Bi-directional interaction

GP Travel Enterprise API supports bi-directional interaction with 3rd party applications in order to solve two kinds of business needs:

• provide some information or functionality upon request (e.g. "provide list of available hotels")

• push some information to external application when something happens (e.g. "inform about new orders immediately upon creation").

Note that for the second scenario it is required to implement identical web service in your external appication and specify URL of your web-service within integration settings in back-office.

Throughout the document for each method it is specified in what mode this method can operate as per table below.

For some methods both ways are applicable.

Origin and destination of information

Along with bi-directional communication GP Travel Enterprise API can also support several approaches to origin and destination of information:

• GP Travel Enterprise as an origin of information (new information is initially created in GP Travel Enterprise and then transferred to external application)

• GP Travel Enterprise as a destination of information (new information is initially created in 3rd party application and then transferred to GP Travel Enterprise)

• External Application as a stateless plug-in to GP Travel Enterprise

• Mixed model

As an example of this concept let's have a look how information about Companies can be stored and exchanged between GP Travel Enterprise and External Application.

Model 1. GP Travel Enterprise as an origin

According to this model GP Travel Enterprise is considered to be an origin of information about Companies. All new companies are initially created there. At the same time external application has own database where this information should be reflected. So upon creation/update of each Company this information should be immeditately transferred to external application.

Model 2. GP Travel Enterprise as a destination

According to this model GP Travel Enterprise is considered as a desination of information about Companies. All new companies are initially created in External Application. At the same time GP Travel Enterprise has own database where this information should be reflected. So upon creation/update of each Company this information should be immeditately transferred to GP Travel Enterprise.

Model 3. External Application as stateless plug-in to GP Travel Enterprise

According to this model it is assumed that External Application does not have own database to store companies (e.g. this can be Web Site for data visualization). In this case all information will be stored in GP Travel Enterprise. And External Application can only request it to get lists of companies, register new company or update profile.

Model 4. Mixed Model

Also the mixed model is possible - e.g. when Companies can be created both in GP Travel Enterprise and External Application. In this case synchronization should be done in both ways - when the new information appear in GP Travel Enterprise it should be transferred to External Application, and vice versa.

Getting, creating or updating information

Using the current API you might need to perform different operations with the same objects - get list of them, view detailed information, create, update or deactivate.

Current API supports all these operations using the same method (e.g. "companies"). The difference is just how you request it. Note the following guidelines for this.

Export of information via API

As was mentioned below some information can be pushed from GP to external application when something happens. For this you need to make some settings in B2B

To configure API settings for export:

1. Ensure that you have API module switched on (contact your account manager for that).

2. Log into GP Travel Enterprise back-office system.

3. Go to menu My Company -> Settings -> API.

4. Check option "Export data to external applications" for setting of export API.

5. Set name and URL for your external application.

6. Configure settings.

NB: It is important that your application as receiver of exported information should be enable to get all the data in used format!

Available API settings for export

Export of objects according to chosen methods to external application is available on any actions (creation/updating) via API or interface of B2B. There are 2 variants of using export via API:

• always to export created/updated objects to external applications

• to export objects only when they are created/updated in B2B (in release 6.7 only for companies, persons and custom fields).

Localization

GP Travel Enterprise is designed for international usage and thus many information can be obtained in different languages.

In order to correctly request information in different languages use the following:

• Use Accept-Language HTTP header to specify needed language

• Use locale query parameter to specify needed language (e.g. locale=en or locale=ru), this parameter overrides the value from Accept-Language header

• Use locale=all query parameter value to get information in all locales - in this case descriptions in all languages will be returned at once.

Depending on whether result will be returned in one language or in several languages the format of response may be sligtly different.

• If the response is in one language this will be simple string, e.g.

"countryName":"France"

• If the response contains information in several languages, then there will be an array, e.g.

"countryName": 
   [
     {
       "en": "France",
       "ru": "Франция"
     }
   ]

Processing errors

Any request contains HTTP response code that defines whether request was successful or not. In case any error occurs the system will also return the standard error code and correponding error message. Along with each error in brackets {} the set of entities and parameters can be returned to specify where exactly this error happened.

HTTP Response Codes