diff --git a/ebl/v3/EBL_v3.0.2.yaml b/ebl/v3/EBL_v3.0.2.yaml new file mode 100644 index 000000000..81f0eb49c --- /dev/null +++ b/ebl/v3/EBL_v3.0.2.yaml @@ -0,0 +1,8828 @@ +openapi: 3.0.3 +info: + version: 3.0.2 + 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#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/). + 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 + 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 + transportDocument: + transportDocumentReference: HHL71800000 + 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 + 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 + 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 + 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` (Transport Document is Drafted) + - `APPROVED` (Transport Document has been Approved by consumer) + - `ISSUED` (Transport Document has been Issued by provider) + - `PENDING_SURRENDER_FOR_AMENDMENT` (Transport Document is Pending for Surrender for an Amendment) + - `SURRENDER_FOR_AMENDMENT` (Transport Document Surrendered for an Amendment) + - `VOID` (the Transport Document has been Voided) + - `PENDING_SURRENDER_FOR_DELIVERY` (Transport Document pending surrender for Delivery) + - `SURRENDER_FOR_DELIVERY` (Transport Document 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 + 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) + 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) + 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' + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + 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' + 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) + 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) + 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' + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + 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' + 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) + 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) + 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' + placeOfIssue: + $ref: '#/components/schemas/PlaceOfIssue' + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAtShippingInstructions' + 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' + 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) + 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) + 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: Geographic coordinate that specifies the north–south position of a point on the Earth's surface. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: Geographic coordinate that specifies the east–west position of a point on the Earth's surface. + 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) + 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 + - 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 + + 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 + - 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 + + 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 + - 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 + - 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 + - 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 to whom the `Bill of Lading` must be issued. + 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) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + + **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 + - 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 + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `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) + 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) + 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) + 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) + 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 + 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 + 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` (Transport Document is Drafted) + - `APPROVED` (Transport Document has been Approved by consumer) + - `ISSUED` (Transport Document has been Issued by provider) + - `PENDING_SURRENDER_FOR_AMENDMENT` (Transport Document is Pending for Surrender for an Amendment) + - `SURRENDERED_FOR_AMENDMENT` (Transport Document Surrendered for an Amendment) + - `PENDING_SURRENDER_FOR_DELIVERY` (Transport Document pending surrender for Delivery) + - `SURRENDERED_FOR_DELIVERY` (Transport Document 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) + 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) + 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' + 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 + 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) + 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' + consignee: + $ref: '#/components/schemas/ConsigneeShipper' + 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' + consignee: + $ref: '#/components/schemas/Consignee' + 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/issuance/EBL_ISS_v3.0.1.yaml b/ebl/v3/issuance/EBL_ISS_v3.0.1.yaml new file mode 100644 index 000000000..ab6f7b7c4 --- /dev/null +++ b/ebl/v3/issuance/EBL_ISS_v3.0.1.yaml @@ -0,0 +1,3466 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_ISS/3.0.1' +info: + version: 3.0.1 + 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.1) 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#v301). 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.1 + 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. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + 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. + # 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 + properties: + name: + type: string + maxLength: 100 + 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 to whom the electronic Bill of Lading (eBL) must be issued. + 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) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + 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 + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `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) + 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 + - APPROVED + - ISSUED + - PENDING_SURRENDER_FOR_AMENDMENT + - SURRENDERED_FOR_AMENDMENT + - PENDING_SURRENDER_FOR_DELIVERY + - SURRENDERED_FOR_DELIVERY + - 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) + 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) + 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' + 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) + 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) + 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 + 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) + 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) + 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: Geographic coordinate that specifies the north–south position of a point on the Earth's surface. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: Geographic coordinate that specifies the east–west position of a point on the Earth's surface. + 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) + 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 + - 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 + + 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 + - 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 + + 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 + - 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 + - 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 + 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 + 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) + 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' + consignee: + $ref: '#/components/schemas/Consignee' + 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/issuance/EBL_ISS_v3.0.2.yaml b/ebl/v3/issuance/EBL_ISS_v3.0.2.yaml new file mode 100644 index 000000000..d497ec2ba --- /dev/null +++ b/ebl/v3/issuance/EBL_ISS_v3.0.2.yaml @@ -0,0 +1,3466 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_ISS/3.0.2' +info: + version: 3.0.2 + 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#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/). + 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. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + 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. + # 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 + properties: + name: + type: string + maxLength: 100 + 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 to whom the electronic Bill of Lading (eBL) must be issued. + 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) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + 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 + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `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) + 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 + - APPROVED + - ISSUED + - PENDING_SURRENDER_FOR_AMENDMENT + - SURRENDERED_FOR_AMENDMENT + - PENDING_SURRENDER_FOR_DELIVERY + - SURRENDERED_FOR_DELIVERY + - 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) + 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) + 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' + 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) + 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) + 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 + 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) + 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) + 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: Geographic coordinate that specifies the north–south position of a point on the Earth's surface. + maxLength: 10 + example: '48.8585500' + longitude: + type: string + description: Geographic coordinate that specifies the east–west position of a point on the Earth's surface. + 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) + 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 + - 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 + + 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 + - 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 + + 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 + - 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 + - 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 + 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 + 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) + 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' + consignee: + $ref: '#/components/schemas/Consignee' + 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.1.yaml b/ebl/v3/surrender/EBL_SUR_v3.0.1.yaml new file mode 100644 index 000000000..bd31a2214 --- /dev/null +++ b/ebl/v3/surrender/EBL_SUR_v3.0.1.yaml @@ -0,0 +1,558 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_SUR/3.0.1' +info: + version: 3.0.1 + 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#v301). 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.1 + 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: + TransactionParty: + type: object + title: Transaction Party + description: Refers to a company or a legal entity. + properties: + eblPlatform: + 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) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + 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' + required: + - partyName + - eblPlatform + - identifyingCodes + EndorsementChainLink: + type: object + title: Endorsement Chain Link + 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 party. This should be one of: + - `ISSUE` (The actor issued the document to the recipient) + - `ENDORSE` (The actor endorsed the document to the recipient) + - `SIGN` (The actor signed or performed an "assignment" to the recipient) + - `SURRENDER_FOR_DELIVERY` (The actor requested this surrender request for delivery to the recipient) + - `SURRENDER_FOR_AMENDMENT` (The actor requested this surrender request for amendment to the recipient) + Not all actions are applicable to all surrender requests. + example: ISSUE + actor: + $ref: '#/components/schemas/TransactionParty' + recipient: + $ref: '#/components/schemas/TransactionParty' + description: | + Entry in the endorsement chain. + 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:\n-\t`SWTP` (Switch to paper)\n" + example: SWTP + comments: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 255 + description: Optional free text comment associated with the surrender request transaction. + example: As requested... + endorsementChain: + type: array + description: | + A list of one or more endorsement related actions that were performed on or after the issuance of the eBL. It is equivalent to the "back side" of the 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 i.e. making the eBL available to the receiver. + - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a specific named party, allowing them to claim or deal with the goods. The user in control of the eBL may endorse the eBL in their turn to another named party. Only applicable to To-Order eBL (`isToOrder=true`). + - **Sign:** A general-purpose signature that can be used by any party to mark their possession of the eBL. Similar to how any possessor in the physical world can put a physical signature on the paper bill of lading. The endorsement chain as defined by DCSA does not record any transfer of possession of the eBL, unless a signature is added to it. + - **Request surrender for amendment:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of amending the eBL. + - **Request surrender for delivery:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of claiming delivery of the goods. + + **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 + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `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 + 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) + 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. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + 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 + 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/ebl/v3/surrender/EBL_SUR_v3.0.2.yaml b/ebl/v3/surrender/EBL_SUR_v3.0.2.yaml new file mode 100644 index 000000000..83ffb057d --- /dev/null +++ b/ebl/v3/surrender/EBL_SUR_v3.0.2.yaml @@ -0,0 +1,558 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_SUR/3.0.2' +info: + version: 3.0.2 + 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#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/). + 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: + TransactionParty: + type: object + title: Transaction Party + description: Refers to a company or a legal entity. + properties: + eblPlatform: + 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) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + 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' + required: + - partyName + - eblPlatform + - identifyingCodes + EndorsementChainLink: + type: object + title: Endorsement Chain Link + 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 party. This should be one of: + - `ISSUE` (The actor issued the document to the recipient) + - `ENDORSE` (The actor endorsed the document to the recipient) + - `SIGN` (The actor signed or performed an "assignment" to the recipient) + - `SURRENDER_FOR_DELIVERY` (The actor requested this surrender request for delivery to the recipient) + - `SURRENDER_FOR_AMENDMENT` (The actor requested this surrender request for amendment to the recipient) + Not all actions are applicable to all surrender requests. + example: ISSUE + actor: + $ref: '#/components/schemas/TransactionParty' + recipient: + $ref: '#/components/schemas/TransactionParty' + description: | + Entry in the endorsement chain. + 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:\n-\t`SWTP` (Switch to paper)\n" + example: SWTP + comments: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 255 + description: Optional free text comment associated with the surrender request transaction. + example: As requested... + endorsementChain: + type: array + description: | + A list of one or more endorsement related actions that were performed on or after the issuance of the eBL. It is equivalent to the "back side" of the 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 i.e. making the eBL available to the receiver. + - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a specific named party, allowing them to claim or deal with the goods. The user in control of the eBL may endorse the eBL in their turn to another named party. Only applicable to To-Order eBL (`isToOrder=true`). + - **Sign:** A general-purpose signature that can be used by any party to mark their possession of the eBL. Similar to how any possessor in the physical world can put a physical signature on the paper bill of lading. The endorsement chain as defined by DCSA does not record any transfer of possession of the eBL, unless a signature is added to it. + - **Request surrender for amendment:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of amending the eBL. + - **Request surrender for delivery:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of claiming delivery of the goods. + + **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 + properties: + codeListProvider: + type: string + maxLength: 100 + description: | + A list of codes identifying a party. Possible values are: + - `WAVE` (Wave) + - `CARX` (CargoX) + - `ESSD` (EssDOCS) + - `IDT` (ICE Digital Trade) + - `BOLE` (Bolero) + - `EDOX` (EdoxOnline) + - `IQAX` (IQAX) + - `SECR` (Secro) + - `TRGO` (TradeGO) + - `ETEU` (eTEU) + - `TRAC` (Enigio trace:original) + - `BRIT` (BRITC eBL) + - `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 + 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) + 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. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + 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 + 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