Label request
Version: 2.0, Date: 2025-05-06
Revision history
Date | Version | Description |
---|---|---|
2025-02-21 | 1.0 | Initial version. |
2025-05-07 | 2.0 | Updated 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.
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:
- Production: https://aalbertshfc.viya.me/api/custom/shipment-label-request/v1
- Test: https://aalbertshfc.viya.me/api/custom/shipment-label-request/v1?environment=test
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 thehandlingUnits.references.reference
field. - The
sscc
is the unique identifier for the handlingUnit. That field determines if a handlingUnit is new or already known. If nosscc
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 theDeliverynumber
from the WMS. - The
Deliverynumber
is also passed in theshipment.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 asender
andtransport
account for the respective carrier as setup in Viya for address with referencecarriers-{locationreference}
.- The
{locationReference}
is the location reference of the sender, identical to thelocationReference
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.
- The
- The
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
- Some examples: