diff --git a/bkg/v2/BKG_v2.0.4.yaml b/bkg/v2/BKG_v2.0.4.yaml new file mode 100644 index 00000000..c50217a9 --- /dev/null +++ b/bkg/v2/BKG_v2.0.4.yaml @@ -0,0 +1,6966 @@ +openapi: 3.0.3 +info: + version: 2.0.4 + title: DCSA Booking API + description: | +

DCSA OpenAPI specification for the Booking process

+ + This API is intended as an API between a carrier and anyone creating a `Booking`. The process includes: + + - Booking request + - Booking update + - Booking confirmation + - Booking amendment + - Booking cancellation + - Booking rejection + + For explanation of specific values or objects please refer to the [Information Model](https://developer.dcsa.org/documentation/information_models). This API specification does not define the allowable updates and their timing in accordance with the established business rules. **All use cases mentioned in this API specification refer to use cases defined in [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2)**. + + All other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/) + + ### Booking (Implemented by provider) + + It is possible to use the Booking API as a standalone API. In that case poll on the following endPoints: + + GET /v2/bookings/{bookingReference} + + in order to poll information about status changes. + + **Note:** All `/v2/bookings` endPoints must be implemented by the provider. + + ### Notifications (Implemented by consumer) + It is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification). + + POST /v2/booking-notifications + + The endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to. + + Signing up for notifications is defined outside the scope of this API specification. + + **Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) + + ### Changelog and GitHub + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v204). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +security: [] +tags: + - name: Booking + description: Booking endPoints to be implemented by **providers** of the Booking API + - name: Notifications + description: Notifications to be implemented by the **consumers** of the Booking API +paths: + /v2/bookings: + post: + tags: + - Booking + summary: | + Creates a new Booking + operationId: create-bookings + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Creates a new booking request. This endPoint corresponds with **UseCase 1 - Submit booking request**. + + ## Precondition + The consumer has information for a `Booking Request` + + ## Postcondition + The provider has received the `Booking Request`. + + The consumer will receive a `202` (Accepted) if the request payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a `Booking Request`: + + 1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means + - all required properties are provided + - all values provided have correct data type. + + A `carrierBookingRequestReference` (as a reference to the `Booking Request`) is created and linked to the payload in the provider system. + + **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference`** + + 3. A `202` (Accepted) response is returned with a payload containing **only** the `carrierBookingRequestReference`: + ``` + { + carrierBookingRequestReference: 'cbrr-123' + } + ``` + + For `POST` `Booking Request` the process ends here. The `Booking Request`: + - is now accepted by the provider system + - the `Booking Request` does not yet have any status and cannot be queried (no `GET` request is possible until the `Booking Request` is further processed in the provider system) + - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `carrierBookingRequestReference` + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the status `RECEIVED` of the `Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v2/bookings/{bookingReference} + + endPoint to check if the `bookingStatus` of the `Booking Request` has changed. + + After the status has changed to `RECEIVED` further processing can continue by provider and will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll the above endPoint. + requestBody: + description: The payload used to create a `Booking Request` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Make a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Make a `Booking Request` with reefer requirements (1° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 1 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - '20097919' + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Make a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Make a `Booking Request` with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Environmentally hazardous substance, liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: 'Jerrican, steel' + dangerousGoods: + - UNNumber: '3082' + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: '9' + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + responses: + '202': + description: | + `Booking Request` has been successfully accepted by the provider. The `Booking Request` does not yet have a `bookingStatus` - it is not possible to call the `GET` endPoint until the `Booking Request` is further processed in provider system. The consumer is now awaiting provider to process the `Booking Request` asynchronously. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBookingResponse' + examples: + acceptedExample: + summary: | + Booking request accepted + description: | + A `Booking Request` has been accepted (no `bookingStatus`) and schema validated by provider + value: + carrierBookingRequestReference: cbrr-123 + '400': + description: | + In case the `Booking Request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking Request`. This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking Request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Bookings Requests + description: | + Calling the endPoint + + POST /v2/bookings + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be created per hour + '/v2/bookings/{bookingReference}': + put: + tags: + - Booking + summary: | + Updates the Booking + operationId: update-bookings + parameters: + - $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`. This endPoint corresponds with one of + - **UseCase 3 - Submit updated Booking request** + - **UseCase 7 - Request amendments to confirmed Booking** + + This endPoint is to be used in response to + - **UseCase 2 - Request to update Booking request** + - **UseCase 6 - Request to amend confirmed Booking** + + the endPoint can also be used in case `bookingStatus='RECEIVED'` and the consumer has an update to the `Booking Request`. + + ## Precondition + In order to update a `Booking Request`, the status of the `Booking Request` needs to be in state + - `RECEIVED` in case the consumer has updated information for the `Booking Request` + - `PENDING_UPDATE` in case the provider has requested the consumer to update the `Booking Request` (a result of **UseCase 2 - Request to update Booking request**) + - `UPDATE_RECEIVED` in case the consumer has additional changes to an already sent update + - `PENDING_AMENDMENT` in case the provider has requested the consumer to amend the `Booking Request` (a result of **UseCase 6 - Request to amend confirmed Booking**) + - `CONFIRMED` in case the consumer has an amendment to the `Booking Request` + + ## Postcondition + The provider has received an update (**UseCase 3 - Submit updated Booking request**) or an amendment (**UseCase 7 - Request amendments to confirmed Booking**) to the `Booking Request`. + + In case an amendment was received to the `Booking Request` (**UseCase 7 - Request to amend confirmed Booking**) - the amendment will be called `Amended Booking`. The `Amended Booking` and the "original" `Booking Request` will **co-exist** until a new amendment is submitted by the consumer (via **UseCase 7: Request amendments to confirmed Booking**) or until the provider requests an update (sets the `bookingStatus='PENDING_AMENDMENT'` via **UseCase 6: Request to amend confirmed Booking**). If the `amendedBookingStatus` is present it always represents the latest version of an amendment received by the provider. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives an **update** (or an **amendment**) to a `Booking Request` + 1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means + - all required properties are provided + - all values provided have correct data type + 3. An empty response along with `202` (Accepted) is returned and the consumer now awaits further processing by the provider. + + For `PUT` `Booking Request` the process ends here. The Booking Request: + - is now accepted by the provider system + - the status of the `Booking Request` is unchanged. + - a `202` (Accepted) response is sent with an empty payload + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the state will change to one of the following values depending on the use case for calling the `PUT` endPoint: + - `UPDATE_RECEIVED` in case this endPoint has been used to: + - send an update to a newly created Booking (precondition: `bookingStatus='RECEIVED'`) + - send an update to a Booking because of a request from provider via **UseCase 2 - Request to update Booking request** (precondition: `bookingStatus='PENDING_UPDATE'`) + - send an additional update to a Booking that has already received an update (precondition: `bookingStatus='UPDATE_RECEIVED'`) + - `bookingStatus` will stay as `PENDING_AMENDMENT` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used in response to a request from provider via **UseCase 6 - Request to amend Confirmed Booking** (precondition: `bookingStatus='PENDING_AMENDMENT'`) + - `bookingStatus` will stay as `CONFIRMED` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used to update an already confirmed Booking via **UseCase 7 - Request Amendments to Confirmed Booking** (precondition: `bookingStatus='CONFIRMED'`) + + Once processed, the new state will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v2/bookings/{bookingReference} + + endPoint to check if the `bookingStatus` and `amendedBookingStatus` of the `Booking` has changed. + + If the consumer wants to get the content of the `Amended Booking` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter: + + GET /v2/bookings/{bookingReference}?amendedContent=true + + It is possible to `GET` the content of the `Amended Booking` via the example above until one of: + + - the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible + - the consumer submits a new update (**UseCase 7: Request amendment to confirmed Booking**) in which case the "new amendment" provided **replaces** the "old amendment". + - the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the "old update" is no longer accessible. + requestBody: + description: | + Parameters used to update the `Booking request` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Updating a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Updating a `Booking Request` with reefer requirements (2° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 2 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - '20097919' + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Update a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Update a `Confirmed Booking` (a `Booking` with `carrierBookingReference='cbr-987'`) with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Environmentally hazardous substance, liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: 'Jerrican, steel' + dangerousGoods: + - UNNumber: '3082' + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: '9' + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + responses: + '202': + description: | + The `Booking request` update has been successfully accepted by the provider. `bookingStatus` does not change and response payload is empty. Further processing will be done by provider. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + noContentExample: + summary: | + Booking request updated with no content + description: | + An updated `Booking request` received, schema validated and accepted by provider - the `Booking` now awaits provider action, `bookingStatus` does not change. + value: null + '400': + description: | + In case the updated/amended `Booking request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking request`. This is an example of how the error object would look in case this property is missing. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + '404': + description: | + In case the provider does not know of the `bookingReference` used in the request (this could be because of a `POST` request that has not finished processing or simply because the resource does not exist) - it is possible for the provider to reject the requests by returning a `404` (Not Found). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. This can be because a `Post` request has not been finished processing or because the `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + '409': + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + GET /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to update a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be updated per hour + get: + tags: + - Booking + summary: | + Gets the Booking + operationId: get-bookings + description: | + 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`. + + GET /v2/bookings/{bookingReference}?amendedContent=true + + The `status` of the "original" `Booking` is included in both payloads as `bookingStatus`. `amendedBookingStatus` and related content is only available after the provider has approved the `Booking` via **UseCase 5: Confirm Booking request** and until: + - the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + - the consumer submits a new amendment (**UseCase 7: Request amendment to confirmed Booking**) in which case the "new update" provided **replaces** the "old update". + - the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the "old update" is no longer accessible. + + If `amendedContent=true` is requested but no amendment has yet been provided by the consumer **or** the state of the "original" `Booking` is `PENDING_AMENDMENT`, then a `404` (Not Found) is returned. + + If the provider is requesting changes to the `Booking`, the `Feedback` object is used to inform the consumer what needs to change. + + In case no subscription (`Notification`) has been set up - it is possible to use this endPoint to poll on in order to detect if `bookingStatus` and/or `amendedBookingStatus` has changed. + + In case a previous request is being processed by the provider - a `202` (Accepted) with **no payload** can be used as a response until the processing is finished. + parameters: + - $ref: '#/components/parameters/bookingReferencePathParam' + - $ref: '#/components/parameters/amendedContent' + - $ref: '#/components/parameters/Api-Version-Major' + responses: + '200': + description: Request successful + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + examples: + dryNotConfirmedExample: + summary: | + Standard dry cargo Booking (not confirmed) + description: | + Gets a `Booking Request` with standard Dry cargo which has not yet been confirmed. The `Booking` is in state `PENDING_UPDATE` and requires some changes (specified in the `feedbacks` property) + value: + carrierBookingRequestReference: cbrr-123 + bookingStatus: PENDING_UPDATE + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + feedbacks: + - severity: ERROR + code: PROPERTY_VALUE_MUST_CHANGE + message: | + Not enough available "42G1" equipment. Please change to "22G1" instead + jsonPath: $.requestedEquipment.units + property: 'units' + dryConfirmedExample: + summary: | + Gets a confirmed Standard dry cargo Booking + description: | + Gets a `Confirmed Booking` with standard Dry cargo. In this example the `Booking` has previously received an amendment which was confirmed (`amendedBookingStatus='AMENDMENT_CONFIRMED'`) + + As part of the confirmation the `Booking` is enriched with a `transportPlan`, `shipmentCutOffTimes`, `carrierClauses` and in this example also an `advanceManifestFiling` since the `Booking` is arriving in US. + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_CONFIRMED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: '2024-01-20' + plannedArrivalDate: '2024-01-31' + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: '2024-01-17T22:30:00Z' + - cutOffDateTimeCode: VCO + cutOffDateTime: '2024-01-18T22:30:00Z' + - cutOffDateTimeCode: FCO + cutOffDateTime: '2024-01-19T13:30:00Z' + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes. + - 'Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.' + - 'Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).' + - 'In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee.' + '202': + description: | + The `Booking` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Booking`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '404': + description: | + In case the consumer is requesting the `Amended Booking` by calling: + + GET /v2/bookings/{bookingReference}?amendedContent=true + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + The `Amended Booking` response is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + '409': + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + getError: + summary: | + GET non-existing Booking Request + description: | + Calling + + GET /v2/bookings/cbrr-123 + + results in an error as booking `cbrr-123` does not exist. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + The requested carrierBookingRequestReference does not exist + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Non existent carrierBookingRequestReference + errorCodeMessage: | + carrierBookingRequestReference `cbrr-123` does not exist + patch: + tags: + - Booking + summary: | + 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`. + + 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**. + + ## Precondition + In order to cancel a `Booking`, the `bookingStatus` must be one of + - `RECEIVED` + - `PENDING_UPDATE` + - `UPDATE_RECEIVED` + - `CONFIRMED` + - `PENDING_AMENDMENT` + + In order to cancel a `Booking Amendment`, the status of the `Booking Amendment` must be + - `AMENDMENT_RECEIVED` + + ## Postcondition + The provider has received a cancellation from the consumer for a `Booking` or for a `Booking Amendment`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a cancellation request: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + Once processed, the `Booking` or `Amended Booking` is cancelled and a [Booking Notification](#/BookingNotification) is sent. In case of a Confirmed Booking - the provider has the opportunity to decline the Cancellation of the Booking (in which case the `bookingCancellationStatus='CANCELLATION_DECLINED'`). + parameters: + - $ref: '#/components/parameters/bookingReferencePathParam' + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CancelBookingRequest' + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer wants to cancel the `Booking Request`. This is done by setting the `bookingStatus` to `CANCELLED` and provide an optional `reason`. + value: + bookingStatus: CANCELLED + reason: Cancelling due to strike + amendmentCancelledExample: + summary: | + Amendment cancelled + description: | + The consumer wants to **only** cancel the amendment (and keep the confirmed `Booking`). This is done by setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED`. + value: + amendedBookingStatus: AMENDMENT_CANCELLED + requestConfirmedBookingCancelledExample: + summary: | + Request to cancel a Confirmed Booking + description: | + The consumer requests to cancel a `Confirmed Booking`. This is done by setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` and provide an optional `reason`. + value: + bookingCancellationStatus: CANCELLATION_RECEIVED + reason: Cancelling due to internal issues + responses: + '202': + description: | + Booking cancellation has been accepted. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer has requested that the `Booking Request` should be cancelled. The cancellation request has been accepted and is now awaiting further processing by the provider + value: null + amendmentCancelledExample: + summary: | + Amendment cancellation on a confirmed Booking accepted + description: | + The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation request as been accepted and is now awaiting further processing by the provider + value: null + confirmedBookingCancellationExample: + summary: | + Request to Cancel a confirmed Booking accepted + description: | + The consumer has requested to cancel a confirmed `Booking`. The cancellation request has been accepted and is now awaiting further processing by the provider + value: null + '400': + description: | + In case the cancel payload does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Wrong `amendedBookingStatus` + description: | + `APPROVE` is not a possible value when PATCHING a `Booking`. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: APPROVE is not a valid status to set + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: amendedBookingStatus + value: APPROVE + errorCodeText: incorrect value + errorCodeMessage: 'Only AMENDMENT_CANCELLED is an allowed value: APPROVE was inserted' + '404': + description: | + In case the consumer is cancelling the `Amended Booking` by setting: + + `amendedBookingStatus='AMENDMENT_CANCELLED'` + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + Cancelling the `Amendment` is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + '409': + description: | + In case the provider is processing a `Booking request` - it is possible for the provider to reject the cancellation by returning a `409` (Conflict). This is also to be used in case a cancellation to a Confirmed Booking is done via the `carrierBookingRequestReference`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: Conflicting request is being processed + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + PATCH /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to cancel a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be cancelled per hour + /v2/booking-notifications: + post: + tags: + - Notifications + summary: Send a new Booking Notification + operationId: booking-notifications + description: | + Creates a new [`Booking Notification`](#/BookingNotification). This endPoint is called whenever a `Booking` that a consumer has subscribed to changes state or is updated. + + **This endPoint is to be implemented by a consumer of the Booking API in order to receive Notifications** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + The payload used to create a [`Booking Notification`](#/BookingNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/BookingNotification' + examples: + receivedLightweightExample: + summary: | + Booking request received (Lightweight) + description: | + A lightweight notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + receivedFullStateTransferExample: + summary: | + Booking request received (Full State Transfer) + description: | + A full state transfer notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + bookingStatus: RECEIVED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + declinedLightweightExample: + summary: | + Booking amendment declined (Lightweight) + description: | + A lightweight notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + declinedFullStateTransferExample: + summary: | + Booking amendment declined (Full State Transfer) + description: | + A full state transfer notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`). The notification both contains the Booking from before the amendment (in the `booking` property) it also contains the amended booking (in the `amendedBooking` property). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: '2024-01-20' + plannedArrivalDate: '2024-01-31' + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: '2024-01-17T22:30:00Z' + - cutOffDateTimeCode: VCO + cutOffDateTime: '2024-01-18T22:30:00Z' + - cutOffDateTimeCode: FCO + cutOffDateTime: '2024-01-19T13:30:00Z' + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes. + - 'Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.' + - 'Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).' + - 'In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee.' + amendedBooking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 30 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + cancelConfirmedBookingLightweightExample: + summary: | + Confirmed Booking cancelled (Lightweight) + description: | + A lightweight notification explaining that a confirmed `Booking` has been cancelled (`bookingCancellationStatus='CANCELLATION_CONFIRMED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CANCELLED + amendedBookingStatus: AMENDMENT_CANCELLED + bookingCancellationStatus: CANCELLATION_CONFIRMED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + responses: + '204': + description: | + No Content + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '400': + description: | + In case the `Notification` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing carrierBookingReference or carrierBookingRequestReference + description: | + `carrierBookingReference` or `carrierBookingRequestReference` is a conditionally property in the `Notification` (at least one of them must be present). This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + carrierBookingReference or carrierBookingRequestReference not found - one of them is a mandatory to provide in a Notification + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: carrierBookingReference or carrierBookingRequestReference + errorCodeText: mandatory property missing + errorCodeMessage: | + carrierBookingReference or carrierBookingRequestReference must be provided as part of a Notification + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Notification + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Notifications + description: | + Calling the endPoint + + POST /v2/booking-notifications + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a Notification has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Notifications reached + errorCodeMessage: A maximum of 10 Notifications can be created per hour +components: + headers: + API-Version: + schema: + type: string + example: 2.0.3 + description: | + SemVer used to indicate the version of the contract (API version) returned. + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '2' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + + ############# + # Path params + ############# + amendedContent: + in: query + name: amendedContent + description: | + Controls whether the content of this payload is the amended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`). + + If `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found + schema: + type: boolean + default: false + example: false + bookingReferencePathParam: + in: path + name: bookingReference + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + example: CBR001 + required: true + schemas: + + ######################### + # Create Booking Response + ######################### + CreateBookingResponse: + type: object + title: Create Booking Response + description: | + **Only** the `carrierBookingRequestReference` is returned. + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + required: + - carrierBookingRequestReference + + ######################## + # Cancel Booking Request + ######################## + CancelBookingRequest: + type: object + title: Cancel Booking Request + description: | + Cancels one of the following things: + - A booking request (prior to a Confirmed Booking) + - An amendment to a Confirmed Booking + - A Confirmed Booking + oneOf: + - type: object + title: Cancel Booking Request (prior to Booking Confirmation) + properties: + bookingStatus: + type: string + maxLength: 50 + description: | + Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLED`. + example: CANCELLED + required: + - bookingStatus + - type: object + title: Only cancel the amendment to a Confirmed Booking + properties: + amendedBookingStatus: + type: string + maxLength: 50 + description: | + Setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`. + + **Condition:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT_RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned. + + Only possible value to set is `AMENDMENT_CANCELLED`. + example: AMENDMENT_CANCELLED + required: + - amendedBookingStatus + - type: object + title: Request to cancel a Confirmed Booking + properties: + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + Setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon receiving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLATION_RECEIVED`. + example: CANCELLATION_RECEIVED + required: + - bookingCancellationStatus + properties: + reason: + type: string + maxLength: 5000 + description: | + An optional property where a reason for cancelling the booking or the amendment can be given. + example: Booking cancelled due to internal problems + + ###################### + # Booking Notification + ###################### + BookingNotification: + type: object + title: Booking Notification + description: | + `CloudEvent` specific properties for the `Notification`. + properties: + specversion: + type: string + description: | + The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of `1.0` when referring to this version of the specification. + + Currently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes. + enum: + - '1.0' + example: '1.0' + id: + type: string + maxLength: 100 + description: | + Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates. + example: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: + type: string + maxLength: 4096 + description: | + Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that `source` + `id` is unique for each distinct event. + example: 'https://member.com/' + type: + type: string + description: | + This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see [Versioning of CloudEvents in the Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#versioning-of-cloudevents) for more information. + enum: + - org.dcsa.booking.v2 + example: org.dcsa.booking.v2 + time: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. + example: '2018-04-05T17:31:00Z' + datacontenttype: + type: string + description: | + Content type of `data` value. This attribute enables `data` to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the [JSON envelope](formats/json-format.md#3-envelope) format might carry an XML payload in `data`, and the consumer is informed by this attribute being set to "application/xml". The rules for how `data` content is rendered for different `datacontenttype` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](formats/json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol. + + In some event formats the `datacontenttype` attribute MAY be omitted. For example, if a JSON format event has no `datacontenttype` attribute, then it is implied that the `data` is a JSON value conforming to the "application/json" media type. In other words: a JSON-format event with no `datacontenttype` is exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a different format or protocol binding, the target `datacontenttype` SHOULD be set explicitly to the implied `datacontenttype` of the source. + enum: + - application/json + example: application/json + subscriptionReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The reference of the subscription that has triggered this event + example: 30675492-50ff-4e17-a7df-7a487a8ad343 + data: + $ref: '#/components/schemas/BookingNotificationData' + required: + - specversion + - id + - source + - type + - time + - datacontenttype + - subscriptionReference + - data + + ############################### + # Data for Booking Notification + ############################### + BookingNotificationData: + type: object + title: Data + description: | + `Booking` specific properties for the `Notification` + properties: + bookingStatus: + type: string + maxLength: 50 + description: | + The status of the `Booking`. Possible values are: + + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + type: string + maxLength: 50 + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are: + + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: ABC709951 + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + booking: + $ref: '#/components/schemas/BookingFullNotification' + amendedBooking: + $ref: '#/components/schemas/AmendedBookingFullNotification' + required: + - bookingStatus + + ######################################### + # Booking object for Booking Notification + ######################################### + BookingFullNotification: + type: object + title: Booking Full Notification + description: | + This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking. + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + + ################################################# + # Amended Booking object for Booking Notification + ################################################# + AmendedBookingFullNotification: + type: object + title: Amended Booking + description: | + This property contains the amended booking in case: + - an amendment is currently active + - the subscriber is subscribing to the `Full State Transfer` of the Booking + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + + ########## + # Feedback + ########## + Feedback: + type: object + title: Feedback + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + properties: + severity: + type: string + maxLength: 50 + description: | + The severity of the feedback. Possible values are: + - `INFO` (Information - "Your reefer container will use renewable energy", "This earlier / premium service is available") + - `WARN` (Warning - "I'm going to replace" / "Ignore this value" / "Use another value instead") + - `ERROR` (Error - "This must be changed!") + example: WARN + code: + type: string + maxLength: 50 + description: | + A code used to describe the feedback. Possible values are: + - `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) + - `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values) + - `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided) + - `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention) + - `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future) + - `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention) + example: PROPERTY_WILL_BE_IGNORED + message: + type: string + maxLength: 5000 + description: | + A description with additional information. + example: Spaces not allowed in facility code + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error/warning. + example: facilityCode + required: + - severity + - code + - message + + ################# + # Error Responses + ################# + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v1/events + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. + type: string + format: date-time + example: '2024-09-04T09:41:00Z' + errors: + type: array + description: | + An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + + DetailedError: + type: object + title: Detailed Error + description: | + A detailed description of what has caused the error. + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + minimum: 7000 + maximum: 9999 + example: 7003 + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error. + example: facilityCode + value: + type: string + maxLength: 500 + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + description: | + A standard short description corresponding to the `errorCode`. + type: string + maxLength: 100 + example: invalidData + errorCodeMessage: + type: string + maxLength: 5000 + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + - errorCodeMessage + + ################## + # Address Location + ################## + Address: + type: object + title: Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the street number. + example: 2nd + postCode: + type: string + maxLength: 10 + description: The post code. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - street + - city + - countryCode + + ################### + # Facility Location + ################### + Facility: + title: Facility + type: object + description: | + An object used to express a location using a `Facility`. The facility can be expressed using one of `BIC` code or `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + properties: + facilityCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 6 + description: | + The code used for identifying the specific facility. This code does not include the UN Location Code. + + The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used: + + - `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)) + - `BIC` (the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)) + example: ADT + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code` + - `BIC` (Requires a UN Location Code) + - `SMDG` (Requires a UN Location Code) + enum: + - BIC + - SMDG + example: SMDG + required: + - facilityCode + - facilityCodeListProvider + + ######################### + # Geo Coordinate Location + ######################### + GeoCoordinate: + type: object + title: Geo Coordinate + description: | + An object used to express a location using `latitude` and `longitude`. + properties: + latitude: + type: string + description: | + Latitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: | + Longitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 11 + example: '2.294492036' + required: + - latitude + - longitude + + ################ + # Create Booking + ################ + CreateBooking: + type: object + title: Create Booking + description: | + Creates a new Booking request. + required: + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + properties: + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** One of `serviceContractReference` or `contractQuotationReference` must be provided, but not both. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** One of `contractQuotationReference` or `serviceContractReference` must be provided, but not both. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank. If `routingReference` is provided - this property MUST not be provided. + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank. If `routingReference` is provided - this property MUST not be provided. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: 2103N + routingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 5000 + description: | + A reference to a predefined `route` specified in **Commercial Schedules - Point to Point**. When specifying this property - it is not needed to specify the following properties: + - `vessel` which includes: + - `vesselName` + - `vesselIMONumber` + - `carrierServiceName` + - `carrierServiceCode` + - `universalServiceReference` + - `carrierExportVoyageNumber` + - `universalExportVoyageReference` + - `expectedDepartureDate` + - `expectedArrivalAtPlaceOfDeliveryStartDate` or `expectedArrivalAtPlaceOfDeliveryEndDate` + - the following `locationTypeCode` in `shipmentLocations`: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + + **Note:** `ROU` (Routing Reference) can be used as a `shipmentLocation` in order to comply with `shipmentLocation` being a mandatory field. + example: Route123 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided. If `declaredValue` is not provided, this field must be empty. + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel at `Port of Loading` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureFromPlaceOfReceiptDate` (at PRE) is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedDepartureFromPlaceOfReceiptDate: + type: string + format: date + description: | + The date when the shipment is expected to be handed over to the carrier at `Place of Receipt` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureDate` (at POL) is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + deprecated: true + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + + **Deprecated:** In case both provider and consumer are on API v2.0.2 (or later), please use `transportDocumentReferences` property instead. + example: reserved-HHL123 + transportDocumentReferences: + type: array + description: | + An array of `transportDocumentReference` requested by the Shipper to be associated to this Booking. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + The `transportDocumentReference` requested by the Shipper to be associated to this Booking. + example: reserved-HHL123 + requestedNumberOfTransportDocuments: + type: integer + format: int32 + minimum: 1 + description: | + The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + example: 3 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: | + The contact details of the Booking requestor(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedPreCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **pre carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedOnCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **on carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + + ################ + # Update Booking + ################ + UpdateBooking: + type: object + title: Update Booking + description: | + Updates a booking request or creates a Booking amendment for a Confirmed Booking + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** One of `serviceContractReference` or `contractQuotationReference` must be provided, but not both. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** One of `contractQuotationReference` or `serviceContractReference` must be provided, but not both. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank. If `routingReference` is provided - this property MUST not be provided. + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank. If `routingReference` is provided - this property MUST not be provided. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: 2103N + routingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 5000 + description: | + A reference to a predefined `route` specified in **Commercial Schedules - Point to Point**. When specifying this property - it is not needed to specify the following properties: + - `vessel` which includes: + - `vesselName` + - `vesselIMONumber` + - `carrierServiceName` + - `carrierServiceCode` + - `universalServiceReference` + - `carrierExportVoyageNumber` + - `universalExportVoyageReference` + - `expectedDepartureDate` + - `expectedArrivalAtPlaceOfDeliveryStartDate` or `expectedArrivalAtPlaceOfDeliveryEndDate` + - the following `locationTypeCode` in `shipmentLocations`: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + example: Route123 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided. If `declaredValue` is not provided, this field must be empty. + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel at `Port of Loading` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureFromPlaceOfReceiptDate` (at PRE) is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedDepartureFromPlaceOfReceiptDate: + type: string + format: date + description: | + The date when the shipment is expected to be handed over to the carrier at `Place of Receipt` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureDate` (at POL) is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + deprecated: true + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + + **Deprecated:** In case both provider and consumer are on API v2.0.2 (or later), please use `transportDocumentReferences` property instead + example: reserved-HHL123 + transportDocumentReferences: + type: array + description: | + An array of `transportDocumentReference` requested by the Shipper to be associated to this Booking. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + The `transportDocumentReference` requested by the Shipper to be associated to this Booking. + example: reserved-HHL123 + requestedNumberOfTransportDocuments: + type: integer + format: int32 + minimum: 1 + description: | + The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + example: 3 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: | + The contact details of the Booking requestor(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedPreCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **pre carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedOnCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **on carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + required: + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + + DocumentPartiesReq: + type: object + title: Document Parties (Shipper) + description: | + All `Parties` with associated roles. + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + issueTo: + $ref: '#/components/schemas/IssueToParty' + other: + type: array + description: 'A list of document parties that can be optionally provided at booking stage.' + items: + $ref: '#/components/schemas/OtherDocumentParty' + required: + - bookingAgent + + ############### + # Fetch Booking + ############### + Booking: + type: object + title: Booking + description: | + The Booking - it can be a Booking request or a Confirmed Booking, defined by the `bookingStatus` property. + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + bookingStatus: + type: string + maxLength: 50 + description: | + The status of the `Booking`. Possible values are: + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + type: string + maxLength: 50 + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are: + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** One of `serviceContractReference` or `contractQuotationReference` must be provided, but not both. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** One of `contractQuotationReference` or `serviceContractReference` must be provided, but not both. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank. If `routingReference` is provided - this property MUST not be provided. + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank. If `routingReference` is provided - this property MUST not be provided. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + maxLength: 5 + minLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + **Condition:** If `routingReference` is provided - this property MUST not be provided. + example: 2103N + routingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 5000 + description: | + A reference to a predefined `route` specified in **Commercial Schedules - Point to Point**. When specifying this property - it is not needed to specify the following properties: + - `vessel` which includes: + - `vesselName` + - `vesselIMONumber` + - `carrierServiceName` + - `carrierServiceCode` + - `universalServiceReference` + - `carrierExportVoyageNumber` + - `universalExportVoyageReference` + - `expectedDepartureDate` + - `expectedArrivalAtPlaceOfDeliveryStartDate` or `expectedArrivalAtPlaceOfDeliveryEndDate` + - the following `locationTypeCode` in `shipmentLocations`: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + example: Route123 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided. If `declaredValue` is not provided, this field must be empty. + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel at `Port of Loading` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureFromPlaceOfReceiptDate` (at PRE) is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedDepartureFromPlaceOfReceiptDate: + type: string + format: date + description: | + The date when the shipment is expected to be handed over to the carrier at `Place of Receipt` as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` or `expectedDepartureDate` (at POL) is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. If `routingReference` is provided - this property MUST not be provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + deprecated: true + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + + **Deprecated:** In case both provider and consumer are on API v2.0.2 (or later), please use `transportDocumentReferences` property instead + example: reserved-HHL123 + transportDocumentReferences: + type: array + description: | + An array of `transportDocumentReference` to be associated to this Booking. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + The `transportDocumentReference` to be associated to this Booking. + example: reserved-HHL123 + requestedNumberOfTransportDocuments: + type: integer + format: int32 + minimum: 1 + description: | + The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + example: 3 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + termsAndConditions: + type: string + maxLength: 50000 + description: | + Carrier terms and conditions of transport. + example: Any reference in... + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentParties' + partyContactDetails: + type: array + description: | + The contact details of the Booking requestor(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedPreCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **pre carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedOnCarriageModeOfTransport: + type: string + maxLength: 50 + description: | + The `Mode of Transport` requested ​by the shipper for the **on carriage**. The supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipment' + confirmedEquipments: + type: array + description: | + A list of `Confirmed Equipments` + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ConfirmedEquipment' + transportPlan: + type: array + description: | + A list of `Transport` objects (legs) describing the entire transport plan including transshipments. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/Transport' + shipmentCutOffTimes: + type: array + description: | + A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ShipmentCutOffTime' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` provided by the carrier + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + charges: + type: array + description: | + A list of `Charges` + items: + $ref: '#/components/schemas/Charge' + carrierClauses: + type: array + description: | + Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20000 + description: | + The content of the clause. + example: It is not allowed to... + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + required: + - bookingStatus + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + + InvoicePayableAt: + title: Invoice Payable At + type: object + description: | + Location where payment of ocean freight and charges for the main transport will take place by the customer. + + The location must be provided as a `UN Location Code` + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + required: + - UNLocationCode + PlaceOfBLIssue: + title: Place of B/L Issue + type: object + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + **Condition:** The location can be specified as one of `UN Location Code` or `CountryCode`, but not both. + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + required: + - UNLocationCode + - type: object + title: Country Code + properties: + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: DK + required: + - countryCode + + DocumentParties: + type: object + title: Document Parties + description: | + All `Parties` with associated roles. + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + issueTo: + $ref: '#/components/schemas/IssueToParty' + other: + type: array + description: 'A list of document parties that can be optionally provided at booking stage.' + items: + $ref: '#/components/schemas/OtherDocumentParty' + + ######################## + # Active Reefer Settings + ######################## + ActiveReeferSettings: + type: object + title: Active Reefer Settings + description: | + The specifications for a Reefer equipment. + + **Condition:** Only applicable when `isNonOperatingReefer` is set to `false` + properties: + temperatureSetpoint: + type: number + format: float + description: | + Target value of the temperature for the Reefer based on the cargo requirement. + example: -15 + temperatureUnit: + type: string + description: | + The unit for temperature in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + + **Condition:** Mandatory if `temperatureSetpoint` is provided. If `temperatureSetpoint` is not provided, this field must be empty. + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere O2 target value + example: 25 + co2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 target value + example: 25 + humiditySetpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere humidity target value + example: 95.6 + airExchangeSetpoint: + type: number + format: float + minimum: 0 + description: | + Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container + example: 15.4 + airExchangeUnit: + type: string + description: | + The unit for `airExchange` in metrics- or imperial- units per hour + - `MQH` (Cubic metre per hour) + - `FQH` (Cubic foot per hour) + + **Condition:** Mandatory if `airExchange` is provided. If `airExchange` is not provided, this field must be empty. + enum: + - MQH + - FQH + example: MQH + isVentilationOpen: + type: boolean + description: | + If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed` + example: true + isDrainholesOpen: + type: boolean + description: | + Is drain holes open on the container + example: true + isBulbMode: + type: boolean + description: | + Is special container setting for handling flower bulbs active + example: true + isColdTreatmentRequired: + type: boolean + description: | + Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD + example: true + isControlledAtmosphereRequired: + type: boolean + description: | + Indicator of whether cargo requires Controlled Atmosphere. + example: true + isPreCoolingRequired: + type: boolean + description: | + Indicator whether reefer container should be pre-cooled to the temperature setting required at time of release from depot + example: true + isGeneratorSetRequired: + type: boolean + description: | + Indicator whether reefer container should have a generator set attached at time of release from depot + example: true + required: + - temperatureSetpoint + - temperatureUnit + + ################## + # Document Parties + ################## + PartyAddress: + type: object + title: Party Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street of the party's address. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street of the party's address. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the party's street number. + example: 2nd + postCode: + type: string + maxLength: 10 + description: The post code of the party's address. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The city name of the party's address. + example: Amsterdam + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + stateRegion: + type: string + maxLength: 65 + description: The state/region of the party's address. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - street + - city + - countryCode + OtherDocumentParty: + type: object + title: Other Document Party + description: | + A list of document parties that can be optionally provided at booking stage + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + - `N1` (First Notify Party) + - `N2` (Second Notify Party) + - `NI` (Other Notify Party) + - `NAC` (Named Account Customer) + example: DDS + required: + - party + - partyFunction + + BookingAgent: + type: object + title: Booking Agent + description: | + The party placing the booking request on behalf of the customer. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Booking Agent`. + example: HHL007 + required: + - partyName + + Shipper: + type: object + title: Shipper + description: | + The party by whom or in whose name or on whose behalf a contract of carriage of goods by sea has been concluded with a carrier, or the party by whom or in whose name, or on whose behalf, the goods are actually delivered to the carrier in relation to the contract of carriage by sea. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Shipper`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Shipper`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Shipper`. + example: HHL007 + required: + - partyName + + Consignee: + type: object + title: Consignee + description: | + The party to which goods are consigned in the Master Bill of Lading. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Consignee`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Consignee`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + required: + - partyName + + ServiceContractOwner: + type: object + title: Service Contract Owner + description: | + The party signing the service contract with the carrier. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Service Contract Owner`. + example: HHL007 + required: + - partyName + + CarrierBookingOffice: + type: object + title: Carrier Booking Office + description: | + The carrier office responsible for processing the booking. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + address: + $ref: '#/components/schemas/Address' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - UNLocationCode + + IssueToParty: + type: object + title: Issue To Party + description: | + The party that receives **possession** of the original Bill of Lading upon issuance. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + sendToPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the transaction party. + The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + + **Condition:** Only applicable when `isElectronic=true` and `transportDocumentTypeCode=BOL`. The property **MUST** be absent for paper B/Ls (`isElectronic=false`) + example: BOLE + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + required: + - partyName + + Party: + type: object + title: Party + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Party`. + example: HHL007 + required: + - partyName + + PartyContactDetail: + type: object + title: Party Contact Detail + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + IdentifyingCode: + type: object + title: Identifying Code + description: | + A code and value that uniquely identifies a party. + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `GSBN` (Global Shipping Business Network) + - `WISE` (WiseTech) + - `GLEIF` (Global Legal Entity Identifier Foundation) + - `W3C` (World Wide Web Consortium) + - `DNB` (Dun and Bradstreet) + - `FMC` (Federal Maritime Commission) + - `DCSA` (Digital Container Shipping Association) + - `ZZZ` (Mutually defined) + example: W3C + partyCode: + type: string + maxLength: 150 + description: | + Code to identify the party as provided by the code list provider + example: MSK + codeListName: + type: string + maxLength: 100 + description: | + The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be: + - `DID` (Decentralized Identifier) for `codeListProvider` `W3C` + - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF` + - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB` + example: DID + required: + - codeListProvider + - partyCode + TaxLegalReference: + type: object + title: Tax & Legal Reference + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: IN + value: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + required: + - type + - countryCode + - value + + ########### + # Reference + ########### + ReferenceShipper: + type: object + title: Reference (Shipper) + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + Reference: + type: object + title: Reference + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `ECR` (Empty container release reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + ################## + # Customs Reference + ################## + CustomsReference: + type: object + title: Customs Reference + description: | + Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |ACID|EG|Advance Cargo Information Declaration in Egypt| + |CERS|CA|Canadian Export Reporting System| + |ITN|US|Internal Transaction Number in US| + |PEB|ID|PEB reference number| + |CSN|IN|Cargo Summary Notification (CSN)| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined in the relevant customs jurisdiction. + example: ACID + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: EG + values: + type: array + minItems: 1 + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `customsReference` + example: '4988470982020120017' + required: + - type + - countryCode + - values + + ################### + # Shipment Location + ################### + ShipmentLocation: + type: object + title: Shipment Location + description: | + Maps the relationship between `Shipment` and `Location`, e.g., the `Place of Receipt` and the `Place of Delivery` for a specific shipment. This is a reusable object between `Booking` and `Transport Document` + + **Condition:** In case `routingReference` is provided - then `PRE` (Place of Receipt), `POL` (Port of Loading), `POD` (Port of Discharge) and `PDE` (Place of Delivery) MUST not be provided. + properties: + location: + $ref: '#/components/schemas/Location' + locationTypeCode: + type: string + maxLength: 3 + description: | + Links to the Location Type Code defined by DCSA. Possible values are: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + - `PCF` (Pre-carriage From) + - `OIR` (Onward In-land Routing) + - `ORI` (Origin of goods) + - `IEL` (Container intermediate export stop off location) + - `PTP` (Prohibited transshipment port) + - `RTP` (Requested transshipment port) + - `FCD` (Full container drop-off location) + - `ROU` (Routing Reference) + + **Note:** Use `ROU` when `routingReference` is used in order to comply with the need to add at least 1 `shipmentLocation` to a Booking request. + example: PRE + required: + - location + - locationTypeCode + + Location: + type: object + title: Location + description: | + The location can be specified using **any** of the nested structures: + - `address` (used to specify the location via an Address) + - `UNLocationCode` + - `facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`) + - `geoCoordinate` (used to specify a location using `latitude` and `longitude`) + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: CMP Container Terminal Copenhagen + UNLocationCode: DKCPH + facility: + facilityCode: CMPDK + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + ###################### + # Requested Equipments + ###################### + RequestedEquipment: + type: object + title: Requested Equipment + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of requested equipment units. + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + originEmptyContainerPickup: + $ref: '#/components/schemas/OriginEmptyContainerPickup' + fullContainerPickupDateTime: + type: string + format: date-time + description: | + The date and time when the loaded container(s) need to be picked up from the `Place of Receipt`, if provided. + example: '2025-05-16T09:14:00Z' + equipmentReferences: + description: | + A list of equipments to be used by the shipper if known at the time of booking + type: array + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/Commodity' + required: + - ISOEquipmentCode + - units + - isShipperOwned + + RequestedEquipmentShipper: + type: object + title: Requested Equipment (Shipper) + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of requested equipment units. + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + originEmptyContainerPickup: + $ref: '#/components/schemas/OriginEmptyContainerPickup' + fullContainerPickupDateTime: + type: string + format: date-time + description: | + The date and time when the loaded container(s) need to be picked up from the `Place of Receipt`, if provided. + example: '2025-05-16T09:14:00Z' + equipmentReferences: + description: | + A list of equipments to be used by the shipper if known at the time of booking + type: array + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/CommodityShipper' + required: + - ISOEquipmentCode + - units + - isShipperOwned + + TareWeight: + type: object + title: Tare Weight + description: | + The weight of an empty container (gross container weight). + + **Condition:** In case of Shipper Owned Containers (`SOC`) this is a required property + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of an empty container (gross container weight). + example: 4000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + ContainerPositioning: + type: object + title: Container Positioning + description: | + An object to capture the `Location` together with an optional `Date and Time`. + properties: + dateTime: + type: string + format: date-time + description: | + The date and time requested by the shipper for the positioning of the container(s) at the Container positioning location (`CPO`), if provided, or the Place of Receipt (`PRE`) if `CPO` location is not provided. + example: '2024-09-04T09:41:00Z' + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + required: + - location + + ContainerPositioningEstimated: + type: object + title: Container Positioning Estimated + description: | + An object to capture the `Location` together with an optional `Date and Time`. + properties: + estimatedDateTime: + type: string + format: date-time + description: | + The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + example: '2024-09-04T09:41:00Z' + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + required: + - location + ContainerPositioningLocation: + type: object + title: Container Positioning Location + description: | + An object to capture the `Container Positioning Location`. + + The location of the customer facility where the container(s) will be loaded. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Shanghai Shengdong International Container Terminal + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + EmptyContainerDepotReleaseLocation: + type: object + title: Empty Container Depot Release Location + description: | + An object to capture the `Empty Container Depot Release Location`. + + The location of the depot from which the empty container(s) will be released from + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Shanghai Shengdong International Container Terminal + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + ########### + # Commodity + ########### + CommodityShipper: + type: object + title: Commodity (Shipper) + description: | + Type of goods, defined by its commodity type + properties: + commodityType: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 550 + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - commodityType + Commodity: + type: object + title: Commodity + description: | + Type of goods, defined by its commodity type + properties: + commoditySubReference: + type: string + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + description: | + A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking. + + **Condition:** Mandatory to provide for `CONFIRMED` bookings + example: COM-001 + commodityType: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 550 + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - commodityType + + ExportLicense: + type: object + title: Export License + description: | + `Export License` required for this commodity + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Export License` applicable to the booking. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Export License` applicable to the booking. + example: '2024-09-21' + + ImportLicense: + type: object + title: Import License + description: | + `Import License` required for this commodity + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that authorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Import License` applicable to the booking. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Import License` applicable to the booking. + example: '2024-09-21' + + CargoGrossWeightReq: + type: object + title: Cargo Gross Weight (Requested Equipment) + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Commodity` level + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoGrossWeight: + type: object + title: Cargo Gross Weight + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Requested Equipment` level. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoGrossVolume: + type: object + title: Cargo Gross Volume + description: | + The estimated grand total volume of the cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total volume of the cargo. + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + + CargoNetWeight: + type: object + title: Cargo Net Weight + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoNetVolume: + type: object + title: Cargo Net Volume + description: | + The estimated net total volume of the cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated net total volume of the cargo. + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + + ######################### + # National Commodity Code + ######################### + NationalCommodityCode: + type: object + title: National Commodity Code + description: | + The national commodity classification code linked to a country with a value. + + An example could look like this: + + | Type | Country | Value | + |-------|:-------:|-------------| + |NCM|BR|['1515', '2106', '2507', '2512']| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The national commodity classification code, which can be one of the following values defined by DCSA: + - `NCM` (Nomenclatura Comum do Mercosul) + - `HTS` (Harmonized Tariff Schedule) + - `SCHEDULE_B` ( Schedule B) + - `TARIC` (Integrated Tariff of the European Communities) + - `CN` (Combined Nomenclature) + - `CUS` (Customs Union and Statistics) + example: NCM + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: BR + values: + type: array + minItems: 1 + description: | + A list of `national commodity codes` values. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The value of the `National Commodity Code` + example: '1515' + example: + - '1515' + - '2106' + - '2507' + - '2512' + required: + - type + - values + + ################# + # Outer Packaging + ################# + OuterPackaging: + type: object + title: Outer Packaging + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + + **Condition:** Mandatory for DG (Dangerous Goods) cargo. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + + **Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available. + example: 5H + imoPackagingCode: + type: string + pattern: ^[A-Z0-9]{1,5}$ + minLength: 1 + maxLength: 5 + description: | + The code of the packaging as per IMO. + + **Condition:** only applicable to dangerous goods if specified in the [IMO IMDG code](https://www.imo.org/en/publications/Pages/IMDG%20Code.aspx). If not available, the `packageCode` as per UN recommendation 21 should be used. + example: 1A2 + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Commodity`. + + **Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide + example: 18 + description: + type: string + maxLength: 100 + description: | + Description of the outer packaging/overpack. + example: 'Drum, steel' + dangerousGoods: + type: array + description: | + A list of `Dangerous Goods` related to the `Commodity` + items: + $ref: '#/components/schemas/DangerousGoods' + + ################# + # Dangerous Goods + ################# + DangerousGoods: + type: object + title: Dangerous Goods + description: | + Specification for `Dangerous Goods`. It is mandatory to provide one of `UNNumber` or `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**. + oneOf: + - type: object + title: UN Number + properties: + UNNumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG. + example: '1463' + required: + - UNNumber + - type: object + title: NA Number + properties: + NANumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation. + example: '9037' + required: + - NANumber + properties: + codedVariantList: + type: string + pattern: ^[0-3][0-9A-Z]{3}$ + minLength: 4 + maxLength: 4 + description: | + Four-character code supplied by Exis Technologies that assists to remove ambiguities when identifying a variant within a single `UN number` or `NA number` that may occur when two companies exchange DG information. + + Character | Valid Characters | Description + :--------:|------------------|------------ + 1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group + 2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs + 3 and 4|0 to 9 and A to Z|Two sequence letters for other information, for the cases where the variant is required because of different in subrisks, packing instruction etc. + example: '2200' + properShippingName: + type: string + maxLength: 250 + description: | + The proper shipping name for goods under IMDG Code, or the product name for goods under IBC Code and IGC Code, or the bulk cargo shipping name for goods under IMSBC Code, or the name of oil for goods under Annex I to the MARPOL Convention. + example: 'Chromium Trioxide, anhydrous' + technicalName: + type: string + maxLength: 250 + description: | + The recognized chemical or biological name or other name currently used for the referenced dangerous goods as described in chapter 3.1.2.8 of the IMDG Code. + example: 'xylene and benzene' + imoClass: + type: string + maxLength: 4 + description: | + The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are: + - `1.1A` (Substances and articles which have a mass explosion hazard) + - `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard) + - `2.1` (Flammable gases) + - `8` (Corrosive substances) + example: 1.4S + subsidiaryRisk1: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + subsidiaryRisk2: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + isMarinePollutant: + type: boolean + description: | + Indicates if the goods belong to the classification of Marine Pollutant. + example: false + packingGroup: + type: integer + format: int32 + minimum: 1 + maximum: 3 + description: | + The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code. + example: 3 + isLimitedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code. + example: false + isExceptedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code. + example: false + isSalvagePackings: + type: boolean + description: | + Indicates if the cargo has special packaging for the transport, recovery or disposal of damaged, defective, leaking or nonconforming hazardous materials packages, or hazardous materials that have spilled or leaked. + example: false + isEmptyUncleanedResidue: + type: boolean + description: | + Indicates if the cargo is residue. + example: false + isWaste: + type: boolean + description: | + Indicates if waste is being shipped + example: false + isHot: + type: boolean + description: | + Indicates if high temperature cargo is shipped. + example: false + isCompetentAuthorityApprovalRequired: + type: boolean + description: | + Indicates if the cargo require approval from authorities + example: false + competentAuthorityApproval: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name and reference number of the competent authority providing the approval. + example: '{Name and reference...}' + segregationGroups: + type: array + description: | + List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code. + + **Condition:** only applicable to specific hazardous goods. + items: + type: string + maxLength: 2 + description: | + Grouping of Dangerous Goods having certain similar chemical properties. Possible values are: + - `1` (Acids) + - `2` (Ammonium Compounds) + - `3` (Bromates) + - `4` (Chlorates) + - `5` (Chlorites) + - `6` (Cyanides) + - `7` (Heavy metals and their salts) + - `8` (Hypochlorites) + - `9` (Lead and its compounds) + - `10` (Liquid halogenated hydrocarbons) + - `11` (Mercury and mercury compounds) + - `12` (Nitrites and their mixtures) + - `13` (Perchlorates) + - `14` (Permanganates) + - `15` (Powdered metals) + - `16` (Peroxides), + - `17` (Azides) + - `18` (Alkalis) + example: '12' + innerPackagings: + type: array + description: | + A list of `Inner Packings` contained inside this `outer packaging/overpack`. + items: + $ref: '#/components/schemas/InnerPackaging' + emergencyContactDetails: + $ref: '#/components/schemas/EmergencyContactDetails' + EMSNumber: + type: string + maxLength: 7 + description: | + The emergency schedule identified in the IMO EmS Guide - Emergency Response Procedures for Ships Carrying Dangerous Goods. Comprises 2 values; 1 for spillage and 1 for fire. Possible values spillage: S-A to S-Z. Possible values fire: F-A to F-Z. + example: F-A S-Q + endOfHoldingTime: + type: string + format: date + description: | + Date by when the refrigerated liquid needs to be delivered. + example: '2021-09-03' + fumigationDateTime: + type: string + format: date-time + description: | + Date & time when the container was fumigated + example: '2024-09-04T09:41:00Z' + isReportableQuantity: + type: boolean + description: | + Indicates if a container of hazardous material is at the reportable quantity level. If `TRUE`, a report to the relevant authority must be made in case of spill. + example: false + inhalationZone: + type: string + maxLength: 1 + minLength: 1 + description: | + The zone classification of the toxicity of the inhalant. Possible values are: + - `A` (Hazard Zone A) can be assigned to specific gases and liquids + - `B` (Hazard Zone B) can be assigned to specific gases and liquids + - `C` (Hazard Zone C) can **only** be assigned to specific gases + - `D` (Hazard Zone D) can **only** be assigned to specific gases + example: A + grossWeight: + $ref: '#/components/schemas/GrossWeight' + netWeight: + $ref: '#/components/schemas/NetWeight' + netExplosiveContent: + $ref: '#/components/schemas/NetExplosiveContent' + netVolume: + $ref: '#/components/schemas/NetVolume' + limits: + $ref: '#/components/schemas/Limits' + specialCertificateNumber: + type: string + maxLength: 255 + description: | + Text field to indicate certificate number & segment for specific stowage requirements overruling IMDG code + example: '22663:3' + additionalContainerCargoHandling: + type: string + maxLength: 255 + description: | + Text field to provide cargo handling information already known at the booking stage. + example: To be handled with extreme care + required: + - properShippingName + - imoClass + - isMarinePollutant + - isLimitedQuantity + - isExceptedQuantity + - isSalvagePackings + - isEmptyUncleanedResidue + - isWaste + - isHot + - isCompetentAuthorityApprovalRequired + - isReportableQuantity + - emergencyContactDetails + - grossWeight + GrossWeight: + type: object + title: Gross Weight + description: | + Total weight of the goods carried, including packaging. + properties: + value: + type: number + format: float + example: 12000.3 + minimum: 0 + exclusiveMinimum: true + description: | + The grand total weight of the DG cargo and weight per `UNNumber`/`NANumber` including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetWeight: + type: object + title: Net Weight + description: | + Total weight of the goods carried, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Total weight of the goods carried, excluding packaging. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetExplosiveContent: + type: object + title: Net Explosive Content + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + example: 2.4 + unit: + type: string + description: | + Unit of measure used to describe the `netExplosiveWeight`. Possible values are: + - `KGM` (Kilograms) + - `LBR` (Pounds) + - `GRM` (Grams) + - `ONZ` (Ounce) + enum: + - KGM + - LBR + - GRM + - ONZ + example: KGM + required: + - value + - unit + NetVolume: + type: object + title: Net Volume + description: | + The volume of the referenced dangerous goods. + + **Condition:** only applicable to liquids and gas. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The volume of the referenced dangerous goods. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + - `LTR` (Litre) + enum: + - MTQ + - FTQ + - LTR + example: MTQ + required: + - value + - unit + InnerPackaging: + type: object + title: Inner Packaging + description: | + Object for inner packaging specification + properties: + quantity: + type: integer + format: int32 + description: | + Count of `Inner Packagings` of the referenced `Dangerous Goods`. + example: 20 + material: + type: string + maxLength: 100 + description: | + The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`. + example: Plastic + description: + type: string + maxLength: 100 + description: | + Description of the packaging. + example: Woven plastic water resistant Bag + required: + - quantity + - material + - description + EmergencyContactDetails: + type: object + title: Emergency Contact Details + description: | + 24 hr emergency contact details + properties: + contact: + type: string + maxLength: 255 + description: | + Name of the Contact person during an emergency. + example: Henrik Larsen + provider: + type: string + maxLength: 255 + description: | + Name of the third party vendor providing emergency support + example: GlobeTeam + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + referenceNumber: + type: string + maxLength: 255 + description: | + Contract reference for the emergency support provided by an external third party vendor. + example: '12234' + required: + - contact + - phone + Limits: + type: object + title: Limits + description: | + Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure. + properties: + temperatureUnit: + type: string + description: | + The unit for **all attributes in the limits structure** in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + enum: + - CEL + - FAH + example: CEL + flashPoint: + type: number + format: float + description: | + Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air. + + **Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code. + example: 42 + transportControlTemperature: + type: number + format: float + description: | + Maximum temperature at which certain substance (such as organic peroxides and self-reactive and related substances) can be safely transported for a prolonged period. + example: 24.1 + transportEmergencyTemperature: + type: number + format: float + description: | + Temperature at which emergency procedures shall be implemented + example: 74.1 + SADT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating decomposition may occur in a substance + example: 54.1 + SAPT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating polymerization may occur in a substance + example: 70 + required: + - temperatureUnit + + ##################### + # Confirmed Equipment + ##################### + ConfirmedEquipment: + type: object + title: Confirmed Equipment + description: | + The confirmed equipments for the booking + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of confirmed equipment units + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated). + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioningEstimated' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + originEmptyContainerPickup: + $ref: '#/components/schemas/OriginEmptyContainerPickup' + required: + - ISOEquipmentCode + - units + + EmptyContainerPickup: + type: object + deprecated: true + title: Empty Container Pickup + description: | + The date and time and location for the empty container pick-up. + + **Condition:** Only applicable to merchant haulage service at origin (`Receipt type at origin = 'CY'`). + + **Deprecated:** In case both provider and consumer are on API v2.0.2 (or later), please use `originEmptyContainerPickup` instead as it contains no conditions. + properties: + dateTime: + type: string + format: date-time + description: | + The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided. + example: '2024-09-04T09:41:00Z' + depotReleaseLocation: + $ref: '#/components/schemas/EmptyContainerDepotReleaseLocation' + + OriginEmptyContainerPickup: + type: object + title: Origin Empty Container Pickup + description: | + The date, time and location of the depot from which the empty container(s) will be released from. + + **Note:** Applicable to **all** `Receipt type at origin`. + properties: + dateTime: + type: string + format: date-time + description: | + The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided. + example: '2024-09-04T09:41:00Z' + depotReleaseLocation: + $ref: '#/components/schemas/EmptyContainerDepotReleaseLocation' + ########### + # Transport + ########### + Transport: + type: object + title: Transport + description: | + A single `leg` of the `Transport Plan` + properties: + transportPlanStage: + type: string + description: | + Code qualifying a specific stage of transport e.g. pre-carriage, main carriage transport or on-carriage transport + - `PRC` (Pre-Carriage) + - `MNC` (Main Carriage Transport) + - `ONC` (On-Carriage Transport) + enum: + - PRC + - MNC + - ONC + example: PRC + transportPlanStageSequenceNumber: + type: integer + format: int32 + description: | + Sequence number of the transport plan stage + example: 5 + loadLocation: + $ref: '#/components/schemas/LoadLocation' + dischargeLocation: + $ref: '#/components/schemas/DischargeLocation' + plannedDepartureDate: + type: string + format: date + description: | + The planned date of departure. + + **Note:** In case no date is available, the date `1970-01-01` should be used. + example: '2021-05-17' + plannedArrivalDate: + type: string + format: date + description: | + The planned date of arrival. + + **Note:** In case no date is available, the date `1970-01-01` should be used. + example: '2021-05-19' + modeOfTransport: + type: string + maxLength: 50 + description: | + The mode of transport as defined by DCSA. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `RAIL_TRUCK`(Rail and truck) + - `BARGE_TRUCK`(Barge and truck) + - `BARGE_RAIL`(Barge and rail) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + vesselName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + type: string + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: '9321483' + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier-specific code of the service for which the schedule details are published. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierImportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + example: 2103N + universalImportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + example: 2103S + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + required: + - transportPlanStage + - transportPlanStageSequenceNumber + - loadLocation + - dischargeLocation + - plannedDepartureDate + - plannedArrivalDate + LoadLocation: + type: object + title: Load Location + description: | + An object to capture the `Load Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + DischargeLocation: + type: object + title: Discharge Location + description: | + An object to capture the `Discharge Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Transnet Port Terminals Cape Town + UNLocationCode: ZACPT + facility: + facilityCode: TNCT + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + ######################## + # Shipment Cut-off times + ######################## + ShipmentCutOffTime: + type: object + title: Shipment Cut-Off Time + description: | + `Cut off times` defined by the carrier + properties: + cutOffDateTimeCode: + type: string + maxLength: 3 + description: | + Code for the cut-off time. Possible values are: + - `DCO` (Documentation cut-off) + - `VCO` (VGM cut-off) + - `FCO` (FCL delivery cut-off) + - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS` + - `EFC` (Earliest full-container delivery date) + example: DCO + cutOffDateTime: + type: string + format: date-time + description: | + Actual cut-off time + example: '2024-09-04T09:41:00Z' + required: + - cutOffDateTimeCode + - cutOffDateTime + + ########################## + # Advance Manifest Filings + ########################## + AdvanceManifestFiling: + type: object + title: Advance Manifest Filing + description: | + An Advance Manifest Filing defined by a Manifest type code in combination with a country code. + + A small list of **potential** examples: + + | manifestTypeCode | countryCode | Description | + |-----------------------|:-------------:|-------------| + |ACI|EG|Advance Cargo Information in Egypt| + |ACE|US|Automated Commercial Environment in the United States| + |AFR|JP|Cargo Summary Notification (CSN)| + properties: + manifestTypeCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The Manifest type code as defined by the provider. + example: ACE + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: US + example: + manifestTypeCode: ACE + countryCode: US + required: + - manifestTypeCode + + ######## + # Charge + ######## + Charge: + type: object + title: Charge + description: | + Addresses the monetary value of freight and other service charges for a `Booking`. + properties: + chargeName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + Free text field describing the charge to apply + example: Documentation fee - Destination + currencyAmount: + type: number + format: float + minimum: 0 + description: | + The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals. + example: 1012.12 + currencyCode: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency for the charge, using a 3-character code according to [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + example: DKK + paymentTermCode: + type: string + description: | + An indicator of whether a charge is prepaid (PRE) or collect (COL). When prepaid, the charge is the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charge is the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + calculationBasis: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The code specifying the measure unit used for the corresponding unit price for this cost, such as per day, per ton, per square metre. + example: Per day + unitPrice: + type: number + format: float + minimum: 0 + description: | + The unit price of this charge item in the currency of the charge. + example: 3456.6 + quantity: + type: number + format: float + minimum: 0 + description: | + The amount of unit for this charge item. + example: 34.4 + required: + - chargeName + - currencyAmount + - currencyCode + - paymentTermCode + - calculationBasis + - unitPrice + - quantity + + ########################## + # OriginChargesPaymentTerm + ########################## + OriginChargesPaymentTerm: + type: object + title: Origin Charges Payment Term + description: | + An indicator of whether origin charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + + ############################### + # DestinationChargesPaymentTerm + ############################### + DestinationChargesPaymentTerm: + type: object + title: Destination Charges Payment Term + description: | + An indicator of whether destination charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + + ######## + # Vessel + ######## + Vessel: + type: object + title: Vessel + description: | + Vessels related to this booking request. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and `carrierServiceCode` or `carrierServiceName` are blank. If `routingReference` is provided - this object MUST not be provided. + required: + - name + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + type: string + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: '9321483' diff --git a/cs/v1/CS_v1.0.2.yaml b/cs/v1/CS_v1.0.2.yaml new file mode 100644 index 00000000..11e9cb29 --- /dev/null +++ b/cs/v1/CS_v1.0.2.yaml @@ -0,0 +1,1773 @@ +openapi: 3.0.3 +info: + title: DCSA OpenAPI specification for Commercial Schedules + version: 1.0.2 + description: | + API specification issued by [Digital Container Shipping Association (DCSA)](https://dcsa.org/). + + The Commercial Schedules API offers BCOs, LSPs, and Solution Platforms three different methods and endpoints to access schedules from carriers based on their specific needs: Point-to-Point Routings, Port Schedules, and Vessel Schedules. + + **Commercial schedules - point-to-point routings**: provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs. + + **Commercial schedules – port schedules**: provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps. + + **Commercial schedules – vessel schedules**: provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s). + + **All use cases mentioned in this API specification refer to use cases defined in the Commercial Schedules Interface Standard.** + + The Commercial Schedules endpoints can be implemented independently: + + `1. GET /v1/point-to-point-routes # For Point to Point Routings` + + `2. GET /v1/port-schedules # For Port Schedules` + + `3. GET /v1/vessel-schedules # For Vessel Schedules` + + Visit the [DCSA Website](https://dcsa.org/standards/commercial-schedules/) to find other documentation related to the standard publication (i.e. Interface Standard, Information Model). + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design). + + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/cs/v1#v102). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + license: + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + name: Apache 2.0 + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org/' + email: info@dcsa.org +paths: + /v1/point-to-point-routes: + get: + summary: Point to Point Routing + tags: + - Point To Point + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/PointToPoint' + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/point-to-point' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7005 + property: placeOfDelivery + value: SG + errorCodeText: invalidQuery + errorCodeMessage: PlaceOfDelivery does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/point-to-point' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Unable to process request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-point-to-point + parameters: + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: placeOfReceipt + description: The `UNLocationCode` specifying where the place is located. + required: true + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: placeOfDelivery + description: The `UNLocationCode` specifying where the place is located. + required: true + - schema: + type: string + format: date + example: '2021-04-01' + in: query + name: departureStartDate + description: | + Limit the result based on the earliest departureDate. + - If provided without departureEndDate, returns all routings with departures from the specified departureStartDate onwards. + - If provided with departureEndDate, returns all routings with departures within the specified date range, inclusive of both dates. + - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date. + - schema: + type: string + format: date + example: '2021-05-01' + in: query + name: departureEndDate + description: | + Limit the result based on the latest departureDate. + - If provided without departureStartDate, returns all routings with departures up to the specified departureEndDate. + - If provided with departureStartDate, returns all routings with departures within the specified date range, inclusive of both dates. + - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date. + - schema: + type: string + format: date + example: '2021-04-01' + in: query + name: arrivalStartDate + description: | + Limit the result based on the earliest arrivalDate. + - If provided without arrivalEndDate, returns all routings with arrivals from the specified arrivalStartDate. + - If provided with arrivalEndDate, returns all routings with arrivals within the specified date range, inclusive of both dates. + - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date. + - schema: + type: string + format: date + example: '2021-05-01' + in: query + name: arrivalEndDate + description: | + Limit the result based on the latest arrivalDate. + - If provided without arrivalStartDate, returns all routings with arrivals up to the specified arrivalEndDate. + - If provided with arrivalStartDate, returns all routings with arrivals within the specified date range, inclusive of both dates. + - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date. + - schema: + type: integer + example: 1 + format: int32 + minimum: 0 + in: query + name: maxTranshipment + description: | + Specifies the maximum number of transhipments that the proposed routings can have in the response. By default, transhipments are allowed and the responses can have either direct routings or routings with transhipment. The default value of maximum transhipments is defined by the carrier for when the consumer does not provide a value. If the user sets the number of transhipments to 0, only direct routings can be returned in the response. + + **Note:** According to the DCSA definition, a “transhipment” specifically refers to transferring containers or cargo from one vessel to another, focusing exclusively on ocean transport. This means that, under the current interpretation, only vessel-to-vessel transfers are counted as transhipments. Moves between road, rail, or barge and a vessel (i.e., inland legs) do not fall under this definition and, therefore, should not be counted as transhipments. + - schema: + type: string + enum: + - CY + - SD + - CFS + maxLength: 3 + example: CY + in: query + name: receiptTypeAtOrigin + description: | + Indicates the type of service offered at Origin. **Carriers can choose to define a default value when the consumer does not provide it.** + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + - schema: + type: string + enum: + - CY + - SD + - CFS + maxLength: 3 + example: CY + in: query + name: deliveryTypeAtDestination + description: | + Indicates the type of service offered at Destination. **Carriers can choose to define a default value when the consumer does not provide it.** + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Point-to-Point` objects to return. + - schema: + type: string + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs. + + The list of solutions returned in the response can be tailored to a specific need by combining available query parameters. + + The minimum required query parameters are `placeOfReceipt` and `placeOfDelivery`. If no further query parameters are used to tailor the response, the provider of the GET endpoint will return their best suggestions in the response. + + The `GET /v1/point-to-point-routes` endpoint can be implemented independently of having implemented the `GET /v1/port-schedules` and `GET /v1/vessel-schedules` endpoints. + /v1/port-schedules: + get: + summary: Port Schedule + tags: + - Port Schedule + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/PortSchedule' + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/port-schedule' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7005 + property: port + value: SG + errorCodeText: invalidQuery + errorCodeMessage: Port does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/port-schedule' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-port-schedules + description: | + Provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps. + + The port must be identified by its UN Location Code. + + The required query parameters are `UNLocationCode` and `date`. + + If the requested port (identified with `UNLocationCode`) has multiple terminals (identified with `facilitySMDGCode`), the response will include a sorted list that provides all the arrivals and departures of the vessels for each terminal of the port (`UNLocationCode`). + + The `GET /v1/port-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/vessel-schedules` endpoints. + parameters: + - schema: + type: string + maxLength: 5 + example: NLAMS + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + in: query + name: UNLocationCode + description: The UN Location code specifying where the place is located. Specifying this filter will only return the set of all vessels arriving and departing from the port and its terminals. + required: true + - schema: + type: string + format: date + pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ + example: '2023-07-01' + in: query + name: date + description: The date since when the estimated arrival and departures of vessels in a given port is required. + required: true + - $ref: '#/components/parameters/Api-Version-Major' + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Port Schedule` objects to return. + - schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + parameters: [] + /v1/vessel-schedules: + get: + summary: Vessel Schedule + tags: + - Vessel Schedule + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/vessel-schedule' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.1 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/vessel-schedule' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-vessel-schedule + parameters: + - schema: + type: string + minLength: 7 + maxLength: 8 + pattern: ^\d{7,8}$ + example: '9321483' + in: query + name: vesselIMONumber + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + - schema: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: King of the Seas + in: query + name: vesselName + description: The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the vesselName is not unique and might match multiple vessels. + - schema: + type: string + maxLength: 11 + example: FE1 + in: query + name: carrierServiceCode + description: The carrier specific service code to filter by. The result will only return schedules including the service code. + - schema: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + example: SR12345A + in: query + name: universalServiceReference + description: The Universal Service Reference (USR) as defined by DCSA to filter by. + - schema: + type: string + maxLength: 50 + example: 2103S + in: query + name: carrierVoyageNumber + description: The carrier specific identifier of a Voyage - can be both `importVoyageNumber` and `exportVoyageNumber`. The result will only return schedules including the Ports where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`. + - schema: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + maxLength: 5 + example: 2201N + in: query + name: universalVoyageReference + description: The Universal Reference of a Voyage - can be both `importUniversalVoyageReference` and `exportUniversalVoyageReference`. The result will only return schedules including the Ports where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference`. + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: UNLocationCode + description: The UN Location Code specifying where a port is located. Specifying this filter will only return schedules including entire Voyages related to this particular UN Location Code. + - schema: + type: string + maxLength: 6 + example: APM + in: query + name: facilitySMDGCode + description: The facilitySMDGCode specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including entire Voyages related to this particular `facilitySMDGCode`. It is recommended to specify a value for this query parameter only if a value is provided for `UNLocationCode`. + - schema: + type: string + example: MAEU + maxLength: 10 + in: query + name: vesselOperatorCarrierCode + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + - schema: + type: string + format: date + example: '2020-04-06' + in: query + name: startDate + description: | + The start date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or after (≥) the `startDate` the entire Voyage (import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call. + If this filter is not provided, the default value is **3 months** prior to the request time. + - schema: + type: string + format: date + example: '2020-04-10' + in: query + name: endDate + description: | + The end date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or before (≤) the `endDate` the entire Voyage(import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call. + If this filter is not provided, the default value is **6 months** after the request time. + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Service Schedule` objects to return. + - schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s). + + The list of schedules returned in the response can be tailored to specific needs by combining available query parameters. + + A filter parameter or a combination of filter parameters MUST always be provided to call the endpoint. Examples of typical query parameters and expected payload returned in the response: + + - a) `carrierServiceCode`: Get all vessels and their full voyages within a service + + - b) `carrierServiceCode` **&** `carrierVoyageNumber`: Get a specific full voyage within a service + + - c) `carrierServiceCode` **&** `vesselIMONumber`: Get a specific vessel’s full voyages within a service. + + - d) `vesselIMONumber`: Get all full voyages for a specific vessel across all the services in which it is involved. + + - e) `UNLocationCode`: Get all vessels and their full voyages where the specific `UNLocationCode` is involved + + - f) `UNLocationCode` **&** `facilitySMDGCode`: Get all vessels and their full voyages where the specific `UNLocationCode` and `facilitySMDGCode` is involved + + Other combinations using `vesselName`, `universalServiceReference`, `universalVoyageReference`, `vesselOperatorCarrierCode`, `startDate`, `endDate` are possible. + + The filter parameters `startDate` and `endDate` MUST always be used in combination with any of the other available parameters. + + The resulting payload returned in the responses will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`. + + Be aware that it is possible to specify filters that are mutually exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: `&vesselIMONumber=9321483&vesselName=King of the Seas`. If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list. + + If no `startDate` filter is provided, then **3 months** before the request date should be used as default. If no `endDate` filter is provided, then **6 months** after the request date should be used as default. The endpoint provider can customize these based on their business definitions and inform the consumers what to expect in a response when these filters are not used. + + The `GET /v1/vessel-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/port-schedules` endpoints. + + **IMPORTANT**: This endpoint is for carriers to make available vessel schedules to BCO, LSP, and Solution Platforms, with a commercial purpose; this is out of the boundaries of their vessel schedules alignment with other carriers and terminals for operational purposes for which the Operational Vessel Schedules [API](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS/3.0.0) is used between carriers, and carriers and terminals. + parameters: [] +components: + schemas: + PlaceOfReceipt: + title: Place of Receipt + type: object + description: | + The Location specifying where the place of receipt is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place. + PlaceOfDelivery: + title: Place of Delivery + type: object + description: | + The Location specifying where the place of delivery is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place. + PlaceOfArrival: + title: Place of Arrival + type: object + description: | + The Location specifying where the place of arrival is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place. + PlaceOfDeparture: + title: Place of Departure + type: object + description: | + The Location specifying where the place of departure is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place. + PointToPoint: + title: Point to Point + type: object + required: + - placeOfReceipt + - placeOfDelivery + - legs + properties: + placeOfReceipt: + $ref: '#/components/schemas/PlaceOfReceipt' + placeOfDelivery: + $ref: '#/components/schemas/PlaceOfDelivery' + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + solutionNumber: + type: integer + format: int32 + minimum: 1 + example: 1 + description: Solution number, starting with 1. Used to group and identify similar or same routings in the response as per the carrier commercial definitions. + routingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 5000 + description: | + A reference to be used when creating a **Booking** in the **Booking API**. + example: Route123 + transitTime: + type: integer + description: The estimated total time in days that it takes a shipment to move from place of receipt to place of delivery. Transit time includes stop-over time during transhipments and waiting time at connection points, if applicable, thus can vary between the same locations. + format: int32 + example: 10 + legs: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Leg' + PortSchedule: + title: Port Schedule + type: object + required: + - location + properties: + location: + $ref: '#/components/schemas/PortScheduleLocation' + vesselSchedules: + type: array + items: + $ref: '#/components/schemas/Schedule' + Schedule: + title: Schedule + type: object + required: + - servicePartners + - isDummyVessel + - timestamps + properties: + universalServiceReference: + type: string + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + servicePartners: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/ServicePartnerSchedule' + vessel: + $ref: '#/components/schemas/Vessel' + isDummyVessel: + type: boolean + description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist. + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + minLength: 5 + maxLength: 5 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + minLength: 5 + maxLength: 5 + timestamps: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Timestamp' + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + TransportCall: + title: Transport Call + type: object + required: + - transportCallReference + - carrierImportVoyageNumber + - timestamps + properties: + portVisitReference: + type: string + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + maxLength: 50 + example: NLRTM1234589 + transportCallReference: + type: string + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + example: SR11111X-9321483-2107W-NLRTM-HPD2-1-1 + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103N + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + universalImportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + maxLength: 5 + minLength: 5 + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + maxLength: 5 + minLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + location: + $ref: '#/components/schemas/TransportCallLocation' + timestamps: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Timestamp' + Timestamp: + title: Timestamp + type: object + required: + - eventTypeCode + - eventClassifierCode + - eventDateTime + properties: + eventTypeCode: + type: string + enum: + - ARRI + - DEPA + example: ARRI + description: | + Identifier for type of transportEvent. + + - `ARRI` (Arrived) + - `DEPA` (Departed) + eventClassifierCode: + type: string + enum: + - PLN + - EST + - ACT + example: PLN + description: | + Code for the event classifier. Values can vary depending on eventType. + + Possible values are: + - `ACT` (Actual) + - `EST` (Estimated) + - `PLN` (Planned) + eventDateTime: + type: string + format: date-time + description: The local date and time, when the event takes place. + example: '2025-01-14T09:21:00+01:00' + ServiceSchedule: + title: Service Schedule + type: object + required: + - carrierServiceName + - carrierServiceCode + - vesselSchedules + properties: + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + description: The carrier-specific code of the service for which the schedule details are published. + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + example: SR12345A + description: A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. + vesselSchedules: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/VesselSchedule' + VesselSchedule: + title: Vessel Schedule + type: object + required: + - isDummyVessel + properties: + vessel: + $ref: '#/components/schemas/Vessel' + isDummyVessel: + type: boolean + description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist. + transportCalls: + type: array + items: + $ref: '#/components/schemas/TransportCall' + CutOffTime: + title: Cut-Off Time + type: object + description: Cut Off Times. + required: + - cutOffDateTimeCode + - cutOffDateTime + properties: + cutOffDateTimeCode: + type: string + description: | + Code for the cut-off time. Possible values are: + - `DCO` (Documentation cut-off) + - `VCO` (VGM cut-off) + - `FCO` (FCL delivery cut-off) + - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS` + - `PCO` (Port cut-off) + - `ECP` (Empty container pick-up date and time) + - `EFC` (Earliest full-container delivery date) + - `RCO` (Reefer cut-off) + - `DGC` (Dangerous Goods cut-off) + - `OBC` (OOG/BB cut-off) + - `TCO` (Transhipment cut-off) + - `STA` (Standard booking acceptance) + - `SPA` (Special booking acceptance) + - `CUA` (Customs Acceptance) + - `AFC` (Advanced filling cut-off) + maxLength: 3 + example: DCO + cutOffDateTime: + type: string + format: date-time + description: Estimated cut-off time expressed in local time with offset. + example: '2019-11-12T07:41:00-08:30' + Address: + title: Address + type: object + description: An object for storing address related information. + required: + - street + - city + - countryCode + properties: + street: + type: string + example: Ruijggoordweg + description : The name of the street. + maxLength: 70 + streetNumber: + type: string + example: '100' + description: The number of the street. + maxLength: 50 + floor: + type: string + example: N/A + pattern: ^\S(?:.*\S)?$ + description: The floor of the street number. + maxLength: 50 + postCode: + type: string + example: 1047 HM + description: The post code. + maxLength: 10 + city: + type: string + example: Amsterdam + pattern: ^\S(?:.*\S)?$ + description: The name of the city. + maxLength: 35 + stateRegion: + type: string + example: North Holland + description: The name of the state/region. + maxLength: 65 + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: NL + ErrorResponse: + title: Error Response + type: object + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + properties: + httpMethod: + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + description: The HTTP method used to make the request e.g. `GET`, `POST`, etc + requestUri: + type: string + description: The URI that was requested. + example: /v1/events + statusCode: + type: integer + description: The HTTP status code returned. + format: int32 + example: 400 + statusCodeText: + type: string + description: A standard short description corresponding to the HTTP status code. + example: Bad Request + maxLength: 50 + statusCodeMessage: + type: string + description: A long description corresponding to the HTTP status code with additional information. + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + type: string + description: A unique identifier to the HTTP request within the scope of the API provider. + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + type: string + description: The DateTime corresponding to the error occurring. + example: '2019-11-12T07:41:00Z' + format: date-time + errors: + type: array + description: An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + Vessel: + title: Vessel + type: object + properties: + vesselIMONumber: + type: string + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + example: '9321483' + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + MMSINumber: + type: string + description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station. + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + example: '278111222' + name: + type: string + description: The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + flag: + type: string + description: The flag of the nation whose laws the vessel is registered under. This is the [ISO 3166](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) two-letter country code. + pattern: ^[A-Z]{2}$ + maxLength: 2 + minLength: 2 + example: DE + callSign: + type: string + description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + pattern: ^\S(?:.*\S)?$ + example: NCVV + maxLength: 10 + operatorCarrierCode: + type: string + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + example: MAEU + maxLength: 10 + operatorCarrierCodeListProvider: + type: string + description: | + Identifies the code list provider used for the operator and partner carriercodes. + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + Barge: + title: Barge + type: object + properties: + vesselIMONumber: + type: string + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + example: '9321483' + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + MMSINumber: + type: string + description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station. + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + example: '278111222' + name: + type: string + description: The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + flag: + type: string + description: The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code. + pattern: ^[A-Z]{2}$ + maxLength: 2 + minLength: 2 + example: DE + callSign: + type: string + description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + pattern: ^\S(?:.*\S)?$ + example: NCVV + maxLength: 10 + operatorCarrierCode: + type: string + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + example: MAEU + maxLength: 10 + operatorCarrierCodeListProvider: + type: string + description: | + Identifies the code list provider used for the operator and partner carriercodes. + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + VesselTransport: + title: Vessel Transport + type: object + description: Transport mode Vessel. + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: The mode of transport as defined by DCSA. For the Vessel Transport mode this needs to be `VESSEL`. + enum: + - VESSEL + example: VESSEL + portVisitReference: + type: string + example: NLAMS1234589 + maxLength: 50 + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + transportCallReference: + type: string + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + servicePartners: + type: array + items: + $ref: '#/components/schemas/ServicePartner' + universalServiceReference: + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + vessel: + $ref: '#/components/schemas/Vessel' + BargeTransport: + title: Barge Transport + type: object + description: Transport mode Barge. + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: The mode of transport as defined by DCSA. For the Barge Transport mode this needs to be `BARGE`. + enum: + - BARGE + example: BARGE + portVisitReference: + type: string + example: NLAMS1234589 + maxLength: 50 + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + transportCallReference: + type: string + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + servicePartners: + type: array + items: + $ref: '#/components/schemas/ServicePartner' + universalServiceReference: + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + barge: + $ref: '#/components/schemas/Barge' + OtherTransport: + title: Other Transport + type: object + description: Other Transport modes. + additionalProperties: false + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: | + The mode of transport as defined by DCSA. The allowed values for the Other Transport mode are: + - `RAIL` (When the transport mode is Rail) + - `TRUCK`(When the transport mode is Truck) + - `RAIL_TRUCK`(When rail and truck are expected to be the mode of transport in a leg of a proposed routing) + - `BARGE_TRUCK`(When barge and truck are expected to be the mode of transport in a leg of a proposed routing) + - `BARGE_RAIL`(When barge and rail are expected to be the mode of transport in a leg of a proposed routing) + - `MULTIMODAL`(When mode of transport is not really defined or unknown at this stage) + enum: + - RAIL_TRUCK + - BARGE_TRUCK + - BARGE_RAIL + - MULTIMODAL + - RAIL + - TRUCK + example: RAIL + Facility: + title: Facility + type: object + description: A way to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + required: + - facilityCode + - facilityCodeListProvider + properties: + facilityCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 6 + example: ADT + description: | + The code used for identifying the specific facility. This code does not include the UN Location Code.The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used: + - for `SMDG` - the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + - for `BIC` - the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/) + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code`. + - `BIC` (Requires a UN Location Code) + - `SMDG` (Requires a UN Location Code) + enum: + - BIC + - SMDG + example: SMDG + ServicePartner: + title: Service Partner + type: object + description: The service code and voyage number as identified by the carriers that are partners in the service. + properties: + carrierCode: + type: string + description: The carrier code based on either the SMDG or SCAC code lists. + maxLength: 4 + pattern: ^\S+$ + example: MAEU + carrierCodeListProvider: + type: string + description: | + Identifies the code list provider used for the `carrierCode`. + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + description: The carrier-specific code of the service for which the schedule details are published. + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + example: 2103N + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + ServicePartnerSchedule: + title: Service Partner Schedule + type: object + required: + - carrierServiceName + - carrierServiceCode + - carrierImportVoyageNumber + - carrierExportVoyageNumber + description: The service code and voyage number as identified by the carriers that are partners in the service. + properties: + carrierCode: + type: string + description: The carrier code based on either the SMDG or SCAC code lists. + maxLength: 4 + pattern: ^\S+$ + example: MAEU + carrierCodeListProvider: + type: string + description: | + Identifies the code list provider used for the `carrierCode`. + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + description: The carrier-specific code of the service for which the schedule details are published. + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + example: 2103N + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + Leg: + title: Leg + type: object + description: Leg of the Point-to-Point routing. The property `Leg` can be conformed by as many leg as needed and this leg must be identified with a sequence number. + required: + - departure + - arrival + properties: + sequenceNumber: + type: integer + format: int32 + description: Sequence number of the leg. + example: 1 + transport: + description: The mode of transport as defined by DCSA. + oneOf: + - $ref: '#/components/schemas/VesselTransport' + - $ref: '#/components/schemas/BargeTransport' + - $ref: '#/components/schemas/OtherTransport' + departure: + $ref: '#/components/schemas/PlaceOfDeparture' + arrival: + $ref: '#/components/schemas/PlaceOfArrival' + Location: + title: Location + type: object + description: | + The location can be specified using **any** of the nested structures: + - `Address` (used to specify the location via an Address) + - `UNLocationCode` + - `Facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`) + + It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + address: + $ref: '#/components/schemas/Address' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facility: + $ref: '#/components/schemas/Facility' + TransportCallLocation: + title: TransportCall Location + type: object + description: | + General purpose object to capture location-related data, the location can be specified in **any** of the following ways: + - `Address` (used to specify the location via an Address) + - `UNLocationCode` + - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`) + It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + address: + $ref: '#/components/schemas/Address' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facilitySMDGCode: + type: string + example: ACT + description: The code used for identifying the specific facility. This code does not include the UN Location Code. + + The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + maxLength: 6 + PortScheduleLocation: + title: Port Schedule Location + type: object + description: | + General purpose object to capture location-related data, the location can be specified in **any** of the following ways: + - `UNLocationCode` + - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`) + + It is expected that if a location is specified in multiple ways (both as a `UNLocationCode` and as a `facilitySMDGCode`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facilitySMDGCode: + type: string + example: ACT + description: The code used for identifying the specific facility. This code does not include the UN Location Code. + + The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + maxLength: 6 + DetailedError: + title: Detailed Error + type: object + description: A detailed description of what has caused the error. + required: + - errorCodeText + - errorCodeMessage + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + example: 7003 + minimum: 7000 + maximum: 9999 + property: + type: string + description: The name of the property causing the error. + example: facilityCode + maxLength: 100 + value: + type: string + description: The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + maxLength: 500 + jsonPath: + type: string + description: A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + maxLength: 500 + errorCodeText: + type: string + description: A standard short description corresponding to the `errorCode`. + example: invalidData + maxLength: 100 + errorCodeMessage: + type: string + description: A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + maxLength: 5000 + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '1' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. +tags: + - name: Point To Point + description: ' ' + - name: Port Schedule + description: ' ' + - name: Vessel Schedule + description: ' ' diff --git a/ebl/v3/EBL_v3.0.3.yaml b/ebl/v3/EBL_v3.0.3.yaml new file mode 100644 index 00000000..3223c9cb --- /dev/null +++ b/ebl/v3/EBL_v3.0.3.yaml @@ -0,0 +1,9005 @@ +openapi: 3.0.3 +info: + version: 3.0.3 + title: DCSA Shipping Instructions and Transport Document API + description: | +

DCSA OpenAPI specification for the Shipping Instructions and Transport Document process

+ + This API is intended as an API between a carrier and anyone creating a `Shipping Instructions` and approving a `Transport Document`. The process includes: + + - Shipping Instructions submission + - Shipping Instructions update + - Draft Transport Document publication + - Draft Transport Document update + - Draft Transport Document approval + + For explanation of specific values or objects please refer to the [Information Model](https://developer.dcsa.org/documentation/information_models). This API specification does not define the allowable updates and their timing in accordance with the established business rules. **All use cases mentioned in this API specification refer to use cases defined in [DCSA Interface Standard for the Bill of Lading 3.0](https://dcsa.org/standards/bill-of-lading/documentation-bill-of-lading-3)**. + + All other documents related to the electronic Bill of Lading (referred to as `eBL`) publication can be found [here](https://dcsa.org/standards/ebill-of-lading/) + + ### eBL (Implemented by provider) + + It is possible to use the eBL API as a standalone API. In that case use one of the poll endPoints: + + GET /v3/shipping-instructions/{documentReference} # For Shipping Instructions status + GET /v3/transport-documents/{transportDocumentReference} # For Transport Document status + + in order to poll information about status changes. + + **Note:** All `/v3/shipping-instructions` and `/v3/transport-documents` endPoints must be implemented by the provider. + + ### Notifications (Implemented by consumer) + It is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Shipping Instructions Notification endPoint](#/ShippingInstructionsNotification) or the [Transport Document Notification endPoint](#/TransportDocumentNotification). + + POST /v3/shipping-instructions-notifications + POST /v3/transport-document-notifications + + The endPoints support both a lightweight Notification and a full State transfer. How much data is sent via this Notification depends on what kind of Notification is being subscribed to. + + Signing up for notifications is defined outside the scope of this API specification. + + **Note:** All of these endPoint is to be implemented by the consumers of the `Shipping Instructions API` and `Transport Document API` in order to receive push events. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) + + ### Changelog and GitHub + For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +tags: + - name: Shipping Instructions + description: | + The Shipping Instructions endPoints to be implemented by **providers** of the Bill of Lading API + - name: Transport Document + description: | + The Transport Document endPoints to be implemented by **providers** of the Bill of Lading API + - name: Notifications + description: The Notifications to be implemented by the **consumers** of the Bill of Lading API +paths: + ############################## + # Shipping Instructions Request + ############################## + '/v3/shipping-instructions': + post: + tags: + - Shipping Instructions + summary: | + Creates a Shipping Instructions + operationId: create-shipping-instructions + description: | + Creates a new `Shipping Instructions`. This endPoint corresponds with **UseCase 1 - Submit Shipping Instructions**. + + ## Precondition + The consumer has information for a `Shipping Instructions`. The empty equipment has been released to the shipper. The `Booking` is in state `CONFIRMED`. + + ## Postcondition + The provider has received the `Shipping Instructions`. + + The consumer will receive a `202` (Accepted) if the payload schema validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a `Shipping Instructions`: + 1. The payload (`Shipping Instructions`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + + A `shippingInstructionsReference` (as a reference to the `Shipping Instructions`) is created and linked to the payload in the provider system. + + **For the rest of this description and in all examples the value `si-123` will be used as `shippingInstructionsReference`** + + 3. A `202` (Accepted) response is returned with a payload containing **only** the `shippingInstructionsReference`: + ``` + { + shippingInstructionsReference: 'si-123' + } + ``` + + For `POST` `Shipping Instructions` the process ends here. The `Shipping Instructions`: + - is now accepted by the provider system + - the `Shipping Instructions` does not yet have any status and cannot be queried (no `GET` request is possible until the `Shipping Instructions` is further processed in the provider system) + - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `shippingInstructionsReference` + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the status `RECEIVED` of the `Shipping Instructions` will be communicated via a [Shipping Instructions Notification](#/ShippingInstructionsNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v3/shipping-instructions/{documentReference} + + endPoint to check if the `shippingInstructionsStatus` of the `Shipping Instructions` has changed. + + After the status has changed to `RECEIVED` further processing can continue by provider and will be communicated via a [Shipping Instructions Notification](#/ShippingInstructionsNotification). + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + Parameters used to create the `Shipping Instructions` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateShippingInstructions' + examples: + regularSTDExample: + summary: | + Create a Shipping Instructions + description: | + A new `Shipping Instructions` with standard Dry cargo: `Black shoes`. The shoes are packed in 400 `Fibreboard boxes` and stuffed inside a single container (`NARU3472484`). The shipment has been booked via `carrierBookingReference` = `CBR_123_REGULAR` + + The `Shipping Instructions` now awaits the provider to `DRAFT` a `Transport Document`. + value: + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + responses: + '202': + description: | + The `Shipping Instructions` has been accepted by the provider. The `Shipping Instructions` does not yet have a `shippingInstructionsStatus` - it is not possible to call the `GET` endPoint until the `Shipping Instructions` is further processed in provider system. The consumer is now awaiting provider to process the `Shipping Instructions` asynchronously. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateShippingInstructionsResponse' + examples: + receExample: + summary: | + Shipping Instructions received + description: | + The `shippingInstructionsReference` has been accepted (no `shippingInstructionsStatus`) and schema validated by provider + value: + shippingInstructionsReference: si-123 + '400': + description: | + In case the `Shipping Instructions` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Shipping Instructions missing isElectronic + description: | + `isElectronic` is a mandatory property in the `Shipping Instructions`. In case this property is missing an error objet is created. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: POST + requestUri: /v3/shipping-instructions + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: isElectronic not found - it is a mandatory property in Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: isElectronic + errorCodeText: mandatory property missing + errorCodeMessage: isElectronic must be provided as part of a Shipping Instructions + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Shipping Instructions + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: POST + requestUri: /v3/shipping-instructions + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Shipping Instructions + description: | + Calling the endPoint + + POST /v3/shipping-instructions + + too many times within a time period results in an error. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: POST + requestUri: /v3/shipping-instructions + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: Too many request to create a Shipping Instructions has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Shipping Instructions reached + errorCodeMessage: A maximum of 10 Shipping Instructions can be created per hour + '/v3/shipping-instructions/{documentReference}': + put: + tags: + - Shipping Instructions + summary: | + Updates the Shipping Instructions + operationId: update-shipping-instructions + parameters: + - $ref: '#/components/parameters/documentReference' + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Updates the `Shipping Instructions` with the `documentReference`. The path can contain one of a `shippingInstructionsReference` or a `transportDocumentReference`. This endPoint corresponds with **UseCase 3 - Submit updated Shipping Instructions** + + ### Precondition + In order to update a `Shipping Instructions`, the status of the `Shipping Instructions` needs to be in state: + + - `RECEIVED` in case the consumer has updated information for the `Shipping Instructions` + - `PENDING_UPDATE` in case the provider has requested the consumer to update the `Shipping Instructions` (a result of **UseCase 2 - Request to update Shipping Instructions**) + + The status of `updatedShippingInstructionsStatus` can be anything. + + ## Postcondition + The provider has received an update to the `Shipping Instructions` (**UseCase 3 - Submit updated Shipping Instructions**). In case this is the first update to the `Shipping Instructions` the update will be called the `Updated Shipping Instructions`. If this is a subsequent update to the `Shipping Instructions` - the update will update the `Updated Shipping Instructions`. In both cases the `updatedShippingInstructionStatus` will be set to `UPDATE_RECEIVED`. + + The `Updated Shipping Instructions` and the "original" `Shipping Instructions` **co-exist** until a new update is submitted by the consumer (via **UseCase 3: Submit updated Shipping Instructions**) in which case the new update replaces the existing. Or until the provider requests an update (sets the `shippingInstructionsStatus='PENDING_UPDATE'` via **UseCase 2: Request to update Shipping Instructions**). The `Updated Shipping Instructions` always represents the latest version of an update received by the provider. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives an **update** to a `Shipping Instructions` + 1. The payload (`Updated Shipping Instructions`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + For `PUT` `Shipping Instructions` the process ends here. The `Shipping Instructions`: + - is now accepted by the provider system + - the status of the `Shipping Instructions` is unchanged + - a `202` (Accepted) response is sent with an empty payload + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the state will change to one of the following values depending on the use case for calling the `PUT` endPoint: + - `shippingInstructionsStatus='RECEIVED'` and `updatedShippingInstructionsStatus='UPDATE_RECEIVED'` (if endPoint is used to make an update to a Submitted Shipping Instructions - **UseCase 1 - Submit Shipping Instructions**) + - `shippingInstructionsStatus='PENDING_UPDATE'` and `updatedShippingInstructionsStatus='UPDATE_RECEIVED'` (if endPoint is used as a response to **UseCase 2 - Request to update Shipping Instructions**) + + The new state will be communicated via a [Shipping Instructions Notification](#/ShippingInstructionsNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v3/shipping-instructions/{documentReference} + + endPoint to check if the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` of the `Shipping Instructions` has changed. + + If the consumer wants to get the content of the `Update Shipping Instructions` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?updatedContent=true` queryParameter: + + GET /v3/shipping-instructions/{documentReference}?updatedContent=true + + It is possible to `GET` the content of the `Updated Shipping Instructions` via the example above until one of: + - the provider requests for a new update (**UseCase 2: Request to update Shipping Instructions**) in which case the "old update" is no longer accessible + - the consumer submits a new update (**UseCase 3: Submit updated Shipping Instructions**) in which case the "new update" provided **replaces** the "old update". + requestBody: + description: | + Parameters used to update the `Shipping Instructions` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateShippingInstructions' + examples: + regularSTDExample: + summary: | + Update Shipping Instructions + description: | + An update for a `Shipping Instructions` with standard Dry cargo. The `Shipping Instructions` update now wait to be confirmed by the provider. + value: + shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9 + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + responses: + '202': + description: | + The `Shipping Instructions` update has been successfully accepted by the provider. `shippingInstructionsStatus` does not change, `updatedShippingInstructionsStatus` is not set and response payload is empty. Further processing will be done by provider. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + receivedExample: + summary: | + Shipping Instructions updated by consumer + description: | + An `Updated Shipping Instructions` received and accepted by provider, the `Updated Shipping Instructions` now awaits provider action, the `shippingInstructionStatus` does not change. + value: null + '400': + description: | + In case the updated `Shipping Instructions` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Shipping Instructions missing isElectronic + description: | + `isElectronic` is a mandatory property in the `Shipping Instructions`. In case this property is missing an error object is created. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/shipping-instructions/si-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: isElectronic not found - it is a mandatory property in Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: isElectronic + errorCodeText: mandatory property missing + errorCodeMessage: isElectronic must be provided as part of a Shipping Instructions + '404': + description: | + In case the provider does not know about the `documentReference` used in the request (this could be because of a `POST` request that has not finished processing or simply because the resource does not exist) - it is possible for the provider to reject the requests by returning a `404` (Not Found) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Not found request + description: | + The provided `documentReference` could not be found. This can be because a `Post` request has not been finished processing or because the `documentReference` does not exist in the provider system. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/shipping-instructions/si-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: shippingInstructionsReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: shippingInstructionsReference not found + errorCodeMessage: The Shipping Instructions does not exist + '409': + description: | + In case the provider is already processing the `Shipping Instructions` matching `shippingInstructionsReference='si-123'` or for any other reason cannot process the request, it is possible to reject the `PUT` request with a `409` (Conflict) response + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting Shipping Instructions update + description: | + The `Shipping Instructions` referenced in the `PUT` request is being processed by the provider. The provider does not support breaking this processing and must complete the processing of the `Shipping Instructions` prior to receiving a new request to update. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/shipping-instructions/si-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: Is being processed + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Shipping Instructions is being processed + errorCodeMessage: The Shipping Instructions cannot be updated while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing `Shipping Instructions` + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/shipping-instructions/si-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while processing Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Shipping Instructions + description: | + Calling the endPoint + + PUT /v3/shipping-instructions/si-123 + + too many times within a time period. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/shipping-instructions/si-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: Too many request to update a Shipping Instructions has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Shipping Instructions requests reached + errorCodeMessage: A maximum of 10 Shipping Instructions can be updated per hour + get: + tags: + - Shipping Instructions + summary: | + Gets the Shipping Instructions + operationId: get-shipping-instructions + parameters: + - $ref: '#/components/parameters/documentReference' + - $ref: '#/components/parameters/updatedContent' + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Retrieves the `Shipping Instructions` with the `documentReference`. The path can contain a `shippingInstructionsReference` or a `transportDocumentReference`. 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" `Shipping Instructions`. It is also possible to get the latest update to a `Shipping Instructions` called the `Updated Shipping Instructions`. In order to get the `Update Shipping Instructions`, it is necessary to use the query parameter `updatedContent` and set it to `true`. + + GET /v3/shipping-instructions/{documentReference}?updatedContent=true + + The `status` of the "original" `Shipping Instructions` is included in both payloads as `shippingInstructionsStatus`. `updatedShippingInstructionsStatus` and related content is only available after a consumer has requested an update via **UseCase 3: Submit updated Shipping Instructions** and until: + - the provider requests for a new update (**UseCase 2: Request to update Shipping Instructions**) in which case the "old update" is no longer accessible. + - the consumer submits a new update (**UseCase 3: Submit updated Shipping Instructions**) in which case the "new update" provided **replaces** the "old update". + + If `updatedContent=true` is requested but no update has yet been provided by the consumer **or** the state of the "original" `Shipping Instructions` is `PENDING_UPDATE`, then a `404` (Not Found) is returned. + + If the provider is requesting changes to the `Shipping Instructions`, the `Feedback` object is used to inform the consumer what needs to change. + + In case no subscription (`Notification`) has been set up - it is possible to use this endPoint to poll on in order to detect if `shippingInstructionsStatus` and/or `updatedShippingInstructionsStatus` has changed. + + In case a previous request is being processed by the provider - a `202` (Accepted) with **no payload** can be used as a response until the processing is finished. + responses: + '200': + description: | + Fetching the content of either the "original" `Shipping Instructions` or the `Updated Shipping Instructions` + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ShippingInstructions' + examples: + regularSTDExample: + summary: | + Fetch Shipping Instructions with standard Dry cargo + description: | + A `RECEIVED` `Shipping Instructions` with standard Dry cargo waiting for the provider to `DRAFT` a `Transport Document`. + value: + shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9 + shippingInstructionsStatus: RECEIVED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + reeferExample: + summary: | + Shipping Instructions with reefer cargo + description: | + A `Shipping Instructions` with reefer cargo (`Diary products`) with US as destination. The provider requests that the `Advance Manifest Filing` be updated by the consumer. + + **Notice** that there are no Reefer info in the `Shipping Instructions`. If any reefer info need to be modified - then a `Booking` amendment must be applied to booking: `CBR_123_REEFER`. + value: + transportDocumentReference: D8931B95625E4B339F2A + shippingInstructionsReference: 9051da7d-4099-4930-af35-7add4e68c635 + shippingInstructionsStatus: PENDING_UPDATE + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REEFER + descriptionOfGoods: + - 'Dairy products' + HSCodes: + - '04052090' + commoditySubReference: ReeferSubRef002 + cargoItems: + - equipmentReference: KKFU6671914 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: BQ + description: Bottles + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: KKFU6671914 + advanceManifestFilings: + - manifestTypeCode: AFR + countryCode: US + advanceManifestFilingsHouseBLPerformedBy: SELF + selfFilerCode: HHL007 + feedbacks: + - severity: ERROR + code: PROPERTY_VALUE_MUST_CHANGE + message: | + Not a legal combination of "manifestTypeCode" (AFR) and "countryCode" (US) + jsonPath: '$.advanceManifestFilings[0]' + property: 'advanceManifestFilings' + - severity: ERROR + code: PROPERTY_VALUE_MUST_CHANGE + message: | + Missing "ACI" filing required for import to US + jsonPath: '$.advanceManifestFilings' + property: 'advanceManifestFilings' + dgExample: + summary: | + Updated Shipping Instructions with DG cargo + description: | + A `Shipping Instructions` with `Environmentally hazardous substance, liquid, N.O.S (Propiconazole)` which is transported in steel Jerrycans. + + The `Shipping Instructions` has already been applied an update which has been confirmed by the provider (`updatedShippingInstructions='UPDATE_CONFIRMED'`). The `Shipping Instructions` is now waiting for the provider to `DRAFT` a `Transport Document`. + + **Notice** that there are no DG (Dangerous Goods) info in the `Shipping Instructions`. If any DG info need to be modified - then a `Booking` amendment must be applied to booking: `RTM1234567`. + value: + transportDocumentReference: 4AD3FA470BB541B980CE + shippingInstructionsReference: b36484d0-1115-43c2-93e4-a378823a8386 + shippingInstructionsStatus: RECEIVED + updatedShippingInstructionsStatus: UPDATE_CONFIRMED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: RTM1234567 + descriptionOfGoods: + - 'Environmentally hazardous substance' + - 'liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + commoditySubReference: DGSubRef003 + cargoItems: + - equipmentReference: HLXU1234567 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + description: 'Jerrycan, steel' + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 22G1 + equipmentReference: HLXU1234567 + tareWeight: + value: 2370 + unit: KGM + '202': + description: | + The `Shipping Instructions` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Shipping Instructions`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '404': + description: | + In case the consumer is requesting the content of the `UpdatedShipping Instructions`, and no update has yet been requested. + + A `404` (Not Found) can also be sent in case the provider does not know of the `documentReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundUpdateExample: + summary: | + Shipping Instructions update not found + description: | + The `Update Shipping Instructions` does not exist. No updates have been requested by the consumer. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/shipping-instructions/si-123?updatedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No update accessible + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Shipping Instructions does not contain an update + errorCodeMessage: The Shipping Instructions has not yet been updated - no update exists + notFoundExample: + summary: | + documentReference not found + description: | + The `documentReference` does not exist. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/shipping-instructions/si-123?updatedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: documentReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: documentReference not found + errorCodeMessage: The Shipping Instructions does not exist + '409': + description: | + In case the provider is processing the `Shipping Instructions` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v3/shipping-instructions/si-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Shipping Instructions cannot be updated/amended while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while fetching the Shipping Instructions + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/shipping-instructions/si-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while fetching the Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Fetching too many `Transport Document` requests + description: | + Calling the endPoint + + GET /v3/shipping-instructions/si-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v3/shipping-instructions/si-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to fetch a Shipping Instructions has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Shipping Instructions requests reached + errorCodeMessage: A maximum of 10 Shipping Instructions can be requested per hour + patch: + tags: + - Shipping Instructions + summary: | + Cancels an update to a Shipping Instructions + operationId: patch-shipping-instructions + parameters: + - $ref: '#/components/parameters/documentReference' + - $ref: '#/components/parameters/Api-Version-Major' + description: | + A way for the consumer to Cancel an `Updated Shipping Instructions`. This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions**. + + ## Precondition + In order to cancel an `Updated Shipping Instructions`, the status of the `Updated Shipping Instructions` must be in in status `UPDATE_RECEIVED`. The status of the `Shipping Instructions` can be one of `RECEIVED` or `PENDING_UPDATE`. + + ## Postcondition + The provider has received a cancellation from the consumer for an `Updated Shipping Instructions` that is in state `UPDATE_RECEIVED`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a cancellation: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + Once processed, the `Updated Shipping Instructions` is cancelled and a [Shipping Instructions Notification](#/ShippingInstructionsNotification) will be sent. In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v3/shipping-instructions/{documentReference} + + endPoint to check if the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` of the `Shipping Instructions` has changed. + requestBody: + description: | + Cancel the `Update Shipping Instructions` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CancelShippingInstructionsUpdate' + examples: + cancelUpdateExample: + summary: | + Cancel a Shipping Instructions update + description: | + Consumer wants to cancel an update provided to a `Shipping Instructions`. The `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED` + value: + updatedShippingInstructionsStatus: UPDATE_CANCELLED + responses: + '202': + description: | + The cancellation of the `Updated Shipping Instructions` is accepted and is now awaiting further processing by the provider. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + cancelUpdateExample: + summary: | + Cancel a Shipping Instructions update + description: | + Consumer wants to cancel an update provided to a `Shipping Instructions`. + value: null + '400': + description: | + In case the cancel payload does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Wrong Update Shipping Instructions status + description: | + `APPROVE` is not a possible value when PATCHING an `Updated Shipping Instructions`. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/shipping-instructions/si-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: APPROVE is not a valid status to set + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: updatedShippingInstructionsStatus + value: APPROVE + errorCodeText: incorrect value + errorCodeMessage: 'Only UPDATE_CANCELLED is an allowed value: APPROVE was inserted' + '404': + description: | + In case the consumer is trying to cancel a `Shipping Instructions` that does not have an ongoing update request, an `Updated Shipping Instructions` that is in state `UPDATE_RECEIVED`. + + A `404` (Not Found) can also be sent in case the provider does not know of the `documentReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notUpdateFoundExample: + summary: | + Shipping Instructions update not found + description: | + The `Update Shipping Instructions` does not exist. No updates have been requested by the consumer. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/shipping-instructions/si-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No update exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Shipping Instructions does not contain an update + errorCodeMessage: The Shipping Instructions has no update request - nothing to cancel + '409': + description: | + In case the provider is already processing the `Updated Shipping Instructions` matching `shippingInstructionsReference='si-123'` it is possible to reject the `PATCH` request with a `409` (Conflict) response + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting Shipping Instructions cancellation + description: | + The `Updated Shipping Instructions` referenced in the `PATCH` request is being processed by the provider. The provider does not support breaking this processing and must complete the processing of the `Updated Shipping Instructions`. The cancellation will not be possible. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/shipping-instructions/si-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: Is being processed + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Shipping Instructions is being processed + errorCodeMessage: The Shipping Instructions cannot be cancelled while it is being processed + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while cancelling the `Shipping Instructions` + description: | + An Internal Server Error has occurred, the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/shipping-instructions/si-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while cancelling the Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Patching the `Shipping Instructions` too many times + description: | + Calling the endPoint + + PATCH /v3/shipping-instructions/si-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v3/shipping-instructions/si-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to patch a Shipping Instructions has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Shipping Instructions requests reached + errorCodeMessage: A maximum of 10 Shipping Instructions patches can be requested per hour + '/v3/transport-documents/{transportDocumentReference}': + get: + tags: + - Transport Document + summary: | + Gets the Transport Document + operationId: get-transport-document + description: | + Retrieves the `Transport Document` with the `transportDocumentReference` in the path. + + **Condition:** Once the `Transport Document` has been Issued (`transportDocumentStatus='ISSUED'`) - the order of **ALL** lists/arrays in this payload **MUST** be preserved as by the provider of the API. + parameters: + - in: path + name: transportDocumentReference + description: | + The `transportDocumentReference` of the `Transport Document` + required: true + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + - $ref: '#/components/parameters/Api-Version-Major' + responses: + '200': + description: | + The `Transport Document` + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/TransportDocument' + examples: + regularSTDExample: + summary: | + Draft Transport Document with regular Dry cargo + description: | + A `DRAFT` Transport Document waiting for consumer approval. + value: + transportDocumentReference: 62CD536BA8D34C469AFD + shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9 + transportDocumentStatus: DRAFT + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + shippedOnBoardDate: '2023-12-20' + termsAndConditions: | + You agree that this transport document exist is name only for the sake of + testing your conformance with the DCSA eBL API. This transport document is NOT backed + by a real shipment with ANY carrier and NONE of the requested services will be + carried out in real life. + + Unless required by applicable law or agreed to in writing, DCSA provides + this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF + ANY KIND, either express or implied, including, without limitation, any + warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, + or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for + determining the appropriateness of using or redistributing this JSON + data and assume any risks associated with Your usage of this data. + + In no event and under no legal theory, whether in tort (including negligence), + contract, or otherwise, unless required by applicable law (such as deliberate + and grossly negligent acts) or agreed to in writing, shall DCSA be liable to + You for damages, including any direct, indirect, special, incidental, or + consequential damages of any character arising as a result of this terms or conditions + or out of the use or inability to use the provided JSON data (including but not limited + to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any + and all other commercial damages or losses), even if DCSA has been advised of the + possibility of such damages. + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: SCR-1234-REGULAR + carrierCode: MSC + carrierCodeListProvider: SMDG + transports: + plannedDepartureDate: '2023-12-20' + plannedArrivalDate: '2023-12-22' + portOfLoading: + UNLocationCode: DKAAR + portOfDischarge: + UNLocationCode: DEBRV + vesselVoyages: + - vesselName: MSC Gülsün + carrierExportVoyageNumber: 402E + charges: + - chargeName: Fictive transport document fee + currencyAmount: 1 + currencyCode: EUR + paymentTermCode: COL + calculationBasis: Per transport document + unitPrice: 1 + quantity: 1 + invoicePayableAt: + UNLocationCode: DKAAR + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + issuingParty: + partyName: Mediterranean Shipping Company + address: + street: Chemin Rieu + streetNumber: 12-14 + city: Geneva + countryCode: CH + identifyingCodes: + - codeListProvider: GLEIF + codeListName: LEI + partyCode: 529900T8BM49AURSDO55 + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 22G1 + equipmentReference: NARU3472484 + reeferExample: + summary: | + Approved Transport Document with reefer cargo + description: | + An `APPROVED` Transport Document by the consumer waiting to be Issued by the provider. The cargo is `Diary products` which need to be transported using a `Reefer` container at -18° CEL. + value: + transportDocumentReference: D8931B95625E4B339F2A + shippingInstructionsReference: 9051da7d-4099-4930-af35-7add4e68c635 + transportDocumentStatus: APPROVED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + shippedOnBoardDate: '2023-12-20' + termsAndConditions: | + You agree that this transport document exist is name only for the sake of + testing your conformance with the DCSA eBL API. This transport document is NOT backed + by a real shipment with ANY carrier and NONE of the requested services will be + carried out in real life. + + Unless required by applicable law or agreed to in writing, DCSA provides + this JSON data on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF + ANY KIND, either express or implied, including, without limitation, any + warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, + or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for + determining the appropriateness of using or redistributing this JSON + data and assume any risks associated with Your usage of this data. + + In no event and under no legal theory, whether in tort (including negligence), + contract, or otherwise, unless required by applicable law (such as deliberate + and grossly negligent acts) or agreed to in writing, shall DCSA be liable to + You for damages, including any direct, indirect, special, incidental, or + consequential damages of any character arising as a result of this terms or conditions + or out of the use or inability to use the provided JSON data (including but not limited + to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any + and all other commercial damages or losses), even if DCSA has been advised of the + possibility of such damages. + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: SCR-1234-REEFER + carrierCode: MSC + carrierCodeListProvider: SMDG + transports: + plannedDepartureDate: '2023-12-20' + plannedArrivalDate: '2023-12-22' + portOfLoading: + UNLocationCode: DKAAR + portOfDischarge: + UNLocationCode: DEBRV + vesselVoyages: + - vesselName: Ever Ace + carrierExportVoyageNumber: 402E + charges: + - chargeName: Fictive transport document fee + currencyAmount: 1 + currencyCode: EUR + paymentTermCode: COL + calculationBasis: Per transport document + unitPrice: 1 + quantity: 1 + invoicePayableAt: + UNLocationCode: DKAAR + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + issuingParty: + partyName: Mediterranean Shipping Company + address: + street: Chemin Rieu + streetNumber: 12-14 + city: Geneva + countryCode: CH + identifyingCodes: + - codeListProvider: GLEIF + codeListName: LEI + partyCode: 529900T8BM49AURSDO55 + consignmentItems: + - carrierBookingReference: CBR_123_REEFER + descriptionOfGoods: + - 'Dairy products' + HSCodes: + - '04052090' + cargoItems: + - equipmentReference: KKFU6671914 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: BQ + description: Bottles + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 45R1 + equipmentReference: KKFU6671914 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: -18 + temperatureUnit: CEL + dgExample: + summary: | + Issued Transport Document with DG (Dangerous Goods) cargo + description: | + An `ISSUED` Transport Document by the provider containing DG (Dangerous Goods). The cargo is `Environmentally hazardous substance, liquid, N.O.S (Propiconazole)` which is transported in steel Jerrycans. + value: + transportDocumentReference: 4AD3FA470BB541B980CE + shippingInstructionsReference: b36484d0-1115-43c2-93e4-a378823a8386 + transportDocumentStatus: ISSUED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + shippedOnBoardDate: '2023-12-20' + termsAndConditions: | + You agree that this transport document exist is name only for the sake of + testing your conformance with the DCSA eBL API. This transport document is NOT backed + by a real shipment with ANY carrier and NONE of the requested services will be + carried out in real life. + + Unless required by applicable law or agreed to in writing, DCSA provides + this JSON data on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF + ANY KIND, either express or implied, including, without limitation, any + warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, + or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for + determining the appropriateness of using or redistributing this JSON + data and assume any risks associated with Your usage of this data. + + In no event and under no legal theory, whether in tort (including negligence), + contract, or otherwise, unless required by applicable law (such as deliberate + and grossly negligent acts) or agreed to in writing, shall DCSA be liable to + You for damages, including any direct, indirect, special, incidental, or + consequential damages of any character arising as a result of this terms or conditions + or out of the use or inability to use the provided JSON data (including but not limited + to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any + and all other commercial damages or losses), even if DCSA has been advised of the + possibility of such damages. + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: SCR-1234-DG + carrierCode: HLC + carrierCodeListProvider: SMDG + transports: + plannedDepartureDate: '2023-12-20' + plannedArrivalDate: '2023-12-22' + portOfLoading: + UNLocationCode: DKAAR + portOfDischarge: + UNLocationCode: DEBRV + vesselVoyages: + - vesselName: Berlin Express + carrierExportVoyageNumber: 402E + charges: + - chargeName: Fictive transport document fee + currencyAmount: 1 + currencyCode: EUR + paymentTermCode: COL + calculationBasis: Per transport document + unitPrice: 1 + quantity: 1 + invoicePayableAt: + UNLocationCode: DKAAR + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + issuingParty: + partyName: Hapag Lloyd + address: + street: Ballindamm + streetNumber: '25' + postCode: D-20095 + city: Hamburg + countryCode: DE + identifyingCodes: + - codeListProvider: GLEIF + codeListName: LEI + partyCode: 529900T8BM49AURSDO55 + consignmentItems: + - carrierBookingReference: RTM1234567 + descriptionOfGoods: + - 'Environmentally hazardous substance' + - 'liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + cargoItems: + - equipmentReference: HLXU1234567 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + imoPackagingCode: 3A1 + description: 'Jerrycan, steel' + dangerousGoods: + - UNNumber: '3082' + properShippingName: 'Environmentally hazardous substance, liquid, N.O.S' + imoClass: '9' + packingGroup: 3 + EMSNumber: F-A S-F + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 22G1 + equipmentReference: HLXU1234567 + '202': + description: | + The `Transport Document` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Transport Document`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '404': + description: | + In case the consumer is requesting a `transportDocumentReference` that does not exist. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + documentReference not found + description: | + The `transportDocumentReference` does not exist. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/transport-documents/td-987 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: documentReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: documentReference not found + errorCodeMessage: The Transport Document does not exist + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while fetching the Transport Document + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/transport-documents/td-987 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while fetching the Transport Document + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Fetching too many `Transport Document` requests + description: | + Calling the endPoint + + GET /v3/transport-documents/td-987 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v3/transport-documents/td-987 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to fetch a Transport Document has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Transport Document requests reached + errorCodeMessage: A maximum of 10 Transport Document can be requested per hour + patch: + tags: + - Transport Document + summary: | + Approve a Transport Document + operationId: approve-transport-document + description: | + A way for the consumer to Approve the `Draft Transport Document`. This endPoint corresponds with **UseCase 7 - Approve Draft Transport Document**. + + ## Precondition + In order to approve a `Draft Transport Document`, the status of the `Transport Document` needs to be in status `DRAFT` + + ## Postcondition + The provider has received an approval from the consumer for a `Transport Document` that is in state `DRAFT`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives an approval: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + Once processed, the `Transport Document` is `ISSUED` and a [Transport Document Notification](#/TransportDocumentNotification) is sent. In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v3/transport-documents/{transportDocumentReference} + + endPoint to check if the `transportDocumentStatus` of the `Transport Document` has changed. + parameters: + - in: path + name: transportDocumentReference + description: | + The `transportDocumentReference` of the `Transport Document` + required: true + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ApproveTransportDocument' + responses: + '202': + description: | + The approval of the `Transport Document` has been accepted and now awaits further processing + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + approveExample: + summary: | + Approve Draft Transport Document + description: | + Consumer approves the drafted `Transport Document` and now awaits further processing by provider. + value: null + '400': + description: | + In case the Approve payload does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Wrong Transport Document status + description: | + `ISSUE` is not a possible value when PATCHING a `Transport Document`. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/transport-documents/td-987 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: ISSUE is not a valid status to set + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: transportDocumentStatus + value: ISSUE + errorCodeText: incorrect value + errorCodeMessage: 'Only APPROVED is an allowed value: ISSUE was inserted' + '404': + description: | + In case the consumer is requesting a `transportDocumentReference` that does not exist. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + documentReference not found + description: | + The `transportDocumentReference` does not exist. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/transport-documents/td-987 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: documentReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: documentReference not found + errorCodeMessage: The Transport Document does not exist + '409': + description: | + In case the consumer is requesting a `transportDocumentReference` that is being processed it is possible to return a `409` (Conflict). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + documentReference is being processed + description: | + The `transportDocumentReference` is currently being processed - try again later. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/transport-documents/td-987 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: documentReference being processed + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: documentReference being processed + errorCodeMessage: The Transport Document is currently being processed + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while approving the `Draft Transport Document` + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v3/transport-documents/td-987 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while approving the Transport Document + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Too many Patch `Transport Document` requests + description: | + Calling the endPoint + + PATCH /v3/transport-documents/td-987 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v3/transport-documents/td-987 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to patch a Transport Document has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Transport Document requests reached + errorCodeMessage: A maximum of 10 Transport Document can be patched per hour + /v3/shipping-instructions-notifications: + post: + tags: + - Notifications + summary: Send a new Shipping Instructions Notification + operationId: shipping-instructions-notifications + description: | + Creates a new [`Shipping Instructions Notification`](#/ShippingInstructionsNotification). This endPoint is called whenever a `Shipping Instructions` that a consumer has subscribed to changes state or is updated. + + **This endPoint is to be implemented by a consumer of the eBL API in order to receive Notifications** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + The payload used to create a [`Shipping Instructions Notification`](#/ShippingInstructionsNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/ShippingInstructionsNotification' + examples: + receivedLightweightExample: + summary: | + Shipping Instructions request received (Lightweight) + description: | + A lightweight notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.shipping-instructions.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: SI001 + data: + shippingInstructionsStatus: RECEIVED + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + receivedFullStateTransferExample: + summary: | + Shipping Instructions request received (Full State Transfer) + description: | + A full state transfer notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.shipping-instructions.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: SI001 + data: + shippingInstructionsStatus: RECEIVED + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + shippingInstructions: + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + shippingInstructionsStatus: RECEIVED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + declinedLightweightExample: + summary: | + Shipping Instructions update declined (Lightweight) + description: | + A lightweight notification explaining that an update to a `Shipping Instructions`, that was pending an update by the consumer (`shippingInstructionsStatus='PENDING_UPDATE'`), has been declined (`updatedShippingInstructionsStatus='UPDATE_DECLINED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.shipping-instructions.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: SI001 + data: + shippingInstructionsStatus: PENDING_UPDATE + updatedShippingInstructionsStatus: UPDATE_DECLINED + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + declinedFullStateTransferExample: + summary: | + Shipping Instructions update declined (Full State Transfer) + description: | + A full state transfer notification explaining that an update to a `Shipping Instructions`, that was pending an update by the consumer (`shippingInstructionsStatus='PENDING_UPDATE'`), has been declined (`updatedShippingInstructionsStatus='UPDATE_DECLINED'`) + + The example shows an original `ShippingInstructions` with a wrong weight on `consignmentItem` and `cargoItem`. The updated weight is also wrong! + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.shipping-instructions.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: SI001 + data: + shippingInstructionsStatus: PENDING_UPDATE + updatedShippingInstructionsStatus: UPDATE_DECLINED + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + shippingInstructions: + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + shippingInstructionsStatus: PENDING_UPDATE + updatedShippingInstructionsStatus: UPDATE_DECLINED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + updatedShippingInstructions: + shippingInstructionsReference: e0559d83-00e2-438e-afd9-fdd610c1a008 + shippingInstructionsStatus: PENDING_UPDATE + updatedShippingInstructionsStatus: UPDATE_DECLINED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + invoicePayableAt: + UNLocationCode: DKAAR + isCargoDeliveredInICS2Zone: false + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + commoditySubReference: RegSubRef001 + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 120000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipmentReference: NARU3472484 + responses: + '204': + description: | + No Content + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '400': + description: | + In case the `Notification` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Shipping Instructions missing shippingInstructionsReference + description: | + `shippingInstructionsReference` is a mandatory property in the `Notification`. This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/shipping-instructions-notifications + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + shippingInstructionsReference not found - mandatory to provide in a Notification + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: shippingInstructionsReference + errorCodeText: mandatory property missing + errorCodeMessage: | + shippingInstructionsReference must be provided as part of a Notification + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Notification + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/shipping-instructions-notifications + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Shipping Instructions + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Notifications + description: | + Calling the endPoint + + POST /v3/shipping-instructions-notifications + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/shipping-instructions-notifications + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a Notification has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Notifications reached + errorCodeMessage: A maximum of 10 Notifications can be created per hour + /v3/transport-document-notifications: + post: + tags: + - Notifications + summary: Send a new Transport Document Notification + operationId: transport-document-notifications + description: | + Creates a new [`Transport Document Notification`](#/TransportDocumentNotification). This endPoint is called whenever a `Transport Document` that a consumer has subscribed to changes state or is updated. + + **This endPoint is to be implemented by a consumer of the eBL API in order to receive Notifications** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + The payload used to create a [`Transport Document Notification`](#/TransportDocumentNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/TransportDocumentNotification' + examples: + draftLightweightExample: + summary: | + Transport Document Draft created (Lightweight) + description: | + A lightweight notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.transport-document.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: EBL001 + data: + transportDocumentStatus: DRAFT + transportDocumentReference: HHL71800000 + draftFullStateTransferExample: + summary: | + Transport Document Draft created (Full State Transfer) + description: | + A full state transfer notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.transport-document.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: EBL001 + data: + transportDocumentStatus: DRAFT + transportDocumentReference: HHL71800000 + transportDocument: + transportDocumentReference: HHL71800000 + shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9 + transportDocumentStatus: DRAFT + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + shippedOnBoardDate: '2023-12-20' + termsAndConditions: | + You agree that this transport document exist is name only for the sake of + testing your conformance with the DCSA eBL API. This transport document is NOT backed + by a real shipment with ANY carrier and NONE of the requested services will be + carried out in real life. + + Unless required by applicable law or agreed to in writing, DCSA provides + this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF + ANY KIND, either express or implied, including, without limitation, any + warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, + or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for + determining the appropriateness of using or redistributing this JSON + data and assume any risks associated with Your usage of this data. + + In no event and under no legal theory, whether in tort (including negligence), + contract, or otherwise, unless required by applicable law (such as deliberate + and grossly negligent acts) or agreed to in writing, shall DCSA be liable to + You for damages, including any direct, indirect, special, incidental, or + consequential damages of any character arising as a result of this terms or conditions + or out of the use or inability to use the provided JSON data (including but not limited + to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any + and all other commercial damages or losses), even if DCSA has been advised of the + possibility of such damages. + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: SCR-1234-REGULAR + carrierCode: MSC + carrierCodeListProvider: SMDG + transports: + plannedDepartureDate: '2023-12-20' + plannedArrivalDate: '2023-12-22' + portOfLoading: + UNLocationCode: DKAAR + portOfDischarge: + UNLocationCode: DEBRV + vesselVoyages: + - vesselName: MSC Gülsün + carrierExportVoyageNumber: 402E + charges: + - chargeName: Fictive transport document fee + currencyAmount: 1 + currencyCode: EUR + paymentTermCode: COL + calculationBasis: Per transport document + unitPrice: 1 + quantity: 1 + invoicePayableAt: + UNLocationCode: DKAAR + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + issuingParty: + partyName: Mediterranean Shipping Company + address: + street: Chemin Rieu + streetNumber: 12-14 + city: Geneva + countryCode: CH + identifyingCodes: + - codeListProvider: GLEIF + codeListName: LEI + partyCode: 529900T8BM49AURSDO55 + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 22G1 + equipmentReference: NARU3472484 + issuedLightweightExample: + summary: | + Transport Document has been issued (Lightweight) + description: | + A lightweight notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.transport-document.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: EBL001 + data: + transportDocumentStatus: ISSUED + transportDocumentReference: HHL71800000 + transportDocumentSubReference: v2 + issuedFullStateTransferExample: + summary: | + Transport Document has been issued (Full State Transfer) + description: | + A full state transfer notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.transport-document.v3 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: EBL001 + data: + transportDocumentStatus: ISSUED + transportDocumentReference: HHL71800000 + transportDocumentSubReference: v2 + transportDocument: + transportDocumentReference: HHL71800000 + transportDocumentSubReference: v2 + shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9 + transportDocumentStatus: ISSUED + transportDocumentTypeCode: BOL + isShippedOnBoardType: true + freightPaymentTermCode: PRE + isElectronic: true + isToOrder: true + shippedOnBoardDate: '2023-12-20' + termsAndConditions: | + You agree that this transport document exist is name only for the sake of + testing your conformance with the DCSA eBL API. This transport document is NOT backed + by a real shipment with ANY carrier and NONE of the requested services will be + carried out in real life. + + Unless required by applicable law or agreed to in writing, DCSA provides + this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF + ANY KIND, either express or implied, including, without limitation, any + warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, + or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for + determining the appropriateness of using or redistributing this JSON + data and assume any risks associated with Your usage of this data. + + In no event and under no legal theory, whether in tort (including negligence), + contract, or otherwise, unless required by applicable law (such as deliberate + and grossly negligent acts) or agreed to in writing, shall DCSA be liable to + You for damages, including any direct, indirect, special, incidental, or + consequential damages of any character arising as a result of this terms or conditions + or out of the use or inability to use the provided JSON data (including but not limited + to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any + and all other commercial damages or losses), even if DCSA has been advised of the + possibility of such damages. + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: SCR-1234-REGULAR + carrierCode: MSC + carrierCodeListProvider: SMDG + transports: + plannedDepartureDate: '2023-12-20' + plannedArrivalDate: '2023-12-22' + portOfLoading: + UNLocationCode: DKAAR + portOfDischarge: + UNLocationCode: DEBRV + vesselVoyages: + - vesselName: MSC Gülsün + carrierExportVoyageNumber: 402E + charges: + - chargeName: Fictive transport document fee + currencyAmount: 1 + currencyCode: EUR + paymentTermCode: COL + calculationBasis: Per transport document + unitPrice: 1 + quantity: 1 + invoicePayableAt: + UNLocationCode: DKAAR + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + documentParties: + shipper: + partyName: DCSA CTK + displayedAddress: + - Strawinskylaan 4117 + partyContactDetails: + - name: DCSA test person + email: no-reply@dcsa.example.org + issuingParty: + partyName: Mediterranean Shipping Company + address: + street: Chemin Rieu + streetNumber: 12-14 + city: Geneva + countryCode: CH + identifyingCodes: + - codeListProvider: GLEIF + codeListName: LEI + partyCode: 529900T8BM49AURSDO55 + consignmentItems: + - carrierBookingReference: CBR_123_REGULAR + descriptionOfGoods: + - 'Shoes - black' + HSCodes: + - '640510' + cargoItems: + - equipmentReference: NARU3472484 + cargoGrossWeight: + value: 12000 + unit: KGM + outerPackaging: + numberOfPackages: 400 + packageCode: 4G + description: Fibreboard boxes + utilizedTransportEquipments: + - isShipperOwned: false + seals: + - number: DCSA-CTK-1234 + equipment: + ISOEquipmentCode: 22G1 + equipmentReference: NARU3472484 + responses: + '204': + description: | + No Content + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '400': + description: | + In case the `Notification` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Transport Document missing transportDocumentReference + description: | + `transportDocumentReference` is a mandatory property in the `Notification`. This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/transport-document-notifications + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + transportDocumentReference not found - mandatory to provide in a Notification + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: transportDocumentReference + errorCodeText: mandatory property missing + errorCodeMessage: | + transportDocumentReference must be provided as part of a Notification + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Notification + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/transport-document-notifications + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Transport Document + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Notifications + description: | + Calling the endPoint + + POST /v3/transport-document-notifications + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v3/transport-document-notifications + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a Notification has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Notifications reached + errorCodeMessage: A maximum of 10 Notifications can be created per hour +components: + headers: + API-Version: + schema: + type: string + example: 3.0.2 + description: | + SemVer used to indicate the version of the contract (API version) returned. + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '3' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + ############# + # Path params + ############# + documentReference: + in: path + name: documentReference + description: | + An identifier for a `Shipping Instructions`. It can be one of `shippingInstructionsReference` or `transportDocumentReference`. + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + required: true + updatedContent: + in: query + name: updatedContent + description: | + If set to `true`, the payload returned is the content of the `Updated Shipping Instructions`. + + Default value is `false` in which case the content of the "original" `Shipping Instructions` is returned. + + **Condition:** Can only be used if an update has been made by the consumer (via **UseCase 3: Submit updated Shipping Instructions**) and **until** a new updated is requested by the provider. If no updates have been made a `404` (Not Found) response will be returned + schema: + type: boolean + default: false + example: false + schemas: + ####################################### + # Create Shipping Instructions Response + ####################################### + CreateShippingInstructionsResponse: + type: object + title: Create Shipping Instructions Response + description: | + **Only** the `shippingInstructionsReference` is returned. + properties: + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + required: + - shippingInstructionsReference + + ##################################### + # Cancel Shipping Instructions Update + ##################################### + CancelShippingInstructionsUpdate: + type: object + title: Cancel Shipping Instructions Update + description: | + Cancel the `Shipping Instructions` update + properties: + updatedShippingInstructionsStatus: + type: string + maxLength: 50 + description: | + The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED` + example: UPDATE_CANCELLED + required: + - updatedShippingInstructionsStatus + + ############################ + # Approve Transport Document + ############################ + ApproveTransportDocument: + type: object + title: Approve Transport Document + description: | + Approves the Draft Transport Document + properties: + transportDocumentStatus: + type: string + maxLength: 50 + description: | + The status of the `Transport Document`. It can only be `APPROVED` + example: APPROVED + required: + - transportDocumentStatus + + #################################### + # Shipping Instructions Notification + #################################### + ShippingInstructionsNotification: + type: object + title: Shipping Instructions Notification + description: | + `CloudEvent` specific properties for the `Notification`. + properties: + specversion: + type: string + description: | + The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of `1.0` when referring to this version of the specification. + + Currently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes. + enum: + - '1.0' + example: '1.0' + id: + type: string + maxLength: 100 + description: | + Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates. + example: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: + type: string + maxLength: 4096 + description: | + Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that `source` + `id` is unique for each distinct event. + example: 'https://member.com/' + type: + type: string + description: | + This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see [Versioning of CloudEvents in the Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#versioning-of-cloudevents) for more information. + enum: + - org.dcsa.shipping-instructions.v3 + example: org.dcsa.shipping-instructions.v3 + time: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. + example: '2018-04-05T17:31:00Z' + datacontenttype: + type: string + description: | + Content type of `data` value. This attribute enables `data` to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the [JSON envelope](formats/json-format.md#3-envelope) format might carry an XML payload in `data`, and the consumer is informed by this attribute being set to "application/xml". The rules for how `data` content is rendered for different `datacontenttype` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](formats/json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol. + + In some event formats the `datacontenttype` attribute MAY be omitted. For example, if a JSON format event has no `datacontenttype` attribute, then it is implied that the `data` is a JSON value conforming to the "application/json" media type. In other words: a JSON-format event with no `datacontenttype` is exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a different format or protocol binding, the target `datacontenttype` SHOULD be set explicitly to the implied `datacontenttype` of the source. + enum: + - application/json + example: application/json + subscriptionReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The reference of the subscription that has triggered this event + example: '30675492-50ff-4e17-a7df-7a487a8ad343' + data: + $ref: '#/components/schemas/ShippingInstructionsData' + required: + - specversion + - id + - source + - type + - time + - datacontenttype + - subscriptionReference + - data + + ############################################# + # Data for Shipping Instructions Notification + ############################################# + ShippingInstructionsData: + type: object + title: Shipping Instructions Data + description: | + `Shipping Instructions` specific properties for the `Notification` + properties: + shippingInstructionsStatus: + type: string + maxLength: 50 + description: | + The status of the `Shipping Instructions`. Possible values are: + + - `RECEIVED` (Shipping Instructions has been received) + - `PENDING_UPDATE` (An update is required to the Shipping Instructions) + - `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery) + example: RECEIVED + updatedShippingInstructionsStatus: + type: string + maxLength: 50 + description: | + The status of latest update to the `Shipping Instructions`. If no update has been requested - then this property is empty. Possible values are: + + - `UPDATE_RECEIVED` (An update to a Shipping Instructions has been received and is awaiting to be processed) + - `UPDATE_CONFIRMED` (Update is confirmed) + - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer) + - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider) + example: UPDATE_RECEIVED + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + + **Condition:** `shippingInstructionsReference` and/or `transportDocumentReference` is required to provide + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + + **Condition:** `shippingInstructionsReference` and/or `transportDocumentReference` is required to provide + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + shippingInstructions: + $ref: '#/components/schemas/ShippingInstructionsFullNotification' + updatedShippingInstructions: + $ref: '#/components/schemas/UpdatedShippingInstructionsFullNotification' + required: + - shippingInstructionsStatus + + ######################################### + # Shipping Instructions Full Notification + ######################################### + ShippingInstructionsFullNotification: + type: object + title: Shipping Instructions Full Notification + description: | + This property contains the shippingInstructions in case the subscriber is subscribing to the `Full State Transfer` of the Shipping Instructions. + + In case the subscriber does not subscribe to the `Full State Transfer` of the Shipping Instructions then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/ShippingInstructions' + + ################################################# + # Updated Shipping Instructions Full Notification + ################################################# + UpdatedShippingInstructionsFullNotification: + type: object + title: Updated Shipping Instructions + description: | + This property contains the updated shipping instructions in case: + - an update is currently active + - the subscriber is subscribing to the `Full State Transfer` of the Shipping Instructions + + In case the subscriber does not subscribe to the `Full State Transfer` of the Shipping Instructions or no update is active - then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/ShippingInstructions' + + ################################# + # Transport Document Notification + ################################# + TransportDocumentNotification: + type: object + title: Transport Document Notification + description: | + `CloudEvent` specific properties for the `Notification`. + properties: + specversion: + type: string + description: | + The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of `1.0` when referring to this version of the specification. + + Currently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes. + enum: + - '1.0' + example: '1.0' + id: + type: string + maxLength: 100 + description: | + Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates. + example: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: + type: string + maxLength: 4096 + description: | + Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that `source` + `id` is unique for each distinct event. + example: 'https://member.com/' + type: + type: string + description: | + This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see [Versioning of CloudEvents in the Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#versioning-of-cloudevents) for more information. + enum: + - org.dcsa.transport-document.v3 + example: org.dcsa.transport-document.v3 + time: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. + example: '2018-04-05T17:31:00Z' + datacontenttype: + type: string + description: | + Content type of `data` value. This attribute enables `data` to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the [JSON envelope](formats/json-format.md#3-envelope) format might carry an XML payload in `data`, and the consumer is informed by this attribute being set to "application/xml". The rules for how `data` content is rendered for different `datacontenttype` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](formats/json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol. + + In some event formats the `datacontenttype` attribute MAY be omitted. For example, if a JSON format event has no`datacontenttype` attribute, then it is implied that the `data` is a JSON value conforming to the "application/json" media type. In other words: a JSON-format event with no `datacontenttype` is exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a different format or protocol binding, the target `datacontenttype` SHOULD be set explicitly to the implied `datacontenttype` of the source. + enum: + - application/json + example: application/json + subscriptionReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The reference of the subscription that has triggered this event + example: '30675492-50ff-4e17-a7df-7a487a8ad343' + data: + $ref: '#/components/schemas/TransportDocumentData' + required: + - specversion + - id + - source + - type + - time + - datacontenttype + - subscriptionReference + - data + + ########################################## + # Data for Transport Document Notification + ########################################## + TransportDocumentData: + type: object + title: Transport Document Data + description: | + `Transport Document` specific properties for the `Notification` + properties: + transportDocumentStatus: + type: string + maxLength: 50 + description: | + The status of the `Transport Document`. Possible values are: + + - `DRAFT` (the Transport Document is currently a Draft) + - `APPROVED` (the Transport Document has been Approved by consumer) + - `ISSUED` (the Transport Document has been Issued by provider) + - `PENDING_SURRENDER_FOR_AMENDMENT` (the Transport Document has a pending Surrender for Amendment) + - `SURRENDER_FOR_AMENDMENT` (the Transport Document is Surrendered for Amendment) + - `VOID` (the Transport Document has been Voided) + - `PENDING_SURRENDER_FOR_DELIVERY` (the Transport Document has a pending Surrender for Delivery) + - `SURRENDER_FOR_DELIVERY` (the Transport Document is Surrendered for Delivery) + example: DRAFT + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + transportDocument: + $ref: '#/components/schemas/TransportDocumentFullNotification' + required: + - transportDocumentStatus + - transportDocumentReference + + ###################################### + # Transport Document Full Notification + ###################################### + TransportDocumentFullNotification: + type: object + title: Transport Document Full Notification + description: | + This property contains the `transportDocument` in case the subscriber is subscribing to the `Full State Transfer` of the `Transport Document`. + + In case the subscriber does not subscribe to the `Full State Transfer` of the `Transport Document` then the content in this property can be ignored. + + **Condition:** Once the `Transport Document` has been Issued (`transportDocumentStatus='ISSUED'`) - the order of **ALL** lists/arrays in this property **MUST** be aligned with the order of the + + GET /v3/transport-documents/{transportDocumentReference} + + payload implemented by the provider of the **Shipping Instructions and Transport Document** API. + allOf: + - $ref: '#/components/schemas/TransportDocument' + + ############################## + # Create Shipping Instructions + ############################## + CreateShippingInstructions: + type: object + description: | + The `Shipping Instructions` is an enrichment to the original booking shared by the Shipper to the Carrier. The information given by the Shipper through the `Shipping Instructions` is the information required to create a `Draft Transport Document`. + title: Create Shipping Instructions + properties: + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line, for the shipper to indicate which `transportDocumentReference` should be linked with this `Shipping Instructions`. + example: HHL71800000 + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the transport document + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + isShippedOnBoardType: + type: boolean + description: | + Specifies whether the Transport Document is a received for shipment, or shipped on board. + example: true + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + isElectronic: + type: boolean + description: | + An indicator whether the transport document is electronically transferred. + example: true + isToOrder: + type: boolean + description: | + Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`). + + `isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill). + example: false + numberOfCopiesWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`| + example: 2 + numberOfCopiesWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`| + example: 2 + numberOfOriginalsWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer with charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + numberOfOriginalsWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer without charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + displayedNameForPlaceOfReceipt: + description: | + The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfLoad: + description: | + The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfDischarge: + description: | + The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPlaceOfDelivery: + description: | + The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the `Shipping Instructions` is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + partyContactDetails: + type: array + minItems: 1 + description: | + The contact details of the Shipping Instructions requestor(s) to contact in relation to the **Transport Document** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + isCarriersAgentAtDestinationRequired: + type: boolean + description: | + Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`. + example: false + documentParties: + $ref: '#/components/schemas/DocumentPartiesShippingInstructions' + isCargoDeliveredInICS2Zone: + type: boolean + description: | + Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland. + example: true + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` + items: + $ref: '#/components/schemas/ConsignmentItemShipper' + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipments` describing the equipment being used. + items: + $ref: '#/components/schemas/UtilizedTransportEquipmentShipper' + exportLicense: + $ref: '#/components/schemas/ExportLicenseShipper' + importLicense: + $ref: '#/components/schemas/ImportLicenseShipper' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + isHouseBillOfLadingsIssued: + type: boolean + description: | + Indicates whether one or more `House Bill of Lading(s)` have been issued. + + **Condition:** Mandatory if `manifestTypeCode` is `ENS` + example: true + houseBillOfLadings: + type: array + description: | + A list of `House Bill of Ladings` specified by the Shipper. + items: + $ref: '#/components/schemas/HouseBillOfLading' + requestedCarrierCertificates: + type: array + description: | + Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + items: + type: string + maxLength: 100 + description: | + Name of the certificate. Detailed information about carrier certificates can be found [here](https://dcsa.org/wp-content/uploads/2023/12/28-12-2023_Carrier-Certificates-shipment-voyage-particulars-and-vessel-particulars.pdf). Possible values are: + - `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1) + - `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2) + - `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3) + - `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4) + - `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5) + - `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6) + - `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7) + - `VESSEL_PARTICULARS_1` (Vessel Particulars 1) + - `VESSEL_PARTICULARS_2` (Vessel Particulars 2) + - `VESSEL_PARTICULARS_3` (Vessel Particulars 3) + - `VESSEL_PARTICULARS_4` (Vessel Particulars 4) + - `VESSEL_PARTICULARS_5` (Vessel Particulars 5) + - `VESSEL_PARTICULARS_6` (Vessel Particulars 6) + - `VESSEL_PARTICULARS_7` (Vessel Particulars 7) + - `VESSEL_PARTICULARS_8` (Vessel Particulars 8) + - `VESSEL_PARTICULARS_9` (Vessel Particulars 9) + - `VESSEL_PARTICULARS_10` (Vessel Particulars 10) + - `VESSEL_PARTICULARS_11` (Vessel Particulars 11) + - `VESSEL_PARTICULARS_12` (Vessel Particulars 12) + - `VESSEL_PARTICULARS_13` (Vessel Particulars 13) + - `VESSEL_PARTICULARS_14` (Vessel Particulars 14) + - `VESSEL_PARTICULARS_15` (Vessel Particulars 15) + - `VESSEL_PARTICULARS_16` (Vessel Particulars 16) + - `VESSEL_PARTICULARS_17` (Vessel Particulars 17) + - `VESSEL_PARTICULARS_18` (Vessel Particulars 18) + example: VESSEL_PARTICULARS_1 + requestedCarrierClauses: + type: array + description: | + Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + items: + type: string + maxLength: 100 + description: | + A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa-website.cdn.prismic.io/dcsa-website/ZvaCMbVsGrYSwERk_202409StandardisedClausesBL-Final.pdf). Possible values are: + - `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics) + - `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific) + - `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container) + - `CARGO_CARGOVALUE` (Cargo/Cargo value) + - `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature) + - `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads) + - `SHIPPERSLOADSTOWWEIGHTANDCOUNT` (Shipper's Load, Stow, Weight and Count) + - `INTRANSITCLAUSE` (In transit clause) + example: CARGO_CARGOSPECIFICS + required: + - transportDocumentTypeCode + - isShippedOnBoardType + - isElectronic + - isToOrder + - freightPaymentTermCode + - partyContactDetails + - documentParties + - isCargoDeliveredInICS2Zone + - consignmentItems + - utilizedTransportEquipments + + UpdateShippingInstructions: + description: | + The `Shipping Instructions` to update. + type: object + title: Update Shipping Instructions + properties: + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line, for the shipper to indicate which `transportDocumentReference` should be linked with this `Shipping Instructions`. + example: HHL71800000 + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the transport document + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + isShippedOnBoardType: + type: boolean + description: | + Specifies whether the Transport Document is a received for shipment, or shipped on board. + example: true + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + isElectronic: + type: boolean + description: | + An indicator whether the transport document is electronically transferred. + example: true + isToOrder: + type: boolean + description: | + Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`). + + `isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill). + example: false + numberOfCopiesWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`| + example: 2 + numberOfCopiesWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`| + example: 2 + numberOfOriginalsWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer with charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + numberOfOriginalsWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer without charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + displayedNameForPlaceOfReceipt: + description: | + The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfLoad: + description: | + The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfDischarge: + description: | + The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPlaceOfDelivery: + description: | + The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the `Shipping Instructions` is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + partyContactDetails: + type: array + minItems: 1 + description: | + The contact details of the Shipping Instructions requestor(s) to contact in relation to the **Transport Document** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + isCarriersAgentAtDestinationRequired: + type: boolean + description: | + Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`. + example: false + documentParties: + $ref: '#/components/schemas/DocumentPartiesShippingInstructions' + isCargoDeliveredInICS2Zone: + type: boolean + description: | + Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland. + example: true + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` + items: + $ref: '#/components/schemas/ConsignmentItemShipper' + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipments` describing the equipment being used. + items: + $ref: '#/components/schemas/UtilizedTransportEquipmentShipper' + exportLicense: + $ref: '#/components/schemas/ExportLicenseShipper' + importLicense: + $ref: '#/components/schemas/ImportLicenseShipper' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + isHouseBillOfLadingsIssued: + type: boolean + description: | + Indicates whether one or more `House Bill of Lading(s)` have been issued. + + **Condition:** Mandatory if `manifestTypeCode` is `ENS` + example: true + houseBillOfLadings: + type: array + description: | + A list of `House Bill of Ladings` specified by the Shipper. + items: + $ref: '#/components/schemas/HouseBillOfLading' + requestedCarrierCertificates: + type: array + description: | + Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + items: + type: string + maxLength: 100 + description: | + Name of the certificate. Detailed information about carrier certificates can be found [here](https://dcsa.org/wp-content/uploads/2023/12/28-12-2023_Carrier-Certificates-shipment-voyage-particulars-and-vessel-particulars.pdf). Possible values are: + - `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1) + - `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2) + - `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3) + - `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4) + - `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5) + - `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6) + - `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7) + - `VESSEL_PARTICULARS_1` (Vessel Particulars 1) + - `VESSEL_PARTICULARS_2` (Vessel Particulars 2) + - `VESSEL_PARTICULARS_3` (Vessel Particulars 3) + - `VESSEL_PARTICULARS_4` (Vessel Particulars 4) + - `VESSEL_PARTICULARS_5` (Vessel Particulars 5) + - `VESSEL_PARTICULARS_6` (Vessel Particulars 6) + - `VESSEL_PARTICULARS_7` (Vessel Particulars 7) + - `VESSEL_PARTICULARS_8` (Vessel Particulars 8) + - `VESSEL_PARTICULARS_9` (Vessel Particulars 9) + - `VESSEL_PARTICULARS_10` (Vessel Particulars 10) + - `VESSEL_PARTICULARS_11` (Vessel Particulars 11) + - `VESSEL_PARTICULARS_12` (Vessel Particulars 12) + - `VESSEL_PARTICULARS_13` (Vessel Particulars 13) + - `VESSEL_PARTICULARS_14` (Vessel Particulars 14) + - `VESSEL_PARTICULARS_15` (Vessel Particulars 15) + - `VESSEL_PARTICULARS_16` (Vessel Particulars 16) + - `VESSEL_PARTICULARS_17` (Vessel Particulars 17) + - `VESSEL_PARTICULARS_18` (Vessel Particulars 18) + example: VESSEL_PARTICULARS_1 + requestedCarrierClauses: + type: array + description: | + Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + items: + type: string + maxLength: 100 + description: | + A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa-website.cdn.prismic.io/dcsa-website/ZvaCMbVsGrYSwERk_202409StandardisedClausesBL-Final.pdf). Possible values are: + - `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics) + - `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific) + - `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container) + - `CARGO_CARGOVALUE` (Cargo/Cargo value) + - `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature) + - `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads) + - `SHIPPERSLOADSTOWWEIGHTANDCOUNT` (Shipper's Load, Stow, Weight and Count) + - `INTRANSITCLAUSE` (In transit clause) + example: CARGO_CARGOSPECIFICS + required: + - shippingInstructionsReference + - transportDocumentTypeCode + - isShippedOnBoardType + - isElectronic + - isToOrder + - freightPaymentTermCode + - partyContactDetails + - documentParties + - isCargoDeliveredInICS2Zone + - consignmentItems + - utilizedTransportEquipments + + ShippingInstructions: + description: | + The `Shipping Instructions` as provided by the Shipper. + type: object + title: Shipping Instructions + properties: + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + shippingInstructionsStatus: + type: string + maxLength: 50 + description: | + The status of the `Shipping Instructions`. Possible values are: + - `RECEIVED` (Shipping Instructions has been received) + - `PENDING_UPDATE` (An update is required to the Shipping Instructions) + - `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery) + example: RECEIVED + updatedShippingInstructionsStatus: + type: string + maxLength: 50 + description: | + The status of the latest update to the `Shipping Instructions`. If no update has been requested - then this field is empty. Possible values are: + - `UPDATE_RECEIVED` (An update to a Shipping Instructions is waiting to be processed) + - `UPDATE_CONFIRMED` (An update to a Shipping Instructions has been confirmed) + - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer) + - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider) + example: UPDATE_RECEIVED + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the transport document + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + isShippedOnBoardType: + type: boolean + description: | + Specifies whether the Transport Document is a received for shipment, or shipped on board. + example: true + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + isElectronic: + type: boolean + description: | + An indicator whether the transport document is electronically transferred. + example: true + isToOrder: + type: boolean + description: | + Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`). + + `isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill). + example: false + numberOfCopiesWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`| + example: 2 + numberOfCopiesWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`| + example: 2 + numberOfOriginalsWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer with charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + numberOfOriginalsWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer without charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + displayedNameForPlaceOfReceipt: + description: | + The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfLoad: + description: | + The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfDischarge: + description: | + The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPlaceOfDelivery: + description: | + The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the `Shipping Instructions` is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + partyContactDetails: + type: array + minItems: 1 + description: | + The contact details of the Shipping Instructions requestor(s) to contact in relation to the **Transport Document** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + isCarriersAgentAtDestinationRequired: + type: boolean + description: | + Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`. + example: false + documentParties: + $ref: '#/components/schemas/DocumentPartiesShippingInstructions' + isCargoDeliveredInICS2Zone: + type: boolean + description: | + Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland. + example: true + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` + items: + $ref: '#/components/schemas/ConsignmentItemShipper' + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipments` describing the equipment being used. + items: + $ref: '#/components/schemas/UtilizedTransportEquipmentShipper' + exportLicense: + $ref: '#/components/schemas/ExportLicenseShipper' + importLicense: + $ref: '#/components/schemas/ImportLicenseShipper' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + isHouseBillOfLadingsIssued: + type: boolean + description: | + Indicates whether one or more `House Bill of Lading(s)` have been issued. + + **Condition:** Mandatory if `manifestTypeCode` is `ENS` + houseBillOfLadings: + type: array + description: | + A list of `House Bill of Ladings` specified by the Shipper. + items: + $ref: '#/components/schemas/HouseBillOfLading' + requestedCarrierCertificates: + type: array + description: | + Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + items: + type: string + maxLength: 100 + description: | + Name of the certificate. Detailed information about carrier certificates can be found [here](https://dcsa.org/wp-content/uploads/2023/12/28-12-2023_Carrier-Certificates-shipment-voyage-particulars-and-vessel-particulars.pdf). Possible values are: + - `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1) + - `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2) + - `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3) + - `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4) + - `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5) + - `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6) + - `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7) + - `VESSEL_PARTICULARS_1` (Vessel Particulars 1) + - `VESSEL_PARTICULARS_2` (Vessel Particulars 2) + - `VESSEL_PARTICULARS_3` (Vessel Particulars 3) + - `VESSEL_PARTICULARS_4` (Vessel Particulars 4) + - `VESSEL_PARTICULARS_5` (Vessel Particulars 5) + - `VESSEL_PARTICULARS_6` (Vessel Particulars 6) + - `VESSEL_PARTICULARS_7` (Vessel Particulars 7) + - `VESSEL_PARTICULARS_8` (Vessel Particulars 8) + - `VESSEL_PARTICULARS_9` (Vessel Particulars 9) + - `VESSEL_PARTICULARS_10` (Vessel Particulars 10) + - `VESSEL_PARTICULARS_11` (Vessel Particulars 11) + - `VESSEL_PARTICULARS_12` (Vessel Particulars 12) + - `VESSEL_PARTICULARS_13` (Vessel Particulars 13) + - `VESSEL_PARTICULARS_14` (Vessel Particulars 14) + - `VESSEL_PARTICULARS_15` (Vessel Particulars 15) + - `VESSEL_PARTICULARS_16` (Vessel Particulars 16) + - `VESSEL_PARTICULARS_17` (Vessel Particulars 17) + - `VESSEL_PARTICULARS_18` (Vessel Particulars 18) + example: VESSEL_PARTICULARS_1 + requestedCarrierClauses: + type: array + description: | + Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + items: + type: string + maxLength: 100 + description: | + A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa-website.cdn.prismic.io/dcsa-website/ZvaCMbVsGrYSwERk_202409StandardisedClausesBL-Final.pdf). Possible values are: + - `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics) + - `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific) + - `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container) + - `CARGO_CARGOVALUE` (Cargo/Cargo value) + - `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature) + - `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads) + - `SHIPPERSLOADSTOWWEIGHTANDCOUNT` (Shipper's Load, Stow, Weight and Count) + - `INTRANSITCLAUSE` (In transit clause) + example: CARGO_CARGOSPECIFICS + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + required: + - shippingInstructionsStatus + - transportDocumentTypeCode + - isShippedOnBoardType + - isElectronic + - isToOrder + - freightPaymentTermCode + - partyContactDetails + - documentParties + - isCargoDeliveredInICS2Zone + - consignmentItems + - utilizedTransportEquipments + + ########## + # Feedback + ########## + Feedback: + type: object + title: Feedback + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + properties: + severity: + type: string + maxLength: 50 + description: | + The severity of the feedback. Possible values are: + - `INFO` (Information - "Your reefer container will use renewable energy", "This earlier / premium service is available") + - `WARN` (Warning - "I'm going to replace" / "Ignore this value" / "Use another value instead") + - `ERROR` (Error - "This must be changed!") + example: WARN + code: + type: string + maxLength: 50 + description: | + A code used to describe the feedback. Possible values are: + - `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) + - `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values) + - `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided) + - `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention) + - `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future) + - `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention) + example: PROPERTY_WILL_BE_IGNORED + message: + type: string + maxLength: 5000 + description: | + A description with additional information. + example: Spaces not allowed in facility code + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error/warning. + example: facilityCode + required: + - severity + - code + - message + + ################# + # Error Responses + ################# + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v1/events + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. + type: string + format: date-time + example: '2024-09-04T09:41:00Z' + errors: + type: array + description: | + An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + + DetailedError: + type: object + title: Detailed Error + description: | + A detailed description of what has caused the error. + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + minimum: 7000 + maximum: 9999 + example: 7003 + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error. + example: facilityCode + value: + type: string + maxLength: 500 + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + description: | + A standard short description corresponding to the `errorCode`. + type: string + maxLength: 100 + example: invalidData + errorCodeMessage: + type: string + maxLength: 5000 + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + - errorCodeMessage + + ################## + # Address Location + ################## + Address: + type: object + title: Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the street number. + example: N/A + postCode: + type: string + maxLength: 10 + description: The post code of the address. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - street + - city + - countryCode + + ############### + # City Location + ############### + City: + type: object + title: City + description: | + An object for storing city, state/region and country related information + properties: + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: | + The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - city + - countryCode + + ################### + # Facility Location + ################### + Facility: + type: object + title: Facility + description: | + An object used to express a location using a `Facility`. The facility can be expressed using one of `BIC` code or `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + properties: + facilityCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 6 + description: |- + The code used for identifying the specific facility. This code does not include the UN Location Code. + The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used: + - `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)) + - `BIC` (the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)) + example: ADT + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code` + - `BIC` (Requires a UN Location Code) + - `SMDG` (Requires a UN Location Code) + enum: + - BIC + - SMDG + example: SMDG + required: + - facilityCode + - facilityCodeListProvider + + ######################### + # Geo Coordinate Location + ######################### + GeoCoordinate: + type: object + title: Geo Coordinate + description: | + An object used to express a location using `latitude` and `longitude`. + properties: + latitude: + type: string + description: | + Latitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: | + Longitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 11 + example: '2.294492036' + required: + - latitude + - longitude + + ################ + # Document Party + ################ + OtherDocumentParty: + type: object + title: Other Document Party + description: | + A list of document parties that can be optionally provided in the `Transport Document`. + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `SCO` (Service Contract Owner) + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + example: DDS + required: + - party + - partyFunction + + OtherDocumentPartyShippingInstructions: + type: object + title: Other Document Party (Shipping Instructions) + description: | + A list of document parties that can be optionally provided in the `Shipping Instructions`. + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `SCO` (Service Contract Owner) + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + - `CS` (Consolidator) + - `MF` (Manufacturer) + - `WH` (Warehouse Keeper) + example: DDS + required: + - party + - partyFunction + + OtherDocumentPartyHBL: + type: object + title: Other Document Party (House B/L) + description: | + A list of document parties that can be optionally provided in the `House B/L`. + properties: + party: + $ref: '#/components/schemas/PartyHBL' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `CS` (Consolidator) + - `MF` (Manufacturer) + - `WH` (Warehouse Keeper) + example: DDS + required: + - party + - partyFunction + + PartyAddress: + type: object + title: Party Address + description: | + Address where the party is located. It is an object of the attributes below. + properties: + street: + type: string + description: The name of the street of the party’s address. + maxLength: 70 + example: Ruijggoordweg + streetNumber: + type: string + description: The number of the street of the party’s address. + maxLength: 50 + example: '100' + floor: + type: string + description: | + The floor of the party’s street number. + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2nd + postCode: + type: string + description: The post code of the party’s address. + maxLength: 10 + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + description: | + The city name of the party’s address. + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + example: Amsterdam + UNLocationCode: + type: string + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + stateRegion: + type: string + description: The state/region of the party’s address. + maxLength: 65 + example: North Holland + countryCode: + type: string + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: NL + required: + - street + - city + - countryCode + + Shipper: + type: object + title: Shipper + description: | + The party by whom or in whose name or on whose behalf a contract of carriage of goods by sea has been concluded with a carrier, or the party by whom or in whose name, or on whose behalf, the goods are actually delivered to the carrier in relation to the contract of carriage by sea. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Shipper`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Shipper`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Shipper`. + example: HHL007 + required: + - partyName + + OnBehalfOfShipper: + type: object + title: On Behalf of Shipper + description: | + The party allowed to act on behalf of the shipper for documentation purposes. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + ShipperHBL: + type: object + title: Shipper (House B/L) + description: | + The `Shipper` on the `House Bill of Lading`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + required: + - partyName + - typeOfPerson + + Consignee: + type: object + title: Consignee + description: | + The party to which goods are consigned in the `Master Bill of Lading`. + + **Condition:** Mandatory for non-negotiable BL (`isToOrder=false`) + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Consignee`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Consignee`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + required: + - partyName + - identifyingCodes + + OnBehalfOfConsignee: + type: object + title: On Behalf of Consignee + description: | + The party allowed to act on behalf of the consignee for documentation purposes. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + ConsigneeShipper: + type: object + title: Consignee (Shipper provided) + description: | + The party to which goods are consigned in the `Master Bill of Lading`. + + **Condition:** Mandatory for non-negotiable BL (`isToOrder=false`) + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Consignee`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Consignee`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + required: + - partyName + + ConsigneeHBL: + type: object + title: Consignee (House B/L) + description: | + The ultimate recipient of the cargo. It must be different from the freight forwarder, (de)consolidator, postal operator, or customs agent. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + required: + - partyName + - typeOfPerson + + Endorsee: + type: object + title: Endorsee + description: | + The party to whom the title to the goods is transferred by means of endorsement. + + **Condition:** Can only be provided for negotiable BLs (`isToOrder=true`). If a negotiable BL does not have an `Endorsee`, the BL is said to be "blank endorsed". Note `Consignee` and `Endorsee` are mutually exclusive. + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - identifyingCodes + + EndorseeShipper: + type: object + title: Endorsee (Shipper provided) + description: | + The party to whom the title to the goods is transferred by means of endorsement. + + **Condition:** Can only be provided for negotiable BLs (`isToOrder=true`). If a negotiable BL does not have an `Endorsee`, the BL is said to be "blank endorsed". Note `Consignee` and `Endorsee` are mutually exclusive. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + + CarriersAgentAtDestination: + type: object + title: Carrier's Agent At Destination + description: | + The party on the import side assigned by the carrier to whom the customer need to reach out to for cargo release. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/Address' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - address + - partyContactDetails + + IssueToParty: + type: object + title: Issue To Party + description: | + The party that receives **possession** of the original Bill of Lading upon issuance. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + sendToPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the transaction party. + The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + + **Condition:** Only applicable when `isElectronic=true` and `transportDocumentTypeCode=BOL`. The property **MUST** be absent for paper B/Ls (`isElectronic=false`) + example: BOLE + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + required: + - partyName + - identifyingCodes + + NotifyParty: + type: object + title: Notify Party + description: | + The person to be notified when a shipment arrives at its destination. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `NotifyParty`. + example: HHL007 + required: + - partyName + + NotifyPartyHBL: + type: object + title: Notify Party (House B/L) + description: | + The person to be notified when a shipment arrives at its destination. + + **Condition:** Mandatory for To Order HBLs (HouseBL `isToOrder=true`) + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + required: + - partyName + - partyContactDetails + - typeOfPerson + + Seller: + type: object + title: Seller + description: | + The seller is the last known entity by whom the goods are sold or agreed to be sold to the buyer. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided. + + **Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` and `manifestTypeCode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'` and `isHouseBillOfLadingsIssued=false`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailWithPattern' + required: + - partyName + - typeOfPerson + + SellerHBL: + type: object + title: Seller (House B/L) + description: | + The seller is the last known entity by whom the goods are sold or agreed to be sold to the buyer. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided. + + **Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) and `manifestTypeCode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + required: + - partyName + - typeOfPerson + + Buyer: + type: object + title: Buyer + description: | + The buyer is the last known entity to whom the goods are sold or agreed to be sold. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided. + + **Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` and `manifestTypeCode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'` and `isHouseBillOfLadingsIssued=false`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailWithPattern' + required: + - partyName + - typeOfPerson + + BuyerHBL: + type: object + title: Buyer (House B/L) + description: | + The buyer is the last known entity to whom the goods are sold or agreed to be sold. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided. + + **Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) and `manifestTypeCode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + required: + - partyName + - typeOfPerson + + Party: + type: object + title: Party + description: | + Refers to a company or a legal entity. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Party`. + example: HHL007 + required: + - partyName + + PartyHBL: + type: object + title: Party (House B/L) + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/Address' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetailHBL' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Party`. + example: HHL007 + required: + - partyName + + IssuingParty: + type: object + title: Issuing Party + description: | + The company or a legal entity issuing the `Transport Document`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - address + + ShippingInstructionsRequestor: + type: object + title: Shipping Instructions Requestor + description: | + The requestor of whoever submits the `Shipping Instructions`. + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + + PartyContactDetail: + type: object + title: Party Contact Detail + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + + PartyContactDetailHBL: + type: object + title: Party Contact Detail (House B/L) + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\+(?:[0-9] ?){6,14}[0-9]$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + + PartyContactDetailWithPattern: + type: object + title: Party Contact Detail (with phone pattern) + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\+(?:[0-9] ?){6,14}[0-9]$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + + IdentifyingCode: + type: object + title: Identifying Code + description: | + A code and value that uniquely identifies a party. + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `GSBN` (Global Shipping Business Network) + - `WISE` (WiseTech) + - `GLEIF` (Global Legal Entity Identifier Foundation) + - `W3C` (World Wide Web Consortium) + - `DNB` (Dun and Bradstreet) + - `FMC` (Federal Maritime Commission) + - `DCSA` (Digital Container Shipping Association) + - `ZZZ` (Mutually defined) + example: W3C + partyCode: + type: string + maxLength: 150 + description: | + Code to identify the party as provided by the code list provider + example: MSK + codeListName: + type: string + maxLength: 100 + description: | + The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be: + - `DID` (Decentralized Identifier) for `codeListProvider` `W3C` + - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF` + - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB` + example: DID + required: + - codeListProvider + - partyCode + TaxLegalReference: + type: object + title: Tax & Legal Reference + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |EORI|NL|Economic Operators Registration and Identification| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: IN + value: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + required: + - type + - countryCode + - value + + ########### + # Reference + ########### + Reference: + type: object + title: Reference + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer’s Reference) + - `AKG` (Vehicle Identification Number) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + ReferenceConsignmentItem: + type: object + title: Reference (Consignment Item) + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer’s Reference) + - `AKG` (Vehicle Identification Number) + - `SPO` (Shipper's Purchase Order) + - `CPO` (Consignee's Purchase Order) + example: CR + values: + type: array + minItems: 1 + description: | + List of `referenceValues` for a given `referenceType`. + items: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - values + + ################## + # Consignment Item + ################## + ConsignmentItem: + type: object + title: Consignment Item + description: | + Defines a list of `CargoItems` belonging together and the associated `Booking`. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems` + properties: + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The associated booking number provided by the carrier for this `Consignment Item`. + example: ABC709951 + descriptionOfGoods: + type: array + description: | + A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + maxItems: 150 + items: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: A line describing the cargo + example: blue shoes size 47 + HSCodes: + type: array + minItems: 1 + description: | + A list of `HS Codes` that apply to this `consignmentItem` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `consignmentItem` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + cargoItems: + type: array + minItems: 1 + description: | + A list of all `cargoItems` + items: + $ref: '#/components/schemas/CargoItem' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceConsignmentItem' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - carrierBookingReference + - descriptionOfGoods + - HSCodes + - cargoItems + ConsignmentItemShipper: + type: object + title: Consignment Item (Shipper) + description: | + Defines a list of `CargoItems` belonging together and the associated `Booking`. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems` + properties: + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The associated booking number provided by the carrier for this `Consignment Item`. + example: ABC709951 + commoditySubReference: + type: string + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + description: | + A unique reference to the commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link this consignment item to the commodity. A commodity reference is only unique in the context of a booking. + example: COM-001 + descriptionOfGoods: + type: array + description: | + A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + maxItems: 150 + items: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: A line describing the cargo + example: blue shoes size 47 + HSCodes: + type: array + minItems: 1 + description: | + A list of `HS Codes` that apply to this `consignmentItem` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `consignmentItem` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + cargoItems: + type: array + minItems: 1 + description: | + A list of all `cargoItems` + items: + $ref: '#/components/schemas/CargoItemShipper' + exportLicense: + $ref: '#/components/schemas/ExportLicenseShipper' + importLicense: + $ref: '#/components/schemas/ImportLicenseShipper' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceConsignmentItem' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - carrierBookingReference + - descriptionOfGoods + - HSCodes + - cargoItems + + ConsignmentItemHBL: + type: object + title: Consignment Item (House B/L) + description: | + Defines a list of `CargoItems` belonging together in the same consignment. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems` + properties: + descriptionOfGoods: + type: string + maxLength: 512 + pattern: ^\S(?:.*\S)?$ + description: | + A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted. Where the declarant provides the CUS code for chemical substances and preparations, Member States may waive the requirement of providing a precise description of the goods. + example: blue shoes size 47 + nationalCommodityCode: + $ref: '#/components/schemas/NationalCommodityCode' + cargoItems: + type: array + minItems: 1 + description: | + A list of all `cargoItems` + items: + $ref: '#/components/schemas/CargoItemHBL' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - descriptionOfGoods + - cargoItems + - nationalCommodityCode + + ######################### + # National Commodity Code + ######################### + NationalCommodityCode: + type: object + title: National Commodity Code + description: | + The national commodity classification code linked to a country with a value. + + An example could look like this: + + | Type | Country | Value | + |-------|:-------:|-------------| + |NCM|BR|['1515', '2106', '2507', '2512']| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The national commodity classification code, which can be one of the following values defined by DCSA: + - `NCM` (Nomenclatura Comum do Mercosul) + - `HTS` (Harmonized Tariff Schedule) + - `SCHEDULE_B` ( Schedule B) + - `TARIC` (Integrated Tariff of the European Communities) + - `CN` (Combined Nomenclature) + - `CUS` (Customs Union and Statistics) + example: NCM + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: BR + values: + type: array + minItems: 1 + description: | + A list of `national commodity codes` values. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The value of the `National Commodity Code` + example: '1515' + example: + - '1515' + - '2106' + - '2507' + - '2512' + example: + type: TARIC + values: + - '85171200' + required: + - type + - values + + ################## + # Customs Reference + ################## + CustomsReference: + type: object + title: Customs Reference + description: | + Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |UCR|NL|Unique Consignment Reference| + |CUS|NL|Customs Union and Statistics| + |ACID|EG|Advance Cargo Information Declaration in Egypt| + |CERS|CA|Canadian Export Reporting System| + |ITN|US|Internal Transaction Number in US| + |PEB|ID|PEB reference number| + |CSN|IN|Cargo Summary Notification (CSN)| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined in the relevant customs jurisdiction. + example: CUS + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + values: + type: array + minItems: 1 + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `customsReference` + example: '4988470982020120017' + required: + - type + - countryCode + - values + + ############ + # Cargo Item + ############ + CargoItem: + type: object + title: Cargo Item + description: | + A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `cargoItem` + items: + $ref: '#/components/schemas/NationalCommodityCode' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - equipmentReference + - cargoGrossWeight + - outerPackaging + + CargoItemShipper: + type: object + title: Cargo Item (Shipper) + description: | + A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicenseShipper' + importLicense: + $ref: '#/components/schemas/ImportLicenseShipper' + outerPackaging: + $ref: '#/components/schemas/OuterPackagingShipper' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `cargoItem` + items: + $ref: '#/components/schemas/NationalCommodityCode' + houseBillOfLadingReference: + type: string + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + description: | + Link to the House Bill of Lading this cargoItem is connected to. + example: ABC123 + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - equipmentReference + - cargoGrossWeight + + CargoItemHBL: + type: object + title: Cargo Item (House B/L) + description: | + A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + outerPackaging: + $ref: '#/components/schemas/OuterPackagingHBL' + required: + - equipmentReference + - cargoGrossWeight + - outerPackaging + + CargoGrossWeight: + type: object + title: Cargo Gross Weight + description: | + The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided. + example: 2400 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + CargoGrossVolume: + type: object + title: Cargo Gross Volume + description: | + Calculated by multiplying the width, height, and length of the packed cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + CargoNetWeight: + type: object + title: Cargo Net Weight + description: | + The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided. + example: 2400 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + CargoNetVolume: + type: object + title: Cargo Net Volume + description: | + Calculated by multiplying the width, height, and length of the cargo, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Calculated by multiplying the width, height, and length of the cargo, excluding packaging. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + ################ + # Outerpackaging + ################ + # Object used for the POST Shipping Instructions - here it is **not** possible to modify DG attributes + # Compared to the outerPackaging of the Booking - this object also contains the `packageCode` + OuterPackagingShipper: + type: object + title: Outer Packaging (Shipper) + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + + **Condition:** Mandatory for non-dangerous goods cargo. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + + **Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available. + example: 5H + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Cargo Item`. + example: 18 + description: + type: string + maxLength: 100 + description: | + Description of the outer packaging/overpack. + example: 'Drum, steel' + woodDeclaration: + type: string + maxLength: 30 + description: | + Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include: + - `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped) + - `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate) + - `PROCESSED` (if the wood or wooden materials are entirely made of processed wood, such as plywood, particle board, sliver plates of wood and wood laminate sheets produced using glue, heat, pressure or a combination of these) + - `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate) + example: TREATED_AND_CERTIFIED + required: + - numberOfPackages + - description + OuterPackaging: + type: object + title: Outer Packaging + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + + **Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available. + example: 5H + imoPackagingCode: + type: string + pattern: ^[A-Z0-9]{1,5}$ + minLength: 1 + maxLength: 5 + description: | + The code of the packaging as per IMO. + + **Condition:** only applicable to dangerous goods if specified in the [IMO IMDG code](https://www.imo.org/en/publications/Pages/IMDG%20Code.aspx). If not available, the `packageCode` as per UN recommendation 21 should be used. + example: 1A2 + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Cargo Item`. + example: 18 + description: + type: string + maxLength: 100 + description: | + Description of the outer packaging/overpack. + example: 'Drum, steel' + woodDeclaration: + type: string + maxLength: 30 + description: | + Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include: + - `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped) + - `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate) + - `PROCESSED` (if the wood or wooden materials are entirely made of processed wood, such as plywood, particle board, sliver plates of wood and wood laminate sheets produced using glue, heat, pressure or a combination of these) + - `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate) + example: TREATED_AND_CERTIFIED + dangerousGoods: + type: array + description: | + A list of `Dangerous Goods` + items: + $ref: '#/components/schemas/DangerousGoods' + required: + - numberOfPackages + - description + + OuterPackagingHBL: + type: object + title: Outer Packaging (House B/L) + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + example: 5H + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Cargo Item`. + + **Condition:** Mandatory if `packageCode` is **NOT** one of the following values: + + - `VY` (Bulk, solid, fine particles ("powders")) + - `VS` (Bulk, scrap metal) + - `VR` (Bulk, solid, granular particles ("grains")) + - `VQ` (Bulk, liquefied gas (at abnormal temperature/pressure)) + - `VO` (Bulk, solid, large particles ("nodules")) + - `VL` (Bulk, liquid) + - `NG` (Unpacked or unpackaged, multiple units) + - `NF` (Unpacked or unpackaged, single unit) + - `NE` (Unpacked or unpackaged) + - `VG` (Bulk, gas (at 1031 mbar and 15°C)) + example: 18 + shippingMarks: + type: string + maxLength: 512 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + UNNumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG. + example: '1463' + required: + - packageCode + + ################# + # Dangerous Goods + ################# + DangerousGoods: + type: object + title: Dangerous Goods + description: | + Specification for `Dangerous Goods`. It is mandatory to provide one of `UNNumber` or `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**. + oneOf: + - type: object + title: UN Number + properties: + UNNumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG. + example: '1463' + required: + - UNNumber + - type: object + title: NA Number + properties: + NANumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation. + example: '9037' + required: + - NANumber + properties: + codedVariantList: + type: string + pattern: ^[0-3][0-9A-Z]{3}$ + minLength: 4 + maxLength: 4 + description: | + Four-character code supplied by Exis Technologies that assists to remove ambiguities when identifying a variant within a single UN number or NA number that may occur when two companies exchange DG information. + + Character | Valid Characters | Description + :--------:|------------------|------------ + 1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group + 2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs + 3 and 4|0 to 9 and A to Z|Two sequence letters for other information, for the cases where the variant is required because of different in subrisks, packing instruction etc. + example: '2200' + properShippingName: + type: string + maxLength: 250 + description: | + The proper shipping name for goods under IMDG Code, or the product name for goods under IBC Code and IGC Code, or the bulk cargo shipping name for goods under IMSBC Code, or the name of oil for goods under Annex I to the MARPOL Convention. + example: 'Chromium Trioxide, anhydrous' + technicalName: + type: string + maxLength: 250 + description: | + The recognized chemical or biological name or other name currently used for the referenced dangerous goods as described in chapter 3.1.2.8 of the IMDG Code. + example: 'xylene and benzene' + imoClass: + type: string + maxLength: 4 + description: | + The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are: + + - `1.1A` (Substances and articles which have a mass explosion hazard) + - `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard) + - `2.1` (Flammable gases) + - `8` (Corrosive substances) + example: 1.4S + subsidiaryRisk1: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + subsidiaryRisk2: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + isMarinePollutant: + type: boolean + description: | + Indicates if the goods belong to the classification of Marine Pollutant. + example: false + packingGroup: + type: integer + format: int32 + minimum: 1 + maximum: 3 + description: | + The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code. + example: 3 + isLimitedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code. + example: false + isExceptedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code. + example: false + isSalvagePackings: + type: boolean + description: | + Indicates if the cargo has special packaging for the transport, recovery or disposal of damaged, defective, leaking or nonconforming hazardous materials packages, or hazardous materials that have spilled or leaked. + example: false + isEmptyUncleanedResidue: + type: boolean + description: | + Indicates if the cargo is residue. + example: false + isWaste: + type: boolean + description: | + Indicates if waste is being shipped + example: false + isHot: + type: boolean + description: | + Indicates if high temperature cargo is shipped. + example: false + isCompetentAuthorityApprovalRequired: + type: boolean + description: | + Indicates if the cargo require approval from authorities + example: false + competentAuthorityApproval: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name and reference number of the competent authority providing the approval. + example: '{Name and reference...}' + segregationGroups: + type: array + description: | + List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code. + + **Condition:** only applicable to specific hazardous goods. + items: + type: string + maxLength: 2 + description: | + Grouping of Dangerous Goods having certain similar chemical properties. Possible values are: + + - `1` (Acids) + - `2` (Ammonium Compounds) + - `3` (Bromates) + - `4` (Chlorates) + - `5` (Chlorites) + - `6` (Cyanides) + - `7` (Heavy metals and their salts) + - `8` (Hypochlorites) + - `9` (Lead and its compounds) + - `10` (Liquid halogenated hydrocarbons) + - `11` (Mercury and mercury compounds) + - `12` (Nitrites and their mixtures) + - `13` (Perchlorates) + - `14` (Permanganates) + - `15` (Powdered metals) + - `16` (Peroxides), + - `17` (Azides) + - `18` (Alkalis) + example: '12' + innerPackagings: + type: array + description: | + A list of `Inner Packings` contained inside this `outer packaging/overpack`. + items: + $ref: '#/components/schemas/InnerPackaging' + emergencyContactDetails: + $ref: '#/components/schemas/EmergencyContactDetails' + EMSNumber: + type: string + maxLength: 7 + description: | + The emergency schedule identified in the IMO EmS Guide – Emergency Response Procedures for Ships Carrying Dangerous Goods. Comprises 2 values; 1 for spillage and 1 for fire. Possible values spillage: S-A to S-Z. Possible values fire: F-A to F-Z. + example: F-A S-Q + endOfHoldingTime: + type: string + format: date + description: | + Date by when the refrigerated liquid needs to be delivered. + example: '2021-09-03' + fumigationDateTime: + type: string + format: date-time + description: | + Date & time when the container was fumigated + example: '2024-09-04T09:41:00Z' + isReportableQuantity: + type: boolean + description: | + Indicates if a container of hazardous material is at the reportable quantity level. If `true`, a report to the relevant authority must be made in case of spill. + example: false + inhalationZone: + type: string + maxLength: 1 + minLength: 1 + description: | + The zone classification of the toxicity of the inhalant. Possible values are: + + - `A` (Hazard Zone A) can be assigned to specific gases and liquids + - `B` (Hazard Zone B) can be assigned to specific gases and liquids + - `C` (Hazard Zone C) can **only** be assigned to specific gases + - `D` (Hazard Zone D) can **only** be assigned to specific gases + example: A + grossWeight: + $ref: '#/components/schemas/GrossWeight' + netWeight: + $ref: '#/components/schemas/NetWeight' + netExplosiveContent: + $ref: '#/components/schemas/NetExplosiveContent' + netVolume: + $ref: '#/components/schemas/NetVolume' + limits: + $ref: '#/components/schemas/Limits' + required: + - properShippingName + - imoClass + GrossWeight: + type: object + title: Gross Weight + description: | + Total weight of the goods carried, including packaging. + properties: + value: + type: number + format: float + example: 12000.3 + minimum: 0 + exclusiveMinimum: true + description: | + The grand total weight of the DG cargo and weight per `UNNumber`/`NANumber` including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetWeight: + type: object + title: Net Weight + description: | + Total weight of the goods carried, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Total weight of the goods carried, excluding packaging. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetExplosiveContent: + type: object + title: Net Explosive Content + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + - `GRM` (Grams) + - `ONZ` (Ounce) + enum: + - KGM + - LBR + - GRM + - ONZ + example: KGM + required: + - value + - unit + NetVolume: + type: object + title: Net Volume + description: | + The volume of the referenced dangerous goods. + + **Condition:** only applicable to liquids and gas. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The volume of the referenced dangerous goods. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + - `LTR` (Litre) + enum: + - MTQ + - FTQ + - LTR + example: MTQ + required: + - value + - unit + InnerPackaging: + type: object + title: Inner Packaging + description: | + Object for inner packaging specification + properties: + quantity: + type: integer + format: int32 + description: | + Count of `Inner Packagings` of the referenced `Dangerous Goods`. + example: 20 + material: + type: string + maxLength: 100 + description: | + The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`. + example: Plastic + description: + type: string + maxLength: 100 + description: | + Description of the packaging. + example: Woven plastic water resistant Bag + required: + - quantity + - material + - description + EmergencyContactDetails: + type: object + title: Emergency Contact Details + description: | + 24 hr emergency contact details + properties: + contact: + type: string + maxLength: 255 + description: | + Name of the Contact person during an emergency. + example: Henrik Larsen + provider: + type: string + maxLength: 255 + description: | + Name of the third party vendor providing emergency support + example: GlobeTeam + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + referenceNumber: + type: string + maxLength: 255 + description: | + Contract reference for the emergency support provided by an external third party vendor. + example: '12234' + required: + - contact + - phone + Limits: + type: object + title: Limits + description: | + Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure. + properties: + temperatureUnit: + type: string + description: | + The unit for **all attributes in the limits structure** in Celsius or Fahrenheit + + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + enum: + - CEL + - FAH + example: CEL + flashPoint: + type: number + format: float + description: | + Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air. + + **Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code. + example: 42 + transportControlTemperature: + type: number + format: float + description: | + Maximum temperature at which certain substance (such as organic peroxides and self-reactive and related substances) can be safely transported for a prolonged period. + example: 24.1 + transportEmergencyTemperature: + type: number + format: float + description: | + Temperature at which emergency procedures shall be implemented + example: 74.1 + SADT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating decomposition may occur in a substance + example: 54.1 + SAPT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating polymerization may occur in a substance + example: 70 + required: + - temperatureUnit + + ############################## + # Utilized Transport Equipment + ############################## + # Calculated fields have been removed + UtilizedTransportEquipment: + type: object + title: Utilized Transport Equipment + description: | + Specifies the container (`equipment`), the total `weight`, total `volume`, possible `ActiveReeferSettings`, `seals` and `references` + properties: + equipment: + $ref: '#/components/schemas/Equipment' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (SOC). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + seals: + type: array + minItems: 1 + description: | + A list of `Seals` + items: + $ref: '#/components/schemas/Seal' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - equipment + - isShipperOwned + - seals + UtilizedTransportEquipmentShipper: + type: object + title: Utilized Transport Equipment (Shipper) + description: | + Specifies the container (`Equipment`), `Seals` and `References` + properties: + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + seals: + type: array + minItems: 1 + description: | + A list of `Seals` + items: + $ref: '#/components/schemas/Seal' + emptyIndicatorCode: + type: string + description: | + Indication if the container is `EMPTY` or `LADEN`. + + - `EMPTY` (Empty) + - `LADEN` (Laden) + enum: + - LADEN + - EMPTY + example: LADEN + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + oneOf: + - $ref: '#/components/schemas/UTEquipment' + - $ref: '#/components/schemas/UTEquipmentReference' + discriminator: + propertyName: isShipperOwned + mapping: + 'true': '#/components/schemas/UTEquipment' + 'false': '#/components/schemas/UTEquipmentReference' + required: + - seals + + UtilizedTransportEquipmentHBL: + type: object + title: Utilized Transport Equipment (House B/L) + description: | + Specifies the container (`Equipment`), `Seals` and `References` + properties: + seals: + type: array + minItems: 1 + description: | + A list of `Seals` + items: + $ref: '#/components/schemas/Seal' + emptyIndicatorCode: + type: string + description: | + Indication if the container is `EMPTY` or `LADEN`. + + - `EMPTY` (Empty) + - `LADEN` (Laden) + enum: + - LADEN + - EMPTY + example: LADEN + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (SOC). + example: false + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + required: + - emptyIndicatorCode + - isShipperOwned + - equipmentReference + - ISOEquipmentCode + + UTEquipment: + type: object + title: Shipper Owned Equipment (SoC) + description: | + To be used for SoC (Shipper owned Containers). If `isShipperOwned` is true then the equipment used needs to be specified + properties: + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (SOC). + example: true + equipment: + $ref: '#/components/schemas/RequiredEquipment' + required: + - isShipperOwned + - equipment + UTEquipmentReference: + type: object + title: Carrier Owned Equipment + description: | + To be used when referring to carrier owned containers (`isShipperOwned` is false). In this case it is only necessary to provide `equipmentReference` + properties: + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (SOC). + example: false + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + required: + - isShipperOwned + - equipmentReference + + ########### + # Equipment + ########### + Equipment: + type: object + title: Equipment + description: | + Used for storing cargo in/on during transport. The equipment size/type is defined by the ISO 6346 code. The most common equipment size/type is 20'/40'/45' DRY Freight Container, but several different versions exist. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + tareWeight: + $ref: '#/components/schemas/TareWeight' + required: + - equipmentReference + + TareWeight: + type: object + title: Tare Weight + description: | + The weight of an empty container (gross container weight). + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of an empty container (gross container weight). + example: 4800 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + RequiredEquipment: + type: object + title: Equipment (Required Properties) + description: | + Used for storing cargo in/on during transport. The equipment size/type is defined by the ISO 6346 code. The most common equipment size/type is 20'/40'/45' DRY Freight Container, but several different versions exist. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + tareWeight: + $ref: '#/components/schemas/TareWeight' + required: + - equipmentReference + - ISOEquipmentCode + - tareWeight + + ###### + # Seal + ###### + Seal: + type: object + title: Seal + description: | + Addresses the seal-related information associated with the shipment equipment. A seal is put on a shipment equipment once it is loaded. This `Seal` is meant to stay on until the shipment equipment reaches its final destination. + properties: + number: + type: string + maxLength: 15 + description: 'Identifies a seal affixed to the container.' + example: VET123 + source: + type: string + description: | + The source of the seal, namely who has affixed the seal. + - `CAR` (Carrier) + - `SHI` (Shipper) + - `VET` (Veterinary) + - `CUS` (Customs) + + **Condition:** Seal source may be required depending on the type of commodity being shipped. + enum: + - CAR + - SHI + - VET + - CUS + example: 'CUS' + required: + - number + + ######################## + # Active Reefer Settings + ######################## + ActiveReeferSettings: + type: object + title: Active Reefer Settings + description: | + The specifications for a Reefer equipment. + + **Condition:** Only applicable when `isNonOperatingReefer` is set to `false` + properties: + temperatureSetpoint: + type: number + format: float + description: | + Target value of the temperature for the Reefer based on the cargo requirement. + example: -15 + temperatureUnit: + type: string + description: | + The unit for temperature in Celsius or Fahrenheit + + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + + **Condition:** Mandatory if `temperatureSetpoint` is provided. If `temperatureSetpoint` is not provided, this field must be empty. + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere O2 target value + example: 25 + co2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 target value + example: 25 + humiditySetpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere humidity target value + example: 95.6 + airExchangeSetpoint: + type: number + format: float + minimum: 0 + description: | + Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container + example: 15.4 + airExchangeUnit: + type: string + description: | + The unit for `airExchange` in metrics- or imperial- units per hour + - `MQH` (Cubic metre per hour) + - `FQH` (Cubic foot per hour) + + **Condition:** Mandatory if `airExchange` is provided. If `airExchange` is not provided, this field must be empty. + enum: + - MQH + - FQH + example: MQH + isVentilationOpen: + type: boolean + description: | + If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed` + example: true + isDrainholesOpen: + type: boolean + description: | + Is drain holes open on the container + example: true + isBulbMode: + type: boolean + description: | + Is special container setting for handling flower bulbs active + example: true + isColdTreatmentRequired: + type: boolean + description: | + Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD + example: true + isControlledAtmosphereRequired: + type: boolean + description: | + Indicator of whether cargo requires Controlled Atmosphere. + example: true + + ########################## + # Advance Manifest Filings + ########################## + + AdvanceManifestFiling: + type: object + title: Advance Manifest Filing + description: | + An Advance Manifest Filing defined by a Manifest type code in combination with a country code. + + A small list of **potential** examples: + + | manifestTypeCode | countryCode | Description | + |-----------------------|:-------------:|-------------| + |ACI|EG|Advance Cargo Information in Egypt| + |ACE|US|Automated Commercial Environment in the United States| + |AFR|JP|Cargo Summary Notification (CSN)| + |ENS|NL|Entry Summary Declaration| + properties: + manifestTypeCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The Manifest type code as defined by the provider. + example: ENS + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + advanceManifestFilingsHouseBLPerformedBy: + type: string + description: | + Indicates whether the shipper (`SELF`) will perform the advance manifest filing(s) for the House BL directly or if the carrier (`CARRIER`) should file them on their behalf. Allowed values are: + + - `SELF` (filing done by the House filer) + - `CARRIER` (the carrier does the filing) + + In case of self-filing (`SELF`), the shipper can provide their `selfFilerCode` for each manifest. + + **Condition:** The `selfFilerCode` must be provided when `manifestTypeCode` is one of `ACE` (US) or `ACI` (CA) and the `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`. + enum: + - SELF + - CARRIER + example: SELF + selfFilerCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Code identifying the party who will submit the advance manifest filing(s) for the House BL. + + **Mandatory** if `manifestTypeCode` is one of `ACE` (US) or `ACI` (CA) and `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`. + example: FLXP + identificationNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 17 + description: | + An identification number of the house filer responsible for submitting the `Advance Manifest Filing`. + + **Condition:** Mandatory if `manifestTypeCode` is `ENS` and `advanceManifestFilingsHouseBLPerformedBy` is `SELF`. + example: 'FLXP-123321' + example: + manifestTypeCode: ENS + advanceManifestFilingsHouseBLPerformedBy: SELF + selfFilerCode: FLXP123 + identificationNumber: NL123456712 + required: + - manifestTypeCode + - advanceManifestFilingsHouseBLPerformedBy + + ###################### + # House Bill of Lading + ###################### + + HouseBillOfLading: + type: object + title: House Bill of Lading + description: | + A legal contract between the Ocean Transport Intermediary (OTI), such as a Non-Vessel Operating Common Carrier (NVOCC) or a freight forwarder, and the shipper that acknowledges the receipt of goods and outlines the terms of shipment. + properties: + houseBillOfLadingReference: + type: string + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + description: | + A unique number allocated by the Ocean Transport Intermediary (OTI) to the `House Bill of Lading`. + example: HBOL001 + isToOrder: + type: boolean + description: | + Indicates whether the `House Bill of Lading` (HBL) is issued `to order` or not. If `true`, `Notify party` at `HBL` level is mandatory + example: false + placeOfAcceptance: + $ref: '#/components/schemas/PlaceOfAcceptance' + placeOfFinalDelivery: + $ref: '#/components/schemas/PlaceOfFinalDelivery' + methodOfPayment: + type: string + maxLength: 1 + description: | + Method used for the payment of freight charges. It can be one of the following values: + - `A` (Payment in cash) + - `B` (Payment by credit card) + - `C` (Payment by cheque) + - `D` (Other (e.g. direct debit to cash account)) + - `H` (Electronic funds transfer) + - `Y` (Account holder with carrier) + - `Z` (Not pre-paid) + example: A + documentParties: + $ref: '#/components/schemas/DocumentPartiesHouseBL' + isCargoDeliveredInICS2Zone: + type: boolean + description: | + Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland. + example: true + routingOfConsignmentCountries: + type: array + minItems: 1 + description: | + Identification in a chronological order of the countries through which the goods are routed between the country of original departure and final destination as stipulated in the lowest House Bill of Lading. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + + **Condition:** If provided - the first country in the list must be the country of `Place of Acceptance`; the last country in the list must be the country of `Place of Final Delivery`. + items: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: NL + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` for this `House Bill of Lading` + items: + $ref: '#/components/schemas/ConsignmentItemHBL' + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipment` for this `House Bill of Lading` + items: + $ref: '#/components/schemas/UtilizedTransportEquipmentHBL' + required: + - houseBillOfLadingReference + - isToOrder + - methodOfPayment + - documentParties + - isCargoDeliveredInICS2Zone + - routingOfConsignmentCountries + - consignmentItems + - utilizedTransportEquipments + + PlaceOfAcceptance: + type: object + title: Place of Acceptance + description: | + An object to capture `Place of Acceptance` location specified as: identification of the seaport, freight terminal or other place at which the goods are taken over from the shipper by the Ocean Transport Intermediary (OTI) issuing the `House Bill of Lading`. + + **Condition:** Mandatory if different from `Place of Receipt` or `Port of Loading` at the `Master Transport Document` level. + + **Condition:** The location can be specified either using `UN Location Code` and/or (`Location Name` together with `Country Code`), all three properties can be specified. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the location. + + **Condition:** Mandatory to provide in case `UN Location Code` is not provided + example: Port of Amsterdam + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Condition:** Mandatory to provide in case `UN Location Code` is not provided + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + PlaceOfFinalDelivery: + type: object + title: Place of Final Delivery + description: | + An object to capture `Place of Final Delivery` location specified as: Identification of the seaport, freight terminal or other place at which the goods are handed over from the `Ocean Transport Intermediary` (OTI) issuing the `House Bill of Lading` to the `Consignee`. + + **Condition:** Mandatory if different from `Place of Delivery` at the `Master Transport Document` level. + + **Condition:** The location can be specified either using `UN Location Code` and/or (`Location Name` together with `Country Code`), all three properties can be specified. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the location. + + **Condition:** Mandatory to provide in case `UN Location Code` is not provided + example: Port of Amsterdam + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Condition:** Mandatory to provide in case `UN Location Code` is not provided + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + #################### + # Transport Document + #################### + TransportDocument: + type: object + title: Transport Document + description: | + The document that governs the terms of carriage between shipper and carrier for maritime transportation. Two distinct types of transport documents exist: + - Bill of Lading + - Sea Waybill. + properties: + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentStatus: + type: string + maxLength: 50 + description: | + The status of the `Transport Document`. Possible values are: + - `DRAFT` (the Transport Document is currently a Draft) + - `APPROVED` (the Transport Document has been Approved by consumer) + - `ISSUED` (the Transport Document has been Issued by provider) + - `PENDING_SURRENDER_FOR_AMENDMENT` (the Transport Document has a pending Surrender for Amendment) + - `SURRENDERED_FOR_AMENDMENT` (the Transport Document is Surrendered for Amendment) + - `PENDING_SURRENDER_FOR_DELIVERY` (the Transport Document has a pending Surrender for Delivery) + - `SURRENDERED_FOR_DELIVERY` (the Transport Document is Surrendered for Delivery) + - `VOIDED` (the Transport Document has been Voided) + example: DRAFT + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the transport document + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + isShippedOnBoardType: + type: boolean + description: | + Specifies whether the Transport Document is a received for shipment, or shipped on board. + example: true + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + isElectronic: + type: boolean + description: | + An indicator whether the transport document is electronically transferred. + example: true + isToOrder: + type: boolean + description: | + Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`). + + `isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill). + example: false + numberOfCopiesWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`| + example: 2 + numberOfCopiesWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`| + example: 2 + numberOfOriginalsWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer with charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + numberOfOriginalsWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer without charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + displayedNameForPlaceOfReceipt: + description: | + The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfLoad: + description: | + The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfDischarge: + description: | + The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPlaceOfDelivery: + description: | + The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + shippedOnBoardDate: + type: string + format: date + description: | + Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document. + + When provided on a transport document, the transportDocument is a `Shipped On Board` B/L. + + Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' + displayedShippedOnBoardReceivedForShipment: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 250 + description: | + The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board. + example: 'Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier' + termsAndConditions: + type: string + maxLength: 50000 + description: | + Carrier terms and conditions of transport. + example: Any reference in... + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + issueDate: + type: string + format: date + description: | + Local date when the transport document has been issued. + + Can be omitted on draft transport documents, but must be provided when the document has been issued. + example: '2020-12-12' + receivedForShipmentDate: + type: string + format: date + description: | + Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel). + + When provided on a transport document, the transportDocument is a `Received For Shipment` B/L. + + Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + example: HHL51800000 + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + example: HHL1401 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + + **Condition:** Included in the transport document upon customer request. If customers want the value to show, evidence is required, and customers need to approve additional insurance fee charge from the carrier (very exceptional). + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided. If `declaredValue` is not provided, this field must be empty. + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the issuing carrier of the `Transport Document`. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + carrierClauses: + type: array + description: | + Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20000 + description: | + The content of the clause. + example: It is not allowed to... + numberOfRiderPages: + type: integer + format: int32 + minimum: 0 + description: | + The number of additional pages required to contain the goods description on a transport document. Only applicable for physical transport documents. + example: 2 + transports: + $ref: '#/components/schemas/Transports' + charges: + type: array + description: | + A list of `Charges` + items: + $ref: '#/components/schemas/Charge' + # New values compared to SI - END + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + partyContactDetails: + type: array + minItems: 1 + description: | + The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + documentParties: + $ref: '#/components/schemas/DocumentParties' + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` + items: + $ref: '#/components/schemas/ConsignmentItem' + # Includes calculated fields! + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipments` describing the equipment being used. + items: + $ref: '#/components/schemas/UtilizedTransportEquipment' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + required: + - transportDocumentReference + - transportDocumentStatus + - transportDocumentTypeCode + - isShippedOnBoardType + - isElectronic + - isToOrder + - invoicePayableAt + - partyContactDetails + - documentParties + - consignmentItems + - utilizedTransportEquipments + - termsAndConditions + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - carrierCode + - carrierCodeListProvider + - transports + + ############ + # Transports + ############ + Transports: + type: object + title: Transports + description: | + This object consolidates information related to dates, origin and destination points, pre- and on-carriage mode of transport and vessel details. + properties: + plannedArrivalDate: + type: string + format: date + description: | + The planned date of arrival. + example: '2024-06-07' + plannedDepartureDate: + type: string + format: date + description: | + The planned date of departure. + example: '2024-06-03' + preCarriageBy: + type: string + maxLength: 50 + description: | + Mode of transportation for pre-carriage when transport to the port of loading is organized by the carrier. If this attributes is populated, then a Place of Receipt must also be defined. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: RAIL + onCarriageBy: + type: string + maxLength: 50 + description: | + Mode of transportation for on-carriage when transport from the port of discharge is organized by the carrier. If this attributes is populated, then a Place of Delivery must also be defined. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: TRUCK + placeOfReceipt: + $ref: '#/components/schemas/PlaceOfReceipt' + portOfLoading: + $ref: '#/components/schemas/PortOfLoading' + portOfDischarge: + $ref: '#/components/schemas/PortOfDischarge' + placeOfDelivery: + $ref: '#/components/schemas/PlaceOfDelivery' + onwardInlandRouting: + $ref: '#/components/schemas/OnwardInlandRouting' + vesselVoyages: + type: array + minItems: 1 + description: | + Allow the possibility to include multiple vessels/voyages in the `Transport Document` (e.g. the first sea going vessel and the mother vessel). At least one is mandatory to provide. + items: + $ref: '#/components/schemas/VesselVoyage' + required: + - plannedArrivalDate + - plannedDepartureDate + - portOfLoading + - portOfDischarge + - vesselVoyages + + VesselVoyage: + type: object + title: Vessel/Voyage + description: 'Vessel and export voyage' + properties: + vesselName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the first sea going Vessel on board which the cargo is loaded or intended to be loaded + example: King of the Seas + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + required: + - vesselName + - carrierExportVoyageNumber + PlaceOfReceipt: + type: object + title: Place of Receipt + description: | + An object to capture `Place of Receipt` location specified as: the location where the cargo is handed over by the shipper, or his agent, to the shipping line. This indicates the point at which the shipping line takes on responsibility for carriage of the container. + + **Condition:** Only when pre-carriage is done by the carrier. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` or a `Geo Coordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + PortOfLoading: + type: object + title: Port of Loading + description: | + An object to capture `Port of Loading` location specified as: the location where the cargo is loaded onto a first sea-going vessel for water transportation. + + The location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `UN Location Code` and as a `City and Country`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + city: + $ref: '#/components/schemas/City' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + PortOfDischarge: + type: object + title: Port of Discharge + description: | + An object to capture `Port of Discharge` location specified as: the location where the cargo is discharged from the last sea-going vessel. + + The location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `UN Location Code` and as a `City and Country`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + city: + $ref: '#/components/schemas/City' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + PlaceOfDelivery: + type: object + title: Place of Delivery + description: | + An object to capture `Place of Delivery` location specified as: the location where the cargo is handed over to the consignee, or his agent, by the shipping line and where responsibility of the shipping line ceases. + + **Condition:** Only when onward transport is done by the carrier + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` or a `Geo Coordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + OnwardInlandRouting: + type: object + title: Onward Inland Routing + description: | + An object to capture `Onward Inland Routing` location specified as the end location of the inland movement that takes place after the container(s) being delivered to the port of discharge/place of delivery for account and risk of merchant (merchant haulage). + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + ######## + # Charge + ######## + Charge: + type: object + title: Charge + description: | + Addresses the monetary value of freight and other service charges for a `Booking`. + properties: + chargeName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + Free text field describing the charge to apply + example: Documentation fee - Destination + currencyAmount: + type: number + format: float + minimum: 0 + description: | + The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals. + example: 1012.12 + currencyCode: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency for the charge, using a 3-character code ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)). + example: DKK + paymentTermCode: + type: string + description: | + An indicator of whether a charge is prepaid (PRE) or collect (COL). When prepaid, the charge is the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charge is the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + calculationBasis: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The code specifying the measure unit used for the corresponding unit price for this cost, such as per day, per ton, per square metre. + example: Per day + unitPrice: + type: number + format: float + minimum: 0 + description: | + The unit price of this charge item in the currency of the charge. + example: 3456.6 + quantity: + type: number + format: float + minimum: 0 + description: | + The amount of unit for this charge item. + example: 34.4 + required: + - chargeName + - currencyAmount + - currencyCode + - paymentTermCode + - calculationBasis + - unitPrice + - quantity + + ########################## + # OriginChargesPaymentTerm + ########################## + OriginChargesPaymentTerm: + type: object + title: Origin Charges Payment Term + description: | + An indicator of whether origin charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + enum: + - PRE + - COL + description: | + An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + + ################################## + # Destination Charges Payment Term + ################################## + DestinationChargesPaymentTerm: + type: object + title: Destination Charges Payment Term + description: | + An indicator of whether destination charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + enum: + - PRE + - COL + description: | + An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + + ################ + # Place of Issue + ################ + PlaceOfIssue: + type: object + title: Place of Issue + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + **Condition:** The location can be specified as one of `UN Location Code` or `CountryCode`, but not both. + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: |- + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + - type: object + title: Country Code + properties: + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - countryCode + + ############################################ + # Invoice Payable At (Shipping Instructions) + ############################################ + InvoicePayableAtShippingInstructions: + type: object + title: Invoice Payable At (Shipping Instructions) + description: | + Location where payment of ocean freight and charges for the main transport will take place by the customer. + + The location must be provided as a `UN Location Code` + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: |- + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + + #################### + # Invoice Payable At + #################### + InvoicePayableAt: + type: object + title: Invoice Payable At + description: | + Location where payment of ocean freight and charges for the main transport will take place by the customer. + + The location can be provided as a `UN Location Code` or as a fallback - a `freeText` field + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: |- + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + - type: object + title: Free text + properties: + freeText: + type: string + maxLength: 35 + description: | + The name of the location where payment will be rendered by the customer. + example: DCSA Headquarters + required: + - freeText + + ########################################## + # Document Parties (Shipping Instructions) + ########################################## + DocumentPartiesShippingInstructions: + type: object + title: Document Parties (Shipping Instructions) + description: | + All `Parties` with associated roles. + + **Condition:** `Buyer` and `Seller` are mandatory if `isCargoDeliveredInICS2Zone=true` **and** `advancedManifestFilingPerformedBy=CARRIER` and `isHouseBillOfLadingsIssued=false` + properties: + shipper: + $ref: '#/components/schemas/Shipper' + onBehalfOfShipper: + $ref: '#/components/schemas/OnBehalfOfShipper' + consignee: + $ref: '#/components/schemas/ConsigneeShipper' + onBehalfOfConsignee: + $ref: '#/components/schemas/OnBehalfOfConsignee' + endorsee: + $ref: '#/components/schemas/EndorseeShipper' + issueTo: + $ref: '#/components/schemas/IssueToParty' + seller: + $ref: '#/components/schemas/Seller' + buyer: + $ref: '#/components/schemas/Buyer' + notifyParties: + type: array + maxItems: 3 + description: | + List of up to 3 `Notify Parties`. The first item in the list is the **First Notify Party** (`N1`), the second item is the **Second Notify Party** (`N2`) and the last item is the **Other Notify Party** (`NI`). + + **Condition:** If provided: + - Mandatory for To Order BLs, `isToOrder=true` + - The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + $ref: '#/components/schemas/NotifyParty' + shippingInstructionsRequestor: + $ref: '#/components/schemas/ShippingInstructionsRequestor' + other: + type: array + description: A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`. + items: + $ref: '#/components/schemas/OtherDocumentPartyShippingInstructions' + required: + - shipper + + ############################ + # Document Parties House B/L + ############################ + DocumentPartiesHouseBL: + type: object + title: Document Parties (House B/L) + description: | + All `Parties` with associated roles for this `House Bill of Lading`. + + **Condition:** `Buyer` and `Seller` are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) **and** `advancedManifestFilingPerformedBy=CARRIER` + properties: + shipper: + $ref: '#/components/schemas/ShipperHBL' + consignee: + $ref: '#/components/schemas/ConsigneeHBL' + notifyParty: + $ref: '#/components/schemas/NotifyPartyHBL' + seller: + $ref: '#/components/schemas/SellerHBL' + buyer: + $ref: '#/components/schemas/BuyerHBL' + other: + type: array + description: A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`. + items: + $ref: '#/components/schemas/OtherDocumentPartyHBL' + required: + - shipper + + ################## + # Document Parties + ################## + DocumentParties: + type: object + title: Document Parties + description: | + All `Parties` with associated roles. + properties: + shipper: + $ref: '#/components/schemas/Shipper' + onBehalfOfShipper: + $ref: '#/components/schemas/OnBehalfOfShipper' + consignee: + $ref: '#/components/schemas/Consignee' + onBehalfOfConsignee: + $ref: '#/components/schemas/OnBehalfOfConsignee' + endorsee: + $ref: '#/components/schemas/Endorsee' + issuingParty: + $ref: '#/components/schemas/IssuingParty' + carriersAgentAtDestination: + $ref: '#/components/schemas/CarriersAgentAtDestination' + notifyParties: + type: array + maxItems: 3 + description: | + List of up to 3 `Notify Parties`. The first item in the list is the **First Notify Party** (`N1`), the second item is the **Second Notify Party** (`N2`) and the last item is the **Other Notify Party** (`NI`). + + **Condition:** If provided: + - Mandatory for To Order BLs, `isToOrder=true` + - The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + $ref: '#/components/schemas/NotifyParty' + other: + type: array + description: A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`. + items: + $ref: '#/components/schemas/OtherDocumentParty' + required: + - shipper + - issuingParty + + ################ + # Export License + ################ + ExportLicenseShipper: + type: object + title: Export License (Shipper) + description: | + `Export License` requirements + + **Condition:** Subject to local customs requirements and commodity. + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Export License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Export License`. + example: '2024-09-21' + + ExportLicense: + type: object + title: Export License + description: | + `Export License` requirements + + **Condition:** Included if the property is provided in the `Shipping Instructions.` + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Export License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Export License`. + example: '2024-09-21' + + ################ + # Import License + ################ + ImportLicenseShipper: + type: object + title: Import License (Shipper) + description: | + `Import License` requirements + + **Condition:** Subject to local customs requirements and commodity. + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that authorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Import License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Import License`. + example: '2024-09-21' + + ImportLicense: + type: object + title: Import License + description: | + `Import License` requirements + + **Condition:** Included if the property is provided in the `Shipping Instructions.` + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that authorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Import License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Import License`. + example: '2024-09-21' diff --git a/ebl/v3/endorsement/EBL_END_v3.0.3.yaml b/ebl/v3/endorsement/EBL_END_v3.0.3.yaml new file mode 100644 index 00000000..cdf99cbd --- /dev/null +++ b/ebl/v3/endorsement/EBL_END_v3.0.3.yaml @@ -0,0 +1,890 @@ +openapi: 3.0.3 +info: + version: 3.0.3 + title: DCSA eBL Endorsement Chain API + description: | +

DCSA OpenAPI specification for electronic Bill of Lading (eBL) Endorsement Chain (END)

+ + ### Changelog and GitHub + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/endorsement#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +tags: + - name: Endorsement Chain + description: Endorsement Chain +paths: + /endorsement-chains/{transportDocumentReference}: + get: + tags: + - Endorsement Chain + summary: Gets the Endorsement Chain + operationId: getEndorsementChain + description: | + Gets the Endorsement Chain by `transportDocumentReference`. It is possible to filter the result by carrier `SCAC` code and/or by `transportDocumentSubReference`. The result is a list of Endorsement Chains matching the filter. + + **Note:** It is not possible to limit the result, this endPoint does not support pagination. + parameters: + - in: path + name: transportDocumentReference + description: | + The `transportDocumentReference` of the `Transport Document` to get the Endorsement Chain from + required: true + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + - in: query + name: transportDocumentSubReference + description: | + Filter by Transport Document Sub-reference (or version). In case a specific version of the Endorsement Chain is requested - adding this filter narrows the result to 1 Endorsement Chain. + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + - in: query + name: carrierSCACCode + description: | + Filter by carrier `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)). Adding this will only match Transport Documents from the carrier matching the `carrierSCACCode` value. + required: false + schema: + type: string + pattern: ^\S+$ + maxLength: 4 + example: YMLU + - in: header + name: API-Version + required: false + schema: + type: string + example: 3.0.2 + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** contain the SemVer of the consumer. + responses: + '200': + description: | + All Endorsement Chains that match the filter criteria. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/EndorsementChain' + examples: + surrenderedStraightBLExample: + summary: | + Surrendered straight B/L + description: | + Endorsement Chain for a surrendered 'Straight Bill of Lading' issued by Yang Ming to Suzano Brazil (who is the Shipper) on the Wave platform. Suzano China is the Consignee. The `Transport Document` contains this information: + - **Shipper:** Suzano Brazil + - **Consignee:** Suzano China + + The Endorsement Chain consists of the follow 4 entries: + |Entry|Action Code|Actor|Recipient| + |:--:|:---------:|-----|----------| + |1|`SURRENDERED`|Yang Ming Marine Transport Corporation|| + |2|`SURRENDER_FOR_DELIVERY`|Suzano China|Yang Ming Marine Transport Corporation| + |3|`TRANSFER`|Suzano Brazil|Suzano China| + |4|`ISSUE`|Yang Ming Marine Transport Corporation|Suzano Brazil| + + Please note that the 4th entry in the example (`actionCode: 'ISSUE'`) is the first entry in the chain, on which further endorsements are made... + value: + - transportDocumentReference: '62CD536BA8D34C469AFD' + transportDocumentSubReference: 'fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9' + carrierSCACCode: 'YMLU' + endorsementChain: + - actionDateTime: '2025-09-12T17:23:12Z' + actionCode: 'SURRENDERED' + actor: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + - actionDateTime: '2025-09-12T17:23:12Z' + actionCode: 'SURRENDER_FOR_DELIVERY' + actor: + partyName: 'Suzano China' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '0665fefb-7c3f-443b-8ccd-73ced178448f' + recipient: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + - actionDateTime: '2025-09-10T14:35:42Z' + actionCode: 'TRANSFER' + actor: + partyName: 'Suzano Brazil' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: 'ee92b6b7-ac27-4537-87df-019c69389346' + recipient: + partyName: 'Suzano China' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '0665fefb-7c3f-443b-8ccd-73ced178448f' + - actionDateTime: '2025-09-09T12:55:31Z' + actionCode: 'ISSUE' + actor: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + recipient: + partyName: 'Suzano Brazil' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: 'ee92b6b7-ac27-4537-87df-019c69389346' + surrenderedStraightBLWithOnBehalfOfPartiesExample: + summary: | + Surrendered straight B/L (using 'On Behalf of Parties') + description: | + Endorsement Chain for a surrendered 'Straight Bill of Lading' issued by ZIM to a Brazilian local agent (the Issue to Party and mentioned as a `On Behalf of Shipper` on the eBL) on the Bolero platform. Suzano China is the Consignee using China local agent as a `On Behalf of Consignee`. The `Transport Document` contains this information: + - **Shipper:** Suzano Brazil + - **On behalf of Shipper:** Brazil local agent + - **Consignee:** Suzano China + - **On behalf of Consignee:** China local agent + + The Endorsement Chain consists of the follow 4 entries: + |Entry|Action Code|Actor|Recipient| + |:--:|:---------:|-----|----------| + |1|`SURRENDERED`|Zim Integrated Shipping Services Ltd|| + |2|`SURRENDER_FOR_DELIVERY`|China local agent **on Behalf of** Suzano China|Zim Integrated Shipping Services Ltd| + |3|`TRANSFER`|Brazil local agent **on Behalf of** Suzano Brazil|China local agent **on Behalf of** Suzano China| + |4|`ISSUE`|Zim Integrated Shipping Services Ltd|Brazil local agent **on Behalf of** Suzano Brazil| + + Please note that the 4th entry in the example (`actionCode: 'ISSUE'`) is the first entry in the chain, on which further endorsements are made... + value: + - transportDocumentReference: '61572195130255734095' + transportDocumentSubReference: 'c5c6b4a8-3645-4209-96e2-453daebbb961' + carrierSCACCode: 'ZIMU' + endorsementChain: + - actionDateTime: '2025-09-12T17:23:12Z' + actionCode: 'SURRENDERED' + actor: + partyName: 'Zim Integrated Shipping Services Ltd' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '0bbf18d8-ee73-40a0-baa2-7349fbfafcee' + - actionDateTime: '2025-09-12T17:13:44Z' + actionCode: 'SURRENDER_FOR_DELIVERY' + actor: + partyName: 'China local agent' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '61cb4944-1f36-428b-9d95-2f5539dea06b' + representedParty: + partyName: 'Suzano China' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: 'd02751e3-2958-4c18-9e18-4e8ee341a93c' + recipient: + partyName: 'Zim Integrated Shipping Services Ltd' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '0bbf18d8-ee73-40a0-baa2-7349fbfafcee' + - actionDateTime: '2025-09-11T15:45:42Z' + actionCode: 'TRANSFER' + actor: + partyName: 'Brazil local agent' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '4b502cf9-627b-4895-8b1f-df0c42e21e17' + representedParty: + partyName: 'Suzano Brazil' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: 'c6880d2f-f0c6-4a59-87b3-9e9284084b60' + recipient: + partyName: 'China local agent' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '61cb4944-1f36-428b-9d95-2f5539dea06b' + representedParty: + partyName: 'Suzano China' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: 'd02751e3-2958-4c18-9e18-4e8ee341a93c' + - actionDateTime: '2025-09-09T12:55:31Z' + actionCode: 'ISSUE' + actor: + partyName: 'Zim Integrated Shipping Services Ltd' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '0bbf18d8-ee73-40a0-baa2-7349fbfafcee' + recipient: + partyName: 'Brazil local agent' + eblPlatform: 'BOLE' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: '4b502cf9-627b-4895-8b1f-df0c42e21e17' + representedParty: + partyName: 'Suzano Brazil' + identifyingCodes: + - codeListProvider: 'BOLE' + partyCode: 'c6880d2f-f0c6-4a59-87b3-9e9284084b60' + twoTDSRExample: + summary: | + Multiple EndorsementChains for same B/L + description: | + 2 endorsement chains for the same `transportDocumentReference`. First entry (`transportDocumentSubReference='v2'`) has only been re-issued. Second entry (`transportDocumentSubReference='v1'`) is the endorsement chain that has been issued and then surrendered for amendments. + value: + - transportDocumentReference: '62CD536BA8D34C469AFD' + transportDocumentSubReference: 'v2' + carrierSCACCode: 'YMLU' + endorsementChain: + - actionDateTime: '2025-09-09T13:55:31Z' + actionCode: 'ISSUE' + actor: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + recipient: + partyName: 'Suzano Brazil' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: 'ee92b6b7-ac27-4537-87df-019c69389346' + - transportDocumentReference: '62CD536BA8D34C469AFD' + transportDocumentSubReference: 'v1' + carrierSCACCode: 'YMLU' + endorsementChain: + - actionDateTime: '2025-09-12T17:23:12Z' + actionCode: 'SURRENDERED' + actor: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + - actionDateTime: '2025-09-12T17:23:12Z' + actionCode: 'SURRENDER_FOR_AMENDMENT' + actor: + partyName: 'Suzano Brazil' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: 'ee92b6b7-ac27-4537-87df-019c69389346' + recipient: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + - actionDateTime: '2025-09-09T12:55:31Z' + actionCode: 'ISSUE' + actor: + partyName: 'Yang Ming Marine Transport Corporation' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: '4bd196da-0d8b-436d-bad4-4cc88f04a035' + recipient: + partyName: 'Suzano Brazil' + eblPlatform: 'WAVE' + identifyingCodes: + - codeListProvider: 'WAVE' + partyCode: 'ee92b6b7-ac27-4537-87df-019c69389346' + '404': + description: | + In case the consumer is requesting a `transportDocumentReference` that does not exist. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + transportDocumentReference not found + description: | + The `transportDocumentReference` does not exist. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/endorsement-chains/td-987 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: transportDocumentReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: transportDocumentReference not found + errorCodeMessage: The requested Endorsement Chain does not exist + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while fetching the Transport Document + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: GET + requestUri: /v3/endorsement-chains/td-987 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Internal Server Error occurred while fetching the Endorsement Chain + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Fetching too many `Endorsement Chain` requests + description: | + Calling the endPoint + + GET /v3/endorsement-chains/td-987 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v3/endorsement-chains/td-987 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to fetch an Endorsement Chain has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Endorsement Chain requests reached + errorCodeMessage: A maximum of 10 Endorsement Chains can be requested per hour +components: + headers: + API-Version: + description: | + SemVer used to indicate the version of the contract (API version) returned. + schema: + type: string + example: 3.0.2 + schemas: + EndorsementChain: + type: object + title: Endorsement Chain + description: | + An endorsement Chain linked to a particular `transportDocumentReference` and potentially a `transportDocumentSubReference`. + properties: + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + carrierSCACCode: + type: string + maxLength: 4 + pattern: ^\S+$ + description: | + The carrier code, based on SCAC code (provided by [NMFTA](https://nmfta.org/scac/)), that Issued the `transportDocumentReference`. + example: MAEU + endorsementChain: + type: array + description: | + A list of one or more actions that affect an eBL, starting from its issuance onward. It is equivalent to the "back side" of a physical Bill of Lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below: + + - **Issue:** The act of issuing an eBL to the `Issue to` party, meaning the designated recipient of the action (typically the shipper or their on behalf of party). + - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee may **NOT** further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`). + - **Sign:** The act of visibly marking the actor's possession of the eBL within the chain. This action has no designated recipient and can only be performed while the actor is the current possessor of the eBL, similar to how a party may sign a physical Bill of Lading while in their possession. + - **Request Surrender for Amendment:** The act of surrendering an eBL so that the carrier can issue an amended version. If the request is accepted, the original eBL is voided, and the amended eBL must be reissued with a new endorsement chain. This action is also used when switching the eBL to a physical document (“switch to paper”), which is treated as part of the amendment process in the DCSA standard. + - **Request Surrender for Delivery:** The act of surrendering an eBL to the carrier to request delivery of the goods. + - **Blank Endorse:** The act of transferring the rights and obligations associated with the eBL in blank, meaning that the endorsement does not specify a recipient. A party in possession of a blank endorsed eBL is allowed to claim or deal with the goods. Only applicable to negotiable eBL (`isToOrder=true`). + - **Endorse to Order:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee can further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`). + - **Transfer:** The act of transferring the possession of the eBL to the recipient. + - **Surrendered:** The act of confirming that the eBL has been surrendered, meaning that its lifecycle is completed. + + **Note:** DCSA member carriers have agreed that the name `endorsementChain` is still the correct name for this list of actions. + items: + $ref: '#/components/schemas/EndorsementChainLink' + required: + - transportDocumentReference + + EndorsementChainLink: + type: object + title: Endorsement Chain Link + description: | + Entry in the endorsement chain. + properties: + actionDateTime: + type: string + format: date-time + description: Date time when the action occurred. + example: '2024-09-04T09:41:00Z' + actionCode: + type: string + maxLength: 50 + description: | + The action performed by the actor. This should be one of: + - `ISSUE` (The actor issued the document to the recipient, who is the first possessor of the eBL, as designated by the `Issue to Party`) + - `ENDORSE` (The actor endorsed the document to the recipient) + - `SIGN` (The actor signed the eBL while it was in the actor's possession) + - `SURRENDER_FOR_DELIVERY` (The actor requested to surrender the eBL to the recipient for delivery) + - `SURRENDER_FOR_AMENDMENT` (The actor requested to surrender the eBL to the recipient for amendment) + - `BLANK_ENDORSE` (The actor endorsed the document in blank) + - `ENDORSE_TO_ORDER` (The actor endorsed the document to order of the recipient, allowing the recipient to further endorse the eBL to another party) + - `TRANSFER` (The actor transferred the possession of the eBL to the recipient) + - `SURRENDERED` (The actor acknowledged that the eBL has been accepted and the lifecycle of the eBL is accomplished) + + Not all actions are applicable to all surrender requests. The combination and order of endorsement chain entries may differ by eBL Solution Provider, based on their rulebook and/or bilateral agreements with carriers. + example: ISSUE + actor: + $ref: '#/components/schemas/ActorParty' + recipient: + $ref: '#/components/schemas/RecipientParty' + auditReference: + type: string + maxLength: 100 + description: | + An identifier issued by the eBL Solution Provider, used for auditing purposes to verify that the endorsement chain action has been securely recorded. The format of this identifier may vary depending on the technology employed by the eBL Solution Provider. + example: AUDIT0007 + required: + - actionDateTime + - actionCode + - actor + + ActorParty: + type: object + title: Actor Party + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + eblPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the `Actor Party`. + The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + example: BOLE + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + representedParty: + $ref: '#/components/schemas/RepresentedActorParty' + required: + - partyName + - eblPlatform + - identifyingCodes + + RecipientParty: + type: object + title: Recipient Party + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + eblPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the `Recipient Party`. + The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + example: BOLE + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + representedParty: + $ref: '#/components/schemas/RepresentedRecipientParty' + required: + - partyName + - eblPlatform + - identifyingCodes + + RepresentedActorParty: + type: object + title: Represented Party + description: The party on whose behalf the action was performed. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + RepresentedRecipientParty: + type: object + title: Represented Party + description: The party on whose behalf the action was directed. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + IdentifyingCode: + type: object + title: Identifying Code + description: | + A code and value that uniquely identifies a party. + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `GSBN` (Global Shipping Business Network) + - `WISE` (WiseTech) + - `GLEIF` (Global Legal Entity Identifier Foundation) + - `W3C` (World Wide Web Consortium) + - `DNB` (Dun and Bradstreet) + - `FMC` (Federal Maritime Commission) + - `DCSA` (Digital Container Shipping Association) + - `ZZZ` (Mutually defined) + example: W3C + partyCode: + type: string + maxLength: 150 + description: | + Code to identify the party as provided by the code list provider + example: MSK + codeListName: + type: string + maxLength: 100 + description: | + The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be: + + - `DID` (Decentralized Identifier) for `codeListProvider` `W3C` + - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF` + - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB` + example: DID + required: + - codeListProvider + - partyCode + + TaxLegalReference: + type: object + title: Tax & Legal Reference + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |EORI|NL|Economic Operators Registration and Identification| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: IN + value: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + required: + - type + - countryCode + - value + + ################# + # Error Responses + ################# + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTIONS + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v3/endorsement-chains/td-123 + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. + type: string + format: date-time + example: '2024-09-04T09:41:00Z' + errors: + type: array + description: | + An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + + DetailedError: + type: object + title: Detailed Error + description: | + A detailed description of what has caused the error. + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + minimum: 7000 + maximum: 9999 + example: 7003 + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error. + example: facilityCode + value: + type: string + maxLength: 500 + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + description: | + A standard short description corresponding to the `errorCode`. + type: string + maxLength: 100 + example: invalidData + errorCodeMessage: + type: string + maxLength: 5000 + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + - errorCodeMessage diff --git a/ebl/v3/issuance/EBL_ISS_v3.0.3.yaml b/ebl/v3/issuance/EBL_ISS_v3.0.3.yaml new file mode 100644 index 00000000..9fdb418c --- /dev/null +++ b/ebl/v3/issuance/EBL_ISS_v3.0.3.yaml @@ -0,0 +1,3553 @@ +openapi: 3.0.3 +info: + version: 3.0.3 + title: DCSA eBL Issuance API + description: | +

DCSA OpenAPI specification for the issuance of an electronic Bill of Lading (referred to as eBL) via an eBL Solution Provider

+ + This API is intended as an API between a carrier and a eBL Solution Platform. + + The eBL Solution Provider is to implement + + PUT /v3/ebl-issuance-requests + + for the carrier to call and the carrier is to implement + + POST /v3/ebl-issuance-responses + + for the eBL Solution Provider to call. + + When the document is to be surrendered, it should happen via a version of the [DCSA eBL Surrender](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_EBL_SUR/3.0.2) API. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) + + ### Digital Signatures + Please look at the following implementation guide for how to create [Digital Signatures](https://developer.dcsa.org/implementing-digital-signatures-for-transport-documents). + + ### Changelog and GitHub + For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/issuance#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +tags: + - name: Issuance eBL + description: | + Issuance eBL **implemented** by eBL Solution Platform + - name: Issuance Response + description: | + Issuance Response **implemented** by carrier +paths: + /v3/ebl-issuance-requests: + put: + tags: + - Issuance eBL + operationId: put-ebl-issuance-requests + summary: Request issuance of an eBL + description: | + Submit a transport document (eBL) for issuance + + **This endPoint is to be implemented by an eBL Solution Provider for the carrier to call** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/IssuanceRequest' + responses: + '204': + description: | + Platform acknowledges the issuance request and will follow up later with a response via the DCSA_ISS_RSP API. Please see the API description for the concrete link and version. + + Note that the platform MUST NOT accept an issuance request twice. If the client misbehaves and attempts to complete the same transaction more than once, then the platform must ensure that at most one of these requests sees a successful response. The rest should an error instead. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '409': + description: | + An Issuance Request is made with a `Transport Document Reference` (TDR), that was used previously to request the issuance of a `Transport Document` (TD). The document is either already issued or an TD with the same TDR. + + The eBL platform will inform the carrier when the carrier needs to act on this document again. If the issuance is pending, then the carrier will be notified via the `/v3/ebl-issuance-responses` endPoint once the issuance process completes. If the issuance has already succeeded, the eBL platform will notify the carrier when there is a surrender request via the DCSA_EBL_SUR API. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting Transport Document issue request + description: | + The `Transport Document` referenced in the `PUT` request has previously been used to Issue and is currently being processed. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PUT + requestUri: /v3/ebl-issuance-requests + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: Is being processed + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Transport Document Reference already Issued + errorCodeMessage: The Transport Document cannot be issued with the same Transport Document Reference (TDR) as previously. The eBL platform will inform the carrier when the carrier needs to act on this document again + default: + description: Request failed for some reason. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + /v3/ebl-issuance-responses: + post: + tags: + - Issuance Response + operationId: create-ebl-issuance-response + summary: Respond to a transport document issuance request + description: | + Submit a response to a carrier issuance request. + + **This endPoint is to be implemented by a carrier for the eBL Solution Provider to call** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/IssuanceResponse' + examples: + issuExample: + summary: | + Issued response + description: | + The document was successfully issued (`ISSU`) and delivered + value: + transportDocumentReference: HHL7180000000 + issuanceResponseCode: ISSU + responses: + '204': + description: Carrier's acknowledgement of the Issuance Response + headers: + API-Version: + $ref: '#/components/headers/API-Version' + default: + description: Request failed for some reason. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + +components: + headers: + API-Version: + schema: + type: string + example: 3.0.2 + description: | + SemVer used to indicate the version of the contract (API version) returned. + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '3' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + schemas: + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v1/events + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. + type: string + format: date-time + example: '2024-09-04T09:41:00Z' + errors: + type: array + description: | + An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + DetailedError: + type: object + title: Detailed Error + description: | + A detailed description of what has caused the error. + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + minimum: 7000 + maximum: 9999 + example: 7003 + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error. + example: facilityCode + value: + type: string + maxLength: 500 + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + description: | + A standard short description corresponding to the `errorCode`. + type: string + maxLength: 100 + example: invalidData + errorCodeMessage: + type: string + maxLength: 5000 + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + - errorCodeMessage + IssuanceRequest: + type: object + title: Issuance Request + description: | + Details of the eBL that the carrier requests to have issued. + + The `eBLVisualisationByCarrier` is an optional document, where the carrier can provide its own visualization of the eBL for the end user. The carrier is the sole responsible party for ensuring there are no discrepancies between the eBL (the `document` attribute) and the provided visualization (the `eBLVisualisationByCarrier` attribute). + properties: + document: + $ref: '#/components/schemas/TransportDocument' + issueTo: + $ref: '#/components/schemas/IssueToParty' + eBLVisualisationByCarrier: + $ref: '#/components/schemas/SupportingDocument' + issuanceManifestSignedContent: + type: string + pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ + description: | + JWS content with compact serialization according to [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-7.1). JWS-signed payload is defined in schema [IssuanceManifest](#/IssuanceManifest). This attribute is used to provide integrity of various parts of the payload that enable parties to validate whether a payload matches what the carrier issued originally. Accordingly, the payload is signed by the carrier or a party (typically an agent) acting on behalf of the carrier. + # TODO: Update example + example: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudENoZWNrc3VtIjogIjhkYzk5ZDhhYzkyMjI0MGM1NWMwMzg0NWY0OWRlZjY0MTg3MTQ2NjUxYmFlNGY5YTYzMTMxMjc3Y2YwMGQ5ZGYiLCJlQkxWaXN1YWxpc2F0aW9uQnlDYXJyaWVyQ2hlY2tzdW0iOiAiNzZhN2QxNGM4M2Q3MjY4ZDY0M2FlNzM0NWM0NDhkZTYwNzAxZjk1NWQyNjRhNzQzZTY5MjhhMGI4MjY4YjI0ZiIsImlzc3VlVG9DaGVja3N1bSI6ICI3NmE3ZDE0YzgzZDcyNjhkNjQzYWU3MzQ1YzQ0OGRlNjA3MDFmOTU1ZDI2NGE3NDNlNjkyOGEwYjgyNjhiMjRmIn0.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA + required: + - document + - issueTo + - issuanceManifestSignedContent + SupportingDocument: + type: object + title: Supporting Document + description: | + A binary document representing the visualisation of the eBL. + properties: + name: + type: string + maxLength: 100 + description: | + Name of the Supporting Document + example: Carrier rendered copy of the EBL.pdf + content: + type: string + format: byte + description: The actual contents of the visual rendering. + example: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAGaSURBVDhPnZO/S0JRFMe/zygxwgqcfZtz0N7SFNgPaKlJpTFLCqwotV9qRYN/gIOL1FK22NISWENT0BTUkNLgIL2iHxYRnc697/kKzdA+cOD8uOec77uXB/oHngMPnd2eSb/pAf5DP2EWhGlQ8ChIikiiQa7vruFacwHdHHwC9nY7mhqgRBTdsbDdA/nVvHQbYnxvHHhnp4XtFZjon4DapTam4Lx4jt7NXlO6WEsreltDA5RFlt4qHDaWXlgrwNnplDX5CcWnIo5vjmWimsGdQV7HjjjJ0gMDAbNZopU1wgwfmQSlL9JCkEkunyMEuLbMFgZZ161G5RsFES5WNrC8lC8Fb49XDlcWWLNVOHqttFGCo90haxUsyeEk8GhEfEm+lA/ZqyyGdof0ocJegMhIpKZZIC8xfhLH0v6SfstCzRubeK42tg9Od3RDm9c4qMV8hWguinAmDHTJvC5bVB6A8nYZtlabTFcjX0EQ6gshNhqTDSbPQGIsUbdZIhT8ZOt0izDFu+dAakI1svX59W/MXGbIveM2or8g+gL+Fn3DwcYf+gAAAABJRU5ErkJggg== + contentType: + type: string + maxLength: 100 + default: application/pdf + description: | + The `Media Type` of the content being transmitted as defined by [Iana](https://www.iana.org/assignments/media-types/media-types.xhtml). Can be left out if the content is `application/pdf` (PDF). + + **Condition:** This property is mandatory to provide if it differs from `application/pdf` + example: application/msword + required: + - name + - content + IssuanceManifest: + type: object + title: 'Issuance Manifest' + description: | + Checksums of the carrier provided documents from the issuance time. + properties: + documentChecksum: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + description: | + The checksum of the `document` attribute computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). The transport document must be in the [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785) canonical form before the checksum is computed. + example: 76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f + eBLVisualisationByCarrierChecksum: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + description: | + The checksum of the `content` attribute of the `eBLVisualisationByCarrier` attribute computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). The checksum is computed on the `content` field in its decoded form. + example: 76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f + issueToChecksum: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + description: | + The checksum of the `issueTo` attribute computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). The value must be in the [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785) canonical form before the checksum is computed. + example: 76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f + required: + - documentChecksum + - issueToChecksum + + IssueToParty: + type: object + title: Issue To Party + description: | + The party that receives **possession** of the eBL upon issuance. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + sendToPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the transaction party. + The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + example: BOLE + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + required: + - partyName + - sendToPlatform + - identifyingCodes + + IdentifyingCode: + type: object + title: Identifying Code + description: | + A code and value that uniquely identifies a party. + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `GSBN` (Global Shipping Business Network) + - `WISE` (WiseTech) + - `GLEIF` (Global Legal Entity Identifier Foundation) + - `W3C` (World Wide Web Consortium) + - `DNB` (Dun and Bradstreet) + - `FMC` (Federal Maritime Commission) + - `DCSA` (Digital Container Shipping Association) + - `ZZZ` (Mutually defined) + + example: W3C + partyCode: + type: string + maxLength: 150 + description: | + Code to identify the party as provided by the code list provider + example: MSK + codeListName: + type: string + maxLength: 100 + description: | + The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be: + + - `DID` (Decentralized Identifier) for `codeListProvider` `W3C` + - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF` + - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB` + + example: DID + required: + - codeListProvider + - partyCode + TaxLegalReference: + type: object + title: Tax & Legal Reference + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |EORI|NL|Economic Operators Registration and Identification| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: IN + value: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + required: + - type + - countryCode + - value + + #################### + # Transport Document + #################### + TransportDocument: + type: object + title: Transport Document + description: | + The document that governs the terms of carriage between shipper and carrier for maritime transportation. Two distinct types of transport documents exist: + - Bill of Lading + - Sea Waybill. + properties: + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + shippingInstructionsReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The identifier for a `Shipping Instructions` provided by the carrier for system purposes. + example: e0559d83-00e2-438e-afd9-fdd610c1a008 + transportDocumentStatus: + type: string + maxLength: 50 + description: | + The status of the `Transport Document`. Possible values are: + - `DRAFT` (the Transport Document is currently a Draft) + - `APPROVED` (the Transport Document has been Approved by consumer) + - `ISSUED` (the Transport Document has been Issued by provider) + - `PENDING_SURRENDER_FOR_AMENDMENT` (the Transport Document has a pending Surrender for Amendment) + - `SURRENDERED_FOR_AMENDMENT` (the Transport Document is Surrendered for Amendment) + - `PENDING_SURRENDER_FOR_DELIVERY` (the Transport Document has a pending Surrender for Delivery) + - `SURRENDERED_FOR_DELIVERY` (the Transport Document is Surrendered for Delivery) + - `VOIDED` (the Transport Document has been Voided) + example: DRAFT + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the transport document + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + isShippedOnBoardType: + type: boolean + description: | + Specifies whether the Transport Document is a received for shipment, or shipped on board. + example: true + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + isElectronic: + type: boolean + description: | + An indicator whether the transport document is electronically transferred. + example: true + isToOrder: + type: boolean + description: | + Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`). + + `isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill). + example: false + numberOfCopiesWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`| + example: 2 + numberOfCopiesWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges. + + **Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property: + | Transport Document Type Code | Is Electronic | Meaning | + |-------|:-------:|-------| + |`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges| + |`BOL`|`true`|Not applicable, there are no copies| + |`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)| + |`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`| + example: 2 + numberOfOriginalsWithCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer with charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + numberOfOriginalsWithoutCharges: + type: integer + format: int32 + minimum: 0 + description: | + Number of originals of the Bill of Lading that has been requested by the customer without charges. + + **Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero). `numberOfOriginalsWithoutCharges` + `numberOfOriginalsWithCharges` must be ≤ 1. + example: 1 + displayedNameForPlaceOfReceipt: + description: | + The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfLoad: + description: | + The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPortOfDischarge: + description: | + The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + displayedNameForPlaceOfDelivery: + description: | + The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + type: array + maxItems: 5 + items: + type: string + maxLength: 35 + description: | + A line of the address to be displayed on the transport document. + example: 'Strawinskylaan 4117' + shippedOnBoardDate: + type: string + format: date + description: | + Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document. + + When provided on a transport document, the transportDocument is a `Shipped On Board` B/L. + + Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' + displayedShippedOnBoardReceivedForShipment: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 250 + description: | + The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board. + example: 'Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier' + termsAndConditions: + type: string + maxLength: 50000 + description: | + Carrier terms and conditions of transport. + example: Any reference in... + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + issueDate: + type: string + format: date + description: | + Local date when the transport document has been issued. + + Can be omitted on draft transport documents, but must be provided when the document has been issued. + example: '2020-12-12' + receivedForShipmentDate: + type: string + format: date + description: | + Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel). + + When provided on a transport document, the transportDocument is a `Received For Shipment` B/L. + + Exactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L. + example: '2020-12-12' + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + example: HHL51800000 + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + example: HHL1401 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + + **Condition:** Included in the transport document upon customer request. If customers want the value to show, evidence is required, and customers need to approve additional insurance fee charge from the carrier (very exceptional). + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided. If `declaredValue` is not provided, this field must be empty. + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the issuing carrier of the `Transport Document`. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + carrierClauses: + type: array + description: | + Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20000 + description: | + The content of the clause. + example: It is not allowed to... + numberOfRiderPages: + type: integer + format: int32 + minimum: 0 + description: | + The number of additional pages required to contain the goods description on a transport document. Only applicable for physical transport documents. + example: 2 + transports: + $ref: '#/components/schemas/Transports' + charges: + type: array + description: | + A list of `Charges` + items: + $ref: '#/components/schemas/Charge' + # New values compared to SI - END + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + partyContactDetails: + type: array + minItems: 1 + description: | + The contact details of the Shipping Instructions requestor(s) to contact in relation to the **Transport Document** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + documentParties: + $ref: '#/components/schemas/DocumentParties' + consignmentItems: + type: array + minItems: 1 + description: | + A list of `ConsignmentItems` + items: + $ref: '#/components/schemas/ConsignmentItem' + # Includes calculated fields! + utilizedTransportEquipments: + type: array + minItems: 1 + description: | + A list of `Utilized Transport Equipments` describing the equipment being used. + items: + $ref: '#/components/schemas/UtilizedTransportEquipment' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - transportDocumentReference + - transportDocumentStatus + - transportDocumentTypeCode + - isShippedOnBoardType + - isElectronic + - isToOrder + - invoicePayableAt + - partyContactDetails + - documentParties + - consignmentItems + - utilizedTransportEquipments + - termsAndConditions + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - carrierCode + - carrierCodeListProvider + - transports + + ###################### + # Party Contact Detail + ###################### + PartyContactDetail: + type: object + title: Party Contact Detail + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + + ########### + # Reference + ########### + Reference: + type: object + title: Reference + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer’s Reference) + - `AKG` (Vehicle Identification Number) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + ReferenceConsignmentItem: + type: object + title: Reference (Consignment Item) + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer’s Reference) + - `AKG` (Vehicle Identification Number) + - `SPO` (Shipper's Purchase Order) + - `CPO` (Consignee's Purchase Order) + example: CR + values: + type: array + minItems: 1 + description: | + List of `referenceValues` for a given `referenceType`. + items: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - values + + ################## + # Consignment Item + ################## + ConsignmentItem: + type: object + title: Consignment Item + description: | + Defines a list of `CargoItems` belonging together and the associated `Booking`. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems` + properties: + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + # Extended description of carrierBookingReference compared to DCSA_DOMAIN description + description: | + The associated booking number provided by the carrier for this `Consignment Item`. + example: ABC709951 + descriptionOfGoods: + type: array + description: | + A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted. + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + maxItems: 150 + items: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: A line describing the cargo + example: blue shoes size 47 + HSCodes: + type: array + minItems: 1 + description: | + A list of `HS Codes` that apply to this `consignmentItem` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `consignmentItem` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + cargoItems: + type: array + minItems: 1 + description: | + A list of all `cargoItems` + items: + $ref: '#/components/schemas/CargoItem' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceConsignmentItem' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - carrierBookingReference + - descriptionOfGoods + - HSCodes + - cargoItems + + ######################### + # National Commodity Code + ######################### + NationalCommodityCode: + type: object + title: National Commodity Code + description: | + The national commodity classification code linked to a country with a value. + + An example could look like this: + + | Type | Country | Value | + |-------|:-------:|-------------| + |NCM|BR|['1515', '2106', '2507', '2512']| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The national commodity classification code, which can be one of the following values defined by DCSA: + - `NCM` (Nomenclatura Comum do Mercosul) + - `HTS` (Harmonized Tariff Schedule) + - `SCHEDULE_B` ( Schedule B) + - `TARIC` (Integrated Tariff of the European Communities) + - `CN` (Combined Nomenclature) + - `CUS` (Customs Union and Statistics) + example: NCM + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: BR + values: + type: array + minItems: 1 + description: | + A list of `national commodity codes` values. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The value of the `National Commodity Code` + example: '1515' + example: + - '1515' + - '2106' + - '2507' + - '2512' + example: + type: TARIC + values: + - '85171200' + required: + - type + - values + + ################### + # Customs Reference + ################### + CustomsReference: + type: object + title: Customs Reference + description: | + Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |UCR|NL|Unique Consignment Reference| + |CUS|NL|Customs Union and Statistics| + |ACID|EG|Advance Cargo Information Declaration in Egypt| + |CERS|CA|Canadian Export Reporting System| + |ITN|US|Internal Transaction Number in US| + |PEB|ID|PEB reference number| + |CSN|IN|Cargo Summary Notification (CSN)| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined in the relevant customs jurisdiction. + example: CUS + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + values: + type: array + minItems: 1 + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `customsReference` + example: '4988470982020120017' + required: + - type + - countryCode + - values + + ############ + # Cargo Item + ############ + CargoItem: + type: object + title: Cargo Item + description: | + A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `cargoItem` + items: + $ref: '#/components/schemas/NationalCommodityCode' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - equipmentReference + - cargoGrossWeight + - outerPackaging + + CargoGrossWeight: + type: object + title: Cargo Gross Weight + description: | + The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided. + example: 2400 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + CargoGrossVolume: + type: object + title: Cargo Gross Volume + description: | + Calculated by multiplying the width, height, and length of the packed cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + CargoNetWeight: + type: object + title: Cargo Net Weight + description: | + The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided. + example: 2400 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + CargoNetVolume: + type: object + title: Cargo Net Volume + description: | + Calculated by multiplying the width, height, and length of the cargo, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Calculated by multiplying the width, height, and length of the cargo, excluding packaging. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + + ################# + # Outer Packaging + ################# + OuterPackaging: + type: object + title: Outer Packaging + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + + **Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available. + example: 5H + imoPackagingCode: + type: string + pattern: ^[A-Z0-9]{1,5}$ + minLength: 1 + maxLength: 5 + description: | + The code of the packaging as per IMO. + + **Condition:** only applicable to dangerous goods if specified in the [IMO IMDG code](https://www.imo.org/en/publications/Pages/IMDG%20Code.aspx). If not available, the `packageCode` as per UN recommendation 21 should be used. + example: 1A2 + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Cargo Item`. + example: 18 + description: + type: string + maxLength: 100 + description: | + Description of the outer packaging/overpack. + example: 'Drum, steel' + woodDeclaration: + type: string + maxLength: 30 + description: | + Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include: + - `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped) + - `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate) + - `PROCESSED` (if the wood or wooden materials are entirely made of processed wood, such as plywood, particle board, sliver plates of wood and wood laminate sheets produced using glue, heat, pressure or a combination of these) + - `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate) + example: TREATED_AND_CERTIFIED + dangerousGoods: + type: array + description: | + A list of `Dangerous Goods` + items: + $ref: '#/components/schemas/DangerousGoods' + required: + - numberOfPackages + - description + + ################# + # Dangerous Goods + ################# + DangerousGoods: + type: object + title: Dangerous Goods + description: | + Specification for `Dangerous Goods`. It is mandatory to provide one of `UNNumber` or `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**. + oneOf: + - type: object + title: UN Number + properties: + UNNumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG. + example: '1463' + required: + - UNNumber + - type: object + title: NA Number + properties: + NANumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation. + example: '9037' + required: + - NANumber + properties: + codedVariantList: + type: string + pattern: ^[0-3][0-9A-Z]{3}$ + minLength: 4 + maxLength: 4 + description: | + Four-character code supplied by Exis Technologies that assists to remove ambiguities when identifying a variant within a single UN number or NA number that may occur when two companies exchange DG information. + + Character | Valid Characters | Description + :--------:|------------------|------------ + 1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group + 2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs + 3 and 4|0 to 9 and A to Z|Two sequence letters for other information, for the cases where the variant is required because of different in subrisks, packing instruction etc. + example: '2200' + properShippingName: + type: string + maxLength: 250 + description: | + The proper shipping name for goods under IMDG Code, or the product name for goods under IBC Code and IGC Code, or the bulk cargo shipping name for goods under IMSBC Code, or the name of oil for goods under Annex I to the MARPOL Convention. + example: 'Chromium Trioxide, anhydrous' + technicalName: + type: string + maxLength: 250 + description: | + The recognized chemical or biological name or other name currently used for the referenced dangerous goods as described in chapter 3.1.2.8 of the IMDG Code. + example: 'xylene and benzene' + imoClass: + type: string + maxLength: 4 + description: | + The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are: + + - `1.1A` (Substances and articles which have a mass explosion hazard) + - `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard) + - `2.1` (Flammable gases) + - `8` (Corrosive substances) + example: 1.4S + subsidiaryRisk1: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + subsidiaryRisk2: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + isMarinePollutant: + type: boolean + description: | + Indicates if the goods belong to the classification of Marine Pollutant. + example: false + packingGroup: + type: integer + format: int32 + minimum: 1 + maximum: 3 + description: | + The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code. + example: 3 + isLimitedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code. + example: false + isExceptedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code. + example: false + isSalvagePackings: + type: boolean + description: | + Indicates if the cargo has special packaging for the transport, recovery or disposal of damaged, defective, leaking or nonconforming hazardous materials packages, or hazardous materials that have spilled or leaked. + example: false + isEmptyUncleanedResidue: + type: boolean + description: | + Indicates if the cargo is residue. + example: false + isWaste: + type: boolean + description: | + Indicates if waste is being shipped + example: false + isHot: + type: boolean + description: | + Indicates if high temperature cargo is shipped. + example: false + isCompetentAuthorityApprovalRequired: + type: boolean + description: | + Indicates if the cargo require approval from authorities + example: false + competentAuthorityApproval: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name and reference number of the competent authority providing the approval. + example: '{Name and reference...}' + segregationGroups: + type: array + description: | + List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code. + + **Condition:** only applicable to specific hazardous goods. + items: + type: string + maxLength: 2 + description: | + Grouping of Dangerous Goods having certain similar chemical properties. Possible values are: + + - `1` (Acids) + - `2` (Ammonium Compounds) + - `3` (Bromates) + - `4` (Chlorates) + - `5` (Chlorites) + - `6` (Cyanides) + - `7` (Heavy metals and their salts) + - `8` (Hypochlorites) + - `9` (Lead and its compounds) + - `10` (Liquid halogenated hydrocarbons) + - `11` (Mercury and mercury compounds) + - `12` (Nitrites and their mixtures) + - `13` (Perchlorates) + - `14` (Permanganates) + - `15` (Powdered metals) + - `16` (Peroxides), + - `17` (Azides) + - `18` (Alkalis) + example: '12' + innerPackagings: + type: array + description: | + A list of `Inner Packings` contained inside this `outer packaging/overpack`. + items: + $ref: '#/components/schemas/InnerPackaging' + emergencyContactDetails: + $ref: '#/components/schemas/EmergencyContactDetails' + EMSNumber: + type: string + maxLength: 7 + description: | + The emergency schedule identified in the IMO EmS Guide – Emergency Response Procedures for Ships Carrying Dangerous Goods. Comprises 2 values; 1 for spillage and 1 for fire. Possible values spillage: S-A to S-Z. Possible values fire: F-A to F-Z. + example: F-A S-Q + endOfHoldingTime: + type: string + format: date + description: | + Date by when the refrigerated liquid needs to be delivered. + example: '2021-09-03' + fumigationDateTime: + type: string + format: date-time + description: | + Date & time when the container was fumigated + example: '2024-09-04T09:41:00Z' + isReportableQuantity: + type: boolean + description: | + Indicates if a container of hazardous material is at the reportable quantity level. If `TRUE`, a report to the relevant authority must be made in case of spill. + example: false + inhalationZone: + type: string + maxLength: 1 + minLength: 1 + description: | + The zone classification of the toxicity of the inhalant. Possible values are: + + - `A` (Hazard Zone A) can be assigned to specific gases and liquids + - `B` (Hazard Zone B) can be assigned to specific gases and liquids + - `C` (Hazard Zone C) can **only** be assigned to specific gases + - `D` (Hazard Zone D) can **only** be assigned to specific gases + example: A + grossWeight: + $ref: '#/components/schemas/GrossWeight' + netWeight: + $ref: '#/components/schemas/NetWeight' + netExplosiveContent: + $ref: '#/components/schemas/NetExplosiveContent' + netVolume: + $ref: '#/components/schemas/NetVolume' + limits: + $ref: '#/components/schemas/Limits' + required: + - properShippingName + - imoClass + GrossWeight: + type: object + title: Gross Weight + description: | + Total weight of the goods carried, including packaging. + properties: + value: + type: number + format: float + example: 12000.3 + minimum: 0 + exclusiveMinimum: true + description: | + The grand total weight of the DG cargo and weight per `UNNumber`/`NANumber` including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetWeight: + type: object + title: Net Weight + description: | + Total weight of the goods carried, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Total weight of the goods carried, excluding packaging. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetExplosiveContent: + type: object + title: Net Explosive Content + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `KGM` (Kilograms) + - `LBR` (Pounds) + - `GRM` (Grams) + - `ONZ` (Ounce) + enum: + - KGM + - LBR + - GRM + - ONZ + example: KGM + required: + - value + - unit + NetVolume: + type: object + title: Net Volume + description: | + The volume of the referenced dangerous goods. + + **Condition:** only applicable to liquids and gas. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The volume of the referenced dangerous goods. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms: + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + - `LTR` (Litre) + enum: + - MTQ + - FTQ + - LTR + example: MTQ + required: + - value + - unit + InnerPackaging: + type: object + title: Inner Packaging + description: | + Object for inner packaging specification + properties: + quantity: + type: integer + format: int32 + description: | + Count of `Inner Packagings` of the referenced `Dangerous Goods`. + example: 20 + material: + type: string + maxLength: 100 + description: | + The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`. + example: Plastic + description: + type: string + maxLength: 100 + description: | + Description of the packaging. + example: Woven plastic water resistant Bag + required: + - quantity + - material + - description + EmergencyContactDetails: + type: object + title: Emergency Contact Details + description: | + 24 hr emergency contact details + properties: + contact: + type: string + maxLength: 255 + description: | + Name of the Contact person during an emergency. + example: Henrik Larsen + provider: + type: string + maxLength: 255 + description: | + Name of the third party vendor providing emergency support + example: GlobeTeam + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + referenceNumber: + type: string + maxLength: 255 + description: | + Contract reference for the emergency support provided by an external third party vendor. + example: '12234' + required: + - contact + - phone + Limits: + type: object + title: Limits + description: | + Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure. + properties: + temperatureUnit: + type: string + description: | + The unit for **all attributes in the limits structure** in Celsius or Fahrenheit + + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + enum: + - CEL + - FAH + example: CEL + flashPoint: + type: number + format: float + description: | + Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air. + + **Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code. + example: 42 + transportControlTemperature: + type: number + format: float + description: | + Maximum temperature at which certain substance (such as organic peroxides and self-reactive and related substances) can be safely transported for a prolonged period. + example: 24.1 + transportEmergencyTemperature: + type: number + format: float + description: | + Temperature at which emergency procedures shall be implemented + example: 74.1 + SADT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating decomposition may occur in a substance + example: 54.1 + SAPT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating polymerization may occur in a substance + example: 70 + required: + - temperatureUnit + + ############################## + # Utilized Transport Equipment + ############################## + UtilizedTransportEquipment: + type: object + title: Utilized Transport Equipment + description: | + Specifies the container (`equipment`), the total `weight`, total `volume`, possible `ActiveReeferSettings`, `seals` and `references` + properties: + equipment: + $ref: '#/components/schemas/Equipment' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (SOC). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + shippingMarks: + type: array + maxItems: 50 + description: | + A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment` + + **Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer. + example: Made in China + seals: + type: array + minItems: 1 + description: | + A list of `Seals` + items: + $ref: '#/components/schemas/Seal' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - equipment + - isShipperOwned + - seals + + ########### + # Equipment + ########### + Equipment: + type: object + title: Equipment + description: | + Used for storing cargo in/on during transport. The equipment size/type is defined by the ISO 6346 code. The most common equipment size/type is 20'/40'/45' DRY Freight Container, but several different versions exist. + properties: + equipmentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + tareWeight: + $ref: '#/components/schemas/TareWeight' + required: + - equipmentReference + + TareWeight: + type: object + title: Tare Weight + description: | + The weight of an empty container (gross container weight). + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of an empty container (gross container weight). + example: 4800 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + ###### + # Seal + ###### + Seal: + type: object + title: Seal + description: | + Addresses the seal-related information associated with the shipment equipment. A seal is put on a shipment equipment once it is loaded. This `Seal` is meant to stay on until the shipment equipment reaches its final destination. + properties: + number: + type: string + maxLength: 15 + description: 'Identifies a seal affixed to the container.' + example: VET123 + source: + type: string + description: | + The source of the seal, namely who has affixed the seal. + - `CAR` (Carrier) + - `SHI` (Shipper) + - `VET` (Veterinary) + - `CUS` (Customs) + + **Condition:** Seal source may be required depending on the type of commodity being shipped. + enum: + - CAR + - SHI + - VET + - CUS + example: 'CUS' + required: + - number + + ######################## + # Active Reefer Settings + ######################## + ActiveReeferSettings: + type: object + title: Active Reefer Settings + description: | + The specifications for a Reefer equipment. + + **Condition:** Only applicable when `isNonOperatingReefer` is set to `false` + properties: + temperatureSetpoint: + type: number + format: float + description: | + Target value of the temperature for the Reefer based on the cargo requirement. + example: -15 + temperatureUnit: + type: string + description: | + The unit for temperature in Celsius or Fahrenheit + + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + + **Condition:** Mandatory if `temperatureSetpoint` is provided. If `temperatureSetpoint` is not provided, this field must be empty. + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere O2 target value + example: 25 + co2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 target value + example: 25 + humiditySetpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere humidity target value + example: 95.6 + airExchangeSetpoint: + type: number + format: float + minimum: 0 + description: | + Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container + example: 15.4 + airExchangeUnit: + type: string + description: | + The unit for `airExchange` in metrics- or imperial- units per hour + - `MQH` (Cubic metre per hour) + - `FQH` (Cubic foot per hour) + + **Condition:** Mandatory if `airExchange` is provided. If `airExchange` is not provided, this field must be empty. + enum: + - MQH + - FQH + example: MQH + isVentilationOpen: + type: boolean + description: | + If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed` + example: true + isDrainholesOpen: + type: boolean + description: | + Is drain holes open on the container + example: true + isBulbMode: + type: boolean + description: | + Is special container setting for handling flower bulbs active + example: true + isColdTreatmentRequired: + type: boolean + description: | + Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD + example: true + isControlledAtmosphereRequired: + type: boolean + description: | + Indicator of whether cargo requires Controlled Atmosphere. + example: true + + ############ + # Transports + ############ + Transports: + type: object + title: Transports + description: | + This object consolidates information related to dates, origin and destination points, pre- and on-carriage mode of transport and vessel details. + properties: + plannedArrivalDate: + type: string + format: date + description: | + The planned date of arrival. + example: '2024-06-07' + plannedDepartureDate: + type: string + format: date + description: | + The planned date of departure. + example: '2024-06-03' + preCarriageBy: + type: string + maxLength: 50 + description: | + Mode of transportation for pre-carriage when transport to the port of loading is organized by the carrier. If this attributes is populated, then a Place of Receipt must also be defined. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: RAIL + onCarriageBy: + type: string + maxLength: 50 + description: | + Mode of transportation for on-carriage when transport from the port of discharge is organized by the carrier. If this attributes is populated, then a Place of Delivery must also be defined. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: TRUCK + placeOfReceipt: + $ref: '#/components/schemas/PlaceOfReceipt' + portOfLoading: + $ref: '#/components/schemas/PortOfLoading' + portOfDischarge: + $ref: '#/components/schemas/PortOfDischarge' + placeOfDelivery: + $ref: '#/components/schemas/PlaceOfDelivery' + onwardInlandRouting: + $ref: '#/components/schemas/OnwardInlandRouting' + vesselVoyages: + type: array + minItems: 1 + description: | + Allow the possibility to include multiple vessels/voyages in the `Transport Document` (e.g. the first sea going vessel and the mother vessel). At least one is mandatory to provide. + items: + $ref: '#/components/schemas/VesselVoyage' + required: + - plannedArrivalDate + - plannedDepartureDate + - portOfLoading + - portOfDischarge + - vesselVoyages + + VesselVoyage: + type: object + title: Vessel/Voyage + description: 'Vessel and export voyage' + properties: + vesselName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the first sea going Vessel on board which the cargo is loaded or intended to be loaded + example: King of the Seas + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + required: + - vesselName + - carrierExportVoyageNumber + PlaceOfReceipt: + type: object + title: Place of Receipt + description: | + An object to capture `Place of Receipt` location specified as: the location where the cargo is handed over by the shipper, or his agent, to the shipping line. This indicates the point at which the shipping line takes on responsibility for carriage of the container. + + **Condition:** Only when pre-carriage is done by the carrier. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` or a `Geo Coordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + PortOfLoading: + type: object + title: Port of Loading + description: | + An object to capture `Port of Loading` location specified as: the location where the cargo is loaded onto a first sea-going vessel for water transportation. + + The location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `UN Location Code` and as a `City and Country`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + city: + $ref: '#/components/schemas/City' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + PortOfDischarge: + type: object + title: Port of Discharge + description: | + An object to capture `Port of Discharge` location specified as: the location where the cargo is discharged from the last sea-going vessel. + + The location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `UN Location Code` and as a `City and Country`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + city: + $ref: '#/components/schemas/City' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + PlaceOfDelivery: + type: object + title: Place of Delivery + description: | + An object to capture `Place of Delivery` location specified as: the location where the cargo is handed over to the consignee, or his agent, by the shipping line and where responsibility of the shipping line ceases. + + **Condition:** Only when onward transport is done by the carrier + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, `Address` or a `Geo Coordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + OnwardInlandRouting: + type: object + title: Onward Inland Routing + description: | + An object to capture `Onward Inland Routing` location specified as the end location of the inland movement that takes place after the container(s) being delivered to the port of discharge/place of delivery for account and risk of merchant (merchant haulage). + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Hamburg + UNLocationCode: DEHAM + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + ######## + # Charge + ######## + Charge: + type: object + title: Charge + description: | + Addresses the monetary value of freight and other service charges for a `Booking`. + properties: + chargeName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + Free text field describing the charge to apply + example: Documentation fee - Destination + currencyAmount: + type: number + format: float + minimum: 0 + description: | + The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals. + example: 1012.12 + currencyCode: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency for the charge, using a 3-character code ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)). + example: DKK + paymentTermCode: + type: string + description: | + An indicator of whether a charge is prepaid (PRE) or collect (COL). When prepaid, the charge is the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charge is the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + calculationBasis: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The code specifying the measure unit used for the corresponding unit price for this cost, such as per day, per ton, per square metre. + example: Per day + unitPrice: + type: number + format: float + minimum: 0 + description: | + The unit price of this charge item in the currency of the charge. + example: 3456.6 + quantity: + type: number + format: float + minimum: 0 + description: | + The amount of unit for this charge item. + example: 34.4 + required: + - chargeName + - currencyAmount + - currencyCode + - paymentTermCode + - calculationBasis + - unitPrice + - quantity + + ################## + # Address Location + ################## + Address: + type: object + title: Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the street number. + example: N/A + postCode: + type: string + maxLength: 10 + description: The post code. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - street + - city + - countryCode + + ############### + # City Location + ############### + City: + type: object + title: City + description: | + An object for storing city, state/region and country related information + properties: + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: | + The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - city + - countryCode + + ################### + # Facility Location + ################### + Facility: + type: object + title: Facility + description: | + An interface used to express a location using a `Facility`. The facility can be expressed using one of `BIC` code or `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + properties: + facilityCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 6 + description: |- + The code used for identifying the specific facility. This code does not include the UN Location Code. + The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used: + - `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)) + - `BIC` (the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)) + example: ADT + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code` + - `BIC` (Requires a UN Location Code) + - `SMDG` (Requires a UN Location Code) + enum: + - BIC + - SMDG + example: SMDG + required: + - facilityCode + - facilityCodeListProvider + + ######################### + # Geo Coordinate Location + ######################### + GeoCoordinate: + type: object + title: Geo Coordinate + description: | + An object used to express a location using `latitude` and `longitude`. + properties: + latitude: + type: string + description: | + Latitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: | + Longitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. + maxLength: 11 + example: '2.294492036' + required: + - latitude + - longitude + + ################## + # Document Parties + ################## + OtherDocumentParty: + type: object + title: Other Document Party + description: | + A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`. + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `SCO` (Service Contract Owner) + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + example: DDS + required: + - party + - partyFunction + + PartyAddress: + type: object + title: Party Address + description: | + An object for storing address related information + properties: + street: + type: string + description: The name of the street of the party’s address. + maxLength: 70 + example: Ruijggoordweg + streetNumber: + type: string + description: The number of the street of the party’s address. + maxLength: 50 + example: '100' + floor: + type: string + description: | + The floor of the party’s street number. + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2nd + postCode: + type: string + description: The post code of the party’s address. + maxLength: 10 + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + description: | + The city name of the party’s address. + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + example: Amsterdam + UNLocationCode: + type: string + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + stateRegion: + type: string + description: The state/region of the party’s address. + maxLength: 65 + example: North Holland + countryCode: + type: string + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: NL + required: + - street + - city + - countryCode + + Shipper: + type: object + title: Shipper + description: | + The party by whom or in whose name or on whose behalf a contract of carriage of goods by sea has been concluded with a carrier, or the party by whom or in whose name, or on whose behalf, the goods are actually delivered to the carrier in relation to the contract of carriage by sea. + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Shipper`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Shipper`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Shipper`. + example: HHL007 + required: + - partyName + + OnBehalfOfShipper: + type: object + title: On Behalf of Shipper + description: | + The party allowed to act on behalf of the shipper for documentation purposes. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + description: | + **Condition:** Either the `address` or a party `identifyingCode` must be provided. + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + Consignee: + type: object + title: Consignee + description: | + The party to which goods are consigned in the `Master Bill of Lading`. + + **Condition:** Mandatory for non-negotiable BL (`isToOrder=false`) + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Consignee`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Consignee`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + required: + - partyName + - identifyingCodes + + OnBehalfOfConsignee: + type: object + title: On Behalf of Consignee + description: | + The party allowed to act on behalf of the consignee for documentation purposes. + + **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + Endorsee: + type: object + title: Endorsee + description: | + The party to whom the title to the goods is transferred by means of endorsement. + + **Condition:** Can only be provided for negotiable BLs (`isToOrder=true`). If a negotiable BL does not have an `Endorsee`, the BL is said to be "blank endorsed". Note `Consignee` and `Endorsee` are mutually exclusive. + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - identifyingCodes + + CarriersAgentAtDestination: + type: object + title: Carrier's Agent At Destination + description: | + The party on the import side assigned by the carrier to whom the customer need to reach out to for cargo release. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/Address' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - address + - partyContactDetails + + NotifyParty: + type: object + title: Notify Party + description: | + The person to be notified when a shipment arrives at its destination. + + **Condition:** If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + typeOfPerson: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: | + Can be one of the following values as per the Union Customs Code art. 5(4): + - `NATURAL_PERSON` (A person that is an individual living human being) + - `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued) + - `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts) + example: 'NATURAL_PERSON' + address: + $ref: '#/components/schemas/PartyAddress' + displayedAddress: + type: array + maxItems: 6 + description: | + The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`. + + **Conditions:** If provided: + - the displayed address must be included in the `Transport Document`. + - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. **Note:** Some carriers may choose to allow more lines, please consult the carrier's API documentation to check if this is the case. + - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + type: string + maxLength: 35 + description: | + A single address line + example: Strawinskylaan 4117 + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `NotifyParty`. + example: HHL007 + required: + - partyName + + Party: + type: object + title: Party + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Party`. + example: HHL007 + required: + - partyName + + IssuingParty: + type: object + title: Issuing Party + description: | + The company or a legal entity issuing the `Transport Document` + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Asseco Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - address + + IssuanceError: + type: object + title: Issuance Error + description: | + A detailed description of why the Issuance failed + properties: + reason: + type: string + maxLength: 255 + pattern: ^\S(?:.*\S)?$ + description: | + Human readable description of the rationale for an unsuccessful issuance. + + The `reason` should be omitted when the `issuanceResponseCode` is `ISSU`. If the platform for some reason chooses to deviate from this and provide the field anyway, they should use canned phrased like `Issued` that matches the meaning of the `issuanceResponseCode`. + example: 'Cannot get...' + errorCode: + type: string + maxLength: 50 + pattern: ^\S+$ + description: | + A vendor provided error code. + + The meaning of each code is agreed bilaterally between the vendor. + example: 'ERR-1234' + + IssuanceResponse: + type: object + title: Issuance Response + description: | + Response from the eBL Solution Provider back to the Issuing party. + properties: + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + issuanceResponseCode: + type: string + description: | + The platforms verdict on the issuance of the eBL identified by the `transportDocumentReference` + + Options are: + - `ISSU`: The document was successfully `ISSU` and successfully delivered to the initial possessor. + - `BREQ`: The platform reviewed the document and believe they cannot issue the document due to an error/issue with the content of the issuance request. + - `REFU`: The eBL issuance is rejected for a reason that the issuing eBL platform cannot resolve (for example when an Interoperable transfer fails, due to a reject of the receiving eBL platform via the `BENV` code from the interoperability standard). One reason could be that the `issueTo` referenced a valid eBL platform but the receiving platform did not recognise the recipient specified. + + Regardless of the response code, the issuance request is now considered handled. In case of successful issuance, the platform will still have some responsibility but that is covered by other processes and APIs (e.g., the DCSA_SUR API mentioned in the description of this API). In case of failed issuance, it is up to the carrier to resolve the issue and, if needed, submit a revised issuance request. + enum: + - ISSU + - BREQ + - REFU + example: ISSU + reason: + type: string + maxLength: 255 + pattern: ^\S(?:.*\S)?$ + description: | + Human readable description of the rationale for an unsuccessful issuance. + + The `reason` should be omitted when the `issuanceResponseCode` is `ISSU`. If the platform for some reason chooses to deviate from this and provide the field anyway, they should use canned phrased like `Issued` that matches the meaning of the `issuanceResponseCode`. + example: 'Cannot get...' + errors: + type: array + description: | + A list of errors if the issuance failed for some reason. + maxItems: 255 + items: + $ref: '#/components/schemas/IssuanceError' + required: + - transportDocumentReference + - issuanceResponseCode + + PlaceOfIssue: + type: object + title: Place of Issue + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + **Condition:** The location can be specified as one of `UN Location Code` or `CountryCode`, but not both. + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: |- + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + - type: object + title: Country Code + properties: + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: NL + required: + - countryCode + + InvoicePayableAt: + type: object + title: Invoice Payable At + description: | + Location where payment of ocean freight and charges for the main transport will take place by the customer. + + The location can be provided as a `UN Location Code` or as a fallback - a `freeText` field + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: |- + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + - type: object + title: Free text + properties: + freeText: + type: string + maxLength: 35 + description: | + The name of the location where payment will be rendered by the customer. + example: DCSA Headquarters + required: + - freeText + + DocumentParties: + type: object + title: Document Parties + description: | + All `Parties` with associated roles. + properties: + shipper: + $ref: '#/components/schemas/Shipper' + onBehalfOfShipper: + $ref: '#/components/schemas/OnBehalfOfShipper' + consignee: + $ref: '#/components/schemas/Consignee' + onBehalfOfConsignee: + $ref: '#/components/schemas/OnBehalfOfConsignee' + endorsee: + $ref: '#/components/schemas/Endorsee' + issuingParty: + $ref: '#/components/schemas/IssuingParty' + carriersAgentAtDestination: + $ref: '#/components/schemas/CarriersAgentAtDestination' + notifyParties: + type: array + maxItems: 3 + description: | + List of up to 3 `Notify Parties`. The first item in the list is the **First Notify Party** (`N1`), the second item is the **Second Notify Party** (`N2`) and the last item is the **Other Notify Party** (`NI`). + + **Conditions:** If provided: + - mandatory for To Order BLs, `isToOrder=true` + - the order of the items in this array **MUST** be preserved as by the provider of the API. + items: + $ref: '#/components/schemas/NotifyParty' + other: + type: array + description: A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`. + items: + $ref: '#/components/schemas/OtherDocumentParty' + required: + - shipper + - issuingParty + + ################ + # Export License + ################ + ExportLicense: + type: object + title: Export License + description: | + `Export License` requirements + + **Condition:** Included if the property is provided in the `Shipping Instructions.` + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Export License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Export License`. + example: '2024-09-21' + + ################ + # Import License + ################ + ImportLicense: + type: object + title: Import License + description: | + `Import License` requirements + + **Condition:** Included if the property is provided in the `Shipping Instructions.` + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that authorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Import License`. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Import License`. + example: '2024-09-21' diff --git a/ebl/v3/surrender/EBL_SUR_v3.0.3.yaml b/ebl/v3/surrender/EBL_SUR_v3.0.3.yaml new file mode 100644 index 00000000..5c44559b --- /dev/null +++ b/ebl/v3/surrender/EBL_SUR_v3.0.3.yaml @@ -0,0 +1,706 @@ +openapi: 3.0.3 +info: + version: 3.0.3 + title: DCSA eBL Surrender API + description: | +

DCSA OpenAPI specification for the surrender of an electronic Bill of Lading (referred to as eBL) via an eBL Solution Provider for amendment (incl. switch to paper), and delivery

+ + This API is intended as an API between a carrier and an eBL Solution Platform. + + The eBL Solution Platform will submit surrender requests to the carrier, via + + POST /v3/ebl-surrender-requests + + which will be processed asynchronously. The eBL Solution Platform submitting the surrender request to the carrier must be the same eBL Solution Platform from which the eBL was issued. Responses to the surrender requests will be submitted by the carrier via + + POST /v3/ebl-surrender-responses + + When the platform submits a surrender request, the platform guarantees *all* of the following: + + 1) The surrender request was submitted by the sole possessor of the eBL. + 2) Depending on the eBL type: + * For non-negotiable ("straight") eBLs, the surrender request was submitted by either the original shipper OR the consignee. + * For negotiable eBLs with a named titleholder, the surrender request was submitted by the named titleholder. + * For negotiable eBLs without a named titleholder / blank eBLs, possession is sufficient for the entity surrendering the eBL. + 3) The carrier holds possession of the eBL with this surrender request until it responds to this surrender request. + + Please see the [Surrender Request](#/surrenderRequestDetails) for details on what data the platform will provide. + + The processes for amendments to eBL (including switch to paper) and for surrender of the eBL for delivery of the goods shall be exclusively governed by and executed in accordance with the Bylaws of the eBL Platform where the Surrender for amendment or Surrender for delivery was received, including establishing whether the User in Control performing the Surrender for amendment or Surrender for delivery is entitled to carry out this action. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) + + ### Changelog and GitHub + For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/surrender#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +tags: + - name: Surrender Requests + description: | + The Surrender Requests **implemented** by carrier + - name: Surrender Request responses + description: | + The Surrender Request responses **implemented** by the eBL Solution Platform +paths: + /v3/ebl-surrender-requests: + post: + tags: + - Surrender Requests + operationId: create-surrender-request + summary: | + Creates a Surrender Request + description: | + The eBL Solution Platform uses this endpoint to submit a surrender request. + + The carrier's answer to the surrender request will be returned via a callback response (see the `Callbacks` tab) + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SurrenderRequestDetails' + responses: + '204': + description: | + Submission registered successfully. + + The carrier will later follow up via the callback with a response. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + default: + description: Error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + /v3/ebl-surrender-responses: + post: + tags: + - Surrender Request responses + operationId: post-ebl-surrender-responses + description: | + The carrier uses this endpoint to inform the eBL Solution Platform about the verdict for a given surrender request. + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SurrenderRequestAnswer' + responses: + '204': + description: Request successful + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '409': + description: | + A carrier may only answer once to a surrender request. Subsequent attempts to answer are considered an error and should be rejected with a 409 Conflict code. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + default: + description: Error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' +components: + headers: + API-Version: + schema: + type: string + example: 3.0.2 + description: | + SemVer used to indicate the version of the contract (API version) returned. + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '3' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + schemas: + ActorParty: + type: object + title: Actor Party + description: | + Refers to a company or a legal entity. + properties: + eblPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the `Actor Party`. The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + example: BOLE + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + representedParty: + $ref: '#/components/schemas/RepresentedActorParty' + required: + - partyName + - eblPlatform + - identifyingCodes + + RecipientParty: + type: object + title: Recipient Party + description: | + Refers to a company or a legal entity. + + **Note:** It is possible to use a '**No Party**' placeholder when the `actionCode` is one of the following values: `SIGN`, `BLANK ENDORSE` or `SURRENDERED` (as none of these `actionCodes` require a `recipient`). A '**No Party**' object MUST be populated with the following values: + ``` + { + 'eblPlatform': 'NONE', + 'partyName': 'NONE', + 'identifyingCodes': [ + { + 'codeListProvider': 'NONE', + 'partyCode': 'NONE', + } + ] + } + ``` + properties: + eblPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The eBL platform of the `Recipient Party`. The value **MUST** be one of: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `NONE` (To be used as part of the '**No Party**' object when `actionCode` is `SIGN`, `BLANK ENDORSE` or `SURRENDERED`) + example: BOLE + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + representedParty: + $ref: '#/components/schemas/RepresentedRecipientParty' + required: + - partyName + - eblPlatform + - identifyingCodes + + RepresentedActorParty: + type: object + title: Represented Party + description: The party on whose behalf the action was performed. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + RepresentedRecipientParty: + type: object + title: Represented Party + description: The party on whose behalf the action was directed. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + required: + - partyName + + EndorsementChainLink: + type: object + title: Endorsement Chain Link + description: | + Entry in the endorsement chain. + properties: + actionDateTime: + type: string + format: date-time + description: Date time when the action occurred. + example: '2024-09-04T09:41:00Z' + actionCode: + type: string + maxLength: 50 + description: | + The action performed by the actor. This should be one of: + - `ISSUE` (The actor issued the document to the recipient, who is the first possessor of the eBL, as designated by the `Issue to Party`) + - `ENDORSE` (The actor endorsed the document to the recipient) + - `SIGN` (The actor signed the eBL while it was in the actor's possession) + - `SURRENDER_FOR_DELIVERY` (The actor requested to surrender the eBL to the recipient for delivery) + - `SURRENDER_FOR_AMENDMENT` (The actor requested to surrender the eBL to the recipient for amendment) + - `BLANK_ENDORSE` (The actor endorsed the document in blank) + - `ENDORSE_TO_ORDER` (The actor endorsed the document to order of the recipient, allowing the recipient to further endorse the eBL to another party) + - `TRANSFER` (The actor transferred the possession of the eBL to the recipient) + - `SURRENDERED` (The actor acknowledged that the eBL has been accepted and the lifecycle of the eBL is accomplished) + + Not all actions are applicable to all surrender requests. The combination and order of endorsement chain entries may differ by eBL Solution Provider, based on their rulebook and/or bilateral agreements with carriers. + example: ISSUE + actor: + $ref: '#/components/schemas/ActorParty' + recipient: + $ref: '#/components/schemas/RecipientParty' + auditReference: + type: string + maxLength: 100 + description: | + An identifier issued by the eBL Solution Provider, used for auditing purposes to verify that the endorsement chain action has been securely recorded. The format of this identifier may vary depending on the technology employed by the eBL Solution Provider. + example: AUDIT0007 + required: + - actionDateTime + - actionCode + - actor + - recipient + SurrenderRequestDetails: + type: object + title: Surrender Request Details + description: | + A concrete surrender request related to a transport document. + + The platform guarantees *all* of the following: + + 1) The surrender request was submitted by the sole possessor of the eBL. + 2) Depending on the eBL type: + * For non-negotiable ("straight") eBLs, the surrender request was submitted by either the original shipper OR the consignee. + * For negotiable eBLs with a named titleholder, the surrender request was submitted by the named titleholder. + * For negotiable eBLs without a named titleholder / blank eBLs, possession is sufficient for the entity surrendering the eBL. + 3) The carrier holds possession of the eBL with this surrender request until it responds to this surrender request. + properties: + surrenderRequestReference: + type: string + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + description: | + A server defined reference for a concrete surrender request. Surrender request references MUST NOT be reused. + example: Z12345 + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique number allocated by the shipping line to the `Transport Document` and the main number used for the tracking of the status of the shipment. + example: HHL71800000 + transportDocumentSubReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. + example: Version_1 + surrenderRequestCode: + type: string + description: | + Surrender Request codes: + - `SREQ` (Requested to Surrender for Delivery) + - `AREQ` (Requested to Surrender for Amendment) + + The surrender request code determines the type of surrender request. Any parallel negotiation between the consignee and the carrier related to any of these type surrender are handled outside this API. Examples could be the shipment release related to a Surrender for Delivery or the actual contents of the amendment in a surrender related to an amendment. + + Note that "Switch to paper" is considered an amendment in how it is modelled via the DCSA eBL data standard. + enum: + - SREQ + - AREQ + example: SREQ + reasonCode: + type: string + maxLength: 4 + description: | + A code defined by DCSA indicating the reason for requesting a Surrender for Amendment. Possible values are: + - `SWTP` (Switch to paper) + - `COD` (Change of destination) + - `SWI` (Switch BL) + + In case no valid `reasonCode` exists for the `AREQ` (Requested to Surrender for Amendment) - it is possible to use the `comments` property below to add more information. + example: SWTP + comments: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 255 + description: | + Optional free text comment associated with the surrender request transaction. In case no valid `reasonCode` exists - this property can also be used to provide a reason. + example: As requested... + endorsementChain: + type: array + description: | + A list of one or more actions that affect an eBL, starting from its issuance onward. It is equivalent to the "back side" of a physical Bill of Lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below: + + - **Issue:** The act of issuing an eBL to the `Issue to` party, meaning the designated recipient of the action (typically the shipper or their on behalf of party). + - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee may **NOT** further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`). + - **Sign:** The act of visibly marking the actor's possession of the eBL within the chain. This action has no designated recipient and can only be performed while the actor is the current possessor of the eBL, similar to how a party may sign a physical Bill of Lading while in their possession. + - **Request Surrender for Amendment:** The act of surrendering an eBL so that the carrier can issue an amended version. If the request is accepted, the original eBL is voided, and the amended eBL must be reissued with a new endorsement chain. This action is also used when switching the eBL to a physical document (“switch to paper”), which is treated as part of the amendment process in the DCSA standard. + - **Request Surrender for Delivery:** The act of surrendering an eBL to the carrier to request delivery of the goods. + - **Blank Endorse:** The act of transferring the rights and obligations associated with the eBL in blank, meaning that the endorsement does not specify a recipient. A party in possession of a blank endorsed eBL is allowed to claim or deal with the goods. Only applicable to negotiable eBL (`isToOrder=true`). + - **Endorse to Order:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee can further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`). + - **Transfer:** The act of transferring the possession of the eBL to the recipient. + - **Surrendered:** The act of confirming that the eBL has been surrendered, meaning that its lifecycle is completed. + + **Note:** DCSA member carriers have agreed that the name `endorsementChain` is still the correct name for this list of actions. + items: + $ref: '#/components/schemas/EndorsementChainLink' + required: + - surrenderRequestReference + - transportDocumentReference + - surrenderRequestCode + IdentifyingCode: + type: object + title: Identifying Code + description: | + A code and value that uniquely identifies a party. + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS - This value has been **deprecated**. Please use `IDT`) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `COVA` (Covantis) + - `ETIT` (e-title) + - `KTNE` (KTNET) + - `CRED` (Credore) + - `BLOC` (BlockPeer Technologies) + - `GSBN` (Global Shipping Business Network) + - `WISE` (WiseTech) + - `GLEIF` (Global Legal Entity Identifier Foundation) + - `W3C` (World Wide Web Consortium) + - `DNB` (Dun and Bradstreet) + - `FMC` (Federal Maritime Commission) + - `DCSA` (Digital Container Shipping Association) + - `ZZZ` (Mutually defined) + - `NONE` (To be used as part of the '**No Party**' object when `actionCode` is `SIGN`, `BLANK ENDORSE` or `SURRENDERED`) + example: W3C + partyCode: + type: string + description: | + Code to identify the party as provided by the `codeListProvider` + maxLength: 150 + example: MSK + codeListName: + type: string + maxLength: 100 + description: | + The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be: + - `DID` (Decentralized Identifier) for `codeListProvider` `W3C` + - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF` + - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB` + example: DID + required: + - codeListProvider + - partyCode + TaxLegalReference: + type: object + title: Tax & Legal Reference + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |EORI|NL|Economic Operators Registration and Identification| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + + **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. + example: IN + value: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + required: + - type + - countryCode + - value + ################# + # Error Responses + ################# + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v1/events + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. + type: string + format: date-time + example: '2024-09-04T09:41:00Z' + errors: + type: array + description: | + An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + DetailedError: + type: object + title: Detailed Error + description: | + A detailed description of what has caused the error. + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + minimum: 7000 + maximum: 9999 + example: 7003 + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error. + example: facilityCode + value: + type: string + maxLength: 500 + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + description: | + A standard short description corresponding to the `errorCode`. + type: string + maxLength: 100 + example: invalidData + errorCodeMessage: + type: string + maxLength: 5000 + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + - errorCodeMessage + + SurrenderRequestAnswer: + type: object + title: Surrender Request Answer + description: | + Response to the Surrender Request + properties: + surrenderRequestReference: + type: string + maxLength: 100 + example: Z12345 + pattern: ^\S(?:.*\S)?$ + description: | + The surrender request provided by the eBL solution in the surrender request. + action: + type: string + description: | + Action performed: + - `SURR` (Surrendered) + - `SREJ` (Surrender rejected) + + When the carrier accepts the surrender (`SURR`), the platform will inform the party that submitted the surrender request that the surrender has been accepted. If the surrender is due to an amendment, the carrier will follow up with issuing the amended document to the party that submitted the surrender. The carrier will immediately become the possessor of the bill and can now void it. + + When the carrier rejects the surrender (`SREJ`), the eBL is returned to the party that submitted the surrender request. + enum: + - SURR + - SREJ + example: SURR + comments: + type: string + description: Free text comment associated with the surrender request transaction. Must be provided for rejections but should be omitted when accepting the surrender. + maxLength: 255 + pattern: ^\S(?:.*\S)?$ + example: Comments... + required: + - surrenderRequestReference + - action diff --git a/ovs/v3/OVS_v3.0.2.yaml b/ovs/v3/OVS_v3.0.2.yaml new file mode 100644 index 00000000..be03b79d --- /dev/null +++ b/ovs/v3/OVS_v3.0.2.yaml @@ -0,0 +1,820 @@ +openapi: 3.0.3 +info: + title: Operational Vessel Schedules + description: | +

DCSA OpenAPI specification for Operational Vessel Schedules

+ + The Interface Standards for OVS and other documentation can be found on the [DCSA Website](https://dcsa.org/standards/operational-vessel-schedules/). + + For explanation to specific values or objects please refer to the [Information Model](https://dcsa.org/wp-content/uploads/2024/01/DCSA-Information-Model-2023.Q4.pdf). + + ### Stats API + The Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Operational Vessel Schedules API. Further details can be found [here](https://developer.dcsa.org/#/http/guides/api-guides/stats-api) + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) + + ### Changelog and Contact Us + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v302). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + + API specification issued by [DCSA.org](https://dcsa.org/). + contact: + name: Digital Container Shipping Association (DCSA) + url: https://dcsa.org + email: info@dcsa.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 3.0.2 +tags: + - name: Operational Vessel Schedules + description: ' ' +paths: + /v3/service-schedules: + get: + tags: + - Operational Vessel Schedules + summary: | + Get a list of Schedules + operationId: get-v3-service-schedules + description: | + Get a list of service schedules. The result is `Vessel-Centric` - this means that the `Vessel` is in the top of the hierarchy of the response structure. A service is a heirarchical structure with the following elements: + - One or more `Services` which can contain one or more `Vessels` + - A `Vessel` which can call multiple `Ports` (`TransportCalls`). + - A `Port` (`TransportCall`) can contain one or more `TimeStamps`. + + The number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. + + An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`. + + Be aware that it is possible to specify filters that are mutially exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: + + ``` + &vesselIMONumber=9321483&vesselName=King of the Seas + ``` + + If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list + + If no `startDate` filter is provided then **3 months** prior to the request data is used. If no `endDate` filters is provided then **6 months** after the request date is used. + parameters: + - name: carrierServiceName + in: query + description: | + The carrier service name to filter by. The result will only return schedules including the service name. + schema: + type: string + maxLength: 50 + example: Great Lion Service + - name: carrierServiceCode + in: query + description: | + The carrier specific service code to filter by. The result will only return schedules including the service code. + schema: + type: string + maxLength: 11 + example: FE1 + - name: universalServiceReference + in: query + description: | + The **U**niversal **S**ervice **R**eference (`USR`) as defined by **DCSA** to filter by. The service code must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. The result will only return schedules including the service reference + schema: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + example: SR12345A + - name: vesselIMONumber + in: query + description: | + The identifier of a vessel via the `vesselIMONumber`. The result will only return schedules including the vessel with the specified `vesselIMONumber`. It is not a requirement for dummy vessels to have an `vesselIMONumber`. In this case filtering by `vesselName` should be used. + schema: + type: string + pattern: ^\d{7}$ + maxLength: 7 + example: '9321483' + - name: MMSINumber + in: query + description: | + The identifier of a vessel via the `MMSINumber`. The result will only return schedules including the vessel with the specified `MMSINumber`. It is not a requirement for dummy vessels to have an `MMSINumber`. In this case filtering by `vesselName` should be used. + schema: + type: string + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + example: '278111222' + - name: vesselName + in: query + description: | + The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the `vesselName` is not unique and might match multiple vessels. If possible, filtering by `IMO Number` is preferred. In case of dummy vessels an `IMO Number` might not exist in which case this filter is to be used.' + schema: + type: string + maxLength: 35 + example: King of the Seas + - name: carrierVoyageNumber + in: query + description: | + The carrier specific identifier of a `Voyage` - can be both **importVoyageNumber** and **exportVoyageNumber**. The result will only return schedules including the `Ports` where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber` + schema: + type: string + maxLength: 50 + example: 2103S + - name: universalVoyageReference + in: query + description: | + The Universal Reference of a `Voyage` - can be both **importUniversalVoyageReference** and **exportUniversalVoyageReference**. The result will only return schedules including the `Ports` where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference` + schema: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + maxLength: 5 + example: 2201N + - name: UNLocationCode + in: query + description: | + The `UN Location Code` specifying where a port is located. Specifying this filter will only return schedules including **entire Voyages** related to this particular `UN Location Code`. + schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + - name: facilitySMDGCode + in: query + description: | + The `facilitySMDGCode` specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including **entire Voyages** related to this particular `facilitySMDGCode`. + schema: + type: string + maxLength: 6 + example: APM + - name: vesselOperatorSMDGLinerCode + in: query + description: | + `SMDG` code identifying the carrier operating the vessel. + schema: + type: string + maxLength: 10 + example: MSK + - name: startDate + in: query + description: | + The start date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or after (`≥`) the `startDate` the **entire Voyage** (import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **3 months** prior to request time. + schema: + type: string + format: date + example: '2020-04-06' + - name: endDate + in: query + description: | + The end date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or before (`≤`) the `endDate` the **entire Voyage**(import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **6 months** after request time. + schema: + type: string + format: date + example: '2020-04-10' + - name: limit + in: query + description: | + Specifies the maximum number of `Service Schedules` to include in each page of the response. + schema: + minimum: 0 + type: number + default: 100 + - name: cursor + in: query + description: | + A server-generated value that identifies the next page position in a collection. When `cursor` is provided, it **MUST NOT** be combined with any other query parameters (including `limit`); such parameters will be ignored and MAY result in a `400` error. + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + - name: API-Version + in: header + description: | + From v3.0.1 and onward - every API request and response must contain the API-Version header, set to the full version of the implemented DCSA standard. + schema: + type: string + example: '3.0.1' + responses: + '200': + description: OK + headers: + API-Version: + $ref: '#/components/headers/API-Version' + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + '400': + description: Bad Request + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + noUNLocationCode: + summary: | + UNLocationCode does not exist + value: + httpMethod: GET + requestUri: https://dcsa.org/ovs/v3/service-schedules?UNLocationCode=XX123 + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + erorCodeMessage: UNLocationCode does not exist + '500': + description: Internal Server Error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalError: + summary: + Internal Error + value: + httpMethod: GET + requestUri: https://dcsa.org/ovs/v3/service-schedules + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: [] +components: + schemas: + ServiceSchedule: + type: object + title: Service Schedule + description: | + The timetable of the roundtrip sequence of ports being served by a (number of) vessel(s) on a specific Proforma (schedule). Synonyms are rotation, loop, or string. A Service is defined by rotation, transit times, weekdays of departure per port, and frequencies. + properties: + carrierServiceName: + type: string + maxLength: 50 + description: | + The name of the service. + example: Great Lion Service + carrierServiceCode: + type: string + maxLength: 11 + description: | + The carrier-specific code of the service for which the schedule details are published. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + vesselSchedules: + type: array + items: + $ref: '#/components/schemas/VesselSchedule' + required: + - carrierServiceCode + - carrierServiceName + VesselSchedule: + type: object + title: Vessel Schedule + description: | + The timetable of departure and arrival times for each port call on the rotation of the vessel in question. + properties: + vesselOperatorSMDGLinerCode: + type: string + maxLength: 10 + description: | + The carrier who is in charge of the vessel operation based on the SMDG code. + + If not available at the moment of sharing the schedule, use `TBD` (To be defined). + + In the case an operator is still using a code not from SMDG, use the available code. + example: HLC + vesselIMONumber: + type: string + pattern: ^\d{7}$ + maxLength: 7 + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + + **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties. If `isDummyVessel` is `true` it is optional to provide this property. + + **Condition:** Please note that if the requester is on a version `3.0.0` (indicated by the `APIVersion` being blank or containing the value `3`) and it is not a dummy vessel (`isDummyVessel: false`) then this property **MUST** be present. + example: '9321483' + MMSINumber: + type: string + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + description: | + Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station. + + **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties. If `isDummyVessel` is `true` it is optional to provide this property. + + **Condition:** It is only possible to use this property in case the requester is on version `3.0.1` or later or `vesselIMONumber` is also provided. In case the requester is on version `3.0.0` (indicated by the `APIVersion` header being blank or containing the value `3`) - this property cannot be used unless `vesselIMONumber` is also present. + example: '278111222' + vesselName: + type: string + maxLength: 35 + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + + **Note:** In case the vessel is a "dummy vessel" (`isDummyVessel='true'`) then the following recommendations should be followed: + + Dummy vessel names should begin with the **SMDG Operating Carrier Code** to ensure uniqueness across carriers. + The suffix can be **alphanumeric** and up to **10 characters long**, allowing each carrier to use internal naming conventions (e.g., `MSKTBN1`, `CMATEMP01`, `MSCX01A`). + + This approach: + - Ensures consistency and uniqueness across carriers + - Allows flexibility in local implementations + - Avoids the need to assign dummy IMO numbers + - Maintains the role of the dummy vessel name as a **stable and persistent identifier** throughout the planning process + example: King of the Seas + vesselCallSign: + type: string + maxLength: 10 + description: | + A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a threeletter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + example: NCVV + isDummyVessel: + type: boolean + description: | + Is this a dummy vessel? In case no vessel has been assigned yet - this property can be set to `true` indicating that the `vesselIMONumber`/`MMSINumber` does not exist. + + When `true`, the `vesselName` must be used as a unique identifier for the dummy vessel. See the `vesselName` field description for the recommended naming convention. + transportCalls: + type: array + items: + $ref: '#/components/schemas/TransportCall' + required: + - isDummyVessel + - vesselOperatorSMDGLinerCode + TransportCall: + type: object + title: Transport Call + description: | + A transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall. + + The order of the list is the sequence of the list + properties: + portVisitReference: + type: string + maxLength: 50 + description: | + The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call + example: NLAMS1234589 + transportCallReference: + type: string + maxLength: 100 + description: | + The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + carrierImportVoyageNumber: + type: string + maxLength: 50 + description: | + The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + + **Note:** In case the `carrierImportVoyageNumber` is not known, `9999R` should be interpreted as "no voyage number". The value `9999R` is reserved as a placeholder and **MUST NOT** be used for real voyage numbers. + example: 2103N + carrierExportVoyageNumber: + type: string + maxLength: 50 + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + example: 2103S + universalImportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + location: + description: | + General purpose object to capture location-related data, the location can be specified in **one** of the following ways: `UN Location Code`, a `Facility` or an `Address`. + discriminator: + propertyName: locationType + mapping: + UNLO: "#/components/schemas/UNLocationLocation" + FACS: "#/components/schemas/FacilitySMDGLocation" + ADDR: "#/components/schemas/AddressLocation" + oneOf: + - $ref: '#/components/schemas/UNLocationLocation' + - $ref: '#/components/schemas/FacilitySMDGLocation' + - $ref: '#/components/schemas/AddressLocation' + statusCode: + type: string + description: | + The set of codes in `Status Code` are ONLY meant to communicate any change / exception to the published schedule. This is not required in case of normal schedule. Possible values are: + + - `OMIT` (Omit) + - `BLNK` (Blank) + - `ADHO` (Ad Hoc) + - `PHOT` (Phase Out) + - `PHIN` (Phase In) + - `SLID` (Sliding) + - `ROTC` (Rotation Change) + - `CUTR` (Cut and Run) + + **Deprecated:** Use `statusCodes` instead. If `statusCodes` is used - then values in this property are ignored. + deprecated: true + example: OMIT + statusCodes: + type: array + description: | + Possibility to add multiple status codes to a `TransportCall`. + + **Note:** This property takes precedence over `statusCode` (if both are present - only the ones provided in this property are used). + items: + type: string + description: | + The set of codes are ONLY meant to communicate any change / exception to the published schedule. This is not required in case of normal schedule. Possible values are: + + - `OMIT` (Omit) + - `BLNK` (Blank) + - `ADHO` (Ad Hoc) + - `PHOT` (Phase Out) + - `PHIN` (Phase In) + - `SLID` (Sliding) + - `ROTC` (Rotation Change) + - `CUTR` (Cut and Run) + - `DRYD` (Dry Dock) + - `BUNK` (Bunkering) + - `OOSV` (Out of service) + example: OMIT + timestamps: + type: array + items: + $ref: '#/components/schemas/Timestamp' + required: + - carrierImportVoyageNumber + - transportCallReference + UNLocationLocation: + type: object + title: UN Location + description: | + An interface used to express a location using a `Un Location Code`. + properties: + locationName: + type: string + pattern: ^\S+(\s+\S+)*$ + maxLength: 100 + description: | + The name of the location. + example: Port of Amsterdam + locationType: + type: string + maxLength: 4 + description: | + Discriminator used to identify this as a `UNLocation` location interface. + example: UNLO + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + required: + - UNLocationCode + - locationType + FacilitySMDGLocation: + type: object + title: Facility SMDG Location + description: | + An interface used to express a location using a `Facility` by the `SMDG` code list. The `facilitySMDGCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + properties: + locationName: + type: string + maxLength: 100 + description: | + The name of the location. + example: Port of Amsterdam + locationType: + type: string + maxLength: 4 + description: | + Discriminator used to identify this as a `Facility Location` interface only using `SMDG` code list. + example: FACS + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE) + example: NLAMS + facilitySMDGCode: + type: string + maxLength: 6 + description: | + The code used for identifying the specific facility. This code does not include the UN Location Code. + + The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx) + example: ACT + required: + - UNLocationCode + - facilitySMDGCode + - locationType + AddressLocation: + type: object + title: Address Location + description: | + An interface used to express a location using an `Address` object. + properties: + locationName: + type: string + maxLength: 100 + description: | + The name of the location. + example: Port of Amsterdam + locationType: + type: string + maxLength: 4 + description: | + Discriminator used to identify this as an `Address` location interface. + example: ADDR + address: + type: object + description: An object for storing address related information. + properties: + name: + maxLength: 100 + type: string + description: Name of the address. + example: John + street: + maxLength: 100 + type: string + description: The name of the street of the party’s address. + example: Ruijggoordweg + streetNumber: + maxLength: 50 + type: string + description: The number of the street of the party’s address. + example: '100' + floor: + maxLength: 50 + type: string + description: The floor of the party’s street number. + example: N/A + postCode: + maxLength: 50 + type: string + description: The post code of the party’s address. + example: 1047 HM + city: + maxLength: 65 + type: string + description: The city name of the party’s address. + example: Amsterdam + stateRegion: + maxLength: 65 + type: string + description: The state/region of the party’s address. + example: North Holland + country: + maxLength: 75 + type: string + description: The country of the party’s address. + example: The Netherlands + required: + - name + required: + - address + - locationType + Timestamp: + type: object + title: Timestamp + description: | + A timestamp for a port. + properties: + eventTypeCode: + type: string + description: | + Identifier for type of `transportEvent` + - `ARRI` (Arrived) + - `DEPA` (Departed) + enum: + - ARRI + - DEPA + example: ARRI + eventClassifierCode: + type: string + description: | + Code for the event classifier. Values can vary depending on eventType. + + - **Actual:** The **recorded time** when the event has actually occurred. + - **Estimated:** The updated schedule time based on the **latest regional or coastal schedule (RS/CS)**. It reflects the most up-to-date estimated time as the voyage progresses and can be updated (weekly or daily) several times after the voyage start. + - **Planned:** The scheduled time based on the **long-term service plan** (LTS), published well in advance (typically 12-14 weeks) before the voyage begins, and showing when an event *is planned* to occur. + + More information can be found in the OVS Definitions document. Possible value codes: + - `ACT` (Actual) + - `EST` (Estimated) + - `PLN` (Planned) + enum: + - PLN + - EST + - ACT + example: EST + eventDateTime: + type: string + format: date-time + description: | + Time in the timestamp. + example: '2025-01-14T09:21:00+01:00' + delayReasonCode: + type: string + maxLength: 3 + description: | + Reason code for the delay. See SMDG [Code list DELAY](https://smdg.org/documents/smdg-code-lists/delay-reason-and-port-call-activity/) for a list of valid codes to be used for this attribute. + + **Deprecated:** Use `delayReasonCodes` instead. If `delayReasonCodes` is used - then values in this property are ignored. + deprecated: true + example: WEA + delayReasonCodes: + type: array + description: | + Possibility to add multiple delay reason codes to a `Timestamp`. + + **Note:** This property takes precedence over `delayReasonCode` (if both are present - only the ones provided in this property are used). + items: + type: string + maxLength: 3 + description: | + Reason code for the delay. See SMDG [Code list DELAY](https://smdg.org/documents/smdg-code-lists/delay-reason-and-port-call-activity/) for a list of valid codes to be used for this attribute. + example: WEA + changeRemark: + type: string + maxLength: 250 + description: | + Free text field to provide information as to why the `TransportEvent` was sent. + example: Bad weather + required: + - eventClassifierCode + - eventDateTime + - eventTypeCode + ErrorResponse: + type: object + title: Error Response + description: | + Unexpected error + properties: + httpMethod: + type: string + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + example: POST + requestUri: + type: string + description: | + The URI that was requested. + example: /v1/events + statusCode: + type: integer + format: int32 + description: | + The HTTP status code returned. + example: 400 + statusCodeText: + type: string + maxLength: 50 + description: | + A standard short description corresponding to the HTTP status code. + example: Bad Request + statusCodeMessage: + type: string + maxLength: 200 + description: | + A long description corresponding to the HTTP status code with additional information. + example: The supplied data could not be accepted + providerCorrelationReference: + type: string + maxLength: 100 + description: | + A unique identifier to the HTTP request within the scope of the API provider. + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + type: string + description: | + The DateTime corresponding to the error occuring. + format: date-time + example: 2019-11-12T07:41:00+08:30 + errors: + type: array + description: | + An array of errors provding more detail about the root cause. + items: + $ref: "#/components/schemas/DetailedError" + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + DetailedError: + type: object + title: Detailed Error + description: | + A detailed object used to describe the error. + properties: + errorCode: + maximum: 9999 + minimum: 7000 + type: integer + description: "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://dcsa.atlassian.net/wiki/spaces/DTG/pages/197132308/Standard+Error+Codes).\n" + format: int32 + example: 7003 + property: + maxLength: 100 + type: string + description: | + The name of the property causing the error. + example: facilityCode + value: + maxLength: 500 + type: string + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + maxLength: 500 + type: string + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + maxLength: 100 + type: string + description: | + A standard short description corresponding to the `errorCode`. + example: invalidData + erorCodeMessage: + maxLength: 200 + type: string + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + required: + - errorCodeText + headers: + API-Version: + description: | + SemVer used to indicate the version of the contract (API version) returned. + schema: + type: string + example: 3.0.0