GLS ShipIT 5.1.4 GLS ShipIT - REST services

GLS ShipIT Documentation

# Introduction

The application provides several operations via a REST API. These are built to integrate 3rd party applications. That is, if you want to integrate your ERP system with GLS ShipIT, you can use the REST API to trigger all parcel related use cases (among others creating and tuitracking parcels, searching parcelshops near a consignees location or retrieving proof of delivery documents).

Important: This documentation reflects all technical possibilities of creating webservice requests for all parcel related issues. Services and conditions may vary between countries and relations. If you have any questions in this regard please contact your local sales team or your main GLS contact.

## Available options for connecting to GLS ShipIT

There are two options available on how to connect your ERP system with GLS ShipIT: You can either host a version of GLS ShipIT on your premises or you can directly connect to GLS ShipIT hosted at the GLS data centers.

Depending on which version of connection you intend to establish, there are two areas throughout this manual where you have have to adapt the samples given:

1. Where the REST endpoint is available
2. How you retrieve the user for authentication

The manual assumes you are connecting to the centrally hosted GLS ShipIT. The endpoints can be obtained from your primary GLS contact and will be given with your credentials for the Service.

If you are connecting to a locally installed GLS ShipIT, you have to adapt this URL to point to the host (and port) in your network where the GLS ShipIT backend is running. E.g. https://10.10.10.10:8443/backend/rs/shipments

As for retrieving the user for authentication:

If you connect to the centrally hosted GLS ShipIT, the user you are using for authentication will be provided by GLS Field IT to you. If you have your own version of GLS ShipIT running, you have to create this user yourself using the client application that is shipped with your GLS ShipIT installation. For details on how to create an user in GLS ShipIT, please refer to the user manual of GLS ShipIT in section user administration.

## Maintenance

Maintenance window for backend update is saturdays between 10 and 12 pm CET. Backends may not be available during this time.

## Authentication

Every REST Request must carry authentication information. With this the system can identify the user issuing the request and limit the requests to the scope that is allowed for this user. The method for authentication is HTTP Basic authentication on webbackends. For ShipIT Farm it is OAuth2.0 - please generate an app in Developer Portal. Every REST Request therefore must contain a header parameter 'Authorization'. The value of the header follows the Basic authentication scheme. That is the fixed value 'Basic ' plus the Base64 representation of the user's login name and password separated by a ':'. Assuming a user with the login name 'restuser' and the password 'secret' the header is built as follows: 'Basic ' + Base64('restuser:secret') which results in 'Basic cmVzdHVzZXI6c2VjcmV0'.

If you want GLS ShipIT to track which user is providing / changing address and shipment data (e.g. to fulfil EU Data Protection Directive) , you can provide the name of the user issuing the requests in HTTP header field 'Requester'. If any data is inserted or updated that is protected by the Data Protection Directive then the creation or update of this data is logged with the timestamp of the request and the content of this http header.

## Additional Headers - Supported Mediatypes

The following headers need to be added for a successful call:

"Accept", "application/glsVersion1+json, application/json"
"Content-Type", "application/glsVersion1+json"

## Certificate handling

Most certificates are handled centrally by AWS with no influence from GLS side.
Anyhow, if you are connected to a webbackend with a URL starting "https://shipit-wbm-..." certificates are changed regularly by GLS. You can find the certificates here: https://shipit-download.gls-group.eu/documentation/. Be prepared that the certificate can change without further notice for security reasons.

# Network requirements

## Connection

For connecting ShipIT webservices please use the URL given by your GLS contact. These will always guide you to the right place. A setup using IP has a potential risk to be changed without further notice. Changes on URLs will be communicated at any time if they need to happen.

## Version

To see which version your assigned backend is running in, enter the backend URL to a browser: {BackendURL}/backend/backendinfo/name .

## Security

Providing a better security level, we are using TLS in version 1.2.

# Available service interfaces

The available REST services are split into the following four areas:

- Processing shipments
- ParcelShop search
- Track your parcels
- Schedule sporadic date

Each web service section will give a detailed explanation of the available operations.