Implementing the DCSA Bill of Lading Surrender Standard Module

This is a guide to implementing the Surrender module of the DCSA Bill of Lading (eBL) standard version 3.0.0, written for the technical teams of DCSA adopting organizations.There are separate guides for implementing the Issuance module and for implementing the SI and TD modules of the standard.

Reference Documentation

To get acquainted with the standard, refer to the introductory Bill of Lading standard page.To understand the key concepts, user stories, use cases and data overview of the standard, refer to the Bill of Lading documentation page.For an overview of the business processes addressed by the standard, refer to the DCSA Industry Blueprint.To understand the data structures used by the standard and how they can be mapped to your own organization's data types, consult the Transport Document model in version 2024.Q3 of the DCSA Information Model.

Implementing 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 Surrender 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 Surrender 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.
Carrier Implementation
To receive eBL surrender requests from any eBL platforms through the Surrender module of the DCSA Bill of Lading standard API:
  • use your organization's technology stack to implement the "/v3/ebl-surrender-requests" endpoint of the DCSA Bill of Lading Surrender OpenAPI specification page; this is the endpoint through which your organization receives asynchronous surrender requests from the eBL platforms.
  • use your organization's technology stack to build a backend API client for the "/v3/ebl-surrender-responses" endpoint of the DCSA Bill of Lading Surrender OpenAPI specification page; this is the endpoint through which your organization sends asynchronous surrender responses to the eBL platforms.
eBL Platform Implementation
To request the surrender of eBL's through the Surrender module of the DCSA Bill of Lading standard API implementation of any carrier:
  • use your organization's technology stack to build a backend API client for the "/v3/ebl-surrender-requests" endpoint of the DCSA Bill of Lading Surrender OpenAPI specification page; this is the endpoint through which your organization sends asynchronous surrender requests to the carrier.
  • use your organization's technology stack to implement the "/v3/ebl-surrender-responses" endpoint of the DCSA Bill of Lading Surrender OpenAPI specification page; this is the endpoint through which your organization receives asynchronous responses from the carrier to previously sent surrender requests.