In technical terms, lightweight notifications in APIs (Application Programming Interfaces) refer to a messaging pattern where the API sends concise and focused messages to notify clients or subscribers about specific events or changes. These notifications are designed to be minimalistic in terms of data payload and typically contain only essential information such as identifiers or key data elements relevant to the event, allowing the recipient to understand the context and take appropriate action without the need for extensive data transfer.
Lightweight notifications have been applied across DCSA standard-based APIs, replacing shipment events as a push mechanism for real-time updates. All parties can independently and optionally subscribe to lightweight notifications supporting the Bill of Lading process defined in this standard. If subscribed, the API consumer (e.g. Shipper, Consignee) is notified whenever the state or content of a Shipping Instructions or Transport Document changes, eliminating their need to proactively poll the GET endpoints for updates. With the transition from polling to lightweight notifications, Carriers benefit from reduced load on their systems, and all parties benefit from reduced network traffic and improved business process latency, facilitating efficient interaction between different systems.
The following applies whenever the Carrier sends a lightweight notification:
The Carrier independently sends the notification to each relevant counterpart who has registered to receive API notifications for the use cases of this standard. The registration mechanism, life cycle and any filtering are out of scope for this standard.
The Carrier sends the lightweight notifications asynchronously, after updating the state and/or content of the document in its own systems. If sending the lightweight notification fails, that does not constitute a use case exception and the Carrier must not revert any of the changes already performed in its own system: the relevant counterpart can be notified out of channel or will receive the update upon a subsequent GET request called to the same API for the same document.
If the Carrier cannot or does not want to accept the API request (e.g. when the Shipper requests to cancel a Shipping Instructions update which is already being processed), it responds with the appropriate error message and HTTP status code. The Carrier does not change the state or content of the document, and it does not send a lightweight notification about the rejected API request.
The following use cases have been defined by DCSA to submit Shipping Instructions, publish, and approve a Draft Transport Document and the issuance, amendment and surrender of a Transport Document. The complete list of use cases supporting the Bill of Lading process is shown below.
# | Use case name | [Actor] to [Actor] |
---|---|---|
1 | Submit Shipping Instructions | Shipper to Carrier |
2 | Request to update Shipping Instructions | Carrier to Shipper |
3 | Submit updated Shipping Instructions | Shipper to Carrier |
4 | Process updated Shipping Instructions | Carrier to Shipper |
5 | Cancel update to Shipping Instructions | Shipper to Carrier |
6 | Publish Draft Transport Document | Carrier to Shipper |
7 | Approve Draft Transport Document | Shipper to Carrier |
8 | Issue Transport Document | Carrier to Shipper |
9 | Request surrender Transport Document (amendment) | Shipper or Consignee to Carrier |
10 | Process Transport Document surrender request (amendment) | Carrier to Shipper |
11 | Void original Transport Document and issue amended Transport Document | Carrier to Shipper |
12 | Request surrender Transport Document (delivery) | Consignee to Carrier |
13 | Process Transport Document surrender request (delivery) | Carrier to Consignee |
14 | Confirm Shipping Instructions completed | Carrier to Shipper |
Shipper to Carrier
The Shipper submits the Shipping Instructions (SI).
The Shipping Instructions are in state RECEIVED.
Carrier to Shipper
The Carrier requests that the Shipper submits an update to the Shipping Instructions.
The Shipping Instructions are in one of the following states:
The Shipping Instructions are in state PENDING UPDATE.
Shipper to Carrier
The Shipper submits updated Shipping Instructions.
The Shipping Instructions are in one of the following states:
The original Shipping Instructions are in the same state as in the preconditions. The updated copy of the Shipping Instructions is in state UPDATE RECEIVED.
Whether or not requested by the Carrier, the Shipper submits an updated version of the Shipping Instructions.
UC3 supports the following user stories:
The Shipper may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.
The Shipper cannot update Reefer or Dangerous Goods details in the Shipping Instructions. In this case, a Booking amendment must be requested via UC7 Request amendment to confirmed Booking (see [Booking use cases])
Carrier to Shipper
The Carrier reviews the updated copy of the Shipping Instructions and decides whether the proposed changes can be confirmed.
The original Shipping Instructions are in one of the following states:
The updated copy of the Shipping Instructions is in state UPDATE RECEIVED.
There are 2 possible scenarios:
If the update is confirmed: The original Shipping Instructions are in state RECEIVED. The updated copy of the Shipping Instructions is in state UPDATE CONFIRMED.
If the update is declined: The original Shipping Instructions are in the same state as in the preconditions. The updated copy of the Shipping Instructions is in state UPDATE DECLINED.
The Carrier performs an initial synchronous processing of the request to update the Shipping Instructions. Whether or not the Carrier will accept the proposed changes, and whether or not it will request additional changes (via UC2 Request to update Shipping Instructions), the Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling above.
There are 2 possible scenarios:
Shipper to Carrier
The Shipper cancels the update to the Shipping Instructions.
The original Shipping Instructions are in one of the following states:
RECEIVED
PENDING UPDATE (if the Carrier has requested that updated Shipping Instructions be submitted)
The updated copy of the Shipping Instructions is in state UPDATE RECEIVED.
The Shipper cancels the updated version of the Shipping Instructions.
The Carrier performs an initial synchronous processing of the request to cancel the updated copy of the Shipping Instructions. The Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling.
The Carrier keeps the original Shipping Instructions unchanged (including their state) and cancels the updated copy of the Shipping Instructions with the changes requested by the Shipper, setting its state to UPDATE CANCELLED.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Shipping Instructions reference and/or the Transport Document reference, the state of the original and of the updated copy of the Shipping Instructions.
The Shipper may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.
Carrier to Shipper
The Carrier publishes the Draft Transport Document based on the input provided by the Shipper in the Shipping Instructions and the Booking request/amendment.
The following conditions must apply:
In addition, the following condition may apply:
The Transport Document is in state DRAFT.
The Carrier publishes the Draft Transport Document and updates the state of the Transport Document to DRAFT.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.
If the Shipper has requested an amendment to the Draft Transport Document via UC3 Submit updated Shipping Instructions or via UC7 Request amendment to confirmed Booking (see Booking use cases) while the Transport Document is in state DRAFT, the Carrier may publish a new Draft Transport Document for Shipper approval following the steps described above, based on the last Booking amendment or update to the Shipping Instructions that was confirmed.
Shipper to Carrier
The Shipper approves the Draft Transport Document.
The Transport Document is in state DRAFT.
The Transport Document is in state APPROVED.
Carrier to Shipper
The Carrier issues the Transport Document to the Shipper.
The Transport Document is in one of the following states:
The Transport Document is in state ISSUED.
Shipper or Consignee to Carrier
The Shipper or Consignee requests the Carrier to surrender the Transport Document for an amendment.
The Transport Document is in state ISSUED.
The Transport Document is in state PENDING SURRENDER FOR AMENDMENT.
Carrier to Shipper or Consignee
The Carrier processes the surrender request for amendment of the Transport Document to ensure that it complies with the terms and conditions specified in the Transport Document and any associated trade documents or trade finance instruments, such as a Letter of Credit (LC). The Carrier verifies the authenticity of the request and the identity of the requesting party and decides whether the surrender request can be accommodated.
The Transport Document is in state PENDING SURRENDER FOR AMENDMENT.
There are 2 possible scenarios:
There are 2 possible scenarios:
Carrier to Shipper or Consignee
The Carrier voids the original Transport Document that was surrendered for amendment by the Shipper or Consignee and issues a new Transport Document, including the requested amendment.
The Transport Document is in state SURRENDERED FOR AMENDMENT.
Consignee to Carrier
The Consignee requests the Carrier to surrender the Transport Document to take delivery of the cargo at destination.
The Transport Document is in state ISSUED.
The Transport Document is in state PENDING SURRENDER FOR DELIVERY.
Carrier to Consignee
The Carrier processes the surrender request of the Transport Document for delivery to ensure that it complies with the terms and conditions specified in the Transport Document and any associated trade documents or trade finance instruments, such as a Letter of Credit (LC). The Carrier verifies the authenticity of the request and the identity of the requesting party and decides whether the surrender request can be accommodated. This use case marks the end of the Bill of Lading process as defined by DCSA.
The Transport Document is in state PENDING SURRENDER FOR DELIVERY.
There are 2 possible scenarios:
If the request is approved: The Transport Document is in state SURRENDERED FOR DELIVERY.
If the request is rejected: The Transport Document is in state ISSUED.
There are 2 possible scenarios:
Carrier to Shipper
The Carrier confirms the Shipping Instructions are completed after the Transport Document has been surrendered for delivery. This use case marks the end of the Shipping Instructions document as defined by DCSA.
The Shipping Instructions are in state COMPLETED.