GLS ShipIT  2.7.11
GLS ShipIT - REST services
Processing shipments

Table of Contents

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.

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/rs/shipments

All REST service operations within this port are about creating or updating shipments. A shipment is a selection of one or more parcels that are collected at address A and delivered to address B. If several parcels should be sent from address A to address B and those parcels should share the same services, they can be combined to a shipment.

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

createParcels (F-114)

This operation creates a shipment that contains one or more shipment units. The operation takes an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.ShipmentRequestData The input object is split into several sections allowing you to specify Shipper data, Consignee data, Shipment unit data, products and services, Printing options as well as some Custom content like an extra barcode or image that should be printed on the label.

The REST method is available at sub-path / with http request method POST
Parameter Mandatory Location in RequestDescription
shipmentRequest TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.ShipmentRequestData with the shipment parameters.

The parts of the request are explained in the following sections in more detail:

Shipment data

When you are creating a shipment, you can specify several attributes on the shipment level. These are:

{
"Shipment": {
"ShipmentReference": ["0363cbed-36ff-4394-b150-5fdffa44b12e"],
"ShippingDate": "2018-11-16",
"IncotermCode": "10",
"Identifier":"userTestId",
"Middleware":"Primavera",
"Product": "PARCEL",
...
}
}


Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Customer reference number ShipmentReference 40 alphanumeric Optional -
Shipping date ShippingDate 10 alphanumeric YYYY-MM-DD Optional - Date for the shipment
Incoterm IncotermCode 2 alphanumeric Optional 10, 20, 30, etc. Specify the inco term for this shipment. Represented by 2 digits
Identifier Identifier 40 alphanumeric Optional - Person in charge
Middleware Middleware 40 alphanumeric Optional - Partner ERP System
Product Group Product 7 alphanumeric Mandatory Parcel, Express or Freight Please select one
Alternative delivery activation ExpressAltDeliveryAllowed 5 boolean Optional true or false Please select one
Consignee Consignee Mandatory - see section Consignee data
Shipper Shipper Mandatory - see section Shipper data
Shipment unit ShipmentUnit Mandatory - see section Shipment unit data
Services Services Optional - see section Services

Consignee data

The consignee is the person to which the shipment shall be sent. The consignee ID will be printed on the label if specified. The consignee address has to be specified within the request.

In case of shipments with return services (pick&return, pick&ship, shopreturn) assigned, the consignee and the shipper data sections will automatically be switched on the return label. That means the consignee address, that you provide within your Webrequest will be used as pickup address on the return label. According to Pick&Ship and Pick&Return Service the following fields are mandatory: ContactPerson and FixedLinePhonenumber.

The consignee address can be specified as follows:

"Address": {
"Name1": "Max Mustermann",
"Name2": "Travel and Co",
"CountryCode": "DE",
"ZIPCode": "38106",
"City": "Braunschweig",
"Street": "Falkenbergstrasse",
"StreetNumber": "47",
"eMail": "max.mustermann@email.test",
"FixedLinePhonenumber": "004953112345",
"MobilePhoneNumber": "00491791234567"
}

To provide an example of a consignee ID that should be printed on the label:

"Consignee": {
"ConsigneeID": "100",
"Address": {...}
}


Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Consignee identifier ConsigneeID 80 alphanumeric Optional -
Cost Center CostCenter 80 alphanumeric Optional - Delivery location cost center for Inbound
Consignee Address Address Mandatory - see section Address data for field details

Address data

Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Name1 Name1 40 alphanumeric Mandatory -
Name2 Name2 40 alphanumeric Optional -
Name3 Name3 40 alphanumeric Optional -
Country code CountryCode 2 alphanumeric Mandatory DE, AT, BE, FR, etc
Province Province 40 alphanumeric Optional -
ZIPCode ZIPCode 10 alphanumeric Mandatory -
City City 40 alphanumeric Mandatory -
Street Street 40 alphanumeric Mandatory > 3 Street name
Street number StreetNumber 40 alphanumeric Optional -
eMail eMail 80 alphanumeric Optional -
Contact person ContactPerson 40 alphanumeric Optional > 5 Contact person to print on the label
Fixed phonenumber FixedLinePhonenumber 40 alphanumeric Optional > 3
Mobile MobilePhoneNumber 40 alphanumeric Optional > 3

Shipper data

This section fulfills two purposes. It identifies the shipper and as such the address from where the shipment shall be collected. It also offers the possibility to use an alternative shipper address that shall be printed on the labels. As the shipper ID please provide the Contact ID that was provided to you by GLS.

