+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 The web service request/response content is encoded using UTF-8.
+
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.
+
+Available REST service operations
+
+Webservices Examples
+
The pages below contain examples of webservice calls and error responses:
+
+createParcels
+
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, Return 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
+
+
The parts of the request are explained in the following sections in more detail.
+ Please generally note that the following characters are not allowed as part of text fields and can cause issues at parcel operations: \"{},;()| line feed(\n)
+
+Shipment data
+
When you are creating a shipment, you can specify several attributes on the shipment level. These are:
+
+-
+ShipmentReference - You can provide one or more identifiers for this shipment.
+-
+ShippingDate - Provide a date for the shipment. If no value is provided, the next working day is picked automatically.
+-
+IncotermCode - If you ship between different commercial zones, you have to specify the inco term for this shipment.
+-
+Identifier - Attribute for storing a person in charge or a work station
+-
+Middleware - Attribute for storing Partner ERP System
+-
+Product - The product group in which you shipment fits (parcel, express). GLS ShipIT will automatically choose the best product (small parcel or euro business parcel) for your shipment based on the defined group (depending on the parcel weight, pickup and delivery address)
+-
+ExpressAltDeliveryAllowed - The user has a possibility to deactivate the alternative delivery for Express shipment.
+-
+Consignee data
+-
+Shipper data
+-
+Return data
+-
+Shipment unit data
+-
+Service - The services that shall be booked for this shipment
+
+
{
"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 | Level | Description |
+
+| Customer reference number | ShipmentReference | 40 | alphanumeric | | Optional | - | | Reference for this consignment of parcels |
+
+| Shipping date | ShippingDate | 10 | alphanumeric | YYYY-MM-DD | Optional | - | | Date for the shipment |
+
+| Incoterm | IncotermCode | 2 | numeric | 10, 20, 30, etc. | Optional | | | Incoterm for this shipment. Represented by 2 digits |
+
+| Identifier | Identifier | 40 | alphanumeric | | Optional | - | | Person who started the parcel creation |
+
+| Middleware | Middleware | 40 | alphanumeric | | Mandatory | - | | Partner ERP System |
+
+| Product Group | Product | 7 | alphanumeric | | Mandatory | PARCEL, EXPRESS | | 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 |
+
+| Return | Return | | | | Optional | - | | see section Return 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. The consignee category can be "BUSINESS" or "PRIVATE". If the field consignee category is omitted, the consignee will have no (empty) category.
+
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"
}
The consignee category can be specified as follows:
"Consignee": {
"Category": "BUSINESS",
"Address": {...}
}
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 | Level | Description |
+
+| Consignee identifier | ConsigneeID | 40 | alphanumeric | | Optional | - | | Identifier for the recipient of the parcels |
+
+| Cost Center | CostCenter | 80 | alphanumeric | | Optional | - | | Delivery location cost center for Inbound |
+
+| Consignee Category | Category | 8 | alphanumeric | CAPS LOCK | Optional | Only PRIVATE or BUSINESS | | Classifies consignee as 2B (BUSINESS) or 2C (PRIVATE) recipient |
+
+| Consignee Address | Address | | | | Mandatory | - | | see section Address data for field details |
+
+
+Address data
+
The following table applies to any kind of address that is possible within the request - only the purpose is different.
+Consignee - generally the recipient of a parcel - only exception are return services: here it is the one where the parcel is handed in to GLS.
+Shipper - shipper address information is automatically assigned / transmitted on the basis of the Contact ID. It must not be transmitted within the web service call, in case the GLS customer has a dedicated Contact ID! Please liaise with your GLS contact if you can use this address, permission-restrictions apply. The shipper address must only be transmitted in case ShipIT is used in a GLS country (Netherlands, Hungary), which does not assign dedicated Contact IDs to a GLS Customer. In this scenario a general “dummy” Contact ID will be used for all customers, which makes it necessary to transmit the real shipper address. The shipper address has an operational impact and can only be used within the same country.
+Alternative Shipper - used for masking the original shipper address. This has only impact on the label where the actual address is overwritten. No operational impact.
+Return Address - identifies the return address a parcel should be returned to, different from the shipper address. This might be the case for example if the recipient rejects the parcel.
+
In addition to these there is the expression of a requester in ShipIT who is always identified by the contactID and therefore part of the shipper. Other address types might apply for certain services. Please refer to the service section here.
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Name1 | Name1 | 40 | alphanumeric | | Mandatory | - | | Name of the consignee |
+
+| Name2 | Name2 | 40 | alphanumeric | | Optional | - | | Additional consignee name information |
+
+| Name3 | Name3 | 40 | alphanumeric | | Optional | - | | Additional consignee name information |
+
+| Country code | CountryCode | 2 | alphanumeric | DE, AT, BE, FR, etc. | Mandatory | - | | Destination country of the shipment |
+
+| Province | Province | 40 | alphanumeric | | Optional | - | | Province where the consignee's city is located in |
+
+| ZIPCode | ZIPCode | 10 | alphanumeric | | Mandatory | - | | ZIP code of the consignee's city |
+
+| City | City | 40 | alphanumeric | | Mandatory | - | | City of the consignee |
+
+| Street | Street | 40 | alphanumeric | | Mandatory | | | Street name |
+
+| Street number | StreetNumber | 40 | alphanumeric | | Optional | - | | Street number (if not part of the street) |
+
+| eMail | eMail | 80 | alphanumeric | | Optional | - | | Email address of the consignee |
+
+| Contact person | ContactPerson | 40 | alphanumeric | | Optional | > 5 | | Contact person to print on the label |
+
+| Fixed phonenumber | FixedLinePhonenumber | 35 | alphanumeric | | Optional | > 3 | | Fixed line phone number of the consignee |
+
+| Mobile | MobilePhoneNumber | 35 | alphanumeric | | Optional | > 3 | | Mobile phone number of the consignee |
+
+
+Shipper data
+
The shipper address information is automatically assigned / transmitted on the basis of the Contact ID. It must not be transmitted within the web service call, in case the GLS customer has a dedicated Contact ID! Please liaise with your GLS contact if you can use this address. The shipper address must only be transmitted in case ShipIT is used in a GLS country (Netherlands, Hungary), which does not assign dedicated Contact IDs to a GLS Customer. In this scenario a general “dummy” Contact ID will be used for all customers, which makes it necessary to transmit the real shipper address. The shipper address has an operational impact and can only be used within the same country.
+
"Shipper": {
"ContactID": "2761234567",
"Address":{
"Name1": "GLS IT Services GmbH",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Eschborn",
"Street": "Kölner Straße",
"StreetNumber": "3"
},
"AlternativeShipperAddress": {
"Name1": "GLS IT Services GmbH",
"CountryCode": "DE",
"ZIPCode": "36286",
"City": "Neuenstein",
"Street": "GLS Germany Straße",
"StreetNumber": "1-7",
"eMail": "test_logistics@gls-group.com",
"FixedLinePhonenumber": "004961961234567"
}
}
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Shipper identifier | ContactID | 20 | alphanumeric | | Mandatory | - | | Shipper identifier as given by GLS |
+
+| Name1 | Name1 | 40 | alphanumeric | | Conditional | - | | Name of the shipper |
+
+| Name2 | Name2 | 40 | alphanumeric | | Optional | - | | Additional shipper name information |
+
+| Name3 | Name3 | 40 | alphanumeric | | Optional | - | | Additional shipper name information |
+
+| Country code | CountryCode | 2 | alphanumeric | DE, AT, BE, FR, etc. | Conditional | - | | Origin country of the shipment |
+
+| Province | Province | 40 | alphanumeric | | Optional | - | | Province where the shipper's city is located in |
+
+| ZIPCode | ZIPCode | 10 | alphanumeric | | Conditional | - | | ZIP code of the shipper's city |
+
+| City | City | 40 | alphanumeric | | Conditional | - | | City of the shipper |
+
+| Street | Street | 40 | alphanumeric | | Conditional | | | Street name |
+
+| Street number | StreetNumber | 40 | alphanumeric | | Optional | - | | Street number (if not part of the street) |
+
+| Alternative address | AlternativeShipperAddress | - | Address | | Optional | - | | see section Address data |
+
+
Conditional = if the address is given all conditional fields get mandatory.
+
+Return data
+
This section identifies the return address a parcel should be returned to, different from the shipper address. This might be the case for example if the recipient rejects the parcel.
+
"Return": {
"Address":{
"Name1": "Mustermann AG",
"Name2": "Return Center",
"Name3": "Mrs. Return",
"CountryCode": "DE",
"ZIPCode": "36286",
"City": "Neuenstein",
"Street": "GLS Germany Str.",
"StreetNumber": "1-7"
}
}
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Name1 | Name1 | 40 | alphanumeric | | Mandatory | - | | Name of the return contact |
+
+| Name2 | Name2 | 40 | alphanumeric | | Optional | - | | Additional return name information |
+
+| Name3 | Name3 | 40 | alphanumeric | | Optional | - | | Additional return name information |
+
+| Country code | CountryCode | 2 | alphanumeric | DE, AT, BE, FR, etc. | Mandatory | - | | Country of the return address |
+
+| Province | Province | 40 | alphanumeric | | Optional | - | | Province where the return city is located in |
+
+| ZIPCode | ZIPCode | 10 | alphanumeric | | Mandatory | - | | ZIP code of the return city |
+
+| City | City | 40 | alphanumeric | | Mandatory | - | | City of the return address |
+
+| Street | Street | 40 | alphanumeric | | Mandatory | | | Street name |
+
+| Street number | StreetNumber | 40 | alphanumeric | | Optional | - | | Street number (if not part of the street) |
+
+
+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:
+-
+ReferenceNumber - You can provide one or more identifiers for this shipment unit.
+-
+Weight - The weight of the parcel
+-
+Service - Zero to many Services
+
+
To create multiple units within a shipment, repeat the unit section as often as needed. Please limit this to 150 units per shipment.
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Parcel reference | ShipmentUnitReference | 40 | alphanumeric | | Optional | - | | Reference to be given to the parcel |
+
+| Parcel Weight | Weight | 10 | decimal | | Mandatory | >0.10 | | Updated weight with at least 200g difference to original weight, max. 2 decimal digits. |
+
+| Parcel note1 | Note1 | 50 | alphanumeric | | Optional | - | | Notes added to the parcel (line 1) |
+
+| Parcel note2 | Note2 | 50 | alphanumeric | | Optional | - | | Notes added to the parcel (line 2) |
+
+| Parcel services | Service | - | | | Optional | - | | see section Services for detailed fields |
+
+| Partner's parcel number | PartnerParcelNumber | 50 | alphanumeric | | Optional | - | | Option for network partners to hand over their own reference |
+
+
+Services
+
You can define services that should apply to your shipment. For further information on the services currently available in your country please go to https://gls-group.eu and check the page of the desired country.
+
The following services can be assigned on the shipment unit level:
+-
+
Cash
+Adding the cash service requires the drivers to collect the requested amount at point of delivery. Limitations apply on the maximum amount in each country.
+"ShipmentUnit": [{
...
"Service": [{
"Cash": {
"ServiceName": "service_cash",
"Reason": "Your order 4711",
"Amount": "12.09",
"Currency": "EUR"
}
}
]
}
]
+-
+
AddonLiability
+If you are sending parcel contents having a higher value, you can define the liability level. The levels depend on each country.
+"ShipmentUnit": [{
...
"Service": [{
"AddonLiability": {
"ServiceName": "service_addonliability",
"Amount": "5000",
"Currency": "EUR"
}
}
]
}
]
+-
+
HazardousGoods
+If your parcels contains goods that have a risk assigned, the content must be mentioned in the request already. Please keep in mind that the overall weight of a shipment must be higher than the sum of all hazardous good's weights.
+"ShipmentUnit": [{
...
"Service": [{
"HazardousGoods": {
"ServiceName": "service_hazardousgoods",
"HazardousGood": [{
"GLSHazNo": "7000004",
"Weight": 1.2
}
]
}
}
]
}
]
+-
+
LimitedQuantities
+If you send hazardous goods in limited amounts according to ADR chapter 3.4 you can use this service.
+"ShipmentUnit": [{
...
"Service": [{
"LimitedQuantities": {
"ServiceName": "service_limitedquantities",
"Weight": 2
}
}
]
}
]
+-
+
ExWorks
+Using this service shipping cost is the recipient’s responsibility.
+"ShipmentUnit": [{
...
"Service": [{
"ExWorks": {
"ServiceName": "service_exworks"
}
}
]
}
]
+
+
Those services may have different attributes for each shipment unit.
+
Services inside shipment unit can be combined like this:
+-
+Cash and AddonLiability
"ShipmentUnit": [{
...
"Service": [{
"Cash": {
"ServiceName": "service_cash",
"Reason": "Bill is due",
"Amount": "0.01",
"Currency": "EUR"
},
"AddonLiability": {
"ServiceName": "service_addonliability",
"Amount": "5000",
"Currency": "EUR",
"ParcelContent": "some very good stuff"
}
}
]
}
]
+
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Cash service | Cash | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_cash | Mandatory | Parcel | Shipment unit | Must use this fixed value for service name |
+
+| Cash reason | Reason | 160 | alphanumeric | | Mandatory | - | | Reason why the cash service was added to the parcel |
+
+| Cash amount | Amount | - | decimal | | Mandatory | >0 | | Cash amount (numeric value), limitations apply per country |
+
+| Cash currency | Currency | 3 | alphanumeric | EUR | Mandatory | - | | Cash currency code (ISO4217 -> 3 digits) |
+
+| AddonLiability service | AddonLiability | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_addonliability | Mandatory | Parcel | Shipment unit | Must use this fixed value for service name |
+
+| AddonLiability amount | Amount | - | decimal | | Mandatory | - | | Liability amount might differ per country, please liaise with your sales contact |
+
+| AddonLiability currency | Currency | 3 | alphanumeric | EUR | Mandatory | - | | AddonLiability 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 | service_hazardousgoods | Mandatory | Parcel | Shipment unit | Must use this fixed value for service name |
+
+| HazardousGoods | HazardousGoods | | | | | - | | Hazardous good item attributes |
+
+| Hazardous goods number | GLSHazNo | 8 | alphanumeric | | Mandatory | - | | Identifier for the hazardous goods type |
+
+| HazardousGoods Weight | Weight | - | decimal | | Mandatory | > 0 | | Weight for the hazardous good shipped (numeric), max. 2 decimal digits. |
+
+| LimitedQuantities service | LimitedQuantities | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_limitedquantities | Mandatory | Parcel | Shipment unit | Must use this fixed value for service name |
+
+| LQ Weight | Weight | - | decimal | | Optional | > 0 | | Weight for the LQ shipped (numeric), max. 2 decimal digits. |
+
+| ExWorks service | ExWorks | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_exworks | Mandatory | Parcel | Shipment unit | Must use this fixed value for service name |
+
+
The following services can be assigned on the shipment level:
+-
+
ShopDelivery
+Parcels with ShopDeliveryServices will be delivered to the given parcelshop (identified by ParcelShopID) instead of the consignee's original address - still it needs to be given. The parcelshop must be located in the same country as the consignee.
+"Shipment": {
...
"Service": [{
"ShopDelivery": {
"ServiceName": "service_shopdelivery",
"ParcelShopID": "GLS_DE-2760238818"
}
}
]
}
+-
+
ShopReturn
+Parcels with ShopReturnService are sent back from the original consignee to the shipper. They must be dropped off at a GLS parcelshop. This request is only creating the return label, the label towards the consignee must be requested separately. The following addresses must be used:
+- Consignee (the sender of the return parcel)
+- Alternative shipper address (if the parcel shall be returned to an address other than the default address)
+
+"Shipment": {
...
"Service": [{
"ShopReturn": {
"ServiceName": "service_shopreturn",
"NumberOfLabels": 10
}
}
]
}
If a QR code is required, an additional parameter must be included. Please note that QR codes are only available for parcel shop drop off in certain countries like Germany and Austria.
"Shipment": {
...
"Service": [{
"ShopReturn": {
"ServiceName": "service_shopreturn",
"NumberOfLabels": 10,
"ReturnQR":"PDF"
}
}
]
}
+-
+
Intercompany
+Parcels with IntercompanyService are sent from one company location (consignee) to another (intercompany address).
+Shipment requests with IntercompanyService attached are only providing a return label. The following addresses must be used:
+- Consignee (address where the parcel is originating from)
+- Intercompany Address (address where the parcel shall be sent to, part of the service section - see below)
+
+"Shipment": {
...
"Service": [{
"Intercompany": {
"ServiceName": "service_intercompany",
"Address": {
"Name1": "Hansi Meier",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Eschborn",
"Street": "Helfmannpark 5"
},
"NumberOfLabels": 15
}
}
]
}
+-
+
Exchange
+When booking the ExchangeService you will receive 3 output data files: the parcel's label sent to the consignee, the label for the parcel returned to the shipper (or a third party) with the exchanged content and an acceptance receipt. The following addresses must be given (at least):
+- Consignee (the original address the parcel is sent to first)
+- Exchange address (the delivery address of the exchanged parcel, can be the original shipper's address or any other)
+
+"Shipment": {
...
"Service": [{
"Exchange": {
"ServiceName": "service_exchange",
"Address": {
"Name1": "Hansi Meier",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Eschborn",
"Street": "Helfmannpark 5"
}
}
}
]
}
+-
+
DeliveryAtWork
+For sending parcels directly to the work location of the consignee the needed information must be specified in the service section.
+"Shipment": {
...
"Service": [{
"DeliveryAtWork": {
"ServiceName": "service_deliveryatwork",
"RecipientName": "Hansi Meier",
"AlternateRecipientName": "Hilde Schmidt",
"Building": "Haus A",
"Floor": "2. Stock",
"Room": "D234.22",
"Phonenumber": "+49 800 111 0 333"
}
}
]
}
+-
+
Deposit
+If you are allowing to let us drop off the parcel at a given place of deposit, request the DepositService. This service is not combinable with other services that require consignee interaction.
+"Shipment": {
...
"Service": [{
"Deposit": {
"ServiceName": "service_deposit",
"PlaceOfDeposit": "Under the doormat"
}
}
]
}
+-
+
Letterbox
+The letterbox service is a special kind of DepositService just specifying the PlaceOfDeposit as being the letterbox (in delivery country's language).
+"Shipment": {
...
"Service": [{
"Deposit": {
"ServiceName": "service_deposit",
"PlaceOfDeposit" : "Letterbox"
}
}
]
}
+-
+
IdentPin
+If you want the consignee to authorize themselves by a given PIN in combination with their birthday.
+"Shipment": {
...
"Service": [{
"IdentPin": {
"ServiceName": "service_identpin",
"PIN": "2342",
"Birthdate": "1970-02-03"
}
}
]
}
+-
+
Ident
+Another way of identifying the actual consignee of being the correct recipient, it can be done by their ID containing the information from the service section.
+"Shipment": {
...
"Service": [{
"Ident": {
"ServiceName": "service_ident",
"Birthdate": "1980-01-02",
"Firstname": "Hansi Herbert",
"Lastname": "Maier",
"Nationality": {
"CountryCode": "DE"
}
}
}
]
}
+-
+
PickAndShip
+The addresses must be used in the following way:
+- Consignee (pick up address where the parcel should be fetched by the driver)
+- Alternative Shipper Address (delivery address of the parcel)
+
+The consignee data must contain values for ContactPerson and FixedLinePhonenumber when this service is used.
+"Shipment": {
...
"Service": [{
"PickAndShip": {
"ServiceName": "service_pickandship",
"PickupDate": "2017-07-31"
}
}
]
}
+-
+
PickAndReturn
+The addresses must be used in the following way:
+- Consignee (pick up address where the parcel should be fetched by the driver) The shipment will be returned to the default address of the shipper's contactID.
+
+The consignee data must contain values for ContactPerson and FixedLinePhonenumber when this service is used.
+"Shipment": {
...
"Service": [{
"PickAndReturn": {
"ServiceName": "service_pickandreturn",
"PickupDate": "2017-07-31"
}
}
]
}
+-
+
InboundLogistics
+In case of inbound logistics a manufacturer is paying the bills for a parcel send between other parties.
+In this case, please enter the supplier data in the shipper fields and the delivery address in the consignee fields.
+A reference number for a delivery location can be defined in the cost-center field.
+"Shipment": {
...
"Consignee": {
"ConsigneeID":"DE00",
"CostCenter":"123456789",
"Address": {
...
"Service": [{
"Service": {
"ServiceName": "service_inbound"
}
}
]
}
+-
+TyreService
"Shipment": {
...
"Service": [{
"Service": {
"ServiceName": "service_tyre"
}
}]
}
+-
+
ConsignmentService
+Adding the consignment service to a shipment will trigger processes in GLS core systems to wait for all the parcels of a consignment that reach GLS within the current or next working day.
+"Shipment": {
...
"Service": [{
"Service": {
"ServiceName": "service_completedeliveryconsignment"
}
}]
}
+-
+
SignatureService
+If you require a signature at delivery, use this service.
+ "Shipment": {
...
"Service": [{
"Service": {
"ServiceName": "service_signature"
}
}]
}
+-
+
T24/48
+For parcels to the United Kingdom using Royal Mail the expected runtime of the parcel can be given in the service section. It is required to set the Carrier to "ROYALMAIL" when booking these services.
+When no service is booked for Royal Mail, T24 will be used automatically.
+Please refer to your GLS contact for onboarding these services.
+"Shipment": {
...
"Carrier":"ROYALMAIL",
"Service": [{
"Service": {
"ServiceName": "service_t24"
}
}
]
}
"Shipment": {
...
"Carrier":"ROYALMAIL",
"Service": [{
"Service": {
"ServiceName": "service_t48"
}
}
]
}
+
+
All other services do not require specific attributes and can be assigned on the shipment level. If you e.g. want to have more possibilities to customise parcel delivery, you can book the FlexDeliveryService as follows:
"Shipment": {
...
"Service": [{
"Service": {
"ServiceName": "service_flexdelivery"
}
}
]
}
The same applies to Express shipments - these services do not require further information and can be added like stated underneath. Please note that parcels targeted to be delivered by the end of the business day do not need a dedicated service attached.
"Shipment": {
...
"Product": "EXPRESS",
...
"Service": [{
"Service": {
"ServiceName": "service_1000"
}
}
]
}
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Other service | Service | | | | | | | |
+
+| Name of the service | ServiceName | - | alphanumeric | | service_name | | | Must use the service name defined in DB |
+
+| ShopDelivery service | ShopDelivery | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_shopdelivery | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Parcel shop identifier | ParcelShopID | 50 | alphanumeric | {partnerID}-{local id} | Mandatory | - | | Specify parcel shop |
+
+| ShopReturn service | ShopReturn | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_shopreturn | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Amount of labels | NumberOfLabels | | numeric | | Mandatory | > 0 | | Specify amount of labels to print |
+
+| ReturnQR | ReturnQR | 3 | alphanumeric | PDF, PNG, ZPL | Optional | | | Specify QR Code Format |
+
+| Intercompany service | Intercompany | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_intercompany | Mandatory | Parcel | Shipment | 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 | | Expected weight of the returned shipment, max. 2 decimal digits. |
+
+| Exchange service | Exchange | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_exchange | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Exchange address | Address | | | | Mandatory | - | | see section Address data |
+
+| Expected Weight | ExpectedWeight | - | decimal | | Optional | > 0 | | Expected weight of the returned shipment, max. 2 decimal digits. |
+
+| DeliveryAtWork service | DeliveryAtWork | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_deliveryatwork | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Name of the Recipient | RecipientName | 40 | alphanumeric | | Mandatory | - | | Person who is allowed to receive the parcel |
+
+| AlternateRecipientName | AlternateRecipientName | 40 | alphanumeric | | Optional | - | | Alternative person who is allowed to receive the parcel |
+
+| Building | Building | 40 | decimal | | Mandatory | - | | Building number |
+
+| Floor | Floor | 40 | decimal | | Mandatory | - | | Floor number |
+
+| Room | Room | 40 | decimal | | Optional | - | | Room number |
+
+| Phonenumber | Phonenumber | 35 | decimal | | Optional | - | | Phone number of the contact person |
+
+| Deposit service | Deposit | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_deposit | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Place of deposit | PlaceOfDeposit | 60 | | | Mandatory | - | | Place where the driver can drop the parcel |
+
+| Letterbox service | Deposit | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_deposit | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Place of deposit | PlaceOfDeposit | 121 | | Letterbox/ Briefkasten/ etc. | Mandatory | - | | Expression for letterbox in the destination's language |
+
+| IdentPin service | IdentPin | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_identpin | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| PIN | PIN | 4 | alphanumeric | | Mandatory | | | 4-digit PIN code that the consignee needs to enter |
+
+| Birthdate | Birthdate | 10 | date | YYYY-MM-DD | Optional | < today | | Birthdate of the consignee |
+
+| Ident service | Ident | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_ident | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Birthdate | Birthdate | 10 | date | YYYY-MM-DD | Mandatory | < today | | Birthdate of the consignee |
+
+| Firstname | Firstname | 40 | alphanumeric | | Mandatory | - | | First name of the consignee |
+
+| Lastname | Lastname | 40 | alphanumeric | | Mandatory | - | | Last name of the consignee |
+
+| Nationality | Nationality | 2 | alphanumeric | | Mandatory | CountryCode | | Nationality of the consignee |
+
+| PickAndShip service | PickAndShip | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_pickandship | Mandatory | Parcel | Shipment | Must use this fixed value |
+
+| PickupDate | PickupDate | 10 | date | YYYY-MM-DD | Mandatory | > today | | Date when parcel should be picked up at shipper |
+
+| PickAndReturn service | PickAndReturn | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_pickandreturn | Mandatory | Parcel | Shipment | Must use this fixed value |
+
+| PickupDate | PickupDate | 10 | date | YYYY-MM-DD | Mandatory | > today | | Date when parcel should be picked up at shipper |
+
+| PrivateDelivery service | PrivateDelivery | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_privatedelivery | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Inbound Logistics | InboundLogistics | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_inbound | Mandatory | Parcel | Shipment | Must use this fixed value for service name |
+
+| Document Return Service | DocumentReturnService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_documentreturn | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| ConsignmentService | CompleteDeliveryConsignmentService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_completedeliveryconsignment | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| Flex Delivery Service | FlexDeliveryService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_flexdelivery | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| Signature Service | SignatureService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_signature | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| T24 Service | T24Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_t24 | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name and Carrier "ROYALMAIL" needs to be given. |
+
+| T48 Service | T48Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_t48 | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name and Carrier "ROYALMAIL" needs to be given. |
+
+| Guaranteed24 Service | Guaranteed24Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_guaranteed24 | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| AddresseeOnly Service | AddresseeOnlyService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_addresseeonly | Mandatory | Parcel | Shipment (w/o attributes) | Must use this fixed value for service name |
+
+| Tyre service | TyreService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_tyre | Mandatory | Parcel/Express | Shipment (w/o attributes) | Must use this fixed value for service name and a weight >3 kg, max. 2 decimal digits. |
+
+| 0800 Service | 0800Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_0800 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| 0900 Service | 0900Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_0900 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| 1000 Service | 1000Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_1000 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| 1200 Service | 1200Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_1200 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| 1300 Service | 1300Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_1300 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name - mandatory for french domestic parcels |
+
+| Saturday 0900 Service | Saturday0900Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_saturday_0900 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| Saturday 1000 Service | Saturday1000Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_saturday_1000 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| Saturday 1200 Service | Saturday1200Service | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_saturday_1200 | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+| Saturday Service | SaturdayService | | | | | | | |
+
+| Name of the service | ServiceName | 80 | alphanumeric | service_Saturday | Mandatory | Parcel²/Express | Shipment | Must use this fixed value for service name |
+
+ | Delivery next working day (EOB) | | | | | | | |
+
+| Name of the service | ServiceName | | | | | Express | | No service needs to be added |
+
+
Parcel² = applies only to selected countries like Poland
+
Service combinations: If you want to send a shipment containing two shipment units (parcels) with FlexDeliveryService 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_flexdelivery"
}
}
]
}
Not all of these services are available in all countries and not all of those services may be combined with each other. For further information on products and services please refer to your key account or to the local homepage of each GLS country: https://gls-group.com/
+
+Products
+
Finding the right product for your shipment will be determined by GLS ShipIT. The only information you have to give: if you want to send a standard parcel or wish to speed up by using express. Depending on the country-relation (where to send your parcel) and the weight the respective shipment product will be calculated.
+
1) Parcels sent within a country are considered as BusinessParcel or ExpressParcel - dependent on the product type chosen.
+Small, light products with a given size and weight will become a "Small" - BusinessSmallParcel
+
You can create a Request BusinessParcel like the following example:
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "PARCEL",
"Consignee": {
"ConsigneeID": "276001",
"Address": {
"Name1": "Max",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Friedrichsdorf",
"Street": "Ringstrasse"
}
},
"Shipper": {
"ContactID": "2769943e0E"
},
"ShipmentUnit": [
{
"Weight": 23.2
}
]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
You can create a Request ExpressParcel like the following example:
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "EXPRESS",
"Consignee": {
"Address": {
"Name1": "Max",
"CountryCode": "DE",
"ZIPCode": "65760",
"City": "Friedrichsdorf",
"Street": "Ringstrasse",
"StreetNumber" : "66"
}
},
"Shipper": {
"ContactID": "2769978j0E"
},
"ShipmentUnit": [{
"Weight": 23.2
}],
"Service": [{
"Service": {
"ServiceName": "service_1200"
}}]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
2) Parcels that are sent cross-border to other European countries will be either EuroBusinessParcels or EuroExpressParcels.
+For EuroBusinessParcel there is as well the option to send them as EuroBusinessSmallParcel.
+Don't forget to add incoterm information to your request, sending to customs areas like Switzerland.
+
Request EuroBusinessParcel
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "PARCEL",
"IncotermCode": "10",
"Consignee": {
"Address": {
"Name1": "Franz Holmes",
"CountryCode": "CH",
"ZIPCode": "3963",
"City": "Crans-Montana",
"Street": "Route du Petit Signal",
"StreetNumber" : "5"
}
},
"Shipper": {
"ContactID": "27699ju76E"
},
"ShipmentUnit": [{
"Weight": 23.2
}]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
Request EuroExpressParcel
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "EXPRESS",
"Consignee": {
"ConsigneeID": "040001",
"Address": {
"Name1": "Franz Huber",
"CountryCode": "AT",
"ZIPCode": "8970",
"City": "Schlagming",
"Street": "Schiliftgasse",
"StreetNumber" : "66"
}
},
"Shipper": {
"ContactID": "276b5r5N0E"
},
"ShipmentUnit": [{
"Weight": 23.2
}],
"Service": [{
"Service": {
"ServiceName": "service_1200"
}
}]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
3) International parcels are marked with a leading "Global" - so either GlobalBusinessParcel or GlobalExpressParcel.
+
Request GlobalBusinessParcel
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "PARCEL",
"IncotermCode": "10",
"Consignee": {
"Address": {
"Name1": "Franz Holmes",
"CountryCode": "UY",
"ZIPCode": "37006",
"City": "Tupambaé",
"Street": "Treinta y Tres",
"StreetNumber" : "5"
}
},
"Shipper": {
"ContactID": "276999ki2E"
},
"ShipmentUnit": [{
"Weight": 23.2
}]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
Request GlobalExpressParcel
POST https://localhost:8443/backend/rs/shipments
POST data:
{
"Shipment": {
"Product": "EXPRESS",
"IncotermCode": "10",
"Consignee": {
"Address": {
"Name1": "Franz Holmes",
"CountryCode": "UY",
"ZIPCode": "37006",
"City": "Tupambaé",
"Street": "Treinta y Tres",
"StreetNumber" : "5"
}
},
"Shipper": {
"ContactID": "276999ju7E"
},
"ShipmentUnit": [{
"Weight": 23.2
}]
},
"PrintingOptions": {
"UseDefault" : "Default"
}
}
+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:
+-
+UseDefault
+-
+DefinePrinter
+-
+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 are working on our GLS-provided central webbackends, the options "UseDefault" and "DefinePrinter" are obsolete - please use "ReturnLabels" instead.
+
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 a ZEBRA with ZPL_200):
"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "ZPL_200",
"LabelFormat": "ZEBRA"
}
}
If you want to retrieve the labels as PDF documents:
"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "NONE",
"LabelFormat": "PDF"
}
}
If you want to retrieve the labels as PNG documents:
"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "NONE",
"LabelFormat": "PNG"
}
}
To reduce the amount of data in the response you can use the two options:
"ReturnOptions": {
"ReturnPrintData": "true",
"ReturnRoutingInfo": "false"
}
+
+
If you are working on our GLS-provided central webbackends, the options "UseDefault" and "DefinePrinter" are obsolete - please use "ReturnLabels" instead.
+
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Use default printer | UseDefault | 7 | alphanumeric | Default | Optional | Default fixed value | | Uses the preset standard printer |
+
+| 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 | | | | | | | Defines the data output formats. |
+
+| Template name | TemplateSet | 7 | alphanumeric | | Optional | Must use one of the defined set | | NONE, ZPL_200, ZPL_300 |
+
+| Printer label format | LabelFormat | 8 | alphanumeric | | Optional | Must use one of the defined set | | PDF, PNG, PNG_200, ZEBRA |
+
+| Define returned data | ReturnOptions | | | | | | | Reduce the amount of data in response |
+
+| Print Data | ReturnPrintData | 5 | boolean | | Optional | true or false | | Returns the printing information and data from response. Default:true |
+
+| Routing Data | ReturnRoutingInfo | 5 | boolean | | Optional | true or false | | Returns all routing information. Default:true |
+
+
+Custom content
+
This section of the request contains several optional attributes when printing as PDF or PNG that can be found in the vertical area of the label. 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. Hint: The available character set of selected barcode type needs to be observed.
+
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"
}
If you want to hide the shipper address on the label you can define the elements like this:
"CustomContent": {
"HideShipperAddress": "true"
}
+
+| Name | Expression in webservices | Field length | Type | Format | Mandatory/Optional | Restrictions | Level | Description |
+
+| Customer logo | CustomerLogo | 255 | base64Binary | | Optional | - | | Custom content provided for label generation (f.e. customer logo) |
+
+| Barcode | Barcode | 30 | alphanumeric | | Optional | - | | Barcode to create in the label |
+
+| Barcode Content | BarcodeContentType | 7 | alphanumeric | | Optional | TRACK_ID or SHIPMENT_REFERENCE | | Creates the barcodes out of the TrackID or ShipmentReference |
+
+| Barcode type | BarcodeType | 7 | alphanumeric | | Optional | EAN_128 or CODE_39 | | The type of barcode to create in the label |
+
+| Hide shipper address | HideShipperAddress | 5 | boolean | | Optional | true or false | | Specify if the shipper address must be removed from the label |
+
+
+Input validation
+
+-
+The referenced shipper must exist and must be accessible for the user issuing the request
+-
+The referenced product group must be available to the shipper that is referenced within the request
+-
+If services are listed, those services must exist and be available to the referenced shipper
+-
+If an incoterm is provided, this incoterm must be available
+-
+The shipment must be valid (no defined validation rule may be violated)
+
+
+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:
+-
+ShipmentReference - The given ShipmentReference from the request.
+-
+ParcelData
+-
+PrintData - If requested, the print data (content) with the corresponding format (PDF, ZEBRA, etc.).
+-
+CustomerID - The ID of the customer to whom the specified shipper belongs.
+-
+PickupLocation - The location where the shipment has to be picked up.
+-
+GDPR - Information about our Group data protection web site.
+-
+Nemonico - Information about Spanish routing.
+
+
+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"
}
In some countries, different routings may apply as you can see for the German example below:
"RoutingInfo": {
"GeoTour":"1829",
"LoadingArea":"7",
"DispositionFlag":"c"
"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.
"NDIArea": {
"NDI1D": "994010486057566095",
"CHParcelNumber": "99.40.104860.57566095",
"CHPRI1D": "0509",
}
+HandlingInformation
+
There are some pre-defined shorthand symbols which are returned in HandlingInformation:
+-
+Express product: T
+-
+Small (weight): S
+-
+Heavy (weight): X
+
+
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 https://localhost:8443/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_flexdelivery"
}
}
]
},
"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": "FlexDeliveryService",
"Information": []
}
]
}
}
],
"CustomerID": "abcdefghij",
"PickupLocation": "DE 777",
"GDPR":["Informationen zum Datenschutz in der GLS-Gruppe finden Sie unter","gls-group.eu/dataprotection"]
}
}
If the request was syntactically correct, but there were 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
+
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. 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
+
+
+Input validation
+
+-
+The referenced shipper must exist and must be accessible for the user issuing the request
+-
+The referenced product group must be available to the shipper that is referenced within the request
+-
+If services are listed, those services must exist and be available to the referenced shipper
+-
+If an incoterm is provided, this incoterm must be available
+-
+The shipment must be valid (no defined validation rule may be violated)
+
+
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 https://localhost:8443/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
+
This operation 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 of the issuing of the request, it will be retried at a later time.
+ The REST service will not wait for the request to be executed, it will return after the request has been scheduled successfully. A second call with the same parcel identifier will respond with error 500.
+ Return parcels can only be cancelled through your responsible depot. A webservice can be called but this does not have any operational impact.
+
- The REST method is available at sub-path
/cancel/{trackID} with http request method POST
+
+
+| Parameter | Mandatory | Location in Request | Description |
+
+| trackID | TRUE | path param | The track ID of the parcel that should be canceled. |
+
+
+Input validation
+
+-
+A parcel with the given ID must exist
+-
+The parcel must belong to a shipper to which the user issuing the request has access to
+
+
The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.CancelParcelResponse or one of the following faults:
+
+Sample request
+
POST https://localhost:8443/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
+
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. It is not checking if the routing between these 2 addresses is possible.
+
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
+
+
+Input validation
+
In case that more than 1 ContactID is provided: REST will use the last parameter inserted.
+
The zip code must 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 https://localhost:8443/backend/rs/shipments/allowedservices
POST data:
{
"Source":{
"CountryCode":"DE",
"ZIPCode":"38106"
},
"Destination":{
"CountryCode":"DE",
"ZIPCode":"65779"
}
}
It is possible to add a specific shipper as an optional parameter to the request above, in order to get the allowed services for that shipper only:
+
POST data:
{
"Source":{
...
},
"Destination":{
...
},
"ContactID":"1234567890"
}
+Sample response
+
If the request was successful:
{
"AllowedServices": [{
"ProductName": "PARCEL"
}, {
"ProductName": "EXPRESS"
},
...
{
"ServiceName": "service_flexdelivery"
}, {
"ServiceName": "service_pickpack"
}, {
"ServiceName": "service_documentreturn"
}, {
"ServiceName": "service_1300"
}, {
"ServiceName": "service_addresseeonly"
}, {
"ServiceName": "service_tyre"
}
]
}
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
+
Executes the end of day procedure for the given day and returns all shipments that where affected by the end of day procedure. On webbackends and ShipIT Farm the end of day is automatically processed 4 days after label creation.
+
- The REST method is available at sub-path
/endofday with http request method POST
+
+
+| Parameter | Mandatory | Location in Request | Description |
+
+| date | TRUE | query param | Shipping or pick up day for which the end of day procedure should be executed |
+
+
The end of day procedure does the following things:
+-
+Ensure that all shipment units that undergo the procedure are transmitted to GLS. That is, each unit that was not yet transmitted, will be transmitted before the procedure can finish.
+-
+All shipment units that undergo the procedure are set to CLOSED.
+
+
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:
+-
+Reports can be generated and printed during end of day (please check the chapter shipment settings in your ShipIT manual on how to configure this).
+-
+E-Mails can be send either when shipments are transmitted or during end of day (please check the chapter E-Mail Settings in your ShipIT manual).
+-
+Old shipments might be deleted during the end of day procedure (please check the chapter my settings in you ShipIT manual).
+
+
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 https://localhost:8443/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
+
Updates the weight of a shipment unit. The shipment unit will be searched by its identifiers: TrackID, ParcelNumber, PartnerParcelNumber, ShipmentReference or ShipmentUnitReference.
+
Changes are only applied if the weight change is >0.2 kg.
+
- The REST method is available at sub-path
/updateparcelweight with http request method POST
+
+
The search is restricted to the shippers to which the user issuing the request has access to.
+
+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 | 8 | alphanumeric | | Conditional | - | | Main identifier of a parcel within GLS. |
+
+| Parcel identifier (numeric) | ParcelNumber | 12 | 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. |
+
+| Parcel Weight | Weight | 10 | decimal | | Mandatory | >0.10 | | Updated weight with at least 200g difference to original weight, max. 2 decimal digits. |
+
+
The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.UpdateParcelWeightResponse or one of the following faults:
+
+Sample request
+
POST https://localhost:8443/backend/rs/shipments/updateparcelweight
POST data:
{
"TrackID": "ZDF8DOSZ",
"ParcelNumber": "P3L73019DE0001",
"PartnerParcelNumber": "202800010015",
"ShipmentReference": "567f2fb4-dd61-4aeb-9515-82f71b12c434",
"ShipmentUnitReference": "0d5145f1-7ec5-4894-ae73-c590201c6c5d",
"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: More than one parcel was identified matching the input criteria. Please redefine criteria to narrow down to one parcel.
error: MORE_THAN_ONE_RESULT
Content-Length: 0
args: []
If the shipment unit cannot be found by the provided reference numbers:
Response headers:
HTTP/1.1 400 Bad Request
message: No shipment unit found for parcel identifier(s) b1119328-584f-4745-9571-d716bbd37656
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: []
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: No shipment unit found for parcel identifier(s) b1119328-584f-4745-9571-d716bbd37656
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: []
If a mandatory parameter is not provided:
Response headers:
HTTP/1.1 400 Bad Request
message: At least one parcel identifier is required.
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: []
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"]
+reprintParcel
+
This REST endpoint reprints the label, cancelling the old one.
+
- The REST method is available at sub-path
/reprintparcel with http request method POST
+
+
At least one of these identifiers must be provided. The parts of the request are explained in the following sections in more detail:
+
+-
+TrackID - Identifier for the parcel.
+-
+ParcelNumber - Identifier for the parcel, 1D barcode printed in the label.
+-
+ShipmentReference - Identifier for the parcel, reference for this consignment of parcels
+-
+ShipmentUnitReference - Identifier for the parcel, reference given to the parcel.
+-
+PartnerParcelNumber - Option for network partners to hand over their own reference.
+-
+CreationDate - Date when the parcel was created, to narrow search for non-unique identifiers like references.
+-
+Printing options
+-
+Custom content
+
+
+Input validation
+
+-
+One of trackID/ParcelNo/ShipmentReference/ShipmentUnitReference/PartnerParcelNumber must identify a shipment unit. 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 |
+
+| Track identifier | TrackID | 8 | alphanumeric | | Optional | - | | Identifier for the parcel. Used for a reprintParcel request |
+
+| 1D barcode number | ParcelNumber | 12 | alphanumeric | | Optional | - | | 1D barcode printed in the label |
+
+| Customer reference number | ShipmentReference | 40 | alphanumeric | | Optional | - | | Reference for this consignment of parcels |
+
+| Parcel reference | ShipmentUnitReference | 40 | alphanumeric | | Optional | - | | Reference given to the parcel |
+
+| Partner's parcel number | PartnerParcelNumber | 50 | alphanumeric | | Optional | - | | Option for network partners to hand over their own reference |
+
+| Creation date | CreationDate | 10 | alphanumeric | YYYY-MM-DD | Optional | - | | Date when the parcel was created |
+
+| Define printer for return labels | ReturnLabels | | | | | | | Defines the data output formats. |
+
+| Template name (basic) | TemplateSet | 7 | alphanumeric | | Optional | Must use one of the defined set | | NONE, ZPL_200, ZPL_300 |
+
+| Printer label format | LabelFormat | 8 | alphanumeric | | Optional | Must use one of the defined formats | | PDF, PNG, PNG_200, ZEBRA |
+
+
The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.shipmentprocessing.ReprintParcelResponse or one of the following faults:
+
+Sample request
+
{
"ShipmentReference" : "OLD556",
"CreationDate" : "2020-02-19",
"PrintingOptions": {
"ReturnLabels": {
"TemplateSet": "NONE",
"LabelFormat": "PDF"
}
}
}
+Sample response
+
On successful reprint:
{
"CreatedShipment":{
"ParcelData":[
{
"TrackID":"YQ26KY68",
"ShipmentUnitReference":[
"NEW772"
],
"ParcelNumber":"000000000009",
"Barcodes":{
"Primary2D":"ADE 777 abcdefghij276equiul YQ26KY68AA 1 081965760 00420001001 ",
"Secondary2D":"A|GLS|Helfmannpark|Eschborn|1|NEW772|SHM998| ",
"Primary1D":"000000000009",
"Primary1DPrint":true
},
"RoutingInfo":{
"Tour":"0819",
"InboundSortingFlag":"10",
"FinalLocationCode":"DE 934",
"HubLocation":"",
"LastRoutingDate":"1970-01-01"
}
}
],
"PrintData":[
{
"Data":"JVBERi0xLjUKJeLjz9MlJUVPRgo=",
"LabelFormat":"PDF"
}
],
"CustomerID":"abcdefghij",
"PickupLocation":"DE 777",
"GDPR":[
"Informationen zum Datenschutz in der GLS-Gruppe finden Sie unter",
"gls-group.eu/dataprotection"
]
}
}
If the request points to more than one shipment unit (specifying a date may narrow the search):
+
Response headers:
HTTP/1.1 400 Bad Request
Connection: keep-alive
message: More than one parcel was identified matching the input criteria. Please redefine criteria to narrow down to one parcel.
serverExecutionTime: 24
error: MORE_THAN_ONE_RESULT
Content-Length: 0
args: []
Date: Tue, 13 Jun 2023 10:13:23 GMT
If the shipment unit cannot be found by the provided parcel identifier:
+
Response headers:
HTTP/1.1 400 Bad Request
Connection: keep-alive
message: Invalid shipment unit number SHM998: No shipment unit found for ShipmentReference SHM998
serverExecutionTime: 20
error: INVALID_SHIPMENT_ID
Content-Length: 0
args: ["SHM998","No shipment unit found for ShipmentReference SHM998"]
Date: Tue, 13 Jun 2023 10:13:25 GMT
If no parcel identifier parameter is provided:
+
Response headers:
HTTP/1.1 400 Bad Request
Connection: keep-alive
message: The Mandatory parameter to identify the parcel is not set
serverExecutionTime: 15
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["to identify the parcel"]
Date: Tue, 13 Jun 2023 10:13:23 GMT