This technical appendix provides technical information required for understanding how to implement the DCSA standard API specifications for Booking 2.0.0 and Bill of Lading 3.0.0. It serves as a critical resource for technical teams responsible for implementing the DCSA standard APIs, providing the necessary information to ensure a successful deployment and operation.Follow these step-by-step guidelines published on the DCSA Developer Portal when implementing the Booking and Bill of Lading standards:
The Booking standard and the Shipping Instructions and Transport Document modules of the Bill of Lading standard provide support for notifications in order to optimize the latency of business processes and the network bandwidth use for the carriers and their counterparts (e.g. shippers, consignees, endorsees).The mechanism reduces the need for polling by allowing each counterpart registered with a carrier to receive notifications for changes in the state of each relevant document (booking, shipping instructions or transport document). Note that the Issuance and Surrender modules of the Bill of Lading standard do not support the notifications mechanism.
5.2.1. Lightweight vs. full notifications
The API specification of the notification endpoints included in the Booking and Bill of Lading standards provides support for:
lightweight notifications, containing only cloud event metadata and the relevant document reference(s) and state(s);
full notifications, sharing the same structure with the lightweight notifications but also including the full content of the document.
Whether lightweight or full notifications are sent by a carrier to a counterpart is out of scope of the Booking and Bill of Lading standards and depends on:
the contractual relationship between the carrier and its counterpart;
the notifications support implemented by the carrier and its counterpart;
the parameters with which the counterpart has registered for notifications with the carrier.
5.2.2. Notification subscriptions
In the Booking and Bill of Lading standards, notification subscriptions (including registration, lifecycle, filtering, authentication & authorization) are out of scope.Each registered counterpart receives notifications from the carrier about the state changes of a booking, shipping instructions or transport document if the following conditions are met:
The carrier implements support for sending notifications to counterpart API endpoints of the corresponding standard module. (Implementing notifications support is recommended, but optional. The carrier may choose to implement notifications for all or only for some of the state transitions of a document.)
The carrier provides the specific counterpart (or category of counterparts) with the option to register for notifications. (Each carrier can choose to offer notifications support only to specific customers or customer tiers.)
The counterpart implements the notifications API endpoint of the corresponding standard module.
The counterpart registers with the carrier to receive notifications for the state transitions of documents of which they are authorized to be informed.
5.2.3. Notifications workflow
The carrier sends a notification for a document to each relevant registered counterpart in the following situations:
The carrier has completed the processing of the document pertaining to a carrier use case or to a shipper / consignee / endorsee use case (even when the document state has not changed, for example when re-confirming an already confirmed booking).
When the carrier responds with HTTP 202 to an API call from a shipper / endorsee / consignee and performs the processing asynchronously, the notification must be sent after the asynchronous processing.
The carrier has changed the state or content of the document outside of the scope of a standard use case (for example when auto-approving a transport document).
The carrier must send notifications asynchronously, such that if a notification API call fails, it does not cause the failure of the use case or operation that has triggered it. The quality of service of notifications (determining whether, when and how failed API notification calls are retried) is out of scope of the Booking and Bill of Lading standards.
5.3 State and content ownership
Within the content of the Booking and Bill of Lading standards, the carrier owns and is the “source of truth” for both the state and the content of the document (booking, shipping instructions, transport document).Therefore, the carrier’s counterpart (shipper / consignee / endorsee) is expected to use a GET request to fetch the latest state and content of a document immediately before attempting to change it (except after it just received a notification).Note that this only reduces, but does not fully eliminate, the possibility of a change request being rejected if the carrier has also just modified (or is in the process of modifying) the document on its own.
5.3.1 State ownership
The carrier is expected to respond with an HTTP 409 whenever its counterpart (shipper / consignee / endorsee) attempts to perform an operation that is invalid in the current state of the document.Moreover, since performing changes on a document is not instantaneous, the carrier can choose to respond with an HTTP 409 if it receives a request to perform a change on a document while it is already itself in the process of changing that document (either as part of one of its own use cases, or of a use case initiated by the same or another counterpart).
5.3.2 Content ownership
The carrier can respond with an HTTP 400 whenever its counterpart attempts to create or modify a document with content that is not allowed by the standard or not supported by the carrier.If on the other hand the requested change would result in a document that would be acceptable by the carrier after a reasonable number of changes, and if the document would transition in a state in which the carrier can make or request changes, then the carrier can choose instead to accept the request and to either request changes from the counterpart or make the changes itself, specifying each made and requested change in a “feedback” object.
5.3.3 Feedback object
The GET response and the notification request of Booking and of eBL SI and TD include a list of “feedback” objects, to be used by the carrier in order to provide instructions that can be processed in a programmatic way by the software system used by the shipper, consignee or endorsee.
The carrier must send a feedback object for each part of the document that the carrier has deleted, or that the carrier leaves in the document but will ignore.
The carrier must send a feedback object for each part of the document that the shipper, consignee or endorsee must change in order for the document to be successfully processed further.
The carrier should send a feedback object for each part of the document that was already changed by the carrier, or that may be changed by the carrier later in the process.
The carrier can also send a feedback object for each part of the document that it encourages (but does not require) the shipper, consignee or endorsee to change.
Whenever providing a “feedback” object, in addition to setting the appropriate severity, code and if applicable the path and name of the property within the JSON document for programmatic processing by the counterpart software system, the human-readable message should also be set for being relayed to a human operator at the counterpart organisation..
5.4 Case sensitivity of identifiers and references
All identifiers and references in the Booking and Bill of Lading standards are case sensitive, meaning that letter capitalisation differences like “reference_a” vs. “Reference_A” distinguish between separate references that identify separate entities.Examples include:
Carrier Booking Request Reference
Carrier Booking Reference
Shipping Instructions Reference
Transport Document Reference
Equipment Reference
Customs reference value
Tax and Legal reference value
Self-filer code
Whether an identifier or a reference is generated by the carrier, by its counterpart (shipper / consignee / endorsee / eBL platform) or by a third party, neither the carrier, nor its counterpart may change its capitalization.Note that this also applies to values of type UUID, which once they are generated must be handled and stored as case-sensitive strings.
5.5 Transport Document checksums
Generating checksums for a transport document is described in this DCSA Developer Portal guide:
Note that the ordering of elements in the lists of a document is generally not guaranteed to be preserved by the carrier or by its counterpart, except in special cases where the ordering is critical for business purposes. However, in order for the receiver of a transport document to be able to validate the checksum created for it by a provider, that document must be transferred and stored between the creation and the validation of the checksum in a way that preserves the entire document content, including the order of all the elements in all its lists.
5.6 eBL interoperability scope
The Issuance and Surrender modules of the Bill of Lading standard only define the communication between the carrier and an eBL platform with which it has a direct connection. However, these APIs (including the definition of the transport document itself) are already designed in a way that supports future interoperability scenarios whereby an eBL is issued to a shipper, or further transferred to endorsees and consignees, having accounts on different eBL platforms.DCSA supports end-to-end multi-platform scenarios with a separate eBL Interoperability package, planned to be released after the Bill of Lading 3.0.0 standard, containing:
the separate DCSA Platform Interoperability (PINT) standard;
a legal framework governing the transfer of eBLs from a User (shipper / consignee / endorsee) on one eBL platform to a User on another platform;
the DCSA Control Tracking Registry (CTR) software, acting as the “source of truth” as to which eBL platform user has exclusive control of an eBL at any given time.
5.6.1 Current limitationsOnce the carrier issues an eBL through a certain eBL platform, only the same eBL platform can use the eBL Surrender API to request the surrender of that eBL, whether on behalf of a user (shipper / endorsee / consignee) on the same or on a different eBL platform.When re-issuing the same eBL after the completion of a transport document amendment, the carrier must issue the new version of the eBL through the same platform through which the initial version was issued, even if the carrier is directly connected to multiple eBL platforms.While the eBL Issuance and Surrender APIs fullysupport the implementation by carriers and solution providers of correct and secure end-to-end multi-platform eBL Interoperability scenarios, these APIs don’t guarantee by themselves the correctness and security of such end-to-end scenarios.
5.7 Transport Document source of information
The Transport Document properties are populated using data from three complementary sources:
Booking
Shipping Instructions
Carrier supplied information
For properties that can be specified both in Booking as well as in the Shipping Instructions, the following rules apply:
If provided in Booking and not in the Shipping Instructions, then the value provided in Booking is used;
if provided both in Booking and in the Shipping Instructions, then the value provided in the Shipping Instructions takes precendence;
If provided in the Shipping Instructions and not in Booking, then the value provided in in the Shipping Instructions is used;
Examples
A Consignee is provided as part of the Booking request. If a Consignee is also provided in the Shipping Instructions, then the latter will be inlcuded as part of the Transport Document.
A First and Second Notify Party are provided as part of the Booking request. If only one Notify Party is provided in the Shipping Instructions, then the latter will be inlcuded as the First Notify Party in the Transport Document, overruling the values provided in Booking.
A First and Second Notify Party are provided as part of the Booking request. If no Notify Party is provided in the Shipping Instructions, then the Notify Parties provided at time of Booking will be inlcuded as part of the Transport Document.