In case of shipments with return services (pick&return, pick&ship, shopreturn) assigned, the shipper data section represents the delivery address on the return label. That is the shipper address, that you provide within your Webrequest and that will be taken as the address on the return label, where the parcel will be delivered to.

"Shipper": {
"ContactID": "2761234567",
"AlternativeShipperAddress": {
"Name1": "Logistics and More",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Eschborn",
"Street": "Elly-Beinhorn-Strasse",
"StreetNumber": "1a",
"eMail": "logistics@more.test",
"FixedLinePhonenumber": "004961961234567"
}
}


Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Shipper identifier ContactID 20 alphanumeric Mandatory - Shipper
Alternative Address AlternativeShipperAddress - Address Optional - see section Address data
French customer reference FRAlphaCustomerReference 10 alphanumeric Optional Field length must be exactly 10 French alpha contact reference number

Shipment unit data

Within this section of the request you specify each shipment unit of your shipment.

A shipment unit can contain the following elements:

Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Parcel reference ShipmentUnitReference 40 alphanumeric Optional -
Parcel Weight Weight - decimal Optional > 0 Each minimum weight is specified by Shipper
Parcel note1 Note1 50 alphanumeric Optional -
Parcel note2 Note2 50 alphanumeric Optional -
Parcel services Service - Optional - see section Services for detailed fields
French parcel reference FRAlphaParcelReference 18 alphanumeric Optional Field length must be exactly 18 French alpha contact parcel reference
Track identifier TrackID 40 alphanumeric Optional - Used for cancelShipment request
1D barcode number ParcelNumber - alphanumeric Optional - 1d barcode printed in the label

Services

You can define services that should apply to your shipment.

The following services can be assigned on the shipment unit level:

Those services may have different attributes for each shipment unit.

Services inside shipment unit can be combined like this:

Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Cash service Cash
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_cash" Must use this fixed value for service name
Cash reason Reason 160 alphanumeric Mandatory -
Cash amount Amount - decimal Mandatory - Cash amount (numeric value)
Cash currency Currency 3 alphanumeric EUR Mandatory - Cash currency code (ISO4217 -> 3 digits)
AddonLiability service AddonLiability
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_addonliability" Must use this fixed value for service name
Cash amount Amount - decimal Mandatory - Cash amount (numeric value)
Cash currency Currency 3 alphanumeric EUR Mandatory - Cash currency code (ISO4217 -> 3 digits)
Parcel description ParcelContent 255 alphanumeric Optional - Specify the parcel content
HazardousGoods service HazardousGoods
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_hazardousgoods" Must use this fixed value for service name
HazardousGoods HazardousGoods - Hazardous good item attributes
Hazardous goods number GLSHazNo 8 alphanumeric Mandatory - Hazardous goods type identifier)
HazardousGoods Weight Weight - decimal Optional > 0 Weight for the GLSHazNo (numeric)
ExWorks service ExWorks
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_exworks" Must use this fixed value for service name

The following services can be assigned on the shipment level:

All other services do not require specific attributes and can be assigned on the shipment level. If you e.g. want to improve your own ecological balance and counterbalance CO2 emissions which are arising during parcel delivery, you can book the ThinkGreenService as follows:

