Label request

Version: 2.0, Date: 2025-05-06

Revision history

DateVersionDescription
2025-02-211.0Initial version.
2025-05-072.0Updated to have all HU packed before labelling

Business process

  • For all, except France pre-packing process: SAP E-WMS picks & packs handlingUnits (SSCCs)
  • SAP E-WMS requests shipping labels from Viya the complete deliver Order
  • Viya returns the labels in ZPL format, SAP stores the ZPL label per handlingUnit
  • SAP E-WMS prints the label on the printer when user scanned the handlingUnit (SSCC)
  • For France pre-packing process: goods are picked & packed in the warehouse and carrier label printed prior to picking.

Business rules

  • Carrier & service is determined in SAP based on destination/pallet vs carrier.
  • Parcel shipments:
    • Only destination within European Union, no export.
  • Pallet shipments:
    • Destinations can be both within or outside European Union, customs paperwork are handled outside of Viya.
  • SAP expects to NOT send commercial invoice data to Viya.

Integration touch points

Below diagram shows the interaction between WMS and Viya for the label request process.

Diagram

State

  • Individual endpoints are available in production
  • Summary endpoint will be developed within project

The proposed summary endpoint combines and simplifies the following endpoints:

Request labels

Goal

Request shipping labels for all handling units inside a shipment.

Request:

Method: POST Headers:

  • Content-Type: application/json
  • x-api-pat: is provided by Viya

Endpoint:

Payload:

  • As a base: see request of “Shipment > Create a new shipment”.
  • Some examples: “print-label-request-samples”.
  • Specifics for this integration:
    • The sscc is passed in the handlingUnits.references.reference field.
    • The sscc is the unique identifier for the handlingUnit. That field determines if a handlingUnit is new or already known. If no sscc is provided, an error is thrown.
    • Every POST to this endpoint until the first label is generated: will determine all the shipment details. Subsequent calls will only return the same set of labels.
    • The shipment.reference contains the Deliverynumber from the WMS.
    • The Deliverynumber is also passed in the shipment.references.sapDelivery field.
      • This is Mandatory, if it is missing an error is returned.
    • The timewindows.pickup.requested should be used for the current or future time. This is the date for when the shipment is expected to be picked up.
    • The carrierReference is the SAP code (only 0-9 and a-Z allowed), which can also be maintained in Viya.
    • The shipment.serviceLevelReference has to be agreed for each carrier/service combination.
    • The shipment.accounts is defaulted with a sender and transport account for the respective carrier as setup in Viya for address with reference carriers-{locationreference}.
      • The {locationReference} is the location reference of the sender, identical to the locationReference in the payload.
      • This means: if a carrier needs an account number: configure the account number in the Viya addressbook, the integration will pick it up.
      • if a carrier account is known in SAP it can be passedin the shipment.accounts section of the payload.

Response:

OK response:
  • Http: 200
  • It will contain the ZPL label for the requested handlingUnit(s) Example:
{
"carrierReference": "DACHSER",
"serviceLevelReference": "Targospeed",
"trackingReference": "123454840",
"handlingUnits": [
{
"sequence": 1,
"reference": "SSCC123459015",
"trackingReference": "ABCD12315460",
"labels": [
{
"format": "zpl",
"base64Content": "base64 encoded ZPL label"
}
]
},
{
"sequence": 2,
"reference": "SSCC123459016",
"trackingReference": "ABCD12315461",
"labels": [
{
"format": "zpl",
"base64Content": "base64 encoded ZPL label 2"
}
]
}
],
"resultMessages": ["string"]
}
Error response:

See Error Responses

Exception scenarios

  • Shipment error that prevents generating a label
    • Eg, Address is not correct, Carrier unknown, servicelevel unknown, etc..
    • Corrective action:
      • Adjust the shipment details in WMS and resubmit the request for label again
  • Pallet needs to be changed after label is printed but not yet manifested/despatch-adviced
    • Some examples:
      • Pallet is labelled but then cannot be fulfilled anymore. (eg fully damaged)
      • Pallet is labelled but dimensions or weight are incorrect. (eg additional colli added, or colli removed)
    • Corrective action:
      • Delete the shipment in Viya platform and relabel all handlingUnits for the given shipment