Accessing the Soap service
The endpoints for the centrally hosted services 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 the 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/TrackingService/TrackingPortType?wsdl
This service is about tracking parcels (retrieving information about the current status as well as retrieving a proof of delivery). The parcels searched for must have been created on the backend you are searching on.
If the user is authenticated successfully the actual backend state is requested from datahub. If the backend is active in datahub, the backend state in backend database is set to active and the request is executed, else the backend state in backend database is set to inactive and a response with HTTP status 490 is returned.
Available web service operations
Any of the below endpoints will refer to one of these status types:
- DATA_RECEIVED (Parcel data was sent to GLS.)
- PICKUP (Parcel was initially scanned by GLS and is starting into GLS network.)
- HUB (Parcel arrived at central GLS hub and will be sorted to the final destination.)
- IN_DELIVERY (Parcel is out with the driver to the recipient.)
- DELIVERED (Parcel was delivered at final destination.)
- CANCELLED (Parcel data got cancelled. Parcel will not be handled by GLS. Not possible anymore once the parcel was initially scanned.)
findParcels
These operations search for parcels. Several parameters can be passed to the service. The search returns all parcels that match the search criteria (and to which the user issuing the request has access to). Partial matches or wildcard matches are not supported. The DateFrom and DateTo each include the shipment day. That means searching DateFrom to '2016-02-07' and DateTo to '2016-02-07' finds all parcels created during that day. Also the shipment unit will be searched by its identifiers: TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference.
Please consider: Only parcels that went through Use case description: getEndOfDayReport are being found by the tracking service.
Input validation
-
The TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference must identify a shipment unit. When more than one identifier is provided a logical AND between identifiers is considered, i.e., only a parcel matching all (non empty) identifiers is returned. If none or more than one unit is found, a fault is returned.
| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
| Parcel identifier (alphanumeric) | TrackID | 40 | alphanumeric | | Optional | - | | Main identifier of a parcel within GLS. |
| Parcel identifier (numeric) | ParcelNumber | - | numeric | | Optional | - | | Either use 11 or 12 digit parcel no given at parcel creation. |
| Shipment reference number | ShipmentReference | 40 | alphanumeric | | Optional | - | | Reference for this consignment of parcels. |
| Parcel reference | ShipmentUnitReference | 40 | alphanumeric | | Optional | - | | Reference given to a single parcel. |
| Partner's parcel number | PartnerParcelNumber | 50 | alphanumeric | | Optional | - | | Option for logistic partners to hand over their own reference. |
| Shipping Date (Start) | DateFrom | 10 | alphanumeric | YYYY-MM-DD | Mandatory | - | | Start of timeframe the parcels shall be searched up. |
| Shipping Date (End) | DateTo | 10 | alphanumeric | YYYY-MM-DD | Mandatory | - | | Start of timeframe the parcels shall be searched up. |
The soap response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.TUListResponse or one of the following soap faults:
To retrieve all parcels created between 7th and 8th February, you could issue a request as follows:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:trac="http://fpcs.gls-group.eu/v1/Tracking">
<soapenv:Header/>
<soapenv:Body>
<trac:TULReferenceData>
<trac:DateFrom>2016-02-07</trac:DateFrom>
<trac:DateTo>2016-02-08</trac:DateTo>
</trac:TULReferenceData>
</soapenv:Body>
</soapenv:Envelope>
If the request was successful:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<TUListResponse xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common">
<UnitItems>
<TrackID>P3L11002</TrackID>
<ShipmentReference>567f2fb4-dd61-4aeb-9515-82f71b12c434</ShipmentReference>
<ShipmentUnitReference>0d5145f1-7ec5-4894-ae73-c590201c6c5d</ShipmentUnitReference>
<ParcelNumber>P3L11004PN0001</ParcelNumber>
<PartnerParcelNumber>P3L11004PPN0001</PartnerParcelNumber>
<InitialDate>2016-02-07T13:17:15+01:00</InitialDate>
<Status>DELIVERED</Status>
</UnitItems>
</TUListResponse>
</soap:Body>
</soap:Envelope>
If the request was successful (but no result was found):
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<TUListResponse xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common"/>
</soap:Body>
</soap:Envelope>
If a mandatory parameter is not provided:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Unmarshalling Error: cvc-complex-type.2.4.b: The content of element 'trac:TULReferenceData' is not complete. One of '{"http://fpcs.gls-group.eu/v1/Tracking":TrackID, "http://fpcs.gls-group.eu/v1/Tracking":ShipmentReference, "http://fpcs.gls-group.eu/v1/Tracking":ShipmentUnitReference, "http://fpcs.gls-group.eu/v1/Tracking":ParcelNumber, "http://fpcs.gls-group.eu/v1/Tracking":PartnerParcelNumber, "http://fpcs.gls-group.eu/v1/Tracking":DateFrom}' is expected.</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
If DateFrom is after DateTo:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>DateTo must be after DateFrom</faultstring>
<detail>
<ns2:InvalidFieldValueFault xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common">
<ns2:field>
<ns2:name>DateTo</ns2:name>
<ns2:value>2015-02-01</ns2:value>
</ns2:field>
</ns2:InvalidFieldValueFault>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
getParcelDetailsByID
Retrieves the detailed Track&Trace information (including the transport history) for a specific shipment unit identified by: TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference. If the parcel has been delivered, the delivery date and the signature will be set.
Input validation
-
The TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference must identify a shipment unit. When more than one identifier is provided a logical AND between identifiers is considered, i.e., only a parcel matching all (non empty) identifiers is returned. If none or more than one unit is found, a fault is returned.
| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
| Parcel identifier (alphanumeric) | TrackID | 40 | alphanumeric | | Conditional | - | | Main identifier of a parcel within GLS. |
| Parcel identifier (numeric) | ParcelNumber | - | numeric | | Conditional | - | | Either use 11 or 12 digit parcel no given at parcel creation. |
| Shipment reference number | ShipmentReference | 40 | alphanumeric | | Conditional | - | | Reference for this consignment of parcels. |
| Parcel reference | ShipmentUnitReference | 40 | alphanumeric | | Conditional | - | | Reference given to a single parcel. |
| Partner's parcel number | PartnerParcelNumber | 50 | alphanumeric | | Conditional | - | | Option for logistic partners to hand over their own reference. |
The soap response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.ParcelDetailResponse or one of the following soap faults:
Sample request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:trac="http://fpcs.gls-group.eu/v1/Tracking">
<soapenv:Header/>
<soapenv:Body>
<trac:DetailsReferenceData>
<trac:TrackID>YZ8YO11K</trac:TrackID>
<ShipmentReference>567f2fb4-dd61-4aeb-9515-82f71b12c434</ShipmentReference>
<ShipmentUnitReference>0d5145f1-7ec5-4894-ae73-c590201c6c5d</ShipmentUnitReference>
<ParcelNumber>P3L11004PN0001</ParcelNumber>
<PartnerParcelNumber>P3L11004PPN0001</PartnerParcelNumber>
</trac:DetailsReferenceData>
</soapenv:Body>
</soapenv:Envelope>
Sample response
If the request was successful:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<ParcelDetailResponse xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common">
<UnitDetail>
<TrackID>YZ8YO11K</TrackID>
<Weight>23.2</Weight>
<Product>Parcel</Product>
<Consignee>
<ns2:Address>
<ns2:Name1>Max</ns2:Name1>
<ns2:CountryCode>DE</ns2:CountryCode>
<ns2:ZIPCode>38106</ns2:ZIPCode>
<ns2:City>Braunschweig</ns2:City>
<ns2:Street>Ringstrasse</ns2:Street>
</ns2:Address>
</Consignee>
<Shipper>
<ns2:ContactID>2761234567</ns2:ContactID>
<ns2:AlternativeShipperAddress>
<ns2:Name1>Public WS/RS Doc Shipper</ns2:Name1>
<ns2:Name2>Docu</ns2:Name2>
<ns2:Name3>Mentation</ns2:Name3>
<ns2:CountryCode>DE</ns2:CountryCode>
<ns2:ZIPCode>65760</ns2:ZIPCode>
<ns2:City>Eschborn</ns2:City>
<ns2:Street>Mergenthalerallee</ns2:Street>
<ns2:StreetNumber>77</ns2:StreetNumber>
<ns2:eMail>fpcs.docu@syrocon.de</ns2:eMail>
<ns2:FixedLinePhonenumber>0172321321</ns2:FixedLinePhonenumber>
<ns2:MobilePhoneNumber>0172123123</ns2:MobilePhoneNumber>
</ns2:AlternativeShipperAddress>
</Shipper>
</UnitDetail>
</ParcelDetailResponse>
</soap:Body>
</soap:Envelope>
If the parcel does not exist / is not accessible:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>No shipment unit found for parcel identifier(s) YZ8YNSJP</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
getParcelPODByID
Retrieves the proof of delivery document for a parcel. The parcel is identified by its trackID, parcelNumber, partnerParcelNumber, shipmentReference or shipmentUnitReference.
Input validation
-
The TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference must identify a shipment unit. When more than one identifier is provided a logical AND between identifiers is considered, i.e., only a parcel matching all (non empty) identifiers is returned. If none or more than one unit is found, a fault is returned.
| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
| Parcel identifier (alphanumeric) | TrackID | 40 | alphanumeric | | Conditional | - | | Main identifier of a parcel within GLS. |
| Parcel identifier (numeric) | ParcelNumber | - | numeric | | Conditional | - | | Either use 11 or 12 digit parcel no given at parcel creation. |
| Shipment reference number | ShipmentReference | 40 | alphanumeric | | Conditional | - | | Reference for this consignment of parcels. |
| Parcel reference | ShipmentUnitReference | 40 | alphanumeric | | Conditional | - | | Reference given to a single parcel. |
| Partner's parcel number | PartnerParcelNumber | 50 | alphanumeric | | Conditional | - | | Option for logistic partners to hand over their own reference. |
The soap response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.PODResponse or one of the following soap faults:
Sample request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:trac="http://fpcs.gls-group.eu/v1/Tracking">
<soapenv:Header/>
<soapenv:Body>
<trac:TUPReferenceData>
<trac:TrackID>P3L11002</trac:TrackID>
<trac:ShipmentReference>567f2fb4-dd61-4aeb-9515-82f71b12c434</trac:ShipmentReference>
<trac:ShipmentUnitReference>0d5145f1-7ec5-4894-ae73-c590201c6c5d</trac:ShipmentUnitReference>
<trac:ParcelNumber>P3L11004PN0001</trac:ParcelNumber>
<trac:PartnerParcelNumber>P3L11004PPN0001</trac:PartnerParcelNumber>
</trac:TUPReferenceData>
</soapenv:Body>
</soapenv:Envelope>
Sample response
If the request was successful (ImageData is shortened. Here a Base64 encoded byte[] will be returned):
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<PODResponse xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common">
<PODItem>
<TrackID>P3L11002</TrackID>
<ImageData>JVBERi0xLjQKJfbk/N8...kKJSVFT0YK</ImageData>
</PODItem>
</PODResponse>
</soap:Body>
</soap:Envelope>
If no signature is available / the parcel is in the wrong state:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>POD cannot be generated, the parcel is in the wrong state.</faultstring>
</soap:Fault>
<detail>
<InvalidShipmentIDFault xmlns="http://fpcs.gls-group.eu/v1/Tracking" xmlns:ns2="http://fpcs.gls-group.eu/v1/Common">
<ShipmentID>ShipmentUnit.TrackTraceStatus</ShipmentID>
</InvalidShipmentIDFault>
</detail>
</soap:Body>
</soap:Envelope>