"Shipment": {
...
"Service": [{
"Service": {
"ServiceName": "service_thinkgreen"
}
}
]
}


Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Other service Service
Name of the service ServiceName - alphanumeric "ServiceName": "service_name " Must use the service name defined in DB
ShopDelivery service ShopDelivery
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_shopdelivery" Must use this fixed value for service name
Parcel shop identifier ParcelShopID 10 alphanumeric Mandatory - Specify parcel shop
ShopReturn service ShopReturn
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_shopreturn" Must use this fixed value for service name
Amount of labels NumberOfLabels numeric Mandatory > 0 Specify amount of labels to print
Intercompany service Intercompany
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_intercompany" Must use this fixed value for service name
Intercompany address Address Mandatory - see section Address data
Amount of labels NumberOfLabels numeric Mandatory > 0 Specify amount of labels to print
Expected Weight ExpectedWeight - decimal Optional > 0
Exchange service Exchange
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_exchange" Must use this fixed value for service name
Exchange address Address Mandatory - see section Address data
Expected Weight ExpectedWeight - decimal Optional > 0
DeliveryAtWork service DeliveryAtWork
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_deliveryatwork" Must use this fixed value for service name
Name of the Recipient RecipientName 40 alphanumeric Mandatory -
AlternateRecipientName AlternateRecipientName 40 alphanumeric Optional -
Building Building 40 decimal Mandatory -
Floor Floor 40 decimal Mandatory -
Room Room 40 decimal Optional -
Phonenumber Phonenumber 40 decimal Mandatory -
Deposit service Deposit
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_deposit" Must use this fixed value for service name
Place of deposit PlaceOfDeposit 255 Mandatory -
IdentPin service IdentPin
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_identpin" Must use this fixed value for service name
PIN PIN 4 alphanumeric Mandatory -
Birthdate Birthdate 10 date YYYY-MM-DD Mandatory < today
Ident service Ident
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_ident" Must use this fixed value for service name
Birthdate Birthdate 10 date YYYY-MM-DD Mandatory < today
Firstname Firstname 40 alphanumeric Mandatory -
Lastname Lastname 40 alphanumeric Mandatory -
Nationality Nationality 2 alphanumeric Mandatory CountryCode Check example above
PickAndShip service PickAndShip
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_pickandship" Must use this fixed value
PickupDate PickupDate 10 date YYYY-MM-DD Mandatory > today Date when parcel should be picked up at shipper
Send email to Shipper SendEMailToShipper 5 boolean Mandatory true or false Specify if email must be sent to shipper
Send email to Consignee SendEMailToConsignee 5 boolean Mandatory true or false Specify if email must be sent to Consignee
Send SMS to Shipper SendSMSToShipper 5 boolean Mandatory true or false Specify if Sms must be sent to shipper
PickAndReturn service PickAndReturn
Name of the service ServiceName 80 alphanumeric Mandatory "ServiceName": "service_pickandreturn" Must use this fixed value
PickupDate PickupDate 10 date YYYY-MM-DD Mandatory > today Date when parcel should be picked up at shipper
Send email to Shipper SendEMailToShipper 5 boolean Mandatory true or false Specify if email must be sent to shipper
Send email to Consignee SendEMailToConsignee 5 boolean Mandatory true or false Specify if email must be sent to Consignee
Send SMS to Shipper SendSMSToShipper 5 boolean Mandatory true or false Specify if Sms must be sent to shipper

If you want to send a shipment containing two shipment units (parcels) with ThinkGreenService and CashService, you could use something like the following:

"Shipment": {
...
"ShipmentUnit": [{
"ShipmentUnitReference": ["Ref-Unit-0815"],
"Weight": 5.00,
"Service": [{
"Cash": {
"ServiceName": "service_cash",
"Reason": "Your order 4711",
"Amount": "230.81",
"Currency": "EUR"
}
}
]
}, {
"ShipmentUnitReference": ["Ref-Unit-0816"],
"Weight": 1.00,
"Service": [{
"Cash": {
"ServiceName": "service_cash",
"Reason": "Your order 4711",
"Amount": "12.09",
"Currency": "EUR"
}
}
]
}
],
"Service": [{
"Service": {
"ServiceName": "service_thinkgreen"
}
}
]
}

Not all of these services are available in all countries and not all of those services may be combined with each other. Please check online which services are available for your region on your local GLS website.

French APN and FNCR

In france for every shipment the french shipper need a French National Customer Reference number (FNCR) and each parcel an Alpha Parcel Number (APN). For french shippers the FNCR and the starting value of the APN can be configured in the GLS ShipIT client in shipper settings. If they are not configured both have to be delivered with each REST request as follows:

"Shipment": {
...
"Shipper": {
...
"FRAlphaCustomerReference": "0123456789"
},
"ShipmentUnit": [{
...
"FRAlphaParcelReference": "0123456789012345FR"
}
]
}

The FNCR has to have a length of 10, the APN has to have a length of 18.

In case FNCR and APN are configured in GLS ShipIT shipper settings they must not be delivered in REST requests.

Printing options

The printing options give you several ways of dealing with the labels that you need to place on your parcels. In general you can choose between GLS ShipIT handling the printing (this option is not available if you are using GLS ShipIT hosted at GLS premises) or for GLS ShipIT to return the created labels. If you choose to retrieve the labels from GLS ShipIT, you can choose the format of the labels to match your printers. Thus when issuing the request, you have to define one of the following printing options:

  1. UseDefault
  2. DefinePrinter
  3. ReturnLabels


The PrintingOptions section is mandatory for all types of shipment creation webservice requests. This also includes services like Pick&Ship and Pick&Return, where no label data is returned.

