Introduction

The application provides several operations via a Soap Web Service 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 Soap API to trigger all parcel related use cases (among others creating and tracking 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:

Where the SOAP endpoint is available
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. You can retrieve the WSDL of the corresponding service by adding '?wsdl' to the URL.

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/ShipmentProcessingService/ShipmentProcessingPortType?wsdl

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.

Authentication

Every Soap 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 Soap 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 'soapuser' and the password 'secret' the header is built as follows: 'Basic ' + Base64('soapuser:secret') which results in 'Basic c29hcHVzZXI6c2VjcmV0'.

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

If you want to ensure a specific encoding you can optionally set following headers in the request:

"Accept-Encoding", "gzip,deflate"
"Content-Type", "text/xml;charset=UTF-8"

UTF-8 may be exchanged to ISO-8859-1 depending on your requirements.

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.

Security

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.

Available service interfaces

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

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