Implementing the DCSA Bill of Lading Issuance Standard Module
This is a guide to implementing the Issuance module of the DCSA Bill of Lading (eBL) standard version 3.0, written for the technical teams of DCSA adopting organizations.There are separate guides for implementing the SI and TD modules and for implementing the Surrender module of the standard.
To get acquainted with the general principles applicable when implementing any DCSA standard, consult the DCSA API Design and Implementation Principles.To review the reference implementation of the Issuance module of the Bill of Lading standard, created by DCSA to verify the standard and used for measuring the conformance of adopter implementations, consult the Bill of Lading Issuance module of the DCSA conformance GitHub repository.To ensure that your organization becomes a successful adopter in the DCSA Bill of Lading standard API ecosystem, use the DCSA conformance framework periodically throughout your implementation project, to measure the conformance of your implementation and to improve it as needed.You can use a DCSA conformance sandbox as a counterpart in your development, since it allows you to easily test the most relevant scenarios that your application needs to support.👉Important note: While implementing the standard, run conformance periodically and use conformance scenarios and validations as a compass to guide the implementation. Don't wait until implementation has been finished to run the conformance scenarios.
Carrier Implementation
To request the issuance of eBL's through the Issuance module of the DCSA Bill of Lading standard API implementation of any eBL platform:
use your organization's technology stack to build a backend API client for the "/v3/ebl-issuance-requests" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization sends asynchronous issuance requests to the eBL platform.
use your organization's technology stack to implement the "/v3/ebl-issuance-responses" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization receives asynchronous responses from the eBL platform to previously sent issuance requests.
eBL Platform (Solution Provider) Implementation
To receive eBL issuance requests from any carriers through the Issuance module of the DCSA Bill of Lading standard API:
use your organization's technology stack to implement the "/v3/ebl-issuance-requests" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization receives asynchronous issuance requests from the carriers.
use your organization's technology stack to build a backend API client for the "/v3/ebl-issuance-responses" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization sends asynchronous issuance responses to the carriers.
Implementing synchronous vs. asynchronous API responses
Synchronous and asynchronous eBL Issuance API responses are defined for different purposes and must be implemented accordingly:
Asynchronous regular responses (ISSU) and errors (BREQ / REFU), posted by the eBL Solution Provider using the "POST /v3/ebl-issuance-responses", are expected to be interpreted and routed programmatically by the Carrier system to their appropriate business process handlers, and to be manually processed if needed by the Carrier's business team.
Synchronous issuance responses must either acknowledge the receipt of the issuance request (204) or reject it as a duplicate (409). Any other synchronous error response (4xx / 5xx) is expected to be programmatically routed by the Carrier's system to their technical team for investigation.
👉Important note: When implementing eBL Issuance as an eBL Solution Provider, even if your system could send the BREQ or REFU issuance request rejections synchronously, it is essential not to do so, and to instead send them asynchronously using the dedicated "POST /v3/ebl-issuance-responses". Failure to do so will inadvertently trigger a technical support process on the Carrier side instead of the rejected issuance request business workflow.
Version overview
List of changes and the version they are released in