If your are connecting to a centrally hosted GLS ShipIT, you can only use the option "ReturnLabels" as there will not be any printer installed within the centrally hosted GLS ShipIT (and you won't be able to retrieve the labels).

If you plan to use GLS ShipIT for printing your labels, please check the chapter "Druckerverwaltung" of the manual for information on how to configure printers in GLS ShipIT.

The option "UseDefault" should be considered when you are using GLS ShipIT with the Client or when you already configured your printers within your GLS ShipIT installation. By choosing that option, all documents are sent to the printers that are configured within GLS ShipIT. As the REST requests are being executed on the GLS ShipIT backend, only the configured backend printers are valid printers for this printing option.

The option "DefinePrinter" should be considered when you have printers configured within GLS ShipIT, but you want to print to different printers then the configured default printers of GLS ShipIT (e.g. you want to use a different printer when using the REST interface as when a user is creating parcels using the GLS ShipIT client application). With this option you have to provide the name of the printers that should be used for printing the labels and the accompanying documents. As the REST requests are being executed on the GLS ShipIT backend, only the configured backend printers are valid printers for this printing option.

The option "ReturnLabels" should be used when you cannot configure your printers in GLS ShipIT (e.g. the printer cannot be reached from the host which runs the GLS ShipIT backend). For this option you have to specify which type of printer you have. GLS ShipIT will return the labels for the desired type of printer. All other documents (e.g. additional documents for addon liability or ident service) will be returned as PDF document. If you do not have any of the supported label printers (or if your label printer is capable of printing PDF), you can specify PDF as the desired label format.

Here are some samples of the printing options you can use in your requests:

If you want to use GLS ShipIT for printing labels and documents:

"PrintingOptions": {
"UseDefault": "Default"
}

If you want to use dedicated printers configured in GLS ShipIT (but not the default printers):

"PrintingOptions": {
"DefinePrinter": {
"LabelPrinter": "ThermoI34",
"DocumentPrinter": "\\\\Logistics\\Laser"
}
}

If you want to print the labels on your thermal printer (in this case an Intermec Easycoder PC4):

"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "PF8D200",
"LabelFormat": "Intermec"
}
}

If you want to retrieve the labels as PDF documents:

"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "NONE",
"LabelFormat": "PDF"
}
}


Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Use default printer UseDefault 7 alphanumeric Default Optional Default fixed value "UseDefault" : "Default"
Define printer DefinePrinter - Define configured printers for printing labels and shipment documents.
Label printer LabelPrinter 255 alphanumeric Optional - Please define name of the label printer
Document printer DocumentPrinter 255 alphanumeric - Optional - Please define name of the document printer
Define printer for return labels ReturnLabels
Template name TemplateSet 7 alphanumeric Optional Must use one of the defined set NONE, D200, PF4I, PF4I200, PF4I300, PF8D200, T200BF, T300BF, ZPL200, ZPL300
Printer label format LabelFormat 8 alphanumeric Optional Must use one of the defined set PDF, Zebra, Intermec, Datamax, Toshiba

Custom content

This section of the request contains several optional attributes. You do not need to fill any of them. If you however have the need of adding your own barcode or logo to the labels or if you want to suppress the shipper address on the labels, you can use this request section to steer this behaviour.

If you want to have a custom logo / image on the labels, fill the content of the element "CustomerLogo" with the binary data of the logo. The data must be Base64 encoded. The image formats jpg, gif and png are supported.

To print your logo on the label, use something like this:

"CustomContent":{
"CustomerLogo": "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"
}

If you need an own barcode on the label there are two elements to support this. In the element "Barcode" you specify the data that should be printed as a barcode. In the element "BarcodeType" you can specify the barcode format that should be used. You can choose between the following barcode formats:

If you want to print a Code39 barcode on the label, you can define the elements like this:

"CustomContent": {
"Barcode": "0123456789",
"BarcodeType": "CODE_39"
}
Name Expression in webservices Field length Type Format Mandatory/Optional Restrictions Description
Customer logo CustomerLogo 5 base64Binary Optional - Custom content provided for label generation (f.e. customer logo)
Barcode Barcode 5 alphanumeric Optional - Barcode to create in the label
Barcode type BarcodeType 7 alphanumeric Optional EAN_128 or CODE_39 The type of barcode to create in the label
BarHide shipper address HideShipperAddress 5 boolean Optional true or false Specify if the shipper address must be removed from the label

