Label request

Version: 2.1, Date: 2024-09-20

Revision history

DateVersionDescription
2024-09-021.0Initial version.
2024-09-092.0Added more details on the request label process.
Printing by Viya (PrintNode) instead through WMS
2024-09-202.1Feedback during review with WMS partner
2024-11-262.2Add default servicelevelReference
2024-12-042.3Add providePrinters=true

Business process:

  • WMS receives order from Navision and picks & packs the handling units.
  • For each handling unit a shipping label is requested to print from Viya. Viya prints the shipping label and returns tracking number.
  • The label is printed through the WMS Viya using PrintNode and attached to the handling unit.
  • The tracking number is updated in Navision through WMS.
  • When shipment is completely packed, WMS sends message to Viya to finalize shipment.
  • When shipment is loaded and ready for departure, WMS sends message to Viya to confirm load.

Integration touch points

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

Diagram

Steps 1,3,4,6,7,9 are all same integration: Request label print, just different moments in the process.

Steps 10 & 11 is a separate integration: Pack shipment.

Steps 12 & 13 is a separate integration: Manifest.

Request label print

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 printed.
        • 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 printed yet for the shipment. If a shipment is printed, the handlingUnit is NOT updated: simply a reprint is done.
    • The handlingUnits.sequence is always 1 when there is only 1 handlingUnit in the request.
      • WMS will never send more than 1 handlingUnits in the request.
    • The printer to use is passed in an additional object printer.printNode in the root. See details in the Printing chapter.
      • If no printer is provided or cannot be found: an error is returned.
    • Every POST to this endpoint until the first printed label: will determine all the shipment details. Subsequent calls will only add handlingUnits to the shipment.
    • The shipment.reference contains the ShippingBillNumber from the WMS. For Indetex there will only be 1 order per wms ShippingBillNumber at this moment but the WMS can have multiple orders for the same ShippingBillNumber in the future.
    • The Indetex/Navision order number MP/24/... is passed in the shipment.references.sapDelivery field.
      • This is Mandatory, if it is missing an error is returned.
      • If multiple orders would get consolidated into one ShippingBillNumber, the multiple values can be comma separated:
        • Eg:shipment.references.sapDelivery = MP/24/11897,MP/24/11898
    • 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 “Transporteur code” is the same between Navision/WMS/Viya.
      • Since Viya does not allow spaces, +, & in the carrierReference field that is used for the the “Transporteur code”, Viya maintains a translation table for these characters inside the integration
    • WMS needs a barcode on the label that can be used to load the handlingUnit onto pallets.

      • For all carriers this is the sscc, but for DPD that sscc is not on the label.. so wms would either need to receive the barcode from DPD OR print the sscc on the DPD label too..

      • For time being added the sscc to the label for DPD too, in the section for the references, if the label used is longer than 15cm it can also be printed at the bottom:

        View Example label:

        alt text

    • The shipment.serviceLevelReference is left empty by WMS, Viya will fill this in based on the carrier selected in the price request.
      • To facilitate testing following additions are implemented:
        • If the shipment.serviceLevelReference is provided, it will be used.
        • For certain carriers a default servicelevel is set in Viya, this will be used if no servicelevel is provided and no price selection for that shipment was done. Defaults are:
          • DHL: ECONOMY
          • DPD: CLASSIC
          • GEODIS: EUROFIRST
          • INTERTRANS: EXPORT
          • KEUHNE+NA: STANDARD
          • MAINFREIGH: STANDARD
          • ON-TIME: DISTRI
          • SCHENKER: STANDARD
          • TRANSUNI: EXPORT
          • UPS: STANDARD
          • UPS-KLANT: STANDARD
    • The shipment.accounts is defaulted with a sender and transport account for the respective carrier as setup in Viya for address with reference indetex-nvsas. This means: if a carrier needs an account number: configure the account number in the Viya addressbook, the integration will pick it up.

Response:

OK response:
Error response:

See Error Responses

Exception scenarios

  • Printer is not available
    • Corrective action:
      • Check printer:
        • Check if the printer is switched on, has paper, etc..
        • Check PrintNode if the printer is online
        • Check in Viya if PrintNode API key is present and correct
      • After printer check: resubmit the request
  • Label is damaged or did not come out of printer or a copy of the label is needed
    • Corrective action: Resubmit the request for labelling again
  • 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
    • Some examples:
      • Pallet/Roll is labelled but then cannot be fulfilled anymore. (eg fully damaged)
      • Pallet/Roll is labelled but dimensions or weight are incorrect. (eg additional rolls added, or rolls removed)
    • Corrective action:
      • For carrier that supports partly Labelling
        • Delete the shipment in Viya platform and relabel all handlingUnits for the given shipment
      • For carrier that does not support partly Labelling
        • Delete the shipment for the respective handlingUnit in Viya platform and resubmit the request for labelling again

Pack shipment

Goal

Inform Viya that the shipment is packed, all carrier labels are requested for the handling units, and ready for transport.

Request

Method: PUT Headers:

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

Endpoint:

Payload: Contains all handlingUnit references that are packed for the shipment.

{
  "reference": "string the ShippingBillNumber",
  "handlingUnitReferences": ["sscc1", "sscc2"]
}

Response

OK response:

http: 202

  • payload: none
Error response:

See Error Responses

