Label request

Version: 2.1, Date: 2025-06-27

Revision history

DateVersionDescription
2025-02-211.0Initial version.
2025-05-072.0Updated to have all HU packed before labelling
2025-06-272.1added View the Shipment API schema documentation

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.
    • Viya will translate the carrier and service level codes to the carrier specific codes.
  • 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

  • The endpoint is available for testing using a pre-defined carrier and service level. While carrier integrations become available, they can also be tested.

Request labels

Goal

Request shipping labels for all handling units inside a shipment.

Request & response

For the request, response and samples: see Shipment API schema documentation.

Payload:

  • See Shipment API schema documentation for schema and samples for request and response.
  • 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 can be left empty, use transportServices.shipperAssigned.carrierReference instead.
    • The shipment.serviceLevelReference can be left empty, use transportServices.shipperAssigned.serviceLevelReference instead.
    • The transportServices.shipperAssigned.carrierReference should contain the SAP code (only 0-9 and a-Z allowed), which can also be maintained in Viya.
      • Note: this value is only used if the carrierReference in the root of the message is not provided.
    • The transportServices.shipperAssigned.serviceLevelReference should contain the SAP code for the service level. Viya will translate this to the carrier specific serviceLevelReference.
      • Note: this value is only used if the serviceLevelReference in the root of the message is not provided.
    • 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.

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