Input validation

Response

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.CreatedShipment or one of the following faults:

Depending of multiple conditions the response can have different content/information:

ParcelData

Barcodes

The Barcodes section varies. The informations (as the NDI numbers or UniShip for example) are filled depending of origin, destination and used services:

"Barcodes": {
"Primary2D": "ADE 777DE 777abcdefghij2761234567YZ8YO127AA 3esa081538106 00560001001 ",
"Secondary2D": "A|Max Mustermann|Falkenbergstrasse 47|Braunschweig|| Ref-Unit-0815| Ref-Ship-4711| ",
"Primary1D": "200010110396",
"Primary1DPrint": true
}

RoutingInfo

The routing informations are returned in section RoutingInfo:

"RoutingInfo": {
"Tour": "0815",
"InboundSortingFlag": "003",
"FinalLocationCode": "DE 777",
"HubLocation": "esa",
"LastRoutingDate": "2017-07-03"
}

ServiceArea

When using a service, the REST response will list all used services with their service attributes:

"ServiceArea": {
"Service": [{
"Header": "DepositService",
"Information": [{
"Name": "Deposit Place",
"Value": "Under the doormat"
}
]
}
]
}

For product EXPRESS there is also a serviceArea entry:

"ServiceArea": {
"Service": [{
"Header": "ExpressParcel",
"Information": []
}
]
}

ExpressData

In case of Express product the response contains additional express delivery/routing informations:

"ExpressData": {
"AlternateDelivery": true,
"ImportStation": "1118",
"TourNumber": "2228",
"CourierParcelNumber": "820510120162"
}

ExpressArea

If the parcel is a Der Kurier parcel the Kurier1D, KurierTourNumber and KurierImportStation are given in the ExpressArea:

"ExpressArea": {
"Kurier1D": "820510120162",
"KurierTourNumber": "2228",
"KurierImportStation": "1118"
}

NDIArea

For some destination countries there are NDI informations (NDI1D) returned. Parcels to Great Britain (GB) and to Switzerland (CH) have additional informations.

For parcels to Great Britain (GB) the GBProductIdentifier is filled with fixed value 24. The GB information GBPostOffice1D contains the zipcode (if longer than 4, the first 4 chars/digits only) surrounded by two asterisk (*):

"NDIArea": {
"NDI1D": "EH936454348GB",
"GBProductIdentifier": "24",
"GBPostOffice1D": "*NN15*"
}

For parcels to Switzerland (CH) the CHParcelNumber is filled with readable NDI number. The CH information CHPRI1D contains the fixed value 0509. The CH information CHSI1D contains the fixed value 0307:

"NDIArea": {
"NDI1D": "994010486057566095",
"CHParcelNumber": "99.40.104860.57566095",
"CHPRI1D": "0509",
"CHSI1D": "0307"
}

HandlingInformation

There are some pre-defined shorthand symbols which are returned in HandlingInformation:

There are more shorthand symbols for various services which are returned if such a service is used. If there are more than one symbol for a parcel, those symbols are concatenated (separated by spaces).

Sample request

POST http://localhost:8080/backend/rs/shipments
POST data:
{
"Shipment": {
"ShippingDate":"2016-04-01",
"Product": "PARCEL",
"Consignee": {
"ConsigneeID":"DE00",
"Address": {
"Name1": "Max",
"CountryCode": "DE",
"ZIPCode": "38106",
"City": "Braunschweig",
"Street": "Ringstrasse"
}
},
"Shipper": {
"ContactID": "2761234567"
},
"ShipmentUnit": [{
"Weight": 23.2
}
],
"Service": [
{
"Service": {
"ServiceName": "service_thinkgreen"
}
}
]
},
"PrintingOptions": {
"UseDefault": "Default"
}
}

Sample response

If the request was successful:

{
"CreatedShipment": {
"ShipmentReference": [],
"ParcelData": [{
"TrackID": "YZ8YO12S",
"Barcodes": {
"Primary2D": "ADE 777DE 777abcdefghij2761234567YZ8YO12SAAz 3esa081538106 02320001001 ",
"Secondary2D": "A|Max|Ringstrasse|Braunschweig|| | | ",
"Primary1D": "200010110600",
"Primary1DPrint": true
},
"RoutingInfo": {
"Tour": "0815",
"InboundSortingFlag": "003",
"FinalLocationCode": "DE 777",
"HubLocation": "esa",
"LastRoutingDate": "2017-06-27"
},
"ServiceArea": {
"Service": [{
"Header": "ThinkGreenService",
"Information": []
}
]
}
}
],
"CustomerID": "abcdefghij",
"PickupLocation": "DE 777"
}
}

