Despatch-advice

Purpose

Confirm what was actually shipped to the carrier.

State

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

The proposed summary endpoint combines and simplifies the following endpoints:

• Consignment creation
• Consignment ordering

Envisioned process

Request

Method: POST

Headers:

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

Endpoint:

• Production: https://aalbertshfc.viya.me/api/custom/despatch-advice/combined/v1
• Test: https://aalbertshfc.viya.me/api/custom/despatch-advice/combined/v1?environment=test

Payload:

{
  "reference": "Reference for the despatch-advice/manifest, unique per despatch-advice",
  "carrierReference": "Carrier reference/transporteurcode for the despatch-advice eg GEODIS or DACHSER",
  "locationReference": "fixed string to indicate the location, must match Viya shipping location reference: expect the SAP location to be stored as the location reference",
  "pickupMoment": "2024-09-03T14:00:00+02:00 --> Note: timezone specification is required",
  "shipments": [
    {
      "reference": "SAP E-WM delivery reference1",
      "handlingUnitReferences": ["sscc1", "sscc2"]
    },
    {
      "reference": "delivery reference2",
      "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 despatch-advice is communicated with carrier:
  • Existing shipments/despatch-advice cannot be changed anymore: the despatch-advice is final.
  • Recovery action:
    • Manually inform the carrier of shipment communicated but not loaded
    • Relabel affected shipment (if despatch-advice contains multiple shipments, only the affected shipment should be re-processed) with new shipment references and sent despatch-advice again.

Technical exceptions

• Despatch-advice already confirmed with same hundlingUnits: response will still be 200
  • Recovery action: No action required
• Despatch-advice reference already used with other handlingUnits and ordered with carrier: 400 error response
  • Recovery action: resubmit the complete Despatch-advice with new reference
• Despatch-advice reference already used with other handlingUnits and not yet ordered: 200 response
  • Recovery action: No action required, it will overwrite old Despatch-advice
• HandlingUnit not found: 400 error response,
  • Recovery action:
    • If handlingUnit should be included: do a label request for that missing handlingUnit
    • Resubmit the complete Despatch-advice 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 Despatch-advice with correct handlingUnits