Label request

Version: 1.0, Date: 2025-02-21

Revision history

Date	Version	Description
2025-02-21	1.0	Initial version.

Business process

For all except France pre-packing process: SAP E-WMS picks & packs handlingUnits (SSCCs)
SAP E-WMS requests shipping labels from Viya for the SSCC
Viya returns the label in ZPL format
SAP E-WMS prints the label on the printer
For France pre-packing process: goods are picked & packed in the warehouse

Business rules

Carrier & service is determined in SAP based on destination/pallet vs carrier.
Parcel shipments:
- Only destination within European Union, no export.
- Will be booked per parcel with the carrier. Deliveries with more than 1 parcel will result in multiple shipments at the carrier.
  - This is because we will only know the actual number of parcels at the time of the label request. If multiple parcels are requested in one transaction, the parcels are booked together as 1 shipment.
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.

1 Per handlingUnit

If processing per ‘handlingUnit’ is applied: so the packer packs & labels 1 SSCC at a time without knowing what the other SSCCs of that same delivery will be: then 1 label is requested at a time.

2 Multiple handlingUnits

If more than 1 handlingUnits are requested in one transaction: then multiple labels are requested at a time.

Example:
- The packer packs & labels multiple SSCCs at a time
- FR pre-packing process: A multi-piece shipment is pre-printed and then packed in the warehouse.

In this scenario all SSCCs in the request will be communicated to the carrier as 1 shipment.

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 label

Goal

Request a shipping label for a handling unit.

The total number of handling Units for a given shipment does not have to be known at this time.

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:
- Only submit the handlingUnit(s) that need a label
  - This means:
    - Requesting label for first pallet contains 1 handlingUnit.
    - Requesting label for second pallet contains only handlingUnit 2, etc..
    - If more than 1 handlingUnit is provided, then the labels for all handlingUnits are provided.
    - Any of the handlingUnits that where not already provided, will be added to the shipment.
- 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.
- A handlingUnit with an sscc that is already known is only updated if no label has been generated yet for the shipment. If a label is generated, the handlingUnit is NOT updated: simply the same label is returned.
- The handlingUnits.sequence is always 1 when there is only 1 handlingUnit in the request.
- Every POST to this endpoint until the first label is generated: will determine all the shipment details. Subsequent calls will only add handlingUnits to the shipment.
- 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"
        }
      ]
    }
  ],
  "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 labelling 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:
  - For pallet carriers (these are carriers that supports partly Labelling)
    - Delete the shipment in Viya platform and relabel all handlingUnits for the given shipment
  - For parcel carriers (these are carriers that do not support partly Labelling)
    - Delete the shipment for the respective handlingUnit in Viya platform and resubmit the request for labelling again