If the request was syntactically correct, but there where validation issues:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field shipper.email. Value ADDRESS_VALID_EMAIL is not a valid value. Shipment validation failed
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["shipper.email","ADDRESS_VALID_EMAIL","Shipment validation failed"]

If you specified an invalid service (or a service that is not available to the shipper used in the request):

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field Shipment.Service.ServiceName. Value service_iamnotvalid is not a valid value. Article does not exist or is not available for shipper
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["Shipment.Service.ServiceName","service_iamnotvalid","Article does not exist or is not available for shipper"]

If a mandatory attribute was not set:

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

validateParcels (F-115)

This operations checks if a shipment is valid. This operation is optional, you do not need to execute this before you create a shipment by calling Use case description: createParcels (F-114). The REST service operation createParcels performs a validation on its own.

The REST method is available at sub-path /validate with http request method POST
Parameter Mandatory Location in RequestDescription
validateShipmentRequestData TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.ValidateShipmentRequestData with the shipment parameters.

Input validation

To verify that the shipment is valid, the following areas are checked:

If at least one rule is violated, validation issues are returned and the validation of the shipment was not successful.

Address validations

Each address that is provided within the request is being validated. The attributes name1, streetname, city, zip and countrycode must be provided. All these attributes must not be empty. The zip code must be valid for the respective country.

If validation rules fail, you will receive an error describing the issue and the position within the request:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "ADDRESS_ZIPCODE_MANDATORY",
"Location": "consignee.zip"
}, {
"Rule": "SHIPMENT_VALID_ROUTING",
"Location": "routing"
}
]
}
}

Valid routing

Checks are being performed to ensure that the shipment can be routed from the origin address to the destination address.

If no routing could be determined for the shipment:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "SHIPMENT_VALID_ROUTING",
"Location": "routing"
}
]
}
}

Service availability

Services and products are usually available for a selection of origin and destination countries. There are validation rules in place that verify if the product and the services are available for the given origin and destination address.

If one or more services are not available for the origin or destination:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "ARTICLES_DESTINATION_EXCLUSIONS",
"Location": "article.routing.notallowed",
"Parameters": ["DE", "27498"]
}
]
}
}

Service combinations

Not all services and products can be combined with each other. An important part of the validation therefore is to check, if all provided services can be combined with the product and with each other.

If one or more services cannot be combined with each other:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "ARTICLE_COMBINATIONS",
"Location": "articlecombination.notallowed",
"Parameters": ["CashService", "IntercompanyService"]
}
]
}
}

Service attribute validations

Service attributes are verified by different criteria. For every service the API defines which attributes are mandatory. The validation further verifies if the attributes have valid values. As an example, there are maximum values for the cash amount of the cash on delivery service.

E.g. if the cash on delivery amount is too high, you will get a validation result as follows:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "ARTICLES_PRODUCT_MAX_COD",
"Location": "shipmentunit.attribute.cod.toohigh",
"Parameters": ["PRODUCT"]
}
]
}
}

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.ValidateParcelsResponse or one of the following faults:

Sample request

POST http://localhost:8080/backend/rs/shipments/validate
POST data:
{
"Shipment": {
"Product": "PARCEL",
"Consignee": {
"ConsigneeID":"DE00",
"Address": {
"Name1": "Max",
"CountryCode": "DE",
"ZIPCode": "38106",
"City": "Braunschweig",
"Street": "Ringstrasse"
}
},
"Shipper": {
"ContactID": "2761234567"
},
"ShipmentUnit": [{
"Weight": 23.2
}
]
}
}

Sample response

If the request was successful, but the shipment contains validation issues:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "ADDRESS_ZIPCODE_MANDATORY",
"Location": "consignee.zip"
}, {
"Rule": "ADDRESS_CITY_MANDATORY",
"Location": "consignee.city"
}, {
"Rule": "SHIPMENT_VALID_ROUTING",
"Location": "routing"
}
]
}
}

If the request was successful and the shipment is valid:

{
"success": true,
"validationResult": {
"Issues": []
}
}

If the request was syntactically incorrect:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "COMMON",
"Location": "Shipment.Service.ServiceName",
"Parameters": ["Article does not exist or is not available for shipper", "abc"]
}
]
}
}

