DCSA Standards Public Reference / Standards / Releases / Booking / Archive / Booking v2.0.4

DCSA BKG 2.0.4 - Implementation Guide

Archived release: Booking v2.0.4 has been superseded. View the current v2 documentation.

This guide is for technical teams implementing the DCSA Booking standard version 2.0.4.

Contents

Reference Documentation

To understand the standard, its scope, and the business processes it supports, review the Introduction, Purpose & Scope, User Stories, and Use Cases.

Map your role and supported use cases to the Endpoint Overview, and map the State Transition Diagram to your internal Booking workflow.

Use the Data Overview and Information Model to map the standard data structures to your organization’s data. The OpenAPI specification is the authoritative endpoint and schema contract for this version.

For the general principles applicable when implementing Booking 2.0.4, consult the DCSA API Design & Implementation Principles v2.0. For detailed Booking API behavior, consult the Technical Implementation Guidelines.

Implementing the Standard

Review the Booking module in the DCSA Conformance Gateway repository for the reference implementation used to verify the standard and measure adopter conformance.

Run the conformance scenarios periodically throughout implementation. A DCSA conformance sandbox can also serve as a development counterpart for exercising the scenarios relevant to your application. Do not postpone conformance testing until implementation is complete.

Carrier Implementation

Implement all /v2/bookings operations needed by the supported use cases. Schema-valid requests can still contain business information the Carrier cannot support. Document unsupported properties and return the applicable structured feedback. Use PROPERTY_WILL_BE_IGNORED when a value can be returned but is not processed downstream, and PROPERTY_HAS_BEEN_DELETED when the Carrier removes a value it cannot retain.

Document at least:

  • supported Booking use cases and cargo types, including dangerous goods and reefer capabilities;
  • whether notifications are supported and how counterparties register;
  • when Carrier Booking Request References and Carrier Booking References can be used;
  • supported validation, feedback, and asynchronous-processing behavior; and
  • authentication, authorization, service limits, and operational support.

Shipper Implementation

Build an API client against the Carrier’s conformant Booking API. Fetch the current Booking before attempting an update, amendment, or cancellation. Handle asynchronous 202 responses and use GET /v2/bookings to obtain the current state and content.

If the organization receives Booking notifications, implement /v2/booking-notifications and follow each Carrier’s registration process. Notification support is optional, so implementations must not assume every Carrier sends notifications for every state transition.

Booking and Bill of Lading

Booking supplies data subsequently used in Shipping Instructions and Transport Documents. Some properties exist only in Booking, while other properties can be supplied again in Shipping Instructions. When a property is present in both, the Shipping Instructions value takes precedence. Changes to Booking-only data require a Booking amendment.

For combined process guidance, see Implementing Booking and Bill of Lading.

FAQ

How does the ZZZ code work in the codeListProvider property of IdentifyingCode?

ZZZ indicates a mutually agreed value that is valid only between a specific consumer and provider and is not known across the ecosystem.

For example, a Carrier and Shipper may agree that Shipper123 is the Shipper’s identifier in the Carrier’s system. The Shipper can then identify itself as follows:

{
  "identifyingCodes": [
    {
      "codeListProvider": "ZZZ",
      "partyCode": "Shipper123"
    }
  ]
}

The Shipper cannot assume that Shipper123 is valid with another Carrier, because it may identify a different party or may not be recognized.

How should errors found in a request be handled?

If a request is not schema-valid, return 400 Bad Request with an error object.

If a payload is schema-valid but a business error is found, either return 400 Bad Request with an error object that explains the problem, or return the successful response applicable to the endpoint (200 or 202) and transition the Booking to PENDING_UPDATE. In the latter case, include information about the problem in the Booking’s feedbacks, including in the corresponding notification when notifications are supported.