Label request

State

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

The proposed summary endpoint combines and simplifies the following endpoints:

• Shipment creation
• Shipment ordering
• Shipment labels

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 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