If a mandatory attribute or element was not provided:

{
"success": false,
"validationResult": {
"Issues": [{
"Rule": "COMMON",
"Location": "Shipment.Consignee",
"Parameters": ["The Mandatory parameter Shipment.Consignee is not set"]
}
]
}
}

cancelParcelById (F-116)

This operations tries to cancel a previously created parcel. This operation is not guaranteed to succeed. If the parcel is already being processed, it cannot be cancelled anymore. The cancel operation itself is handled asynchronously in most cases. If the system is not connected to the central systems of GLS at the time issuing the request, the request will be retried at later times. The REST service will not wait for the request to be executed, it returns after the request has successfully been scheduled.

The REST method is available at sub-path /cancel/{trackID} with http request method POST
Parameter Mandatory Location in RequestDescription
trackID TRUE path param The track ID of the parcel that should be canceled.

Input validation

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.CancelParcelResponse or one of the following faults:

Sample request

POST http://localhost:8080/backend/rs/shipments/cancel/YZ8YPH2Q
POST data:

If the cancellation was successful:

{
"TrackID": "YZ8YPH2Q",
"result": "CANCELLED"
}

If the cancellation was successfully scheduled:

{
"TrackID": "YZ8YPH2Q",
"result": "CANCELLATION_PENDING"
}

Sample response

If the request was successful, but the parcel cannot be cancelled:

{
"TrackID": "YZ8YPH2Q",
"result": "SCANNED"
}

If a wrong TrackID has been transmitted:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field TrackID. Value zzZZzzZZ is not a valid value. A parcel with the given ID does not exist
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["TrackID","zzZZzzZZ","A parcel with the given ID does not exist"]

If a mandatory attribute was not provided (e.g. the TrackID):

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

If a shipper shall be used to which the user does not have access:

Response headers:
HTTP/1.1 400 Bad Request
message: Customer 2760001154 - Auth-User user: access to shipper denied
error: ACCESS_TO_SHIPPER_DENIED
Content-Length: 0
args: ["012345678912","user","access to shipper denied"]

getAllowedServices (F-117)

This REST service operation returns a list of services (product/articles) that can be used for a shipment from a specific source address to a specific destination address.

The operation takes an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.AllowedServicesRequestParameter

The REST method is available at sub-path /allowedservices with http request method POST
Parameter Mandatory Location in RequestDescription
allowedServicesRequestParameter TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.AllowedServicesRequestParameter with the request parameters.

Input validation

No special input validation is being done. The zip code should comply with zip code rules of the respective country.

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.AllowedServicesResponse or one of the following faults:

Sample request

POST http://localhost:8080/backend/rs/shipments/allowedservices
POST data:
{
"Source":{
"CountryCode":"DE",
"ZIPCode":"38106"
},
"Destination":{
"CountryCode":"DE",
"ZIPCode":"65779"
}
}

Sample response

If the request was successful:

{
"AllowedServices": [{
"ProductName": "PARCEL"
}, {
"ProductName": "EXPRESS"
}, {
"ProductName": "FREIGHT"
}, {
"ServiceName": "service_cash"
}, {
"ServiceName": "service_pickandship"
}, {
"ServiceName": "service_pickandreturn"
}, {
"ServiceName": "service_addonliability"
}, {
"ServiceName": "service_deliveryatwork"
}, {
"ServiceName": "service_deposit"
}, {
"ServiceName": "service_hazardousgoods"
}, {
"ServiceName": "service_exchange"
}, {
"ServiceName": "service_saturday_1000"
}, {
"ServiceName": "service_guaranteed24"
}, {
"ServiceName": "service_shopreturn"
}, {
"ServiceName": "service_0800"
}, {
"ServiceName": "service_0900"
}, {
"ServiceName": "service_1000"
}, {
"ServiceName": "service_1200"
}, {
"ServiceName": "service_intercompany"
}, {
"ServiceName": "service_directshop"
}, {
"ServiceName": "service_smsservice"
}, {
"ServiceName": "service_ident"
}, {
"ServiceName": "service_identpin"
}, {
"ServiceName": "service_shopdelivery"
}, {
"ServiceName": "service_preadvice"
}, {
"ServiceName": "service_saturday_1200"
}, {
"ServiceName": "service_Saturday"
}, {
"ServiceName": "service_thinkgreen"
}, {
"ServiceName": "service_exworks"
}, {
"ServiceName": "service_tyre"
}, {
"ServiceName": "service_flexdelivery"
}, {
"ServiceName": "service_pickpack"
}, {
"ServiceName": "service_documentreturn"
}, {
"ServiceName": "service_1300"
}, {
"ServiceName": "service_addresseeonly"
}
]
}

