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:

Envisioned process

Request

Method: POST

Headers:

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

Endpoint:

Payload:

{
  "reference": "Reference for the despatch-advice/manifest, unique per despatch-advice",
  "preAdviceReference": "Reference from the pre-advice, used to link the pre-advice to the 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
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