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

DCSA BKG 2.0.4 - Technical Appendix

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

Contents

Notifications

Booking supports notifications to reduce polling and improve the latency of business processes. A Carrier can notify registered counterparties when it completes processing or changes the state or content of a Booking.

Lightweight and full notifications

The Booking Notifications endpoint supports:

  • lightweight notifications containing CloudEvents metadata, document references, and states; and
  • full notifications with the same metadata plus the Booking content.

Whether a Carrier sends lightweight or full notifications depends on its supported capabilities, its relationship with the counterparty, and the counterparty’s registration parameters. Notification subscription, lifecycle, filtering, authentication, and authorization are outside the Booking API contract.

Notification workflow

The Carrier sends a notification to each relevant registered counterparty after completing a Carrier use case or processing a request initiated by a counterparty. When the Carrier responds synchronously with 202 Accepted, it sends the notification after asynchronous processing completes. A Carrier can also notify counterparties after changing Booking state or content outside a standard use case.

Notification delivery must be asynchronous: failure of a notification request must not cause the Booking operation that triggered it to fail. Retry behavior and other notification quality-of-service choices are outside the standard.

State and content ownership

The Carrier owns the authoritative Booking state and content. A counterparty should retrieve the latest Booking immediately before attempting to change it, unless it has just received an up-to-date notification. This reduces but does not eliminate conflicts with changes being processed by the Carrier.

The Carrier responds with 409 Conflict when the requested operation is invalid in the current Booking state. It can also use 409 Conflict while processing another change to the same Booking.

The Carrier can respond with 400 Bad Request when a request contains content that is not permitted by the standard or supported by the Carrier. If a request can be accepted subject to reasonable changes, the Carrier can accept it and describe requested or applied changes through feedback.

Feedback

Booking GET responses and notifications can contain feedback objects. The Carrier:

  • must provide feedback for each part of the Booking it deleted or will ignore;
  • must provide feedback for each part the counterparty must change before processing can continue;
  • should provide feedback for values it changed or may change later; and
  • can provide informational feedback for recommended but optional changes.

Feedback includes the appropriate severity and code and, where applicable, the JSON path and property name. It should also include a human-readable message suitable for an operator.

Case sensitivity

Identifiers and references in Booking are case sensitive. This includes Carrier Booking Request References, Carrier Booking References, Equipment References, customs reference values, tax and legal reference values, and UUID values. Neither party may change capitalization after an identifier or reference is created.

Transport Document sources

Transport Document data can originate from Booking, Shipping Instructions, and Carrier-supplied information. If a property is present in Booking but not Shipping Instructions, the Booking value is used. If both provide it, the Shipping Instructions value takes precedence. If only Shipping Instructions provides it, that value is used.

Removing or changing a Booking-only property requires a Booking amendment. See the combined Booking and Bill of Lading implementation guide for the cross-standard amendment process.