Skip to content

BKG 2.0: SD-2267: Fix GET, PUT and PATCH description #523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HenrikHL merged 1 commit into from
Jun 30, 2025
Merged

BKG 2.0: SD-2267: Fix GET, PUT and PATCH description #523

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions bkg/v2/BKG_v2.0.2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -552,7 +552,7 @@ paths:
- $ref: '#/components/parameters/bookingReferencePathParam'
- $ref: '#/components/parameters/Api-Version-Major'
description: |
Updates the `Booking Request` with the `bookingReference`. The path can contain one of `carrierBookingRequestReference` or `carrierBookingReference`. Once a Booking has been `CONFIRMED` the `carrierBookingReference` **MUST** always be used. This endPoint corresponds with one of
Updates the `Booking Request` with the `bookingReference`. The path can contain one of `carrierBookingRequestReference` or `carrierBookingReference`. This endPoint corresponds with one of
- **UseCase 3 - Submit updated Booking request**
- **UseCase 7 - Request amendments to confirmed Booking**

Expand Down Expand Up @@ -1119,7 +1119,7 @@ paths:
Gets the Booking
operationId: get-bookings
description: |
Retrieves the `Booking Request` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the Booking is confirmed - it is **only** possible to use the `carrierBookingReference`. It is recommended to use this endPoint to `GET` data before an update is made to make sure latest version is being updated.
Retrieves the `Booking Request` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. It is recommended to use this endPoint to `GET` data before an update is made to make sure latest version is being updated.

The default payload when calling this endPoint is the "original" `Booking`. It is also possible to get the latest amendment to a `Booking` called the `Amended Booking`. In order to get the `Amended Booking`, it is necessary to use the query parameter `amendedContent` and set it to `true`.

Expand Down Expand Up @@ -1509,7 +1509,7 @@ paths:
Cancels the Booking or cancels an Amendment
operationId: cancel-booking
description: |
A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the `Booking` is confirmed - it is **only** possible to use the `carrierBookingReference`.
A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`.

This endPoint corresponds with **UseCase 11 - Cancel Booking Request by shipper**, **UseCase 9 - Cancel amendment to confirmed Booking** or **UseCase 13 - Cancel confirmed Booking by shipper**.

Expand Down
7 changes: 4 additions & 3 deletions bkg/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Publications related to the Booking API:

<a name="v202"></a>[Release v2.0.2 (TBD)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_BKG/2.0.2)
---
This is a patch release for the DCSA Booking API. A lot of minor changes have been added to this patch, here is a list of changes
This is a patch release for the DCSA Booking API. A bug in the `GET`, `PUT` and `PATCH` description has been fixed (chaning the semantics of the endPoints) and a lot of minor changes have been added to this patch, here is a list of changes

- allow `countryCode` `ZZ` in case it is not known
- added `expectedDepartureFromPlaceOfReceiptDate` next to `expectedDepartureDate` for the Shipper to also be able to specify the departure date from PoR
- added `expectedDepartureFromPlaceOfReceiptDate` next to `expectedDepartureDate` for the Shipper to also be able to specify the departure date from `PRE` (Place of Receipt)
- `transportDocumentReferences` (a list of TDR) to replace `transportDocumentReference` (a single TDR) as a Booking can potentially result in multiple Transport Documents
- `transportDocumentReference` marked as Deprecated
- `requestedNumberOfTransportDocuments` added in case the Shipper does not know the TDR(s) but knows how many are needed
Expand All @@ -25,8 +25,9 @@ This is a patch release for the DCSA Booking API. A lot of minor changes have be
- `RAIL_TRUCK`(Rail and truck)
- `BARGE_TRUCK`(Barge and truck)
- `BARGE_RAIL`(Barge and rail)
- fixed a bug in the description of the `PUT`, `GET` and `PATCH`. It is now possible to use CBRR (`carrierBookingRequestReference`) after a Booking has been Confirmed (the description wrongly prevented this). This changes the semantics of the endPoints - but the change is needed as the standard cannot be used as it is in case a Shipper does not implement the ability to receive PUSH notifications.

Link to [commits included in this patch](https://github.com/dcsaorg/DCSA-OpenAPI/commits/master/bkg/v2/BKG_v2.0.2.yaml?since=2025-04-25&until=2025-06-12)
Link to [commits included in this patch](https://github.com/dcsaorg/DCSA-OpenAPI/commits/master/bkg/v2/BKG_v2.0.2.yaml?since=2025-04-25&until=2025-06-28)

<a name="v201"></a>[Release v2.0.1 (25 April 2025)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_BKG/2.0.1)
---
Expand Down