|
GLS ShipIT
GLS ShipIT - REST services
|
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.
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:
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.
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. 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.
The following headers need to be added for a successful call:
"Accept", "application/glsVersion1+json, application/json"
"Content-Type", "application/glsVersion1+json"
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.
Providing a better security level, we are using TLS in version 1.2. After updating from an older ShipIT version to 2.8 (and higher) please update this manually.
The available REST services are split into the following four areas:
Each web service section will give a detailed explanation of the available operations.
1.9.5