Exceptions

  • Shipment already packed: response will still be 202
    • Corrective action: No action required
  • Shipment not found: 400 error response
    • Corrective action: Adjust the shipment reference and resubmit the request
  • HandlingUnit not found: response will still be 202
    • Corrective action: No action required

Manifest

Goal

Confirm the handlingUnits loaded for departure.

  • This is one message for all handlingUnits in a trailer consignment.
  • HandlingUnits of multiple shipments can be included the manifest.

Request:

Method: POST

Headers:

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

Endpoint: (to be confirmed)

Payload:

{
  "reference": "Reference for the manifest, unique per manifest",
  "carrierReference": "Carrier reference/transporteurcode for the manifest eg DPD or Mainfreight",
  "locationReference": "fixed string to indicate the location, must match Viya shipping location reference: MOESKROEN",
  "pickupMoment": "2024-09-03T14:00:00+02:00 --> Note: timezone specification is required",
  "shipments": [
    {
      "reference": "ShippingBillNumber shipment1",
      "handlingUnitReferences": ["sscc1", "sscc2"]
    },
    {
      "reference": "ShippingBillNumber shipment2",
      "handlingUnitReferences": ["sscc3", "sscc4"]
    }
  ]
}

Response

OK response:

Http: 200

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08 --> unique identifier for the manifest",
  "reference": "reference as proviced in the request",
  "carrierAssignedReference": "if carrier assigned a reference, it is returned here",
  "documents": [],
  "resultMessages": ["Any information message that is relevant for the manifest"]
}
Error response:

See Error Responses

Exceptions

Functional exceptions:

  • Add or Remove handlingUnit after manifest is communicated with carrier:
    • Existing shipments/manifest cannot be changed anymore: the manifest is final.
    • Recovery action:
      • Manually inform the carrier of shipment communicated but not loaded
      • Relabel affected shipment (if manifest contains multiple shipments, only the affected shipment should be re-processed) with new shipment references and manifest again.

Technical exceptions:

  • Manifest already confirmed with same hundlingUnits: response will still be 200
    • Recovery action: No action required
  • Manifest reference already used with other handlingUnits and ordered with carrier: 400 error response
    • Recovery action: resubmit the complete manifest with new reference
  • Manifest reference already used with other handlingUnits and not yet ordered: 200 response
    • Recovery action: No action required, it will overwrite old manifest
  • HandlingUnit not found: 400 error response,
    • Recovery action:
      • If handlingUnit should be included: do a label request for that missing handlingUnit
      • Resubmit the complete manifest with correct handlingUnits
  • Shipment not reported packed: 400 error response
    • Recovery action: First send a pack shipment request for the shipment, then resubmit the manifest.
  • Carrier integration failed: 400 error response
    • This should not happen as the label generation should then already have stopped the process. This must be an incident on communication.
    • Recovery action: resubmit the complete manifest with correct handlingUnits

Error responses

  • Http: 4xx or 5xx
  • payload:
{
  "type": "string",
  "title": "Compact error message",
  "status": 400,
  "detail": "Error message",
  "instance": "string",
  "errors": [
    {
      "code": "string",
      "message": "Optional: Detailed error message",
      "explanation": "Optional: Extra explanation on cause and sometimes instructions how to resolve"
    }
  ]
}

Printing

Printing via PrintNode is done by Viya.

  • The PrintNode API key is purchased by Indetex and entered in Viya.
  • Question: Printers support ZPL II in 203 DPI? (TEC/Toshiba or Zebra?) or should we only print PDF?

In the request to Viya, the printer to use is passed in the printer.printNode object in the root.

  • Use the printNode.id to assign the specific printnode printer. This id is the unique identifier for the printer in PrintNode.
{ 'printer': { 'printNode': { 'id': '72001929', 'name': '' } }, ... }
  • If the printNode.id is unknown the printer printNode.name can be used, Viya will use this name to find the printer in PrintNode. This name is the printer name as assigned in your operating system and synchronized with PrintNode.
{ 'printer': { 'printNode': { 'id': '', 'name': 'packstation1Printer' } }, ... }

Below picture shows where to find the printer name and Id in printnode and windows. printNode and windows

No printer found

In the event no printer is found, an error is returned like

{
  "type": "about:blank",
  "title": "Printer id not found",
  "status": 400,
  "detail": "Printer Id 72001929ABC not found",
  "instance": "/customers/indetex/print-label-request",
  "errors": [
    {
      "code": "PRINTER_ID_NOT_FOUND",
      "message": "Printer Id 72001929ABC not found",
      "explanation": "Check your PrintNode API key and check in PrintNode if the printer is still available. To get a list of available printers, add providePrinters=true to the URL of the request"
    }
  ]
}

To see the printers available in PrintNode, add providePrinters=true to the URL of the request. This will return a list of first 100 available printers in the explanation. This feature is placed behind a querystring to avoid large responses in normal requests. Example response:

{
  "type": "about:blank",
  "title": "Printer id not found",
  "status": 400,
  "detail": "Printer Id 72001929ABC not found",
  "instance": "/customers/indetex/print-label-request",
  "errors": [
    {
      "code": "PRINTER_ID_NOT_FOUND",
      "message": "Printer Id 72001929ABC not found",
      "explanation": "Check your PrintNode API key and check in PrintNode if the printer is still available. Available printers: 73555650: Servername\\printername1,  73555609: Servername1\\printername2,  73555608: etc\\etc.."
    }
  ]
}