If the request was syntactically incorrect:

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

If an attribute had a wrong value (e.g. a invalid country code):

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field source.countryCode. Value XY is not a valid value. Mandatory field is not set or invalid
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["source.countryCode","XY","Mandatory field is not set or invalid"]

getEndOfDayReport (F-118)

Executes the end of day procedure for the given day and returns all shipments that where affected by the end of day procedure.

The REST method is available at sub-path /endofday with http request method POST
Parameter Mandatory Location in RequestDescription
date TRUE query param The day for which the end of day procedure should be executed.

The end of day procedure does the following things:

The shipment units for which end of day will be performed is limited by the shipments to which the user issuing the request has access to. This means, it affects all shippers to which the user has access based on the roles assigned to him.

If you are connecting to a local installation of GLS ShipIT on your premises, you can configure the following actions to be done during end of day:

The operation takes a date as an input parameter.

Input validation

No input validation is to be done.

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.EndOfDayResponse or one of the following faults:

Sample request

POST http://localhost:8080/backend/rs/shipments/endofday?date=2017-06-28
POST data:

Sample response

{
"Shipments": [{
"ShippingDate": "2017-06-28",
"Product": "PARCEL",
"Consignee": {
"Address": {
"Name1": "Max",
"CountryCode": "DE",
"ZIPCode": "38106",
"City": "Braunschweig",
"Street": "Ringstrasse",
"eMail": null
}
},
"Shipper": {
"ContactID": "2761234567",
"AlternativeShipperAddress": {
"Name1": "Logistics and More",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Eschborn",
"Street": "Elly-Beinhorn-Strasse",
"StreetNumber": "1a",
"eMail": "logistics@more.test",
"FixedLinePhonenumber": "004961961234567"
}
},
"ShipmentUnit": [{
"Weight": "23.2",
"TrackID":"YZDLDM5I",
"ParcelNumber":"20281021030"
}
]
}
]
}

If shipments still need to be transmitted, but could not be transmitted:

Response headers:
HTTP/1.1 400 Bad Request
message: Transmission of one or more of the following shipment units not successful: XYZ00012
error: COULD_NOT_TRANSMIT
Content-Length: 0
args: ["Transmission of one or more of the following shipment units not successful","XYZ00012"]

updateParcelWeight (F-119)

Updates the weight of a shipment unit. The shipment unit will be searched by its trackID.

The REST method is available at sub-path /updateparcelweight with http request method POST
Parameter Mandatory Location in RequestDescription
updateParcelWeightRequestParameter TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.UpdateParcelWeightRequestParameter with the request parameters.

The search is restricted to the shippers to which the user issuing the request has access to.

Input validation

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.UpdateParcelWeightResponse or one of the following faults:

Sample request

POST http://localhost:8080/backend/rs/shipments/updateparcelweight
POST data:
{
"TrackID": "ZDF8DOSZ",
"Weight": "17.0"
}

Sample response

If the request was successful:

{
"UpdatedWeight": "17.0"
}

If the request points to more than one shipment unit:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid shipment unit number unitref47: Shipment unit could not be identified. IDs are not unique (shipment reference number: 47110815, shipment unit reference number: unitref47)
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: ["unitref47","Shipment unit could not be identified. IDs are not unique (shipment reference number: 47110815, shipment unit reference number: unitref47)"]

If the shipment unit cannot be found by the provided reference numbers:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid shipment unit number unitref47: No shipment unit found for shipment reference number 47110815 and shipment unit reference number unitref47
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: ["unitref47","No shipment unit found for shipment reference number 47110815 and shipment unit reference number unitref47"]

If the shipment unit cannot be found by the provided reference number on shipment unit level (no shipment reference number passed to the service):

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid shipment unit number unitref48: No shipment unit found for shipment reference number null and shipment unit reference number unitref48
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: ["unitref48","No shipment unit found for shipment reference number null and shipment unit reference number unitref48"]

If a mandatory parameter is not provided:

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

If an invalid value is provided (e.g. a too high weight):

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field Weight. Value 40.0 is not a valid value. Invalid field Weight. Value 40.0 is not a valid value. Max value is 25.0
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["Weight","40.0","Invalid field Weight. Value 40.0 is not a valid value. Max value is 25.0"]