Accessing the REST 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 REST service operations

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 specified day. That means searching DateFrom to '2017-02-07' and DateTo to '2017-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.

The REST method is available at sub-path /parcels with http request method POST

Parameter	Mandatory	Location in Request	Description
tulReferenceData	TRUE	request body	The eu.glsgroup.fpcs.datatypes.soap.v1.tracking.TULReferenceData with the request parameters.

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	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 REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.TUListResponse or one of the following faults:

eu.gls_group.fpcs.v1.tracking.InvalidFieldValueMessage

To retrieve all parcels created between 7th and 8th February, you could issue a request as follows:

Sample request

POST https://localhost:8443/backend/rs/tracking/parcels
 
POST data:
{
    "DateFrom": "2016-02-07",
    "DateTo": "2016-02-08"
}

If the request was successful:

{
    "UnitItems": [{
            "TrackID": "P3L11002",
            "ShipmentReference": "abdeckjdefsss012",
            "ShipmentUnitReference": "RefTwo",
            "InitialDate": "2016-02-07T13:17:15+01:00",
            "Status": "DELIVERED"
        }
    ]
}

If the request was successful (but no result was found):

{}

If a mandatory parameter is not provided, a HTTP response with error code '400 Bad Request' is returned:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter TULReferenceData.DateTo is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["TULReferenceData.DateTo"]

If DateFrom is after DateTo, a HTTP response with error code '400 Bad Request' is returned:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field DateTo. Value 2017-02-17 is not a valid value. DateTo must be after DateFrom
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["DateTo","2017-02-17","DateTo must be after DateFrom"]

getParcelDetailsByID

Retrieves the detailed Track&Trace information (including the transport history) for a specific shipment unit identified by its TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference. If the parcel has been delivered, the delivery date and the signature will be set.

The REST method is available at sub-path /parceldetails with http request method POST

Parameter	Mandatory	Location in Request	Description
detailsReferenceData	TRUE	request body	The eu.glsgroup.fpcs.datatypes.soap.v1.tracking.DetailsReferenceData with the request parameters.

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	Mandatory/Optional	Restrictions	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 REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.ParcelDetailResponse or one of the following faults:

eu.gls_group.fpcs.v1.tracking.MandatoryFieldMissingMessage
eu.gls_group.fpcs.v1.tracking.InvalidFieldValueMessage
eu.gls_group.fpcs.v1.tracking.InvalidShipmentIDMessage

Sample request

POST https://localhost:8443/backend/rs/tracking/parceldetails
 
POST data:
{
"TrackID" : "YZ8YO11K",
"ShipmentReference": "567f2fb4-dd61-4aeb-9515-82f71b12c434",
"ShipmentUnitReference": "0d5145f1-7ec5-4894-ae73-c590201c6c5d",
"ParcelNumber": "P3L11004PN0001",
"PartnerParcelNumber": "P3L11004PPN0001"
}

Sample response

If the request was successful:

{
    "UnitDetail": {
        "TrackID": "YZ8YO11K",
        "Weight": "23.2",
        "Product": "PARCEL",
        "Consignee": {
            "Address": {
                "Name1": "Max",
                "CountryCode": "DE",
                "ZIPCode": "38106",
                "City": "Braunschweig",
                "Street": "Ringstrasse",
                "eMail": null
            }
        },
        "Shipper": {
            "ContactID": "2761234567",
            "AlternativeShipperAddress": {
                "Name1": "Public WS/RS Doc Shipper",
                "Name2": "Docu",
                "Name3": "Mentation",
                "CountryCode": "DE",
                "ZIPCode": "65760",
                "City": "Eschborn",
                "Street": "Mergenthalerallee",
                "StreetNumber": "77",
                "eMail": "fpcs.docu@syrocon.de",
                "FixedLinePhonenumber": "0172321321",
                "MobilePhoneNumber": "0172123123"
            }
        }
    }
}

If the parcel does not exist / is not accessible:

Response headers:
HTTP/1.1 400 Bad Request
message: No shipment unit found for parcel identifier(s) YZ8YNSJP.
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: []

getParcelPODByID

Retrieves the proof of delivery document for a parcel. The parcel is identified by its TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference.

The REST method is available at sub-path /parcelpod with http request method POST

Parameter	Mandatory	Location in Request	Description
tupReferenceData	TRUE	request body	The eu.glsgroup.fpcs.datatypes.soap.v1.tracking.TUPReferenceData with the request parameters.

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	Mandatory/Optional	Restrictions	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 rest response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.tracking.PODResponse or one of the following rest faults:

eu.gls_group.fpcs.v1.tracking.MandatoryFieldMissingMessage
eu.gls_group.fpcs.v1.tracking.InvalidFieldValueMessage
eu.gls_group.fpcs.v1.tracking.InvalidShipmentIDMessage

Sample request

POST https://localhost:8443/backend/rs/tracking/parcelpod
 
POST data:
{
"TrackID" : "P3L11002",
"ShipmentReference": "567f2fb4-dd61-4aeb-9515-82f71b12c434",
"ShipmentUnitReference": "0d5145f1-7ec5-4894-ae73-c590201c6c5d",
"ParcelNumber": "P3L11004PN0001",
"PartnerParcelNumber": "P3L11004PPN0001"
}

Sample response

If the request was successful (ImageData is shortened. Here a Base64 encoded byte[] will be returned):

{
    "PODItem": {
        "TrackID": "P3L11002",
        "ImageData": "JVBERi0xLjQKJfbk/N8...kKJSVFT0YK"
    }
}

If no signature is available / the parcel is in the wrong state:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid shipment unit number ShipmentUnit.TrackTraceStatus: POD cannot be generated, the parcel is in the wrong state.
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: ["ShipmentUnit.TrackTraceStatus","POD cannot be generated, the parcel is in the wrong state."]

Table of Contents

Accessing the REST service

Available REST service operations

findParcels

Input validation

Sample request

getParcelDetailsByID

Input validation

Sample request

Sample response

getParcelPODByID

Input validation

Sample request

Sample response