From e2cfc2d904c6d164566d1230beb60fdffce9c220 Mon Sep 17 00:00:00 2001 From: "J. Koster" Date: Mon, 11 Nov 2024 09:51:02 +0100 Subject: [PATCH] SD-1575 Convert schemas from JSON to YAML (#218) * Convert all JSON schemas to YAML, except for JIT which will be addressed later. * For CS and OVS: I needed to manually add an array of objects, to get it working. * Upgraded the library json-schema-validator to the latest version --- .../adoption/AdoptionComponentFactory.java | 2 +- .../adoption/schemas/ADOPT_v1.0.0.yaml | 311 + .../adoption-1.0.0_with_push-resolved.json | 371 - .../booking/BookingComponentFactory.java | 3 +- .../booking/BookingScenarioListBuilder.java | 5 +- .../messages/booking-api-2.0.0-dg.json | 2 + .../standards/booking/schemas/BKG_v2.0.0.yaml | 6582 +++++++++++++ .../standards/cs/CsComponentFactory.java | 10 +- .../standards/cs/CsScenarioListBuilder.java | 7 +- .../schemas/CS_v1.0.0.yaml | 1767 ++++ .../schemas/commercialschedules-api-v10.json | 2056 ---- core/pom.xml | 2 +- .../core/check/JsonSchemaValidator.java | 71 +- .../core/check/JsonSchemaValidatorTest.java | 36 +- .../resources/examples/booking-request.json | 10 +- .../examples/booking-request_with_errors.json | 88 + .../resources/schemas/booking-api-v20.json | 7620 --------------- .../dcsaorg-DCSA_BKG-2.0.0-resolved.json | 2449 ++--- .../dcsaorg-DCSA_BKG-2.0.0-resolved.yaml | 6376 +++++++++++++ .../EblIssuanceComponentFactory.java | 2 +- .../eblissuance/schemas/EBL_ISS_v3.0.0.yaml | 3458 +++++++ .../schemas/eblissuance-v3.0.0.json | 3154 ------ .../EblSurrenderComponentFactory.java | 2 +- .../party/EblSurrenderCarrier.java | 14 + .../eblsurrender/schemas/EBL_SUR_v3.0.0.yaml | 557 ++ .../schemas/eblsurrender-v3.0.0.json | 535 -- .../standards/ebl/EblScenarioListBuilder.java | 3 +- .../models/CarrierShippingInstructions.java | 2 +- .../ebl/messages/ebl-api-3.0.0-2c2u1e.json | 8 + .../ebl/messages/ebl-api-3.0.0-2c2u2e.json | 8 + .../ebl/messages/ebl-api-3.0.0-amf.json | 8 + .../ebl/messages/ebl-api-3.0.0-clad.json | 8 + .../ebl/messages/ebl-api-3.0.0-dg.json | 9 + .../messages/ebl-api-3.0.0-negotiable-bl.json | 8 + ...l-api-3.0.0-no-commodity-subreference.json | 8 + .../ebl/messages/ebl-api-3.0.0-request.json | 8 + .../ebl-api-3.0.0-soc-references.json | 8 + .../standards/ebl/schemas/EBL_v3.0.0.yaml | 8473 +++++++++++++++++ .../standards/ebl/schemas/ebl-api-3.0.0.json | 7982 ---------------- .../standards/ovs/OvsComponentFactory.java | 6 +- .../standards/ovs/schemas/OVS_v3.0.0.yaml | 560 ++ .../ovs/schemas/ovs-300-publisher.json | 832 -- .../eblinterop/PintScenarioListBuilder.java | 2 +- .../pint/schemas/EBL_PINT_v3.0.0.yaml | 3960 ++++++++ .../standards/pint/schemas/pint-3.0.0.json | 3677 ------- .../conformance/frontend/SeleniumTest.java | 5 +- .../standards/tnt/TntComponentFactory.java | 2 +- .../standards/tnt/party/AttributeMapping.java | 2 +- .../tnt/party/QueryParameterSpecificRule.java | 13 +- .../tnt/schemas/TNT_v2.2.0-resolved.yaml | 2613 +++++ .../tnt/schemas/tnt-220-publisher.json | 3344 ------- 51 files changed, 35789 insertions(+), 31250 deletions(-) create mode 100644 adoption/src/main/resources/standards/adoption/schemas/ADOPT_v1.0.0.yaml delete mode 100644 adoption/src/main/resources/standards/adoption/schemas/adoption-1.0.0_with_push-resolved.json create mode 100644 booking/src/main/resources/standards/booking/schemas/BKG_v2.0.0.yaml create mode 100644 commercial-schedules/src/main/resources/standards/commercialschedules/schemas/CS_v1.0.0.yaml delete mode 100644 commercial-schedules/src/main/resources/standards/commercialschedules/schemas/commercialschedules-api-v10.json create mode 100644 core/src/test/resources/examples/booking-request_with_errors.json delete mode 100644 core/src/test/resources/schemas/booking-api-v20.json rename booking/src/main/resources/standards/booking/schemas/booking-api-v20.json => core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json (84%) create mode 100644 core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.yaml create mode 100644 ebl-issuance/src/main/resources/standards/eblissuance/schemas/EBL_ISS_v3.0.0.yaml delete mode 100644 ebl-issuance/src/main/resources/standards/eblissuance/schemas/eblissuance-v3.0.0.json create mode 100644 ebl-surrender/src/main/resources/standards/eblsurrender/schemas/EBL_SUR_v3.0.0.yaml delete mode 100644 ebl-surrender/src/main/resources/standards/eblsurrender/schemas/eblsurrender-v3.0.0.json create mode 100644 ebl/src/main/resources/standards/ebl/schemas/EBL_v3.0.0.yaml delete mode 100644 ebl/src/main/resources/standards/ebl/schemas/ebl-api-3.0.0.json create mode 100644 ovs/src/main/resources/standards/ovs/schemas/OVS_v3.0.0.yaml delete mode 100644 ovs/src/main/resources/standards/ovs/schemas/ovs-300-publisher.json create mode 100644 pint/src/main/resources/standards/pint/schemas/EBL_PINT_v3.0.0.yaml delete mode 100644 pint/src/main/resources/standards/pint/schemas/pint-3.0.0.json create mode 100644 tnt/src/main/resources/standards/tnt/schemas/TNT_v2.2.0-resolved.yaml delete mode 100644 tnt/src/main/resources/standards/tnt/schemas/tnt-220-publisher.json diff --git a/adoption/src/main/java/org/dcsa/conformance/standards/adoption/AdoptionComponentFactory.java b/adoption/src/main/java/org/dcsa/conformance/standards/adoption/AdoptionComponentFactory.java index fd2038ee..f7162de7 100644 --- a/adoption/src/main/java/org/dcsa/conformance/standards/adoption/AdoptionComponentFactory.java +++ b/adoption/src/main/java/org/dcsa/conformance/standards/adoption/AdoptionComponentFactory.java @@ -114,7 +114,7 @@ public Set getReportRoleNames( public JsonSchemaValidator getMessageSchemaValidator() { String schemaFilePath = - "/standards/adoption/schemas/adoption-%s_with_push-resolved.json" + "/standards/adoption/schemas/ADOPT_v%s.yaml" .formatted(standardVersion); return JsonSchemaValidator.getInstance(schemaFilePath, "AdoptionStats"); } diff --git a/adoption/src/main/resources/standards/adoption/schemas/ADOPT_v1.0.0.yaml b/adoption/src/main/resources/standards/adoption/schemas/ADOPT_v1.0.0.yaml new file mode 100644 index 00000000..086e31de --- /dev/null +++ b/adoption/src/main/resources/standards/adoption/schemas/ADOPT_v1.0.0.yaml @@ -0,0 +1,311 @@ +openapi: 3.0.3 +info: + title: DCSA Adoption API + description: | + Meta-API with which container shipping organizations can share statistics on their adoption of DCSA standards. + contact: + name: Digital Container Shipping Association (DCSA) + url: https://dcsa.org/ + email: info@dcsa.org + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 1.0.0 +paths: + /v1/adoption-stats: + get: + summary: Retrieve adoption statistics (DCSA to call "Adopter" endPoint) + description: | + Retrieve the adoption statistics, currently the number of API calls by DCSA standard, version, traffic-direction, endpoint, query parameter set and response status. + + **Note:** This endPoint is to be implemented on "adopter" side and for DCSA to call + operationId: get-adoption-stats + parameters: + - name: interval + in: query + description: | + The type of interval for which to retrieve statistics: + - `day` (one day) + - `week` (one calendar week) + - `month`(one calendar month) + required: true + style: form + explode: true + schema: + type: string + enum: + - day + - week + - month + example: week + - name: date + in: query + description: | + The date (or any date within the calendar week or month) for which to return the statistics, in YYYY-MM-DD format. + required: true + schema: + type: string + format: date + example: '2024-06-21' + - $ref: '#/components/parameters/Api-Version-Major' + responses: + '200': + description: | + A successful response containing the adoption statistics. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/AdoptionStats' + '400': + description: | + Invalid request parameters. + '500': + description: | + Internal server error. + put: + summary: Send (Push) adoption statistics (DCSA endPoint) + description: | + Send (Push) the adoption statistics, currently the number of API calls by DCSA standard, version, traffic-direction, endpoint, query parameter set and response status. + + **Note:** This endPoint is for DCSA to implement and for the adopter to call + operationId: put-adoption-stats + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + The adoption statistics being pushed by the adopter to DCSA. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AdoptionStats' + responses: + '204': + description: '' + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '400': + description: | + Invalid request. + '500': + description: | + Internal server error. + +components: + headers: + API-Version: + schema: + type: string + example: 1.0.0 + 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: '1' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + schemas: + AdoptionStats: + type: object + properties: + lastUpdatedDateTime: + type: string + format: date-time + description: | + The DateTime when the stats were last updated. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + example: '2024-06-18T20:44:37+01:00' + interval: + type: string + description: | + The type of interval for the statistics are provided (day, week, or month). + enum: + - day + - week + - month + example: week + startDate: + type: string + format: date + description: | + The first date of the time interval for which the stats are provided, in YYYY-MM-DD format. + example: '2024-06-16' + endDate: + type: string + format: date + description: | + The last date of the time interval for which the stats are provided, in YYYY-MM-DD format. + example: '2024-06-22' + apiCallsStatsByStandards: + type: array + minItems: 1 + description: | + The API call statistics by DCSA standard, version, traffic-direction, endpoint, query parameter set and response HTTP status. + items: + $ref: '#/components/schemas/ApiCallsStandardStats' + required: + - lastUpdatedDateTime + - interval + - startDate + - endDate + - apiCallsStatsByStandards + ApiCallsStandardStats: + type: object + description: | + The API calls statistics for one DCSA standard. + properties: + standardName: + type: string + maxLength: 20 + description: | + Name of the DCSA standard. + - `AN` (Arrival Notice) + - `BKG` (Booking) + - `CBF` (Consolidated Booking Forecast) + - `CRO` (Container Release Order) + - `CS` (Commercial Schedules) + - `DI` (Delivery Instruction) + - `DO` (Delivery Order) + - `EBL` (Electronic Bill of Lading) + - `EBL_ISS` (Electronic Bill of Lading Issuance) + - `EBL_SUR` (Electronic Bill of Lading Surrender) + - `IC` (IoT Commercial) + - `IO` (IoT Operations) + - `JIT` (Just In Time Portcall) + - `OVS` (Operational Vessel Schedules) + - `RMC` (Reefer Monitoring Commercial) + - `RMO` (Operational Reefer Monitoring) + - `TNT` (Track and Trace) + - `TO` (Transport Order) + example: TNT + byVersions: + type: array + minItems: 1 + description: | + The API calls statistics for each version of this DCSA standard. + items: + $ref: '#/components/schemas/ApiCallsVersionStats' + required: + - standardName + - byVersions + ApiCallsVersionStats: + type: object + description: | + The API calls statistics for each version of a DCSA standard. + properties: + versionNumber: + type: string + maxLength: 50 + description: | + The version number of the DCSA standard. + example: 2.2.0 + byInboundEndpoints: + type: array + description: | + The statistics of the API calls received on each inbound endpoint of a standard. + + If no `inbound` traffic has been recorded the empty list should be returned + items: + $ref: '#/components/schemas/ApiCallsEndpointStats' + byOutboundEndpoints: + type: array + description: | + The statistics of the API calls made to each outbound endpoint of a standard. + + If no `outbound` traffic has been recorded the empty list should be returned + items: + $ref: '#/components/schemas/ApiCallsEndpointStats' + required: + - versionNumber + - byInboundEndpoints + - byOutboundEndpoints + ApiCallsEndpointStats: + type: object + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - POST + - PUT + - DELETE + - PATCH + endpointUri: + type: string + description: | + The URI of the OpenAPI endpoint on which these calls are made / received. + example: /v1/events + byQueryParameterSets: + type: array + minItems: 1 + description: | + The API calls statistics by the request query parameter set. + items: + $ref: '#/components/schemas/ApiCallsQueryParameterSetStats' + required: + - httpMethod + - endpointUri + - byQueryParameterSets + ApiCallsQueryParameterSetStats: + type: object + properties: + queryParameterSet: + type: array + description: | + The list of query parameters used for a call. If none have been supplied this property should be omitted. + example: + - equipmentReference + - limit + items: + type: string + description: | + Name of a queryParameter + maxLength: 50 + byHttpStatuses: + type: array + minItems: 1 + description: | + The API calls statistics by the HTTP status with which they were responded. + items: + $ref: '#/components/schemas/ApiCallsHttpStatusStats' + required: + - byHttpStatuses + ApiCallsHttpStatusStats: + type: object + properties: + httpStatusCode: + type: integer + description: | + The HTTP status code with which these API calls were responded. + example: 200 + apiCallCount: + type: integer + description: | + The number of API calls for this DCSA standard, version, direction, endpoint, query parameter set and response status. + example: 5400 + uniqueCounterpartCount: + type: integer + description: | + The number of unique counterparts with which these calls were exchanged. If the value cannot be provided a `0` should be returned. + example: 320 + averageResponseTime: + type: integer + description: | + The average response time of these calls, in milliseconds. If the value cannot be provided a `0` should be returned. + example: 1250 + required: + - httpStatusCode + - apiCallCount + - uniqueCounterpartCount + - averageResponseTime diff --git a/adoption/src/main/resources/standards/adoption/schemas/adoption-1.0.0_with_push-resolved.json b/adoption/src/main/resources/standards/adoption/schemas/adoption-1.0.0_with_push-resolved.json deleted file mode 100644 index 2f8969a1..00000000 --- a/adoption/src/main/resources/standards/adoption/schemas/adoption-1.0.0_with_push-resolved.json +++ /dev/null @@ -1,371 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA Adoption API", - "description": "Meta-API with which container shipping organizations can share statistics on their adoption of DCSA standards.\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org/", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "1.0.0_with_push" - }, - "servers": [ - { - "url": "/" - } - ], - "paths": { - "/v1/adoption-stats": { - "get": { - "summary": "Retrieve adoption statistics (DCSA to call \"Adopter\" endPoint)", - "description": "Retrieve the adoption statistics, currently the number of API calls by DCSA standard, version, traffic-direction, endpoint, query parameter set and response status.\n\n**Note:** This endPoint is to be implemented on \"adopter\" side and for DCSA to call\n", - "operationId": "get-adoption-stats", - "parameters": [ - { - "name": "interval", - "in": "query", - "description": "The type of interval for which to retrieve statistics:\n- `day` (per day)\n- `week` (per week)\n- `month`(per month)\n", - "required": true, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "example": "month", - "enum": [ - "day", - "week", - "month" - ] - } - }, - { - "name": "date", - "in": "query", - "description": "The date (or any date within the week or month interval) for which to return the statistics, in YYYY-MM-DD format.\n", - "required": true, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2024-06-21" - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "A successful response containing the adoption statistics.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AdoptionStats" - } - } - } - }, - "400": { - "description": "Invalid request parameters.\n" - }, - "500": { - "description": "Internal server error.\n" - } - } - }, - "put": { - "summary": "Send (Push) adoption statistics (DCSA endPoint)", - "description": "Send (Push) the adoption statistics, currently the number of API calls by DCSA standard, version, traffic-direction, endpoint, query parameter set and response status.\n\n**Note:** This endPoint is for DCSA to implement and for the adopter to call\n", - "operationId": "put-adoption-stats", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "requestBody": { - "description": "The adoption statistics being pushed by the adopter to DCSA.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AdoptionStats" - } - } - }, - "required": true - }, - "responses": { - "204": { - "description": "", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - } - }, - "400": { - "description": "Invalid request.\n" - }, - "500": { - "description": "Internal server error.\n" - } - } - } - } - }, - "components": { - "schemas": { - "AdoptionStats": { - "required": [ - "apiCallsStatsByStandards", - "endDate", - "interval", - "lastUpdatedDateTime", - "startDate" - ], - "type": "object", - "properties": { - "lastUpdatedDateTime": { - "type": "string", - "description": "The DateTime when the stats were last updated. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.\n", - "format": "date-time", - "example": "2024-06-18T20:44:37+01:00" - }, - "interval": { - "type": "string", - "description": "The type of interval for the statistics are provided (day, week, or month).\n", - "example": "day", - "enum": [ - "day", - "week", - "month" - ] - }, - "startDate": { - "type": "string", - "description": "The first date of the time interval for which the stats are provided, in YYYY-MM-DD format.\n", - "format": "date", - "example": "2024-06-16" - }, - "endDate": { - "type": "string", - "description": "The last date of the time interval for which the stats are provided, in YYYY-MM-DD format.\n", - "format": "date", - "example": "2024-06-22" - }, - "apiCallsStatsByStandards": { - "minItems": 1, - "type": "array", - "description": "The API call statistics by DCSA standard, version, traffic-direction, endpoint, query parameter set and response HTTP status.\n", - "items": { - "$ref": "#/components/schemas/ApiCallsStandardStats" - } - } - } - }, - "ApiCallsStandardStats": { - "required": [ - "byVersions", - "standardName" - ], - "type": "object", - "properties": { - "standardName": { - "maxLength": 20, - "type": "string", - "description": "Name of the DCSA standard.\n- `AN` (Arrival Notice)\n- `BKG` (Booking)\n- `CBF` (Consolidated Booking Forecast)\n- `CRO` (Container Release Order)\n- `CS` (Commercial Schedules)\n- `DI` (Delivery Instruction)\n- `DO` (Delivery Order)\n- `EBL` (Electronic Bill of Lading)\n- `EBL_ISS` (Electronic Bill of Lading Issuance)\n- `EBL_SUR` (Electronic Bill of Lading Surrender)\n- `IC` (IoT Commercial)\n- `IO` (IoT Operations)\n- `JIT` (Just In Time Portcall)\n- `OVS` (Operational Vessel Schedules)\n- `RMC` (Reefer Monitoring Commercial)\n- `RMO` (Operational Reefer Monitoring)\n- `TNT` (Track and Trace)\n- `TO` (Transport Order)\n", - "example": "TNT" - }, - "byVersions": { - "minItems": 1, - "type": "array", - "description": "The API calls statistics for each version of this DCSA standard.\n", - "items": { - "$ref": "#/components/schemas/ApiCallsVersionStats" - } - } - }, - "description": "The API calls statistics for one DCSA standard.\n" - }, - "ApiCallsVersionStats": { - "required": [ - "byInboundEndpoints", - "byOutboundEndpoints", - "versionNumber" - ], - "type": "object", - "properties": { - "versionNumber": { - "maxLength": 50, - "type": "string", - "description": "The version number of the DCSA standard.\n", - "example": "2.2.0" - }, - "byInboundEndpoints": { - "type": "array", - "description": "The statistics of the API calls received on each inbound endpoint of a standard.\n\nIf no `inbound` traffic has been recorded the empty list should be returned\n", - "items": { - "$ref": "#/components/schemas/ApiCallsEndpointStats" - } - }, - "byOutboundEndpoints": { - "type": "array", - "description": "The statistics of the API calls made to each outbound endpoint of a standard.\n\nIf no `outbound` traffic has been recorded the empty list should be returned\n", - "items": { - "$ref": "#/components/schemas/ApiCallsEndpointStats" - } - } - }, - "description": "The API calls statistics for each version of a DCSA standard.\n" - }, - "ApiCallsEndpointStats": { - "required": [ - "byQueryParameterSets", - "endpointUri", - "httpMethod" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "example": "POST", - "enum": [ - "GET", - "POST", - "PUT", - "DELETE", - "PATCH" - ] - }, - "endpointUri": { - "type": "string", - "description": "The URI of the OpenAPI endpoint on which these calls are made / received.\n", - "example": "/v1/events" - }, - "byQueryParameterSets": { - "minItems": 1, - "type": "array", - "description": "The API calls statistics by the request query parameter set.\n", - "items": { - "$ref": "#/components/schemas/ApiCallsQueryParameterSetStats" - } - } - } - }, - "ApiCallsQueryParameterSetStats": { - "required": [ - "byHttpStatuses" - ], - "type": "object", - "properties": { - "queryParameterSet": { - "type": "array", - "description": "The list of query parameters used for a call. If none have been supplied this property should be omitted.\n", - "example": [ - "equipmentReference", - "limit" - ], - "items": { - "maxLength": 50, - "type": "string", - "description": "Name of a queryParameter\n" - } - }, - "byHttpStatuses": { - "minItems": 1, - "type": "array", - "description": "The API calls statistics by the HTTP status with which they were responded.\n", - "items": { - "$ref": "#/components/schemas/ApiCallsHttpStatusStats" - } - } - } - }, - "ApiCallsHttpStatusStats": { - "required": [ - "apiCallCount", - "averageResponseTime", - "httpStatusCode", - "uniqueCounterpartCount" - ], - "type": "object", - "properties": { - "httpStatusCode": { - "type": "integer", - "description": "The HTTP status code with which these API calls were responded.\n", - "example": 200 - }, - "apiCallCount": { - "type": "integer", - "description": "The number of API calls for this DCSA standard, version, direction, endpoint, query parameter set and response status.\n", - "example": 5400 - }, - "uniqueCounterpartCount": { - "type": "integer", - "description": "The number of unique counterparts with which these calls were exchanged. If the value cannot be provided a `0` should be returned.\n", - "example": 320 - }, - "averageResponseTime": { - "type": "integer", - "description": "The average response time of these calls, in milliseconds. If the value cannot be provided a `0` should be returned.\n", - "example": 1250 - } - } - } - }, - "parameters": { - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - } - } -} diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingComponentFactory.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingComponentFactory.java index d0eac45b..89e89b9d 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingComponentFactory.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingComponentFactory.java @@ -98,8 +98,7 @@ public Set getReportRoleNames( } public JsonSchemaValidator getMessageSchemaValidator(String apiName, String jsonSchema) { - String schemaFilePath = "/standards/booking/schemas/booking-%s-v%s0.json" - .formatted(apiName, standardVersion.charAt(0)); + String schemaFilePath = "/standards/booking/schemas/BKG_v%s.yaml".formatted(standardVersion); return JsonSchemaValidator.getInstance(schemaFilePath, jsonSchema); } } diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingScenarioListBuilder.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingScenarioListBuilder.java index 813f122f..a8ff8542 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingScenarioListBuilder.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/BookingScenarioListBuilder.java @@ -9,7 +9,6 @@ import java.util.function.Function; import java.util.stream.Collectors; import java.util.stream.Stream; - import lombok.extern.slf4j.Slf4j; import org.dcsa.conformance.core.check.JsonSchemaValidator; import org.dcsa.conformance.core.scenario.ConformanceAction; @@ -34,8 +33,8 @@ class BookingScenarioListBuilder extends ScenarioListBuilder createModuleScenarioListBuilders( diff --git a/booking/src/main/resources/standards/booking/messages/booking-api-2.0.0-dg.json b/booking/src/main/resources/standards/booking/messages/booking-api-2.0.0-dg.json index 33bd85f3..c676af24 100644 --- a/booking/src/main/resources/standards/booking/messages/booking-api-2.0.0-dg.json +++ b/booking/src/main/resources/standards/booking/messages/booking-api-2.0.0-dg.json @@ -35,6 +35,7 @@ "description": "Jerrican, steel", "dangerousGoods": [ { + "UNNumber": "1463", "codedVariantList": "2200", "properShippingName": "Environmentally hazardous substance, liquid, N.O.S", "technicalName": "xylene and benzene", @@ -91,6 +92,7 @@ "unNumber": "3082" }, { + "NANumber": "9037", "codedVariantList": "2300", "properShippingName": "ETHANOL (ETHYL ALCOHOL)", "technicalName": "DIESEL or FUEL OIL or FURNACE OIL / PG III", diff --git a/booking/src/main/resources/standards/booking/schemas/BKG_v2.0.0.yaml b/booking/src/main/resources/standards/booking/schemas/BKG_v2.0.0.yaml new file mode 100644 index 00000000..b0bfe9d4 --- /dev/null +++ b/booking/src/main/resources/standards/booking/schemas/BKG_v2.0.0.yaml @@ -0,0 +1,6582 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_BKG/2.0.0' +info: + version: 2.0.0 + title: DCSA Booking API + description: | +

DCSA OpenAPI specification for the Booking process

+ + This API is intended as an API between a carrier and anyone creating a `Booking`. The process includes: + + - Booking request + - Booking update + - Booking confirmation + - Booking amendment + - Booking cancellation + - Booking rejection + + For explanation of specific values or objects please refer to the [Information Model](https://developer.dcsa.org/documentation/information_models). This API specification does not define the allowable updates and their timing in accordance with the established business rules. **All use cases mentioned in this API specification refer to use cases defined in [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2)**. + + All other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/) + + ### Booking (Implemented by provider) + + It is possible to use the Booking API as a standalone API. In that case poll on the following endPoints: + + GET /v2/bookings/{bookingReference} + + in order to poll information about status changes. + + **Note:** All `/v2/bookings` endPoints must be implemented by the provider. + + ### Notifications (Implemented by consumer) + It is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification). + + POST /v2/booking-notifications + + The endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to. + + Signing up for notifications is defined outside the scope of this API specification. + + **Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design) + + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v200). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org +security: [] +tags: + - name: Booking + description: Booking endPoints to be implemented by **providers** of the Booking API + - name: Notifications + description: Notifications to be implemented by the **consumers** of the Booking API +paths: + /v2/bookings: + post: + tags: + - Booking + summary: | + Creates a new Booking + operationId: create-bookings + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Creates a new booking request. This endPoint corresponds with **UseCase 1 - Submit booking request**. + + ## Precondition + The consumer has information for a `Booking Request` + + ## Postcondition + The provider has received the `Booking Request`. + + The consumer will receive a `202` (Accepted) if the request payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a `Booking Request`: + + 1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means + - all required properties are provided + - all values provided have correct data type. + + A `carrierBookingRequestReference` (as a reference to the `Booking Request`) is created and linked to the payload in the provider system. + + **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference`** + + 3. A `202` (Accepted) response is returned with a payload containing **only** the `carrierBookingRequestReference`: + ``` + { + carrierBookingRequestReference: 'cbrr-123' + } + ``` + + For `POST` `Booking Request` the process ends here. The `Booking Request`: + - is now accepted by the provider system + - the `Booking Request` does not yet have any status and cannot be queried (no `GET` request is possible until the `Booking Request` is further processed in the provider system) + - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `carrierBookingRequestReference` + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the status `RECEIVED` of the `Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v2/bookings/{bookingReference} + + endPoint to check if the `bookingStatus` of the `Booking Request` has changed. + + After the status has changed to `RECEIVED` further processing can continue by provider and will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll the above endPoint. + requestBody: + description: The payload used to create a `Booking Request` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Make a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Make a `Booking Request` with reefer requirements (1° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 1 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - '20097919' + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Make a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Make a `Booking Request` with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Environmentally hazardous substance, liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: 'Jerrican, steel' + dangerousGoods: + - UNNumber: '3082' + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: '9' + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + responses: + '202': + description: | + `Booking Request` has been successfully accepted by the provider. The `Booking Request` does not yet have a `bookingStatus` - it is not possible to call the `GET` endPoint until the `Booking Request` is further processed in provider system. The consumer is now awaiting provider to process the `Booking Request` asynchronously. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBookingResponse' + examples: + acceptedExample: + summary: | + Booking request accepted + description: | + A `Booking Request` has been accepted (no `bookingStatus`) and schema validated by provider + value: + carrierBookingRequestReference: cbrr-123 + '400': + description: | + In case the `Booking Request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking Request`. This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking Request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Bookings Requests + description: | + Calling the endPoint + + POST /v2/bookings + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be created per hour + '/v2/bookings/{bookingReference}': + put: + tags: + - Booking + summary: | + Updates the Booking + operationId: update-bookings + parameters: + - $ref: '#/components/parameters/bookingReferencePathParam' + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Updates the `Booking Request` with the `bookingReference`. The path can contain either a `carrierBookingRequestReference` or a `carrierBookingReference`. Once a Booking has been `CONFIRMED` the `carrierBookingReference` **MUST** always be used. This endPoint corresponds with either + - **UseCase 3 - Submit updated Booking request** + - **UseCase 7 - Request amendments to confirmed Booking** + + This endPoint is to be used in response to + - **UseCase 2 - Request to update Booking request** + - **UseCase 6 - Request to amend confirmed Booking** + + the endPoint can also be used in case `bookingStatus='RECEIVED'` and the consumer has an update to the `Booking Request`. + + ## Precondition + In order to update a `Booking Request`, the status of the `Booking Request` needs to be in state + - `RECEIVED` in case the consumer has updated information for the `Booking Request` + - `PENDING_UPDATE` in case the provider has requested the consumer to update the `Booking Request` (a result of **UseCase 2 - Request to update Booking request**) + - `UPDATE_RECEIVED` in case the consumer has additional changes to an already sent update + - `PENDING_AMENDMENT` in case the provider has requested the consumer to amend the `Booking Request` (a result of **UseCase 6 - Request to amend confirmed Booking**) + - `CONFIRMED` in case the consumer has an amendment to the `Booking Request` + + ## Postcondition + The provider has received an update (**UseCase 3 - Submit updated Booking request**) or an amendment (**UseCase 7 - Request amendments to confirmed Booking**) to the `Booking Request`. + + In case an amendment was received to the `Booking Request` (**UseCase 7 - Request to amend confirmed Booking**) - the amendment will be called `Amended Booking`. The `Amended Booking` and the "original" `Booking Request` will **co-exist** until a new amendment is submitted by the consumer (via **UseCase 7: Request amendments to confirmed Booking**) or until the provider requests an update (sets the `bookingStatus='PENDING_AMENDMENT'` via **UseCase 6: Request to amend confirmed Booking**). If the `amendedBookingStatus` is present it always represents the latest version of an amendment received by the provider. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives an **update** (or an **amendment**) to a `Booking Request` + 1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means + - all required properties are provided + - all values provided have correct data type + 3. An empty response along with `202` (Accepted) is returned and the consumer now awaits further processing by the provider. + + For `PUT` `Booking Request` the process ends here. The Booking Request: + - is now accepted by the provider system + - the status of the `Booking Request` is unchanged. + - a `202` (Accepted) response is sent with an empty payload + - awaits further processing by the provider + + The provider will now start asynchronous processing. Once processed, the state will change to one of the following values depending on the use case for calling the `PUT` endPoint: + - `UPDATE_RECEIVED` in case this endPoint has been used to: + - send an update to a newly created Booking (precondition: `bookingStatus='RECEIVED'`) + - send an update to a Booking because of a request from provider via **UseCase 2 - Request to update Booking request** (precondition: `bookingStatus='PENDING_UPDATE'`) + - send an additional update to a Booking that has already received an update (precondition: `bookingStatus='UPDATE_RECEIVED'`) + - `bookingStatus` will stay as `PENDING_AMENDMENT` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used in response to a request from provider via **UseCase 6 - Request to amend Confirmed Booking** (precondition: `bookingStatus='PENDING_AMENDMENT'`) + - `bookingStatus` will stay as `CONFIRMED` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used to update an already confirmed Booking via **UseCase 7 - Request Amendments to Confirmed Booking** (precondition: `bookingStatus='CONFIRMED'`) + + Once processed, the new state will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the + + GET /v2/bookings/{bookingReference} + + endPoint to check if the `bookingStatus` and `amendedBookingStatus` of the `Booking` has changed. + + If the consumer wants to get the content of the `Amended Booking` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter: + + GET /v2/bookings/{bookingReference}?amendedContent=true + + It is possible to `GET` the content of the `Amended Booking` via the example above until either: + + - the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible + - the consumer submits a new update (**UseCase 7: Request amendment to confirmed Booking**) in which case the "new amendment" provided **replaces** the "old amendment". + - the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the "old update" is no longer accessible. + requestBody: + description: | + Parameters used to update the `Booking request` + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Updating a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Updating a `Booking Request` with reefer requirements (2° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 2 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - '20097919' + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Update a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Update a `Confirmed Booking` (a `Booking` with `carrierBookingReference='cbr-987'`) with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Environmentally hazardous substance, liquid, N.O.S (Propiconazole)' + HSCodes: + - '293499' + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: 'Jerrican, steel' + dangerousGoods: + - UNNumber: '3082' + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: '9' + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + responses: + '202': + description: | + The `Booking request` update has been successfully accepted by the provider. `bookingStatus` does not change and response payload is empty. Further processing will be done by provider. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + noContentExample: + summary: | + Booking request updated with no content + description: | + An updated `Booking request` received, schema validated and accepted by provider - the `Booking` now awaits provider action, `bookingStatus` does not change. + value: + '400': + description: | + In case the updated/amended `Booking request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking request`. This is an example of how the error object would look in case this property is missing. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + '404': + description: | + In case the provider does not know of the `bookingReference` used in the request (this could be because of a `POST` request that has not finished processing or simply because the resource does not exist) - it is possible for the provider to reject the requests by returning a `404` (Not Found). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. This can be because a `Post` request has not been finished processing or because the `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + '409': + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + GET /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to update a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be updated per hour + get: + tags: + - Booking + summary: | + Gets the Booking + operationId: get-bookings + description: | + Retrieves the `Booking Request` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the Booking is confirmed - it is **only** possible to use the `carrierBookingReference`. It is recommended to use this endPoint to `GET` data before an update is made to make sure latest version is being updated. + + The default payload when calling this endPoint is the "original" `Booking`. It is also possible to get the latest amendment to a `Booking` called the `Amended Booking`. In order to get the `Amended Booking`, it is necessary to use the query parameter `amendedContent` and set it to `true`. + + GET /v2/bookings/{bookingReference}?amendedContent=true + + The `status` of the "original" `Booking` is included in both payloads as `bookingStatus`. `amendedBookingStatus` and related content is only available after the provider has approved the `Booking` via **UseCase 5: Confirm Booking request** and until: + - the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + - the consumer submits a new amendment (**UseCase 7: Request amendment to confirmed Booking**) in which case the "new update" provided **replaces** the "old update". + - the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the "old update" is no longer accessible. + + If `amendedContent=true` is requested but no amendment has yet been provided by the consumer **or** the state of the "original" `Booking` is `PENDING_AMENDMENT`, then a `404` (Not Found) is returned. + + If the provider is requesting changes to the `Booking`, the `Feedback` object is used to inform the consumer what needs to change. + + In case no subscription (`Notification`) has been set up - it is possible to use this endPoint to poll on in order to detect if `bookingStatus` and/or `amendedBookingStatus` has changed. + + In case a previous request is being processed by the provider - a `202` (Accepted) with **no payload** can be used as a response until the processing is finished. + parameters: + - $ref: '#/components/parameters/bookingReferencePathParam' + - $ref: '#/components/parameters/amendedContent' + - $ref: '#/components/parameters/Api-Version-Major' + responses: + '200': + description: Request successful + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + examples: + dryNotConfirmedExample: + summary: | + Standard dry cargo Booking (not confirmed) + description: | + Gets a `Booking Request` with standard Dry cargo which has not yet been confirmed. The `Booking` is in state `PENDING_UPDATE` and requires some changes (specified in the `feedbacks` property) + value: + carrierBookingRequestReference: cbrr-123 + bookingStatus: PENDING_UPDATE + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + feedbacks: + - severity: ERROR + code: PROPERTY_VALUE_MUST_CHANGE + message: | + Not enough available "42G1" equipment. Please change to "22G1" instead + jsonPath: $.requestedEquipment.units + property: 'units' + dryConfirmedExample: + summary: | + Gets a confirmed Standard dry cargo Booking + description: | + Gets a `Confirmed Booking` with standard Dry cargo. In this example the `Booking` has previously received an amendment which was confirmed (`amendedBookingStatus='AMENDMENT_CONFIRMED'`) + + As part of the confirmation the `Booking` is enriched with a `transportPlan`, `shipmentCutOffTimes`, `carrierClauses` and in this example also an `advanceManifestFiling` since the `Booking` is arriving in US. + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_CONFIRMED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: '2024-01-20' + plannedArrivalDate: '2024-01-31' + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: '2024-01-17T22:30:00Z' + - cutOffDateTimeCode: VCO + cutOffDateTime: '2024-01-18T22:30:00Z' + - cutOffDateTimeCode: FCO + cutOffDateTime: '2024-01-19T13:30:00Z' + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes. + - 'Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.' + - 'Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).' + - 'In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee.' + '202': + description: | + The `Booking` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Booking`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '404': + description: | + In case the consumer is requesting the `Amended Booking` by calling: + + GET /v2/bookings/{bookingReference}?amendedContent=true + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + The `Amended Booking` response is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + '409': + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + getError: + summary: | + GET non-existing Booking Request + description: | + Calling + + GET /v2/bookings/cbrr-123 + + results in an error as booking `cbrr-123` does not exist. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + The requested carrierBookingRequestReference does not exist + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Non existent carrierBookingRequestReference + errorCodeMessage: | + carrierBookingRequestReference `cbrr-123` does not exist + patch: + tags: + - Booking + summary: | + Cancels the Booking or cancels an Amendment + operationId: cancel-booking + description: | + A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the `Booking` is confirmed - it is **only** possible to use the `carrierBookingReference`. + + This endPoint corresponds with **UseCase 11 - Cancel Booking Request by shipper**, **UseCase 9 - Cancel amendment to confirmed Booking** or **UseCase 13 - Cancel confirmed Booking by shipper**. + + ## Precondition + In order to cancel a `Booking`, the `bookingStatus` must be either + - `RECEIVED` + - `PENDING_UPDATE` + - `UPDATE_RECEIVED` + - `CONFIRMED` + - `PENDING_AMENDMENT` + + In order to cancel a `Booking Amendment`, the status of the `Booking Amendment` must be + - `AMENDMENT_RECEIVED` + + ## Postcondition + The provider has received a cancellation from the consumer for a `Booking` or for a `Booking Amendment`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a cancellation request: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + Once processed, the `Booking` or `Amended Booking` is cancelled and a [Booking Notification](#/BookingNotification) is sent. In case of a Confirmed Booking - the provider has the opportunity to decline the Cancellation of the Booking (in which case the `bookingCancellationStatus='CANCELLATION_DECLINED'`). + parameters: + - $ref: '#/components/parameters/bookingReferencePathParam' + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CancelBookingRequest' + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer wants to cancel the `Booking Request`. This is done by setting the `bookingStatus` to `CANCELLED` and provide an optional `reason`. + value: + bookingStatus: CANCELLED + reason: Cancelling due to strike + amendmentCancelledExample: + summary: | + Amendment cancelled + description: | + The consumer wants to **only** cancel the amendment (and keep the confirmed `Booking`). This is done by setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED`. + value: + amendedBookingStatus: AMENDMENT_CANCELLED + requestConfirmedBookingCancelledExample: + summary: | + Request to cancel a Confirmed Booking + description: | + The consumer requests to cancel a `Confirmed Booking`. This is done by setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` and provide an optional `reason`. + value: + bookingCancellationStatus: CANCELLATION_RECEIVED + reason: Cancelling due to internal issues + responses: + '202': + description: | + Booking cancellation has been accepted. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer has requested that the `Booking Request` should be cancelled. The cancellation request has been accepted and is now awaiting further processing by the provider + value: + amendmentCancelledExample: + summary: | + Amendment cancellation on a confirmed Booking accepted + description: | + The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation request as been accepted and is now awaiting further processing by the provider + value: + confirmedBookingCancellationExample: + summary: | + Request to Cancel a confirmed Booking accepted + description: | + The consumer has requested to cancel a confirmed `Booking`. The cancellation request has been accepted and is now awaiting further processing by the provider + value: + '400': + description: | + In case the cancel payload does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Wrong `amendedBookingStatus` + description: | + `APPROVE` is not a possible value when PATCHING a `Booking`. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: APPROVE is not a valid status to set + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: amendedBookingStatus + value: APPROVE + errorCodeText: incorrect value + errorCodeMessage: 'Only AMENDMENT_CANCELLED is an allowed value: APPROVE was inserted' + '404': + description: | + In case the consumer is cancelling the `Amended Booking` by setting: + + `amendedBookingStatus='AMENDMENT_CANCELLED'` + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + Cancelling the `Amendment` is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + '409': + description: | + In case the provider is processing a `Booking request` - it is possible for the provider to reject the cancellation by returning a `409` (Conflict). This is also to be used in case a cancellation to a Confirmed Booking is done via the `carrierBookingRequestReference`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: Conflicting request is being processed + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + PATCH /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to cancel a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be cancelled per hour + /v2/booking-notifications: + post: + tags: + - Notifications + summary: Send a new Booking Notification + operationId: booking-notifications + description: | + Creates a new [`Booking Notification`](#/BookingNotification). This endPoint is called whenever a `Booking` that a consumer has subscribed to changes state or is updated. + + **This endPoint is to be implemented by a consumer of the Booking API in order to receive Notifications** + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + description: | + The payload used to create a [`Booking Notification`](#/BookingNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/BookingNotification' + examples: + receivedLightweightExample: + summary: | + Booking request received (Lightweight) + description: | + A lightweight notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + receivedFullStateTransferExample: + summary: | + Booking request received (Full State Transfer) + description: | + A full state transfer notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + bookingStatus: RECEIVED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + declinedLightweightExample: + summary: | + Booking amendment declined (Lightweight) + description: | + A lightweight notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + declinedFullStateTransferExample: + summary: | + Booking amendment declined (Full State Transfer) + description: | + A full state transfer notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`). The notification both contains the Booking from before the amendment (in the `booking` property) it also contains the amended booking (in the `amendedBooking` property). + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: '2024-01-20' + plannedArrivalDate: '2024-01-31' + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: '2024-01-17T22:30:00Z' + - cutOffDateTimeCode: VCO + cutOffDateTime: '2024-01-18T22:30:00Z' + - cutOffDateTimeCode: FCO + cutOffDateTime: '2024-01-19T13:30:00Z' + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes. + - 'Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.' + - 'Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).' + - 'In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee.' + amendedBooking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: '9298686' + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: '2024-01-20' + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: '40' + postCode: '27568' + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 30 + commodities: + - commodityType: 'Dry cargo, Freight all kinds' + cargoGrossWeight: + value: 36000 + unit: KGM + cancelConfirmedBookingLightweightExample: + summary: | + Confirmed Booking cancelled (Lightweight) + description: | + A lightweight notification explaining that a confirmed `Booking` has been cancelled (`bookingCancellationStatus='CANCELLATION_CONFIRMED'`) + value: + specversion: '1.0' + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: 'https://member.com/' + type: org.dcsa.booking.v2 + time: '2018-04-05T17:31:00Z' + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CANCELLED + amendedBookingStatus: AMENDMENT_CANCELLED + bookingCancellationStatus: CANCELLATION_CONFIRMED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + responses: + '204': + description: | + No Content + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '400': + description: | + In case the `Notification` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing carrierBookingReference or carrierBookingRequestReference + description: | + `carrierBookingReference` or `carrierBookingRequestReference` is a conditionally property in the `Notification` (at least one of them must be present). This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + carrierBookingReference or carrierBookingRequestReference not found - one of them is a mandatory to provide in a Notification + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + property: carrierBookingReference or carrierBookingRequestReference + errorCodeText: mandatory property missing + errorCodeMessage: | + carrierBookingReference or carrierBookingRequestReference must be provided as part of a Notification + '500': + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Notification + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Notifications + description: | + Calling the endPoint + + POST /v2/booking-notifications + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a Notification has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2024-09-04T09:41:00Z' + errors: + - errorCode: 7003 + errorCodeText: Max Notifications reached + errorCodeMessage: A maximum of 10 Notifications can be created per hour +components: + headers: + API-Version: + schema: + type: string + example: 2.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '2' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. + + ############# + # Path params + ############# + amendedContent: + in: query + name: amendedContent + description: | + Controls whether the content of this payload is the amended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`). + + If `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found + schema: + type: boolean + default: false + example: false + bookingReferencePathParam: + in: path + name: bookingReference + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + schema: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + example: CBR001 + required: true + schemas: + + ######################### + # Create Booking Response + ######################### + CreateBookingResponse: + type: object + title: Create Booking Response + description: | + **Only** the `carrierBookingRequestReference` is returned. + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + required: + - carrierBookingRequestReference + + ######################## + # Cancel Booking Request + ######################## + CancelBookingRequest: + type: object + title: Cancel Booking Request + oneOf: + - type: object + title: Cancel Booking Request (prior to Booking Confirmation) + properties: + bookingStatus: + type: string + maxLength: 50 + description: | + Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLED`. + example: CANCELLED + required: + - bookingStatus + - type: object + title: Only cancel the amendment to a Confirmed Booking + properties: + amendedBookingStatus: + type: string + maxLength: 50 + description: | + Setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`. + + **Condition:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT_RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned. + + Only possible value to set is `AMENDMENT_CANCELLED`. + example: AMENDMENT_CANCELLED + required: + - amendedBookingStatus + - type: object + title: Request to cancel a Confirmed Booking + properties: + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + Setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon receiving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLATION_RECEIVED`. + example: CANCELLATION_RECEIVED + required: + - bookingCancellationStatus + properties: + reason: + type: string + maxLength: 5000 + description: | + An optional property where a reason for cancelling the booking or the amendment can be given. + example: Booking cancelled due to internal problems + + ###################### + # Booking Notification + ###################### + BookingNotification: + type: object + title: Booking Notification + description: | + `CloudEvent` specific properties for the `Notification`. + properties: + specversion: + type: string + description: | + The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of `1.0` when referring to this version of the specification. + + Currently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes. + enum: + - '1.0' + example: '1.0' + id: + type: string + maxLength: 100 + description: | + Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates. + example: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: + type: string + maxLength: 4096 + description: | + Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that `source` + `id` is unique for each distinct event. + example: 'https://member.com/' + type: + type: string + description: | + This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see [Versioning of CloudEvents in the Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#versioning-of-cloudevents) for more information. + enum: + - org.dcsa.booking.v2 + example: org.dcsa.booking.v2 + time: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. + example: '2018-04-05T17:31:00Z' + datacontenttype: + type: string + description: | + Content type of `data` value. This attribute enables `data` to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the [JSON envelope](formats/json-format.md#3-envelope) format might carry an XML payload in `data`, and the consumer is informed by this attribute being set to "application/xml". The rules for how `data` content is rendered for different `datacontenttype` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](formats/json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol. + + In some event formats the `datacontenttype` attribute MAY be omitted. For example, if a JSON format event has no `datacontenttype` attribute, then it is implied that the `data` is a JSON value conforming to the "application/json" media type. In other words: a JSON-format event with no `datacontenttype` is exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a different format or protocol binding, the target `datacontenttype` SHOULD be set explicitly to the implied `datacontenttype` of the source. + enum: + - application/json + example: application/json + subscriptionReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + The reference of the subscription that has triggered this event + example: 30675492-50ff-4e17-a7df-7a487a8ad343 + data: + $ref: '#/components/schemas/BookingNotificationData' + required: + - specversion + - id + - source + - type + - time + - datacontenttype + - subscriptionReference + - data + + ############################### + # Data for Booking Notification + ############################### + BookingNotificationData: + type: object + title: Data + description: | + `Booking` specific properties for the `Notification` + properties: + bookingStatus: + type: string + maxLength: 50 + description: | + The status of the `Booking`. Possible values are: + + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + type: string + maxLength: 50 + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are: + + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: ABC709951 + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + booking: + $ref: '#/components/schemas/BookingFullNotification' + amendedBooking: + $ref: '#/components/schemas/AmendedBookingFullNotification' + required: + - bookingStatus + + ######################################### + # Booking object for Booking Notification + ######################################### + BookingFullNotification: + type: object + title: Booking + description: | + This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking. + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + + ################################################# + # Amended Booking object for Booking Notification + ################################################# + AmendedBookingFullNotification: + type: object + title: Amended Booking + description: | + This property contains the amended booking in case: + - an amendment is currently active + - the subscriber is subscribing to the `Full State Transfer` of the Booking + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + + ########## + # Feedback + ########## + Feedback: + type: object + title: Feedback + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + properties: + severity: + type: string + maxLength: 50 + description: | + The severity of the feedback. Possible values are: + - `INFO` (Information - "Your reefer container will use renewable energy", "This earlier / premium service is available") + - `WARN` (Warning - "I'm going to replace" / "Ignore this value" / "Use another value instead") + - `ERROR` (Error - "This must be changed!") + example: WARN + code: + type: string + maxLength: 50 + description: | + A code used to describe the feedback. Possible values are: + - `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) + - `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values) + - `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided) + - `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention) + - `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future) + - `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention) + example: PROPERTY_WILL_BE_IGNORED + message: + type: string + maxLength: 5000 + description: | + A description with additional information. + example: Spaces not allowed in facility code + jsonPath: + type: string + maxLength: 500 + description: | + A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + property: + type: string + maxLength: 100 + description: | + The name of the property causing the error/warning. + example: facilityCode + required: + - severity + - code + - message + + ################# + # Error Responses + ################# + ErrorResponse: + title: Error Response + type: object + description: Unexpected error + properties: + httpMethod: + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + description: | + The URI that was requested. + type: string + example: /v1/events + statusCode: + description: | + The HTTP status code returned. + type: integer + format: int32 + example: 400 + statusCodeText: + description: | + A standard short description corresponding to the HTTP status code. + type: string + maxLength: 50 + example: Bad Request + statusCodeMessage: + description: | + A long description corresponding to the HTTP status code with additional information. + type: string + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + description: | + A unique identifier to the HTTP request within the scope of the API provider. + type: string + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + description: | + The DateTime corresponding to the error occurring. 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 + + ################## + # Address Location + ################## + Address: + type: object + title: Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the street number. + example: 2nd + postCode: + type: string + maxLength: 10 + description: The post code. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The name of the city. + example: Amsterdam + stateRegion: + type: string + maxLength: 65 + description: The name of the state/region. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: NL + required: + - street + - city + - countryCode + + ################### + # Facility Location + ################### + Facility: + title: Facility + type: object + description: | + An object used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + 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 + + ################ + # Create Booking + ################ + CreateBooking: + type: object + title: Create Booking + required: + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + properties: + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + 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 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: | + The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + + ################ + # Update Booking + ################ + UpdateBooking: + type: object + title: Update Booking + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + 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 + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: | + The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + required: + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + + DocumentPartiesReq: + type: object + title: Document Parties + description: | + All `Parties` with associated roles. + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + other: + type: array + description: 'A list of document parties that can be optionally provided at booking stage.' + items: + $ref: '#/components/schemas/OtherDocumentParty' + required: + - bookingAgent + + ############### + # Fetch Booking + ############### + Booking: + type: object + title: Booking + properties: + carrierBookingRequestReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 100 + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + bookingStatus: + type: string + maxLength: 50 + description: | + The status of the `Booking`. Possible values are: + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + type: string + maxLength: 50 + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are: + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + type: string + maxLength: 50 + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cargoMovementTypeAtOrigin: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **loading** of the cargo into the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + cargoMovementTypeAtDestination: + type: string + maxLength: 3 + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + type: string + maxLength: 30 + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + example: 2103S + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + maxLength: 5 + minLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + declaredValue: + type: number + format: float + minimum: 0 + description: | + The value of the cargo that the shipper declares in order to avoid the carrier's limitation of liability and "Ad Valorem" freight, i.e., freight which is calculated based on the value of the goods declared by the shipper. + example: 1231.1 + declaredValueCurrency: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + + **Condition:** Mandatory if `declaredValue` is provided + example: DKK + carrierCode: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + enum: + - SMDG + - NMFTA + example: NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + format: date + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + format: date + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-17' + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + format: date + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + example: '2021-05-19' + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + enum: + - BOL + - SWB + example: SWB + transportDocumentReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20 + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + type: string + maxLength: 3 + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + termsAndConditions: + type: string + maxLength: 50000 + description: | + Carrier terms and conditions of transport. + example: Any reference in... + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentParties' + partyContactDetails: + type: array + description: | + The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + type: array + minItems: 1 + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + type: array + minItems: 1 + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipment' + confirmedEquipments: + type: array + description: | + A list of `Confirmed Equipments` + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ConfirmedEquipment' + transportPlan: + type: array + description: | + A list of `Transport` objects (legs) describing the entire transport plan including transshipments. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/Transport' + shipmentCutOffTimes: + type: array + description: | + A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ShipmentCutOffTime' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` provided by the carrier + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + charges: + type: array + description: | + A list of `Charges` + items: + $ref: '#/components/schemas/Charge' + carrierClauses: + type: array + description: | + Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 20000 + description: | + The content of the clause. + example: It is not allowed to... + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + required: + - bookingStatus + - receiptTypeAtOrigin + - deliveryTypeAtDestination + - cargoMovementTypeAtOrigin + - cargoMovementTypeAtDestination + - isEquipmentSubstitutionAllowed + - shipmentLocations + - requestedEquipments + - documentParties + + InvoicePayableAt: + title: Invoice Payable At + type: object + description: | + Location where payment of ocean freight and charges for the main transport will take place by the customer. + + The location must be provided as a `UN Location Code` + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + required: + - UNLocationCode + PlaceOfBLIssue: + title: Place of B/L Issue + type: object + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + The location can be specified either as a `UN Location Code` or as a `CountryCode`. + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + oneOf: + - type: object + title: UN Location Code + properties: + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + required: + - UNLocationCode + - type: object + title: Country Code + properties: + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: DK + required: + - countryCode + + DocumentParties: + type: object + title: Document Parties + description: | + All `Parties` with associated roles. + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + other: + type: array + description: 'A list of document parties that can be optionally provided at booking stage.' + items: + $ref: '#/components/schemas/OtherDocumentParty' + + ######################## + # Active Reefer Settings + ######################## + ActiveReeferSettings: + type: object + title: Active Reefer Settings + description: | + The specifications for a Reefer equipment. + + **Condition:** Only applicable when `isNonOperatingReefer` is set to `false` + properties: + temperatureSetpoint: + type: number + format: float + description: | + Target value of the temperature for the Reefer based on the cargo requirement. + example: -15 + temperatureUnit: + type: string + description: | + The unit for temperature in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + + **Condition:** Mandatory to provide if `temperatureSetpoint` is provided + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 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 to provide if `airExchange` is provided + enum: + - MQH + - FQH + example: MQH + isVentilationOpen: + type: boolean + description: | + If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed` + example: true + isDrainholesOpen: + type: boolean + description: | + Is drain holes open on the container + example: true + isBulbMode: + type: boolean + description: | + Is special container setting for handling flower bulbs active + example: true + isColdTreatmentRequired: + type: boolean + description: | + Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD + example: true + isControlledAtmosphereRequired: + type: boolean + description: | + Indicator of whether cargo requires Controlled Atmosphere. + example: true + isPreCoolingRequired: + type: boolean + description: | + Indicator whether reefer container should be pre-cooled to the temperature setting required at time of release from depot + example: true + isGeneratorSetRequired: + type: boolean + description: | + Indicator whether reefer container should have a generator set attached at time of release from depot + example: true + required: + - temperatureSetpoint + - temperatureUnit + + ################## + # Document Parties + ################## + PartyAddress: + type: object + title: Party Address + description: | + An object for storing address related information + properties: + street: + type: string + maxLength: 70 + description: The name of the street of the party's address. + example: Ruijggoordweg + streetNumber: + type: string + maxLength: 50 + description: The number of the street of the party's address. + example: '100' + floor: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The floor of the party's street number. + example: 2nd + postCode: + type: string + maxLength: 10 + description: The post code of the party's address. + example: 1047 HM + POBox: + type: string + maxLength: 20 + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: '123' + city: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The city name of the party's address. + example: Amsterdam + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + stateRegion: + type: string + maxLength: 65 + description: The state/region of the party's address. + example: North Holland + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: NL + required: + - street + - city + - countryCode + OtherDocumentParty: + type: object + title: Other Document Party + description: | + A list of document parties that can be optionally provided at booking stage + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + type: string + maxLength: 3 + description: | + Specifies the role of the party in a given context. Possible values are: + + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + - `N1` (First Notify Party) + - `N2` (Second Notify Party) + - `NI` (Other Notify Party) + example: DDS + required: + - party + - partyFunction + + BookingAgent: + type: object + title: Booking Agent + description: | + The party placing the booking request on behalf of the customer. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Booking Agent`. + example: HHL007 + required: + - partyName + + Shipper: + type: object + title: Shipper + description: | + The party by whom or in whose name or on whose behalf a contract of carriage of goods by sea has been concluded with a carrier, or the party by whom or in whose name, or on whose behalf, the goods are actually delivered to the carrier in relation to the contract of carriage by sea. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Shipper`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Shipper`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Shipper`. + example: HHL007 + required: + - partyName + + Consignee: + type: object + title: Consignee + description: | + The party to which goods are consigned in the Master Bill of Lading. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Consignee`. + example: HHL007 + purchaseOrderReferences: + type: array + description: | + A list of `Purchase Order Reference`s linked to the `Consignee`. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + required: + - partyName + + ServiceContractOwner: + type: object + title: Service Contract Owner + description: | + The party signing the service contract with the carrier. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Service Contract Owner`. + example: HHL007 + required: + - partyName + + CarrierBookingOffice: + type: object + title: Carrier Booking Office + description: | + The carrier office responsible for processing the booking. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the carrier booking office is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + address: + $ref: '#/components/schemas/Address' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + required: + - partyName + - UNLocationCode + + Party: + type: object + title: Party + description: | + Refers to a company or a legal entity. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + description: | + A list of `Tax References` for a `Party` + type: array + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + type: array + minItems: 1 + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + A reference linked to the `Party`. + example: HHL007 + required: + - partyName + + PartyContactDetail: + type: object + title: Party Contact Detail + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`. + example: + name: Henrik + phone: +45 51801234 + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Name of the contact + example: Henrik + anyOf: + - type: object + title: Phone required + description: | + `Phone` is mandatory to provide + properties: + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + required: + - phone + - type: object + title: Email required + description: | + `Email` is mandatory to provide + properties: + email: + type: string + pattern: ^.+@\S+$ + maxLength: 100 + description: | + `E-mail` address to be used + example: info@dcsa.org + required: + - email + required: + - name + IdentifyingCode: + type: object + title: Identifying Code + 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 | + |-------|:-------:|-------------| + |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 + ########### + ReferenceShipper: + type: object + title: Reference (Shipper) + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + Reference: + type: object + title: Reference + description: | + References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + properties: + type: + type: string + maxLength: 3 + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `ECR` (Empty container release reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + type: string + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + description: | + The value of the reference. + example: HHL00103004 + required: + - type + - value + + ################## + # Customs Reference + ################## + CustomsReference: + type: object + title: Customs Reference + description: | + Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |ACID|EG|Advance Cargo Information Declaration in Egypt| + |CERS|CA|Canadian Export Reporting System| + |ITN|US|Internal Transaction Number in US| + |PEB|ID|PEB reference number| + |CSN|IN|Cargo Summary Notification (CSN)| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The reference type code as defined in the relevant customs jurisdiction. + example: ACID + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: EG + values: + type: array + minItems: 1 + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + The value of the `customsReference` + example: '4988470982020120017' + required: + - type + - countryCode + - values + + ################### + # Shipment Location + ################### + ShipmentLocation: + type: object + title: Shipment Location + description: | + Maps the relationship between `Shipment` and `Location`, e.g., the `Place of Receipt` and the `Place of Delivery` for a specific shipment. This is a reusable object between `Booking` and `Transport Document` + properties: + location: + $ref: '#/components/schemas/Location' + locationTypeCode: + type: string + maxLength: 3 + description: | + Links to the Location Type Code defined by DCSA. Possible values are: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + - `PCF` (Pre-carriage From) + - `OIR` (Onward In-land Routing) + - `ORI` (Origin of goods) + - `IEL` (Container intermediate export stop off location) + - `PTP` (Prohibited transshipment port) + - `RTP` (Requested transshipment port) + - `FCD` (Full container drop-off location) + example: PRE + required: + - location + - locationTypeCode + + Location: + type: object + title: Location + description: | + The location can be specified using **any** of the nested structures: + - `address` (used to specify the location via an Address) + - `UNLocationCode` + - `facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`) + - `geoCoordinate` (used to specify a location using `latitude` and `longitude`) + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: CMP Container Terminal Copenhagen + UNLocationCode: DKCPH + facility: + facilityCode: CMPDK + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + ###################### + # Requested Equipments + ###################### + RequestedEquipment: + type: object + title: Requested Equipment + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of requested equipment units. + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + equipmentReferences: + description: | + A list of equipments to be used by the shipper if known at the time of booking + type: array + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/Commodity' + required: + - ISOEquipmentCode + - units + - isShipperOwned + + RequestedEquipmentShipper: + type: object + title: Requested Equipment (Shipper) + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of requested equipment units. + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + equipmentReferences: + description: | + A list of equipments to be used by the shipper if known at the time of booking + type: array + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/CommodityShipper' + required: + - ISOEquipmentCode + - units + - isShipperOwned + + TareWeight: + type: object + title: Tare Weight + description: | + The weight of an empty container (gross container weight). + + **Condition:** In case of Shipper Owned Containers (`SOC`) this is a required property + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The weight of an empty container (gross container weight). + example: 4000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + ContainerPositioning: + type: object + title: Container Positioning + description: | + An object to capture the `Location` together with an optional `Date and Time`. + properties: + dateTime: + type: string + format: date-time + description: | + The date and time requested by the shipper for the positioning of the container(s) at the Container positioning location (`CPO`), if provided, or the Place of Receipt (`PRE`) if `CPO` location is not provided. + example: '2024-09-04T09:41:00Z' + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + required: + - location + + ContainerPositioningEstimated: + type: object + title: Container Positioning Estimated + description: | + An object to capture the `Location` together with an optional `Date and Time`. + properties: + estimatedDateTime: + type: string + format: date-time + description: | + The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + example: '2024-09-04T09:41:00Z' + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + required: + - location + ContainerPositioningLocation: + type: object + title: Container Positioning Location + description: | + An object to capture the `Container Positioning Location`. + + The location of the customer facility where the container(s) will be loaded. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Shanghai Shengdong International Container Terminal + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + EmptyContainerDepotReleaseLocation: + type: object + title: Empty Container Depot Release Location + description: | + An object to capture the `Empty Container Depot Release Location`. + + The location of the depot from which the empty container(s) will be released from + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Shanghai Shengdong International Container Terminal + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + geoCoordinate: + $ref: '#/components/schemas/GeoCoordinate' + + ########### + # Commodity + ########### + CommodityShipper: + type: object + title: Commodity (Shipper) + description: | + Type of goods, defined by its commodity type + properties: + commodityType: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 550 + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - commodityType + Commodity: + type: object + title: Commodity + description: | + Type of goods, defined by its commodity type + properties: + commoditySubReference: + type: string + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + description: | + A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking. + + **Condition:** Mandatory to provide for `CONFIRMED` bookings + example: COM-001 + commodityType: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 550 + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + type: string + pattern: ^\d{6,10}$ + minLength: 6 + maxLength: 10 + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: '851713' + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + required: + - commodityType + + ExportLicense: + type: object + title: Export License + description: | + `Export License` required for this commodity + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Export License` applicable to the booking. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Export License` applicable to the booking. + example: '2024-09-21' + + ImportLicense: + type: object + title: Import License + description: | + `Import License` required for this commodity + properties: + isRequired: + type: boolean + description: | + Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + reference: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 35 + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that athorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + format: date + description: | + Issue date of the `Import License` applicable to the booking. + example: '2024-09-14' + expiryDate: + type: string + format: date + description: | + Expiry date of the `Import License` applicable to the booking. + example: '2024-09-21' + + CargoGrossWeightReq: + type: object + title: Cargo Gross Weight (Requested Equipment) + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Commodity` level + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoGrossWeight: + type: object + title: Cargo Gross Weight + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Requested Equipment` level. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoGrossVolume: + type: object + title: Cargo Gross Volume + description: | + The estimated grand total volume of the cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total volume of the cargo. + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + + CargoNetWeight: + type: object + title: Cargo Net Weight + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + + CargoNetVolume: + type: object + title: Cargo Net Volume + description: | + The estimated net total volume of the cargo. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The estimated net total volume of the cargo. + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + enum: + - MTQ + - FTQ + example: MTQ + required: + - value + - unit + + ######################### + # National Commodity Code + ######################### + NationalCommodityCode: + type: object + title: National Commodity Code + description: | + The national commodity classification code linked to a country with a value. + + An example could look like this: + + | Type | Country | Value | + |-------|:-------:|-------------| + |NCM|BR|['1515', '2106', '2507', '2512']| + properties: + type: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The national commodity classification code, which can be one of the following values defined by DCSA: + - `NCM` (Nomenclatura Comum do Mercosul) + - `HTS` (Harmonized Tariff Schedule) + - `SCHEDULE_B` ( Schedule B) + - `TARIC` (Integrated Tariff of the European Communities) + - `CN` (Combined Nomenclature) + - `CUS` (Customs Union and Statistics) + example: NCM + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: BR + values: + type: array + minItems: 1 + description: | + A list of `national commodity codes` values. + items: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 10 + description: | + The value of the `National Commodity Code` + example: '1515' + example: + - '1515' + - '2106' + - '2507' + - '2512' + required: + - type + - values + + ################# + # Outer Packaging + ################# + OuterPackaging: + type: object + title: Outer Packaging + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + + **Condition:** Mandatory for DG (Dangerous Goods) cargo. + properties: + packageCode: + type: string + pattern: ^[A-Z0-9]{2}$ + minLength: 2 + maxLength: 2 + description: | + A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations) + + **Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available. + example: 5H + imoPackagingCode: + type: string + pattern: ^[A-Z0-9]{1,5}$ + minLength: 1 + maxLength: 5 + description: | + The code of the packaging as per IMO. + + **Condition:** only applicable to dangerous goods if specified in the [IMO IMDG code](https://www.imo.org/en/publications/Pages/IMDG%20Code.aspx). If not available, the `packageCode` as per UN recommendation 21 should be used. + example: 1A2 + numberOfPackages: + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + description: | + Specifies the number of outer packagings/overpacks associated with this `Commodity`. + + **Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide + example: 18 + description: + type: string + maxLength: 100 + description: | + Description of the outer packaging/overpack. + example: 'Drum, steel' + dangerousGoods: + type: array + description: | + A list of `Dangerous Goods` related to the `Commodity` + items: + $ref: '#/components/schemas/DangerousGoods' + + ################# + # Dangerous Goods + ################# + DangerousGoods: + type: object + title: Dangerous Goods + description: | + Specification for `Dangerous Goods`. It is mandatory to either provide the `UNNumber` or the `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**. + oneOf: + - type: object + title: UN Number + properties: + UNNumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG. + example: '1463' + required: + - UNNumber + - type: object + title: NA Number + properties: + NANumber: + type: string + pattern: ^\d{4}$ + minLength: 4 + maxLength: 4 + description: | + Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation. + example: '9037' + required: + - NANumber + properties: + codedVariantList: + type: string + pattern: ^[0-3][0-9A-Z]{3}$ + minLength: 4 + maxLength: 4 + description: | + Four-character code supplied by Exis Technologies that assists to remove ambiguities when identifying a variant within a single `UN number` or `NA number` that may occur when two companies exchange DG information. + + Character | Valid Characters | Description + :--------:|------------------|------------ + 1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group + 2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs + 3 and 4|0 to 9 and A to Z|Two sequence letters for other information, for the cases where the variant is required because of different in subrisks, packing instruction etc. + example: '2200' + properShippingName: + type: string + maxLength: 250 + description: | + The proper shipping name for goods under IMDG Code, or the product name for goods under IBC Code and IGC Code, or the bulk cargo shipping name for goods under IMSBC Code, or the name of oil for goods under Annex I to the MARPOL Convention. + example: 'Chromium Trioxide, anhydrous' + technicalName: + type: string + maxLength: 250 + description: | + The recognized chemical or biological name or other name currently used for the referenced dangerous goods as described in chapter 3.1.2.8 of the IMDG Code. + example: 'xylene and benzene' + imoClass: + type: string + maxLength: 4 + description: | + The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are: + - `1.1A` (Substances and articles which have a mass explosion hazard) + - `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard) + - `2.1` (Flammable gases) + - `8` (Corrosive substances) + example: 1.4S + subsidiaryRisk1: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + subsidiaryRisk2: + type: string + pattern: ^[0-9](\.[0-9])?$ + minLength: 1 + maxLength: 3 + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: '1.2' + isMarinePollutant: + type: boolean + description: | + Indicates if the goods belong to the classification of Marine Pollutant. + example: false + packingGroup: + type: integer + format: int32 + minimum: 1 + maximum: 3 + description: | + The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code. + example: 3 + isLimitedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code. + example: false + isExceptedQuantity: + type: boolean + description: | + Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code. + example: false + isSalvagePackings: + type: boolean + description: | + Indicates if the cargo has special packaging for the transport, recovery or disposal of damaged, defective, leaking or nonconforming hazardous materials packages, or hazardous materials that have spilled or leaked. + example: false + isEmptyUncleanedResidue: + type: boolean + description: | + Indicates if the cargo is residue. + example: false + isWaste: + type: boolean + description: | + Indicates if waste is being shipped + example: false + isHot: + type: boolean + description: | + Indicates if high temperature cargo is shipped. + example: false + isCompetentAuthorityApprovalRequired: + type: boolean + description: | + Indicates if the cargo require approval from authorities + example: false + competentAuthorityApproval: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name and reference number of the competent authority providing the approval. + example: '{Name and reference...}' + segregationGroups: + type: array + description: | + List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code. + + **Condition:** only applicable to specific hazardous goods. + items: + type: string + maxLength: 2 + description: | + Grouping of Dangerous Goods having certain similar chemical properties. Possible values are: + - `1` (Acids) + - `2` (Ammonium Compounds) + - `3` (Bromates) + - `4` (Chlorates) + - `5` (Chlorites) + - `6` (Cyanides) + - `7` (Heavy metals and their salts) + - `8` (Hypochlorites) + - `9` (Lead and its compounds) + - `10` (Liquid halogenated hydrocarbons) + - `11` (Mercury and mercury compounds) + - `12` (Nitrites and their mixtures) + - `13` (Perchlorates) + - `14` (Permanganates) + - `15` (Powdered metals) + - `16` (Peroxides), + - `17` (Azides) + - `18` (Alkalis) + example: '12' + innerPackagings: + type: array + description: | + A list of `Inner Packings` contained inside this `outer packaging/overpack`. + items: + $ref: '#/components/schemas/InnerPackaging' + emergencyContactDetails: + $ref: '#/components/schemas/EmergencyContactDetails' + EMSNumber: + type: string + maxLength: 7 + description: | + The emergency schedule identified in the IMO EmS Guide - Emergency Response Procedures for Ships Carrying Dangerous Goods. Comprises 2 values; 1 for spillage and 1 for fire. Possible values spillage: S-A to S-Z. Possible values fire: F-A to F-Z. + example: F-A S-Q + endOfHoldingTime: + type: string + format: date + description: | + Date by when the refrigerated liquid needs to be delivered. + example: '2021-09-03' + fumigationDateTime: + type: string + format: date-time + description: | + Date & time when the container was fumigated + example: '2024-09-04T09:41:00Z' + isReportableQuantity: + type: boolean + description: | + Indicates if a container of hazardous material is at the reportable quantity level. If `TRUE`, a report to the relevant authority must be made in case of spill. + example: false + inhalationZone: + type: string + maxLength: 1 + minLength: 1 + description: | + The zone classification of the toxicity of the inhalant. Possible values are: + - `A` (Hazard Zone A) can be assigned to specific gases and liquids + - `B` (Hazard Zone B) can be assigned to specific gases and liquids + - `C` (Hazard Zone C) can **only** be assigned to specific gases + - `D` (Hazard Zone D) can **only** be assigned to specific gases + example: A + grossWeight: + $ref: '#/components/schemas/GrossWeight' + netWeight: + $ref: '#/components/schemas/NetWeight' + netExplosiveContent: + $ref: '#/components/schemas/NetExplosiveContent' + netVolume: + $ref: '#/components/schemas/NetVolume' + limits: + $ref: '#/components/schemas/Limits' + specialCertificateNumber: + type: string + maxLength: 255 + description: | + Text field to indicate certificate number & segment for specific stowage requirements overruling IMDG code + example: '22663:3' + additionalContainerCargoHandling: + type: string + maxLength: 255 + description: | + Text field to provide cargo handling information already known at the booking stage. + example: To be handled with extreme care + required: + - properShippingName + - imoClass + - isMarinePollutant + - isLimitedQuantity + - isExceptedQuantity + - isSalvagePackings + - isEmptyUncleanedResidue + - isWaste + - isHot + - isCompetentAuthorityApprovalRequired + - isReportableQuantity + - emergencyContactDetails + - grossWeight + GrossWeight: + type: object + title: Gross Weight + description: | + Total weight of the goods carried, including packaging. + properties: + value: + type: number + format: float + example: 12000.3 + minimum: 0 + exclusiveMinimum: true + description: | + The grand total weight of the DG cargo and weight per `UNNumber`/`NANumber` including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetWeight: + type: object + title: Net Weight + description: | + Total weight of the goods carried, excluding packaging. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + Total weight of the goods carried, excluding packaging. + example: 2.4 + unit: + type: string + description: | + Unit of measure used to describe the `netWeight`. Possible values are + + - `KGM` (Kilograms) + - `LBR` (Pounds) + enum: + - KGM + - LBR + example: KGM + required: + - value + - unit + NetExplosiveContent: + type: object + title: Net Explosive Content + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + example: 2.4 + unit: + type: string + description: | + Unit of measure used to describe the `netExplosiveWeight`. Possible values are + + - `KGM` (Kilograms) + - `LBR` (Pounds) + - `GRM` (Grams) + - `ONZ` (Ounce) + enum: + - KGM + - LBR + - GRM + - ONZ + example: KGM + required: + - value + - unit + NetVolume: + type: object + title: Net Volume + description: | + The volume of the referenced dangerous goods. + + **Condition:** only applicable to liquids and gas. + properties: + value: + type: number + format: float + minimum: 0 + exclusiveMinimum: true + description: | + The volume of the referenced dangerous goods. + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + - `LTR` (Litre) + enum: + - MTQ + - FTQ + - LTR + example: MTQ + required: + - value + - unit + InnerPackaging: + type: object + title: Inner Packaging + description: | + Object for inner packaging specification + properties: + quantity: + type: integer + format: int32 + description: | + Count of `Inner Packagings` of the referenced `Dangerous Goods`. + example: 20 + material: + type: string + maxLength: 100 + description: | + The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`. + example: Plastic + description: + type: string + maxLength: 100 + description: | + Description of the packaging. + example: Woven plastic water resistant Bag + required: + - quantity + - material + - description + EmergencyContactDetails: + type: object + title: Emergency Contact Details + description: | + 24 hr emergency contact details + properties: + contact: + type: string + maxLength: 255 + description: | + Name of the Contact person during an emergency. + example: Henrik Larsen + provider: + type: string + maxLength: 255 + description: | + Name of the third party vendor providing emergency support + example: GlobeTeam + phone: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 30 + description: | + Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en). + example: +45 70262970 + referenceNumber: + type: string + maxLength: 255 + description: | + Contract reference for the emergency support provided by an external third party vendor. + example: '12234' + required: + - contact + - phone + Limits: + type: object + title: Limits + description: | + Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure. + properties: + temperatureUnit: + type: string + description: | + The unit for **all attributes in the limits structure** in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + enum: + - CEL + - FAH + example: CEL + flashPoint: + type: number + format: float + description: | + Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air. + + **Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code. + example: 42 + transportControlTemperature: + type: number + format: float + description: | + Maximum temperature at which certain substance (such as organic peroxides and self-reactive and related substances) can be safely transported for a prolonged period. + example: 24.1 + transportEmergencyTemperature: + type: number + format: float + description: | + Temperature at which emergency procedures shall be implemented + example: 74.1 + SADT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating decomposition may occur in a substance + example: 54.1 + SAPT: + type: number + format: float + description: | + Lowest temperature in which self-accelerating polymerization may occur in a substance + example: 70 + required: + - temperatureUnit + + ##################### + # Confirmed Equipment + ##################### + ConfirmedEquipment: + type: object + title: Confirmed Equipment + description: | + The confirmed equipments for the booking + properties: + ISOEquipmentCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 4 + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + units: + type: integer + format: int32 + minimum: 1 + description: | + Number of confirmed equipment units + example: 3 + containerPositionings: + type: array + description: | + A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated). + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + items: + $ref: '#/components/schemas/ContainerPositioningEstimated' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + required: + - ISOEquipmentCode + - units + + EmptyContainerPickup: + type: object + title: Empty Container Pickup + description: | + The date and time and location for the empty container pick-up. + + **Condition:** Only applicable to merchant haulage service at origin (`Receipt type at origin = 'CY'`). + properties: + dateTime: + type: string + format: date-time + description: | + The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided. + example: '2024-09-04T09:41:00Z' + depotReleaseLocation: + $ref: '#/components/schemas/EmptyContainerDepotReleaseLocation' + + ########### + # Transport + ########### + Transport: + type: object + title: Transport + description: | + A single `leg` of the `Transport Plan` + properties: + transportPlanStage: + type: string + description: | + Code qualifying a specific stage of transport e.g. pre-carriage, main carriage transport or on-carriage transport + - `PRC` (Pre-Carriage) + - `MNC` (Main Carriage Transport) + - `ONC` (On-Carriage Transport) + enum: + - PRC + - MNC + - ONC + example: PRC + transportPlanStageSequenceNumber: + type: integer + format: int32 + description: | + Sequence number of the transport plan stage + example: 5 + loadLocation: + $ref: '#/components/schemas/LoadLocation' + dischargeLocation: + $ref: '#/components/schemas/DischargeLocation' + plannedDepartureDate: + type: string + format: date + description: | + The planned date of departure. + example: '2021-05-17' + plannedArrivalDate: + type: string + format: date + description: | + The planned date of arrival. + example: '2021-05-19' + modeOfTransport: + type: string + maxLength: 50 + description: | + The mode of transport as defined by DCSA. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + vesselName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + type: string + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: '9321483' + carrierServiceCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 11 + description: | + The carrier-specific code of the service for which the schedule details are published. + example: FE1 + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + minLength: 8 + maxLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierImportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + example: 2103N + universalImportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + carrierExportVoyageNumber: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + example: 2103S + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + required: + - transportPlanStage + - transportPlanStageSequenceNumber + - loadLocation + - dischargeLocation + - plannedDepartureDate + - plannedArrivalDate + LoadLocation: + type: object + title: Load Location + description: | + An object to capture the `Load Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + DischargeLocation: + type: object + title: Discharge Location + description: | + An object to capture the `Discharge Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Transnet Port Terminals Cape Town + UNLocationCode: ZACPT + facility: + facilityCode: TNCT + facilityCodeListProvider: SMDG + properties: + locationName: + type: string + description: The name of the location. + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + + ######################## + # Shipment Cut-off times + ######################## + ShipmentCutOffTime: + type: object + title: Shipment Cut-Off Time + description: | + `Cut off times` defined by the carrier + properties: + cutOffDateTimeCode: + type: string + maxLength: 3 + description: | + Code for the cut-off time. Possible values are: + - `DCO` (Documentation cut-off) + - `VCO` (VGM cut-off) + - `FCO` (FCL delivery cut-off) + - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS` + - `EFC` (Earliest full-container delivery date) + example: DCO + cutOffDateTime: + type: string + format: date-time + description: | + Actual cut-off time + example: '2024-09-04T09:41:00Z' + required: + - cutOffDateTimeCode + - cutOffDateTime + + ########################## + # Advance Manifest Filings + ########################## + AdvanceManifestFiling: + type: object + title: Advance Manifest Filing + description: | + An Advance Manifest Filing defined by a Manifest type code in combination with a country code. + + A small list of **potential** examples: + + | manifestTypeCode | countryCode | Description | + |-----------------------|:-------------:|-------------| + |ACI|EG|Advance Cargo Information in Egypt| + |ACE|US|Automated Commercial Environment in the United States| + |AFR|JP|Cargo Summary Notification (CSN)| + properties: + manifestTypeCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The Manifest type code as defined by the provider. + example: ACE + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: US + example: + manifestTypeCode: ACE + countryCode: US + required: + - manifestTypeCode + + ######## + # Charge + ######## + Charge: + type: object + title: Charge + description: | + Addresses the monetary value of freight and other service charges for a `Booking`. + properties: + chargeName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + Free text field describing the charge to apply + example: Documentation fee - Destination + currencyAmount: + type: number + format: float + minimum: 0 + description: | + The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals. + example: 1012.12 + currencyCode: + type: string + pattern: ^[A-Z]{3}$ + minLength: 3 + maxLength: 3 + description: | + The currency for the charge, using a 3-character code according to [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + example: DKK + paymentTermCode: + type: string + description: | + An indicator of whether a charge is prepaid (PRE) or collect (COL). When prepaid, the charge is the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charge is the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + calculationBasis: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The code specifying the measure unit used for the corresponding unit price for this cost, such as per day, per ton, per square metre. + example: Per day + unitPrice: + type: number + format: float + minimum: 0 + description: | + The unit price of this charge item in the currency of the charge. + example: 3456.6 + quantity: + type: number + format: float + minimum: 0 + description: | + The amount of unit for this charge item. + example: 34.4 + required: + - chargeName + - currencyAmount + - currencyCode + - paymentTermCode + - calculationBasis + - unitPrice + - quantity + + ########################## + # OriginChargesPaymentTerm + ########################## + OriginChargesPaymentTerm: + type: object + title: Origin Charges Payment Term + description: | + An indicator of whether origin charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + + ############################### + # DestinationChargesPaymentTerm + ############################### + DestinationChargesPaymentTerm: + type: object + title: Destination Charges Payment Term + description: | + An indicator of whether destination charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + properties: + haulageChargesPaymentTermCode: + type: string + description: | + An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + enum: + - PRE + - COL + example: PRE + + ######## + # Vessel + ######## + Vessel: + type: object + title: Vessel + description: | + Vessels related to this booking request. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and `carrierServiceCode` or `carrierServiceName` are blank. + required: + - name + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 50 + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + type: string + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: '9321483' diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsComponentFactory.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsComponentFactory.java index aace6b16..fe7f209d 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsComponentFactory.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsComponentFactory.java @@ -96,13 +96,9 @@ public Set getReportRoleNames(PartyConfiguration[] partyConfigurations, .collect(Collectors.toSet())); } - - - public JsonSchemaValidator getMessageSchemaValidator(String api, String jsonSchema) { - String schemaFilePath = "/standards/commercialschedules/schemas/commercialschedules-%s-v%s0.json" - .formatted(api, standardVersion.charAt(0)); - + public JsonSchemaValidator getMessageSchemaValidator(String jsonSchema) { + String schemaFilePath = + "/standards/commercialschedules/schemas/CS_v%s.yaml".formatted(standardVersion); return JsonSchemaValidator.getInstance(schemaFilePath, jsonSchema); } - } diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsScenarioListBuilder.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsScenarioListBuilder.java index 264c524c..97f0bcc2 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsScenarioListBuilder.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/CsScenarioListBuilder.java @@ -27,7 +27,6 @@ import lombok.extern.slf4j.Slf4j; import org.dcsa.conformance.core.scenario.ConformanceAction; import org.dcsa.conformance.core.scenario.ScenarioListBuilder; - import org.dcsa.conformance.standards.cs.action.CsAction; import org.dcsa.conformance.standards.cs.action.CsGetPortSchedulesAction; import org.dcsa.conformance.standards.cs.action.CsGetRoutingsAction; @@ -195,7 +194,7 @@ private static CsScenarioListBuilder getVesselSchedules() { subscriberPartyName, publisherPartyName, (CsAction) previousAction, - componentFactory.getMessageSchemaValidator("api", "serviceSchedules"))); + componentFactory.getMessageSchemaValidator("serviceSchedules"))); } private static CsScenarioListBuilder getPtpRoutings() { @@ -208,7 +207,7 @@ private static CsScenarioListBuilder getPtpRoutings() { subscriberPartyName, publisherPartyName, (CsAction) previousAction, - componentFactory.getMessageSchemaValidator("api", "pointToPointRoutings"))); + componentFactory.getMessageSchemaValidator("pointToPointRoutings"))); } private static CsScenarioListBuilder getPortSchedules() { @@ -221,6 +220,6 @@ private static CsScenarioListBuilder getPortSchedules() { subscriberPartyName, publisherPartyName, (CsAction) previousAction, - componentFactory.getMessageSchemaValidator("api", "portSchedules"))); + componentFactory.getMessageSchemaValidator("portSchedules"))); } } diff --git a/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/CS_v1.0.0.yaml b/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/CS_v1.0.0.yaml new file mode 100644 index 00000000..6c09b9db --- /dev/null +++ b/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/CS_v1.0.0.yaml @@ -0,0 +1,1767 @@ +openapi: 3.0.3 +info: + title: DCSA OpenAPI specification for Commercial Schedules + version: 1.0.0 + description: | + API specification issued by [Digital Container Shipping Association (DCSA)](https://dcsa.org/). + + The Commercial Schedules API offers BCOs, LSPs, and Solution Platforms three different methods and endpoints to access schedules from carriers based on their specific needs: Point-to-Point Routings, Port Schedules, and Vessel Schedules. + + **Commercial schedules - point-to-point routings**: provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs. + + **Commercial schedules – port schedules**: provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps. + + **Commercial schedules – vessel schedules**: provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s). + + **All use cases mentioned in this API specification refer to use cases defined in the Commercial Schedules Interface Standard.** + + The Commercial Schedules endpoints can be implemented independently: + + `1. GET /v1/point-to-point-routes # For Point to Point Routings` + + `2. GET /v1/port-schedules # For Port Schedules` + + `3. GET /v1/vessel-schedules # For Vessel Schedules` + + Visit the [DCSA Website](https://dcsa.org/standards/commercial-schedules/) to find other documentation related to the standard publication (i.e. Interface Standard, Information Model). + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design). + + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/cs/v1#v100). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + license: + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + name: Apache 2.0 + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org/' + email: info@dcsa.org +servers: + - url: 'http://localhost:3000' +paths: + /v1/point-to-point-routes: + get: + summary: Point to Point Routing + tags: + - Point To Point + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/PointToPoint' + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/point-to-point' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7005 + property: placeOfDelivery + value: SG + errorCodeText: invalidQuery + errorCodeMessage: PlaceOfDelivery does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/point-to-point' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Unable to process request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-point-to-point + parameters: + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: placeOfReceipt + description: The `UNLocationCode` specifying where the place is located. + required: true + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: placeOfDelivery + description: The `UNLocationCode` specifying where the place is located. + required: true + - schema: + type: string + format: date + example: '2021-04-01' + in: query + name: departureStartDate + description: | + Limit the result based on the earliest departureDate. + - If provided without departureEndDate, returns all routings with departures from the specified departureStartDate onwards. + - If provided with departureEndDate, returns all routings with departures within the specified date range, inclusive of both dates. + - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date. + - schema: + type: string + format: date + example: '2021-05-01' + in: query + name: departureEndDate + description: | + Limit the result based on the latest departureDate. + - If provided without departureStartDate, returns all routings with departures up to the specified departureEndDate. + - If provided with departureStartDate, returns all routings with departures within the specified date range, inclusive of both dates. + - If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date. + - schema: + type: string + format: date + example: '2021-04-01' + in: query + name: arrivalStartDate + description: | + Limit the result based on the earliest arrivalDate. + - If provided without arrivalEndDate, returns all routings with arrivals from the specified arrivalStartDate. + - If provided with arrivalEndDate, returns all routings with arrivals within the specified date range, inclusive of both dates. + - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date. + - schema: + type: string + format: date + example: '2021-05-01' + in: query + name: arrivalEndDate + description: | + Limit the result based on the latest arrivalDate. + - If provided without arrivalStartDate, returns all routings with arrivals up to the specified arrivalEndDate. + - If provided with arrivalStartDate, returns all routings with arrivals within the specified date range, inclusive of both dates. + - If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date. + - schema: + type: integer + example: 1 + format: int32 + minimum: 0 + in: query + name: maxTranshipment + description: Specifies the maximum number of transhipments that the proposed routings can have in the response. By default, transhipments are allowed and the responses can have either direct routings or routings with transhipment. The default value of maximum transhipments is defined by the carrier for when the consumer does not provide a value. If the user sets the number of transhipments to 0, only direct routings can be returned in the response. + - schema: + type: string + enum: + - CY + - SD + - CFS + maxLength: 3 + example: CY + in: query + name: receiptTypeAtOrigin + description: | + Indicates the type of service offered at Origin. **Carriers can choose to define a default value when the consumer does not provide it.** + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + - schema: + type: string + enum: + - CY + - SD + - CFS + maxLength: 3 + example: CY + in: query + name: deliveryTypeAtDestination + description: | + Indicates the type of service offered at Destination. **Carriers can choose to define a default value when the consumer does not provide it.** + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Point-to-Point` objects to return. + - schema: + type: string + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs. + + The list of solutions returned in the response can be tailored to a specific need by combining available query parameters. + + The minimum required query parameters are `placeOfReceipt` and `placeOfDelivery`. If no further query parameters are used to tailor the response, the provider of the GET endpoint will return their best suggestions in the response. + + The `GET /v1/point-to-point-routes` endpoint can be implemented independently of having implemented the `GET /v1/port-schedules` and `GET /v1/vessel-schedules` endpoints. + /v1/port-schedules: + get: + summary: Port Schedule + tags: + - Port Schedule + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/PortSchedule' + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/port-schedule' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7005 + property: port + value: SG + errorCodeText: invalidQuery + errorCodeMessage: Port does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/port-schedule' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-port-schedules + description: | + Provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps. + + The port must be identified by its UN Location Code. + + The required query parameters are `UNLocationCode` and `date`. + + If the requested port (identified with `UNLocationCode`) has multiple terminals (identified with `facilitySMDGCode`), the response will include a sorted list that provides all the arrivals and departures of the vessels for each terminal of the port (`UNLocationCode`). + + The `GET /v1/port-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/vessel-schedules` endpoints. + parameters: + - schema: + type: string + maxLength: 5 + example: NLAMS + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + in: query + name: UNLocationCode + description: The UN Location code specifying where the place is located. Specifying this filter will only return the set of all vessels arriving and departing from the port and its terminals. + required: true + - schema: + type: string + format: date + pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ + example: '2023-07-01' + in: query + name: date + description: The date since when the estimated arrival and departures of vessels in a given port is required. + required: true + - $ref: '#/components/parameters/Api-Version-Major' + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Port Schedule` objects to return. + - schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + parameters: [] + /v1/vessel-schedules: + get: + summary: Vessel Schedule + tags: + - Vessel Schedule + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + Next-Page-Cursor: + schema: + type: string + maxLength: 1024 + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + description: | + The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response. + When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: + `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. + + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. + '400': + description: Bad Request + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/vessel-schedule' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + '500': + description: Internal Server Error + headers: + API-Version: + schema: + type: string + example: 1.0.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/cs/v1/vessel-schedule' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + errorCodeMessage: UNLocationCode does not exist + operationId: get-v1-vessel-schedule + parameters: + - schema: + type: string + minLength: 7 + maxLength: 8 + pattern: ^\d{7,8}$ + example: '9321483' + in: query + name: vesselIMONumber + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + - schema: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: King of the Seas + in: query + name: vesselName + description: The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the vesselName is not unique and might match multiple vessels. + - schema: + type: string + maxLength: 11 + example: FE1 + in: query + name: carrierServiceCode + description: The carrier specific service code to filter by. The result will only return schedules including the service code. + - schema: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + example: SR12345A + in: query + name: universalServiceReference + description: The Universal Service Reference (USR) as defined by DCSA to filter by. + - schema: + type: string + maxLength: 50 + example: 2103S + in: query + name: carrierVoyageNumber + description: The carrier specific identifier of a Voyage - can be both `importVoyageNumber` and `exportVoyageNumber`. The result will only return schedules including the Ports where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`. + - schema: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + maxLength: 5 + example: 2201N + in: query + name: universalVoyageReference + description: The Universal Reference of a Voyage - can be both `importUniversalVoyageReference` and `exportUniversalVoyageReference`. The result will only return schedules including the Ports where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference`. + - schema: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: UNLocationCode + description: The UN Location Code specifying where a port is located. Specifying this filter will only return schedules including entire Voyages related to this particular UN Location Code. + - schema: + type: string + maxLength: 6 + example: APM + in: query + name: facilitySMDGCode + description: The facilitySMDGCode specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including entire Voyages related to this particular `facilitySMDGCode`. + - schema: + type: string + example: MAEU + maxLength: 10 + in: query + name: vesselOperatorCarrierCode + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + - schema: + type: string + format: date + example: '2020-04-06' + in: query + name: startDate + description: | + The start date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or after (≥) the `startDate` the entire Voyage (import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call. + If this filter is not provided the default value is `3 months` prior to request time. The value is populated in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date format. + - schema: + type: string + format: date + example: '2020-04-10' + in: query + name: endDate + description: | + The end date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or before (≤) the `endDate` the entire Voyage(import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call. + If this filter is not provided the default value is `6 months` after request time. The value is populated in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date format. + - schema: + type: integer + format: int32 + default: 100 + example: 100 + minimum: 1 + in: query + name: limit + description: Specifies the maximum number of `Service Schedule` objects to return. + - schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA + maxLength: 1024 + in: query + name: cursor + description: A server generated value to specify a specific point in a collection result, used for pagination. + - $ref: '#/components/parameters/Api-Version-Major' + description: | + Provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s). + + The list of schedules returned in the response can be tailored to specific needs by combining available query parameters. + + A filter parameter or a combination of filter parameters MUST always be provided to call the endpoint. Examples of typical query parameters and expected payload returned in the response: + + - a) `carrierServiceCode`: Get all vessels and their full voyages within a service + + - b) `carrierServiceCode` **&** `carrierVoyageNumber`: Get a specific full voyage within a service + + - c) `carrierServiceCode` **&** `vesselIMONumber`: Get a specific vessel’s full voyages within a service. + + - d) `vesselIMONumber`: Get all full voyages for a specific vessel across all the services in which it is involved. + + - e) `UNLocationCode`: Get all vessels and their full voyages where the specific `UNLocationCode` is involved + + - f) `UNLocationCode` **&** `facilitySMDGCode`: Get all vessels and their full voyages where the specific `UNLocationCode` and `facilitySMDGCode` is involved + + Other combinations using `vesselName`, `universalServiceReference`, `universalVoyageReference`, `vesselOperatorCarrierCode`, `startDate`, `endDate` are possible. + + The filter parameters `startDate` and `endDate` MUST always be used in combination with any of the other available parameters. + + The resulting payload returned in the responses will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`. + + Be aware that it is possible to specify filters that are mutually exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: `&vesselIMONumber=9321483&vesselName=King of the Seas`. If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list. + + If no `startDate` filter is provided, then **3 months** before the request date should be used as default. If no `endDate` filter is provided, then **6 months** after the request date should be used as default. The endpoint provider can customize these based on their business definitions and inform the consumers what to expect in a response when these filters are not used. + + The `GET /v1/vessel-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/port-schedules` endpoints. + + **IMPORTANT**: This endpoint is for carriers to make available vessel schedules to BCO, LSP, and Solution Platforms, with a commercial purpose; this is out of the boundaries of their vessel schedules alignment with other carriers and terminals for operational purposes for which the Operational Vessel Schedules [API](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS/3.0.0) is used between carriers, and carriers and terminals. + parameters: [] +components: + schemas: + PlaceOfReceipt: + title: Place of Receipt + type: object + description: | + The Location specifying where the place of receipt is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset. + PlaceOfDelivery: + title: Place of Delivery + type: object + description: | + The Location specifying where the place of delivery is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset. + PlaceOfArrival: + title: Place of Arrival + type: object + description: | + The Location specifying where the place of arrival is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset. + PlaceOfDeparture: + title: Place of Departure + type: object + description: | + The Location specifying where the place of departure is located. + required: + - facilityTypeCode + - location + - dateTime + properties: + facilityTypeCode: + description: | + The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall. + - `BORD` (Border) + - `CLOC` (Customer Location) + - `COFS` (Container Freight Station) + - `OFFD` (Off Dock Storage) + - `DEPO` (Depot) + - `INTE` (Inland Terminal) + - `POTE` (Port Terminal) + - `PBPL` (Pilot Boarding Place) + - `BRTH` (Berth) + - `RAMP` (Ramp) + - `WAYP` (Waypoint) + example: POTE + maxLength: 4 + type: string + location: + $ref: '#/components/schemas/Location' + dateTime: + type: string + format: date-time + example: '2025-01-14T09:21:00+01:00' + description: The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset. + pointToPointRoutings: + type: array + items: + $ref: '#/components/schemas/PointToPoint' + PointToPoint: + title: Point to Point + type: object + required: + - placeOfReceipt + - placeOfDelivery + - legs + properties: + placeOfReceipt: + $ref: '#/components/schemas/PlaceOfReceipt' + placeOfDelivery: + $ref: '#/components/schemas/PlaceOfDelivery' + receiptTypeAtOrigin: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Origin`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + deliveryTypeAtDestination: + type: string + maxLength: 3 + description: | + Indicates the type of service offered at `Destination`. The options are: + - `CY` (Container yard (incl. rail ramp)) + - `SD` (Store Door) + - `CFS` (Container Freight Station) + enum: + - CY + - SD + - CFS + example: CY + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + solutionNumber: + type: integer + format: int32 + minimum: 1 + example: 1 + description: Solution number, starting with 1. Used to group and identify similar or same routings in the response as per the carrier commercial definitions. + transitTime: + type: integer + description: The estimated total time in days that it takes a shipment to move from place of receipt to place of delivery. Transit time includes stop-over time during transhipments and waiting time at connection points, if applicable, thus can vary between the same locations. + format: int32 + example: 10 + legs: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Leg' + portSchedules: + type: array + items: + $ref: '#/components/schemas/PortSchedule' + PortSchedule: + title: Port Schedule + type: object + required: + - location + properties: + location: + $ref: '#/components/schemas/PortScheduleLocation' + vesselSchedules: + type: array + items: + $ref: '#/components/schemas/Schedule' + Schedule: + title: Schedule + type: object + required: + - servicePartners + - isDummyVessel + - timestamps + properties: + universalServiceReference: + type: string + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + servicePartners: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/ServicePartnerSchedule' + vessel: + $ref: '#/components/schemas/Vessel' + isDummyVessel: + type: boolean + description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist. + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + minLength: 5 + maxLength: 5 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + minLength: 5 + maxLength: 5 + timestamps: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Timestamp' + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + TransportCall: + title: Transport Call + type: object + required: + - transportCallReference + - carrierImportVoyageNumber + - timestamps + properties: + portVisitReference: + type: string + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + maxLength: 50 + example: NLRTM1234589 + transportCallReference: + type: string + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + example: SR11111X-9321483-2107W-NLRTM-HPD2-1-1 + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103N + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + universalImportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + maxLength: 5 + minLength: 5 + universalExportVoyageReference: + type: string + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + example: 2103N + maxLength: 5 + minLength: 5 + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + cutOffTimes: + type: array + description: A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper. + items: + $ref: '#/components/schemas/CutOffTime' + location: + $ref: '#/components/schemas/TransportCallLocation' + timestamps: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/Timestamp' + Timestamp: + title: Timestamp + type: object + required: + - eventTypeCode + - eventClassifierCode + - eventDateTime + properties: + eventTypeCode: + type: string + enum: + - ARRI + - DEPA + example: ARRI + description: | + Identifier for type of transportEvent. + + - `ARRI` (Arrived) + - `DEPA` (Departed) + eventClassifierCode: + type: string + enum: + - PLN + - EST + - ACT + example: PLN + description: | + Code for the event classifier. Values can vary depending on eventType. + + Possible values are: + - `ACT` (Actual) + - `EST` (Estimated) + - `PLN` (Planned) + eventDateTime: + type: string + format: date-time + description: The local date and time, when the event takes place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset. + example: '2025-01-14T09:21:00+01:00' + serviceSchedules: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + ServiceSchedule: + title: Service Schedule + type: object + required: + - carrierServiceName + - carrierServiceCode + - vesselSchedules + properties: + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + description: The carrier-specific code of the service for which the schedule details are published. + universalServiceReference: + type: string + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + example: SR12345A + description: A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. + vesselSchedules: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/VesselSchedule' + VesselSchedule: + title: Vessel Schedule + type: object + required: + - isDummyVessel + properties: + vessel: + $ref: '#/components/schemas/Vessel' + isDummyVessel: + type: boolean + description: This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist. + transportCalls: + type: array + items: + $ref: '#/components/schemas/TransportCall' + CutOffTime: + title: Cut-Off Time + type: object + description: Cut Off Times. + required: + - cutOffDateTimeCode + - cutOffDateTime + properties: + cutOffDateTimeCode: + type: string + description: | + Code for the cut-off time. Possible values are: + - `DCO` (Documentation cut-off) + - `VCO` (VGM cut-off) + - `FCO` (FCL delivery cut-off) + - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS` + - `PCO` (Port cut-off) + - `ECP` (Empty container pick-up date and time) + - `EFC` (Earliest full-container delivery date) + - `RCO` (Reefer cut-off) + - `DGC` (Dangerous Goods cut-off) + - `OBC` (OOG/BB cut-off) + - `TCO` (Transhipment cut-off) + - `STA` (Standard booking acceptance) + - `SPA` (Special booking acceptance) + - `CUA` (Customs Acceptance) + - `AFC` (Advanced filling cut-off) + + More details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/CutOffDateTimeCodeList-CS_v1.0.0.csv) + maxLength: 3 + example: DCO + cutOffDateTime: + type: string + format: date-time + description: Estimated cut-off time expressed in local time with offset following [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + example: '2019-11-12T07:41:00-08:30' + Address: + title: Address + type: object + description: An object for storing address related information. + required: + - street + - city + - countryCode + properties: + street: + type: string + example: Ruijggoordweg + description : The name of the street. + maxLength: 70 + streetNumber: + type: string + example: '100' + description: The number of the street. + maxLength: 50 + floor: + type: string + example: N/A + pattern: ^\S(?:.*\S)?$ + description: The floor of the street number. + maxLength: 50 + postCode: + type: string + example: 1047 HM + description: The post code. + maxLength: 10 + city: + type: string + example: Amsterdam + pattern: ^\S(?:.*\S)?$ + description: The name of the city. + maxLength: 35 + stateRegion: + type: string + example: North Holland + description: The name of the state/region. + maxLength: 65 + countryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + example: NL + ErrorResponse: + title: Error Response + type: object + required: + - httpMethod + - requestUri + - statusCode + - statusCodeText + - errorDateTime + - errors + properties: + httpMethod: + type: string + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + description: The HTTP method used to make the request e.g. `GET`, `POST`, etc + requestUri: + type: string + description: The URI that was requested. + example: /v1/events + statusCode: + type: integer + description: The HTTP status code returned. + format: int32 + example: 400 + statusCodeText: + type: string + description: A standard short description corresponding to the HTTP status code. + example: Bad Request + maxLength: 50 + statusCodeMessage: + type: string + description: A long description corresponding to the HTTP status code with additional information. + maxLength: 200 + example: The supplied data could not be accepted + providerCorrelationReference: + type: string + description: A unique identifier to the HTTP request within the scope of the API provider. + maxLength: 100 + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + type: string + description: The DateTime corresponding to the error occurring. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + example: '2019-11-12T07:41:00Z' + format: date-time + errors: + type: array + description: An array of errors providing more detail about the root cause. + minItems: 1 + items: + $ref: '#/components/schemas/DetailedError' + Vessel: + title: Vessel + type: object + properties: + vesselIMONumber: + type: string + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + example: '9321483' + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + MMSINumber: + type: string + description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station. + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + example: '278111222' + name: + type: string + description: The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + flag: + type: string + description: The flag of the nation whose laws the vessel is registered under. This is the [ISO 3166](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) two-letter country code. + pattern: ^[A-Z]{2}$ + maxLength: 2 + minLength: 2 + example: DE + callSign: + type: string + description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + pattern: ^\S(?:.*\S)?$ + example: NCVV + maxLength: 10 + operatorCarrierCode: + type: string + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + example: MAEU + maxLength: 10 + operatorCarrierCodeListProvider: + type: string + description: Identifies the code list provider used for the operator and partner carriercodes. + example: NMFTA + enum: + - SMDG + - NMFTA + Barge: + title: Barge + type: object + properties: + vesselIMONumber: + type: string + description: The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel. + example: '9321483' + pattern: ^\d{7,8}$ + minLength: 7 + maxLength: 8 + MMSINumber: + type: string + description: Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station. + pattern: ^\d{9}$ + minLength: 9 + maxLength: 9 + example: '278111222' + name: + type: string + description: The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + flag: + type: string + description: The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code. + pattern: ^[A-Z]{2}$ + maxLength: 2 + minLength: 2 + example: DE + callSign: + type: string + description: A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + pattern: ^\S(?:.*\S)?$ + example: NCVV + maxLength: 10 + operatorCarrierCode: + type: string + description: The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists. + example: MAEU + maxLength: 10 + operatorCarrierCodeListProvider: + type: string + description: Identifies the code list provider used for the operator and partner carriercodes. + example: NMFTA + enum: + - SMDG + - NMFTA + VesselTransport: + title: Vessel Transport + type: object + description: Transport mode Vessel. + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: The mode of transport as defined by DCSA. For the Vessel Transport mode this needs to be `VESSEL`. + enum: + - VESSEL + example: VESSEL + portVisitReference: + type: string + example: NLAMS1234589 + maxLength: 50 + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + transportCallReference: + type: string + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + servicePartners: + type: array + items: + $ref: '#/components/schemas/ServicePartner' + universalServiceReference: + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + vessel: + $ref: '#/components/schemas/Vessel' + BargeTransport: + title: Barge Transport + type: object + description: Transport mode Barge. + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: The mode of transport as defined by DCSA. For the Barge Transport mode this needs to be `BARGE`. + enum: + - BARGE + example: BARGE + portVisitReference: + type: string + example: NLAMS1234589 + maxLength: 50 + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call. + transportCallReference: + type: string + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + maxLength: 100 + description: The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + servicePartners: + type: array + items: + $ref: '#/components/schemas/ServicePartner' + universalServiceReference: + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + pattern: ^SR\d{5}[A-Z]$ + maxLength: 8 + minLength: 8 + universalExportVoyageReference: + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + universalImportVoyageReference: + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + + pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ + minLength: 5 + maxLength: 5 + example: 2103N + barge: + $ref: '#/components/schemas/Barge' + OtherTransport: + title: Other Transport + type: object + description: Other Transport modes. + additionalProperties: false + required: + - modeOfTransport + properties: + modeOfTransport: + type: string + description: | + The mode of transport as defined by DCSA. The allowed values for the Other Transport mode are: + - `RAIL` (When the transport mode is Rail) + - `TRUCK`(When the transport mode is Truck) + - `RAIL_TRUCK`(When rail and truck are expected to be the mode of transport in a leg of a proposed routing) + - `BARGE_TRUCK`(When barge and truck are expected to be the mode of transport in a leg of a proposed routing) + - `BARGE_RAIL`(When barge and rail are expected to be the mode of transport in a leg of a proposed routing) + - `MULTIMODAL`(When mode of transport is not really defined or unknown at this stage) + enum: + - RAIL_TRUCK + - BARGE_TRUCK + - BARGE_RAIL + - MULTIMODAL + - RAIL + - TRUCK + example: RAIL + Facility: + title: Facility + type: object + description: A way to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + required: + - facilityCode + - facilityCodeListProvider + properties: + facilityCode: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 6 + example: ADT + description: | + The code used for identifying the specific facility. This code does not include the UN Location Code.The definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used: + - for `SMDG` - the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + - for `BIC` - the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/) + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code`. + - `BIC` (Requires a UN Location Code) + - `SMDG` (Requires a UN Location Code) + enum: + - BIC + - SMDG + example: SMDG + ServicePartner: + title: Service Partner + type: object + description: The service code and voyage number as identified by the carriers that are partners in the service. + properties: + carrierCode: + type: string + description: The carrier code based on either the SMDG or SCAC code lists. + maxLength: 4 + pattern: ^\S+$ + example: MAEU + carrierCodeListProvider: + type: string + description: Identifies the code list provider used for the `carrierCode`. + example: NMFTA + enum: + - SMDG + - NMFTA + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + description: The carrier-specific code of the service for which the schedule details are published. + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + example: 2103N + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + ServicePartnerSchedule: + title: Service Partner Schedule + type: object + required: + - carrierServiceName + - carrierServiceCode + - carrierImportVoyageNumber + - carrierExportVoyageNumber + description: The service code and voyage number as identified by the carriers that are partners in the service. + properties: + carrierCode: + type: string + description: The carrier code based on either the SMDG or SCAC code lists. + maxLength: 4 + pattern: ^\S+$ + example: MAEU + carrierCodeListProvider: + type: string + description: Identifies the code list provider used for the `carrierCode`. + example: NMFTA + enum: + - SMDG + - NMFTA + carrierServiceName: + type: string + description: The name of the service. + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: Great Lion Service + carrierServiceCode: + type: string + description: The carrier-specific code of the service for which the schedule details are published. + maxLength: 11 + example: FE1 + pattern: ^\S(?:.*\S)?$ + carrierImportVoyageNumber: + type: string + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + example: 2103S + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + carrierExportVoyageNumber: + type: string + example: 2103N + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + Leg: + title: Leg + type: object + description: Leg of the Point-to-Point routing. The property `Leg` can be conformed by as many leg as needed and this leg must be identified with a sequence number. + required: + - departure + - arrival + properties: + sequenceNumber: + type: integer + format: int32 + description: Sequence number of the leg. + example: 1 + transport: + description: The mode of transport as defined by DCSA. + oneOf: + - $ref: '#/components/schemas/VesselTransport' + - $ref: '#/components/schemas/BargeTransport' + - $ref: '#/components/schemas/OtherTransport' + departure: + $ref: '#/components/schemas/PlaceOfDeparture' + arrival: + $ref: '#/components/schemas/PlaceOfArrival' + Location: + title: Location + type: object + description: | + The location can be specified using **any** of the nested structures: + - `Address` (used to specify the location via an Address) + - `UNLocationCode` + - `Facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`) + + It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + address: + $ref: '#/components/schemas/Address' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facility: + $ref: '#/components/schemas/Facility' + TransportCallLocation: + title: TransportCall Location + type: object + description: | + General purpose object to capture location-related data, the location can be specified in **any** of the following ways: + - `Address` (used to specify the location via an Address) + - `UNLocationCode` + - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`) + It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + address: + $ref: '#/components/schemas/Address' + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facilitySMDGCode: + type: string + example: ACT + description: The code used for identifying the specific facility. This code does not include the UN Location Code. + + The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + maxLength: 6 + PortScheduleLocation: + title: Port Schedule Location + type: object + description: | + General purpose object to capture location-related data, the location can be specified in **any** of the following ways: + - `UNLocationCode` + - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`) + + It is expected that if a location is specified in multiple ways (both as a `UNLocationCode` and as a `facilitySMDGCode`) that both ways point to the same location. + properties: + locationName: + type: string + pattern: ^\S(?:.*\S)?$ + example: Port of Amsterdam + maxLength: 100 + description: An optional name for the location. + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN Location code specifying where the place is located. The pattern used must be + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download) + example: NLAMS + facilitySMDGCode: + type: string + example: ACT + description: The code used for identifying the specific facility. This code does not include the UN Location Code. + + The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/) + maxLength: 6 + DetailedError: + title: Detailed Error + type: object + description: A detailed description of what has caused the error. + required: + - errorCodeText + - errorCodeMessage + properties: + errorCode: + type: integer + format: int32 + description: | + The detailed error code returned. + + - `7000-7999` Technical error codes + - `8000-8999` Functional error codes + - `9000-9999` API provider-specific error codes + + [Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes). + example: 7003 + minimum: 7000 + maximum: 9999 + property: + type: string + description: The name of the property causing the error. + example: facilityCode + maxLength: 100 + value: + type: string + description: The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + maxLength: 500 + jsonPath: + type: string + description: A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + maxLength: 500 + errorCodeText: + type: string + description: A standard short description corresponding to the `errorCode`. + example: invalidData + maxLength: 100 + errorCodeMessage: + type: string + description: A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + maxLength: 5000 + parameters: + Api-Version-Major: + in: header + name: API-Version + required: false + schema: + type: string + example: '1' + description: | + An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version. +tags: + - name: Point To Point + description: ' ' + - name: Port Schedule + description: ' ' + - name: Vessel Schedule + description: ' ' diff --git a/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/commercialschedules-api-v10.json b/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/commercialschedules-api-v10.json deleted file mode 100644 index a88c2e80..00000000 --- a/commercial-schedules/src/main/resources/standards/commercialschedules/schemas/commercialschedules-api-v10.json +++ /dev/null @@ -1,2056 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA OpenAPI specification for Commercial Schedules", - "description": "API specification issued by [Digital Container Shipping Association (DCSA)](https://dcsa.org/).\n\nThe Commercial Schedules API offers BCOs, LSPs, and Solution Platforms three different methods and endpoints to access schedules from carriers based on their specific needs: Point-to-Point Routings, Port Schedules, and Vessel Schedules. \n\n**Commercial schedules - point-to-point routings**: provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs.\n \n**Commercial schedules – port schedules**: provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps.\n \n**Commercial schedules – vessel schedules**: provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s).\n\n**All use cases mentioned in this API specification refer to use cases defined in the Commercial Schedules Interface Standard.**\n\nThe Commercial Schedules endpoints can be implemented independently:\n\n`1. GET /v1/point-to-point-routes # For Point to Point Routings`\n\n`2. GET /v1/port-schedules # For Port Schedules`\n\n`3. GET /v1/vessel-schedules # For Vessel Schedules`\n\nVisit the [DCSA Website](https://dcsa.org/standards/commercial-schedules/) to find other documentation related to the standard publication (i.e. Interface Standard, Information Model).\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design).\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/cs/v1#v100). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org/", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://localhost:3000" - } - ], - "tags": [ - { - "name": "Point To Point", - "description": " " - }, - { - "name": "Port Schedule", - "description": " " - }, - { - "name": "Vessel Schedule", - "description": " " - } - ], - "paths": { - "/v1/point-to-point-routes": { - "get": { - "tags": [ - "Point To Point" - ], - "summary": "Point to Point Routing", - "description": "Provides the product offering of single or multiple estimated end-to-end route options for a shipment in the pre-booking phase. This includes point-to-point specification of all transport legs, estimated timings, estimated schedules and interdependencies between transport legs.\n\nThe list of solutions returned in the response can be tailored to a specific need by combining available query parameters.\n\nThe minimum required query parameters are `placeOfReceipt` and `placeOfDelivery`. If no further query parameters are used to tailor the response, the provider of the GET endpoint will return their best suggestions in the response. \n\nThe `GET /v1/point-to-point-routes` endpoint can be implemented independently of having implemented the `GET /v1/port-schedules` and `GET /v1/vessel-schedules` endpoints.\n", - "operationId": "get-v1-point-to-point", - "parameters": [ - { - "name": "placeOfReceipt", - "in": "query", - "description": "The `UNLocationCode` specifying where the place is located.", - "required": true, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "example": "NLAMS" - } - }, - { - "name": "placeOfDelivery", - "in": "query", - "description": "The `UNLocationCode` specifying where the place is located.", - "required": true, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "example": "NLAMS" - } - }, - { - "name": "departureStartDate", - "in": "query", - "description": "Limit the result based on the earliest departureDate. \n- If provided without departureEndDate, returns all routings with departures from the specified departureStartDate onwards.\n- If provided with departureEndDate, returns all routings with departures within the specified date range, inclusive of both dates.\n- If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date.\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2021-04-01" - } - }, - { - "name": "departureEndDate", - "in": "query", - "description": "Limit the result based on the latest departureDate. \n- If provided without departureStartDate, returns all routings with departures up to the specified departureEndDate.\n- If provided with departureStartDate, returns all routings with departures within the specified date range, inclusive of both dates.\n- If the same date is provided for both departureStartDate and departureEndDate, returns all routings with departures on that specific date. \n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2021-05-01" - } - }, - { - "name": "arrivalStartDate", - "in": "query", - "description": "Limit the result based on the earliest arrivalDate.\n- If provided without arrivalEndDate, returns all routings with arrivals from the specified arrivalStartDate.\n- If provided with arrivalEndDate, returns all routings with arrivals within the specified date range, inclusive of both dates.\n- If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date.\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2021-04-01" - } - }, - { - "name": "arrivalEndDate", - "in": "query", - "description": "Limit the result based on the latest arrivalDate.\n- If provided without arrivalStartDate, returns all routings with arrivals up to the specified arrivalEndDate.\n- If provided with arrivalStartDate, returns all routings with arrivals within the specified date range, inclusive of both dates.\n- If the same date is provided for both arrivalStartDate and arrivalEndDate, returns all routings with arrivals on that specific date.\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2021-05-01" - } - }, - { - "name": "maxTranshipment", - "in": "query", - "description": "Specifies the maximum number of transhipments that the proposed routings can have in the response. By default, transhipments are allowed and the responses can have either direct routings or routings with transhipment. The default value of maximum transhipments is defined by the carrier for when the consumer does not provide a value. If the user sets the number of transhipments to 0, only direct routings can be returned in the response.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "example": 1 - } - }, - { - "name": "receiptTypeAtOrigin", - "in": "query", - "description": "Indicates the type of service offered at Origin. **Carriers can choose to define a default value when the consumer does not provide it.**\n - `CY` (Container yard (incl. rail ramp)) \n - `SD` (Store Door) \n - `CFS` (Container Freight Station)\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 3, - "type": "string", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - } - }, - { - "name": "deliveryTypeAtDestination", - "in": "query", - "description": "Indicates the type of service offered at Destination. **Carriers can choose to define a default value when the consumer does not provide it.**\n - `CY` (Container yard (incl. rail ramp)) \n - `SD` (Store Door) \n - `CFS` (Container Freight Station)\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 3, - "type": "string", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - } - }, - { - "name": "limit", - "in": "query", - "description": "Specifies the maximum number of `Point-to-Point` objects to return.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "example": 100, - "default": 100 - } - }, - { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 1024, - "type": "string" - }, - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - }, - "Next-Page-Cursor": { - "description": "The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response.\nWhen an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:\n`Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.\n\nTo retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`.\n", - "style": "simple", - "explode": false, - "schema": { - "maxLength": 1024, - "type": "string", - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PointToPoint" - } - } - } - } - }, - "400": { - "description": "Bad Request", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/point-to-point", - "statusCode": 400, - "statusCodeText": "Bad Request", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7005, - "property": "placeOfDelivery", - "value": "SG", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "PlaceOfDelivery does not exist" - } - ] - } - } - } - } - } - }, - "500": { - "description": "Internal Server Error", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/point-to-point", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Unable to process request", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7007, - "property": "UNLocationCode", - "value": "NA", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "UNLocationCode does not exist" - } - ] - } - } - } - } - } - } - } - } - }, - "/v1/port-schedules": { - "get": { - "tags": [ - "Port Schedule" - ], - "summary": "Port Schedule", - "description": "Provides, for a required specific port and starting date, the set of all vessels arriving and departing from the port with the corresponding estimated timestamps.\n\nThe port must be identified by its UN Location Code. \n\nThe required query parameters are `UNLocationCode` and `date`. \n\nIf the requested port (identified with `UNLocationCode`) has multiple terminals (identified with `facilitySMDGCode`), the response will include a sorted list that provides all the arrivals and departures of the vessels for each terminal of the port (`UNLocationCode`). \n\nThe `GET /v1/port-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/vessel-schedules` endpoints. \n", - "operationId": "get-v1-port-schedules", - "parameters": [ - { - "name": "UNLocationCode", - "in": "query", - "description": "The UN Location code specifying where the place is located. Specifying this filter will only return the set of all vessels arriving and departing from the port and its terminals.", - "required": true, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "example": "NLAMS" - } - }, - { - "name": "date", - "in": "query", - "description": "The date since when the estimated arrival and departures of vessels in a given port is required.", - "required": true, - "style": "form", - "explode": true, - "schema": { - "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", - "type": "string", - "format": "date", - "example": "2023-07-01" - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - }, - { - "name": "limit", - "in": "query", - "description": "Specifies the maximum number of `Port Schedule` objects to return.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "example": 100, - "default": 100 - } - }, - { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 1024, - "type": "string", - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - }, - "Next-Page-Cursor": { - "description": "The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response.\nWhen an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:\n`Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.\n\nTo retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`.\n", - "style": "simple", - "explode": false, - "schema": { - "maxLength": 1024, - "type": "string", - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PortSchedule" - } - } - } - } - }, - "400": { - "description": "Bad Request", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/port-schedule", - "statusCode": 400, - "statusCodeText": "Bad Request", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7005, - "property": "port", - "value": "SG", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "Port does not exist" - } - ] - } - } - } - } - } - }, - "500": { - "description": "Internal Server Error", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/port-schedule", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Cannot process request.", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7007, - "property": "UNLocationCode", - "value": "NA", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "UNLocationCode does not exist" - } - ] - } - } - } - } - } - } - } - } - }, - "/v1/vessel-schedules": { - "get": { - "tags": [ - "Vessel Schedule" - ], - "summary": "Vessel Schedule", - "description": "Provides, for a required specific service and/or voyage and/or vessel and/or location, the timetable of estimated departure and arrival times for each port call on the rotation of the vessel(s).\n\nThe list of schedules returned in the response can be tailored to specific needs by combining available query parameters. \n\nA filter parameter or a combination of filter parameters MUST always be provided to call the endpoint. Examples of typical query parameters and expected payload returned in the response:\n\n- a) `carrierServiceCode`: Get all vessels and their full voyages within a service \n\n- b) `carrierServiceCode` **&** `carrierVoyageNumber`: Get a specific full voyage within a service\n\n- c) `carrierServiceCode` **&** `vesselIMONumber`: Get a specific vessel’s full voyages within a service. \n\n- d) `vesselIMONumber`: Get all full voyages for a specific vessel across all the services in which it is involved.\n\n- e) `UNLocationCode`: Get all vessels and their full voyages where the specific `UNLocationCode` is involved\n\n- f) `UNLocationCode` **&** `facilitySMDGCode`: Get all vessels and their full voyages where the specific `UNLocationCode` and `facilitySMDGCode` is involved\n\nOther combinations using `vesselName`, `universalServiceReference`, `universalVoyageReference`, `vesselOperatorCarrierCode`, `startDate`, `endDate` are possible. \n\nThe filter parameters `startDate` and `endDate` MUST always be used in combination with any of the other available parameters.\n\nThe resulting payload returned in the responses will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.\n\nBe aware that it is possible to specify filters that are mutually exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time: `&vesselIMONumber=9321483&vesselName=King of the Seas`. If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list. \n\nIf no `startDate` filter is provided, then **3 months** before the request date should be used as default. If no `endDate` filter is provided, then **6 months** after the request date should be used as default. The endpoint provider can customize these based on their business definitions and inform the consumers what to expect in a response when these filters are not used. \n\nThe `GET /v1/vessel-schedules` endpoint can be implemented independently of having implemented the `GET /v1/point-to-point-routes` and `GET /v1/port-schedules` endpoints. \n\n**IMPORTANT**: This endpoint is for carriers to make available vessel schedules to BCO, LSP, and Solution Platforms, with a commercial purpose; this is out of the boundaries of their vessel schedules alignment with other carriers and terminals for operational purposes for which the Operational Vessel Schedules [API](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS/3.0.0) is used between carriers, and carriers and terminals. \n", - "operationId": "get-v1-vessel-schedule", - "parameters": [ - { - "name": "vesselIMONumber", - "in": "query", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 8, - "minLength": 7, - "pattern": "^\\d{7,8}$", - "type": "string", - "example": "9321483" - } - }, - { - "name": "vesselName", - "in": "query", - "description": "The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the vesselName is not unique and might match multiple vessels.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "King of the Seas" - } - }, - { - "name": "carrierServiceCode", - "in": "query", - "description": "The carrier specific service code to filter by. The result will only return schedules including the service code.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 11, - "type": "string", - "example": "FE1" - } - }, - { - "name": "universalServiceReference", - "in": "query", - "description": "The Universal Service Reference (USR) as defined by DCSA to filter by.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "example": "SR12345A" - } - }, - { - "name": "carrierVoyageNumber", - "in": "query", - "description": "The carrier specific identifier of a Voyage - can be both `importVoyageNumber` and `exportVoyageNumber`. The result will only return schedules including the Ports where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 50, - "type": "string", - "example": "2103S" - } - }, - { - "name": "universalVoyageReference", - "in": "query", - "description": "The Universal Reference of a Voyage - can be both `importUniversalVoyageReference` and `exportUniversalVoyageReference`. The result will only return schedules including the Ports where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference`.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "example": "2201N" - } - }, - { - "name": "UNLocationCode", - "in": "query", - "description": "The UN Location Code specifying where a port is located. Specifying this filter will only return schedules including entire Voyages related to this particular UN Location Code.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "example": "NLAMS" - } - }, - { - "name": "facilitySMDGCode", - "in": "query", - "description": "The facilitySMDGCode specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including entire Voyages related to this particular `facilitySMDGCode`.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 6, - "type": "string", - "example": "APM" - } - }, - { - "name": "vesselOperatorCarrierCode", - "in": "query", - "description": "The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 10, - "type": "string", - "example": "MAEU" - } - }, - { - "name": "startDate", - "in": "query", - "description": "The start date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or after (≥) the `startDate` the entire Voyage (import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call.\nIf this filter is not provided the default value is `3 months` prior to request time. The value is populated in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date format.\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2020-04-06" - } - }, - { - "name": "endDate", - "in": "query", - "description": "The end date of the period for which schedule information is requested. If a date of any Timestamp (ATA, ETA or PTA) inside a PortCall matches a date on or before (≤) the `endDate` the entire Voyage(import- and export-Voyage) matching the PortCall will be included in the result. All matching is done towards local Date at the place of the port call. \nIf this filter is not provided the default value is `6 months` after request time. The value is populated in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date format.\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2020-04-10" - } - }, - { - "name": "limit", - "in": "query", - "description": "Specifies the maximum number of `Service Schedule` objects to return.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "example": 100, - "default": 100 - } - }, - { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 1024, - "type": "string", - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - }, - "Next-Page-Cursor": { - "description": "The Next-Page-Cursor header contains a cursor value that points to the next page of results in a paginated API response.\nWhen an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header:\n`Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The cursor value is used in subsequent requests to retrieve the next page by passing it as a query parameter: `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`.\n\nTo retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`.\n", - "style": "simple", - "explode": false, - "schema": { - "maxLength": 1024, - "type": "string", - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA" - } - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServiceSchedule" - } - } - } - } - }, - "400": { - "description": "Bad Request", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/vessel-schedule", - "statusCode": 400, - "statusCodeText": "Bad Request", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7007, - "property": "UNLocationCode", - "value": "NA", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "UNLocationCode does not exist" - } - ] - } - } - } - } - } - }, - "500": { - "description": "Internal Server Error", - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/cs/v1/vessel-schedule", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Cannot process request.", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7007, - "property": "UNLocationCode", - "value": "NA", - "errorCodeText": "invalidQuery", - "errorCodeMessage": "UNLocationCode does not exist" - } - ] - } - } - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "PlaceOfReceipt": { - "title": "Place of Receipt", - "required": [ - "dateTime", - "facilityTypeCode", - "location" - ], - "type": "object", - "properties": { - "facilityTypeCode": { - "maxLength": 4, - "type": "string", - "description": "The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.\n- `BORD` (Border)\n- `CLOC` (Customer Location)\n- `COFS` (Container Freight Station)\n- `OFFD` (Off Dock Storage)\n- `DEPO` (Depot)\n- `INTE` (Inland Terminal)\n- `POTE` (Port Terminal)\n- `PBPL` (Pilot Boarding Place)\n- `BRTH` (Berth)\n- `RAMP` (Ramp)\n- `WAYP` (Waypoint)\n", - "example": "POTE" - }, - "location": { - "$ref": "#/components/schemas/Location" - }, - "dateTime": { - "type": "string", - "description": "The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset.", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - } - }, - "description": "The Location specifying where the place of receipt is located.\n" - }, - "PlaceOfDelivery": { - "title": "Place of Delivery", - "required": [ - "dateTime", - "facilityTypeCode", - "location" - ], - "type": "object", - "properties": { - "facilityTypeCode": { - "maxLength": 4, - "type": "string", - "description": "The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.\n- `BORD` (Border)\n- `CLOC` (Customer Location)\n- `COFS` (Container Freight Station)\n- `OFFD` (Off Dock Storage)\n- `DEPO` (Depot)\n- `INTE` (Inland Terminal)\n- `POTE` (Port Terminal)\n- `PBPL` (Pilot Boarding Place)\n- `BRTH` (Berth)\n- `RAMP` (Ramp)\n- `WAYP` (Waypoint)\n", - "example": "POTE" - }, - "location": { - "$ref": "#/components/schemas/Location" - }, - "dateTime": { - "type": "string", - "description": "The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset.", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - } - }, - "description": "The Location specifying where the place of delivery is located.\n" - }, - "PlaceOfArrival": { - "title": "Place of Arrival", - "required": [ - "dateTime", - "facilityTypeCode", - "location" - ], - "type": "object", - "properties": { - "facilityTypeCode": { - "maxLength": 4, - "type": "string", - "description": "The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.\n- `BORD` (Border)\n- `CLOC` (Customer Location)\n- `COFS` (Container Freight Station)\n- `OFFD` (Off Dock Storage)\n- `DEPO` (Depot)\n- `INTE` (Inland Terminal)\n- `POTE` (Port Terminal)\n- `PBPL` (Pilot Boarding Place)\n- `BRTH` (Berth)\n- `RAMP` (Ramp)\n- `WAYP` (Waypoint)\n", - "example": "POTE" - }, - "location": { - "$ref": "#/components/schemas/Location" - }, - "dateTime": { - "type": "string", - "description": "The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset.", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - } - }, - "description": "The Location specifying where the place of arrival is located.\n" - }, - "PlaceOfDeparture": { - "title": "Place of Departure", - "required": [ - "dateTime", - "facilityTypeCode", - "location" - ], - "type": "object", - "properties": { - "facilityTypeCode": { - "maxLength": 4, - "type": "string", - "description": "The code to identify the specific type of facility. The code indicates which role the facility plays during the transportCall.\n- `BORD` (Border)\n- `CLOC` (Customer Location)\n- `COFS` (Container Freight Station)\n- `OFFD` (Off Dock Storage)\n- `DEPO` (Depot)\n- `INTE` (Inland Terminal)\n- `POTE` (Port Terminal)\n- `PBPL` (Pilot Boarding Place)\n- `BRTH` (Berth)\n- `RAMP` (Ramp)\n- `WAYP` (Waypoint)\n", - "example": "POTE" - }, - "location": { - "$ref": "#/components/schemas/Location" - }, - "dateTime": { - "type": "string", - "description": "The local date and time, when the event will take place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset.", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - } - }, - "description": "The Location specifying where the place of departure is located.\n" - }, - "pointToPointRoutings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PointToPoint" - } - }, - "PointToPoint": { - "title": "Point to Point", - "required": [ - "legs", - "placeOfDelivery", - "placeOfReceipt" - ], - "type": "object", - "properties": { - "placeOfReceipt": { - "$ref": "#/components/schemas/PlaceOfReceipt" - }, - "placeOfDelivery": { - "$ref": "#/components/schemas/PlaceOfDelivery" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cutOffTimes": { - "type": "array", - "description": "A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.", - "items": { - "$ref": "#/components/schemas/CutOffTime" - } - }, - "solutionNumber": { - "minimum": 1, - "type": "integer", - "description": "Solution number, starting with 1. Used to group and identify similar or same routings in the response as per the carrier commercial definitions.", - "format": "int32", - "example": 1 - }, - "transitTime": { - "type": "integer", - "description": "The estimated total time in days that it takes a shipment to move from place of receipt to place of delivery. Transit time includes stop-over time during transhipments and waiting time at connection points, if applicable, thus can vary between the same locations.", - "format": "int32", - "example": 10 - }, - "legs": { - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/Leg" - } - } - } - }, - "portSchedules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PortSchedule" - } - }, - "PortSchedule": { - "title": "Port Schedule", - "required": [ - "location" - ], - "type": "object", - "properties": { - "location": { - "$ref": "#/components/schemas/PortScheduleLocation" - }, - "vesselSchedules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Schedule" - } - } - } - }, - "Schedule": { - "title": "Schedule", - "required": [ - "isDummyVessel", - "servicePartners", - "timestamps" - ], - "type": "object", - "properties": { - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "servicePartners": { - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/ServicePartnerSchedule" - } - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "isDummyVessel": { - "type": "boolean", - "description": "This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist." - }, - "universalImportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "timestamps": { - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/Timestamp" - } - }, - "cutOffTimes": { - "type": "array", - "description": "A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.", - "items": { - "$ref": "#/components/schemas/CutOffTime" - } - } - } - }, - "TransportCall": { - "title": "Transport Call", - "required": [ - "carrierImportVoyageNumber", - "timestamps", - "transportCallReference" - ], - "type": "object", - "properties": { - "portVisitReference": { - "maxLength": 50, - "type": "string", - "description": "The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.", - "example": "NLRTM1234589" - }, - "transportCallReference": { - "maxLength": 100, - "type": "string", - "description": "The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.", - "example": "SR11111X-9321483-2107W-NLRTM-HPD2-1-1" - }, - "carrierImportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an import voyage. The carrier-specific identifier of the import Voyage.", - "example": "2103N" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.", - "example": "2103S" - }, - "universalImportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "cutOffTimes": { - "type": "array", - "description": "A list of cut-offs times provided by the carrier when available. A cut-off time indicates the latest date and time by which a task must be completed. For example, the latest date and time by which a container must be delivered to a terminal to be loaded on a vessel, or where certain documentation must be provided by the Shipper.", - "items": { - "$ref": "#/components/schemas/CutOffTime" - } - }, - "location": { - "$ref": "#/components/schemas/TransportCallLocation" - }, - "timestamps": { - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/Timestamp" - } - } - } - }, - "Timestamp": { - "title": "Timestamp", - "required": [ - "eventClassifierCode", - "eventDateTime", - "eventTypeCode" - ], - "type": "object", - "properties": { - "eventTypeCode": { - "type": "string", - "description": "Identifier for type of transportEvent.\n\n- `ARRI` (Arrived)\n- `DEPA` (Departed)\n", - "example": "ARRI", - "enum": [ - "ARRI", - "DEPA" - ] - }, - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier. Values can vary depending on eventType.\n\nPossible values are:\n- `ACT` (Actual)\n- `EST` (Estimated)\n- `PLN` (Planned)\n", - "example": "PLN", - "enum": [ - "PLN", - "EST", - "ACT" - ] - }, - "eventDateTime": { - "type": "string", - "description": "The local date and time, when the event takes place, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format specifying the offset.", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - } - } - }, - "serviceSchedules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServiceSchedule" - } - }, - "ServiceSchedule": { - "title": "Service Schedule", - "required": [ - "carrierServiceCode", - "carrierServiceName", - "vesselSchedules" - ], - "type": "object", - "properties": { - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the service.", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier-specific code of the service for which the schedule details are published.", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service.", - "example": "SR12345A" - }, - "vesselSchedules": { - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/VesselSchedule" - } - } - } - }, - "VesselSchedule": { - "title": "Vessel Schedule", - "required": [ - "isDummyVessel" - ], - "type": "object", - "properties": { - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "isDummyVessel": { - "type": "boolean", - "description": "This property can be set to `true` when no vessel has been assigned, indicating that the `vesselIMONumber` does not exist." - }, - "transportCalls": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TransportCall" - } - } - } - }, - "CutOffTime": { - "title": "Cut-Off Time", - "required": [ - "cutOffDateTime", - "cutOffDateTimeCode" - ], - "type": "object", - "properties": { - "cutOffDateTimeCode": { - "maxLength": 3, - "type": "string", - "description": "Code for the cut-off time. Possible values are:\n - `DCO` (Documentation cut-off)\n - `VCO` (VGM cut-off)\n - `FCO` (FCL delivery cut-off)\n - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS`\n - `PCO` (Port cut-off)\n - `ECP` (Empty container pick-up date and time)\n - `EFC` (Earliest full-container delivery date)\n - `RCO` (Reefer cut-off)\n - `DGC` (Dangerous Goods cut-off)\n - `OBC` (OOG/BB cut-off)\n - `TCO` (Transhipment cut-off)\n - `STA` (Standard booking acceptance)\n - `SPA` (Special booking acceptance)\n - `CUA` (Customs Acceptance)\n - `AFC` (Advanced filling cut-off)\n \nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/CutOffDateTimeCodeList-CS_v1.0.0.csv)\n", - "example": "DCO" - }, - "cutOffDateTime": { - "type": "string", - "description": "Estimated cut-off time expressed in local time with offset following [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.", - "format": "date-time", - "example": "2019-11-12T07:41:00-08:30" - } - }, - "description": "Cut Off Times." - }, - "Address": { - "title": "Address", - "required": [ - "city", - "countryCode", - "street" - ], - "type": "object", - "properties": { - "street": { - "maxLength": 70, - "type": "string", - "description": "The name of the street.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The floor of the street number.", - "example": "N/A" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code.", - "example": "1047 HM" - }, - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the city.", - "example": "Amsterdam" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The name of the state/region.", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing address related information." - }, - "ErrorResponse": { - "title": "Error Response", - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc", - "example": "POST", - "enum": [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ] - }, - "requestUri": { - "type": "string", - "description": "The URI that was requested.", - "example": "/v1/events" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code returned.", - "format": "int32", - "example": 400 - }, - "statusCodeText": { - "maxLength": 50, - "type": "string", - "description": "A standard short description corresponding to the HTTP status code.", - "example": "Bad Request" - }, - "statusCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the HTTP status code with additional information.", - "example": "The supplied data could not be accepted" - }, - "providerCorrelationReference": { - "maxLength": 100, - "type": "string", - "description": "A unique identifier to the HTTP request within the scope of the API provider.", - "example": "4426d965-0dd8-4005-8c63-dc68b01c4962" - }, - "errorDateTime": { - "type": "string", - "description": "The DateTime corresponding to the error occurring. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.", - "format": "date-time", - "example": "2019-11-12T07:41:00Z" - }, - "errors": { - "minItems": 1, - "type": "array", - "description": "An array of errors providing more detail about the root cause.", - "items": { - "$ref": "#/components/schemas/DetailedError" - } - } - } - }, - "Vessel": { - "title": "Vessel", - "type": "object", - "properties": { - "vesselIMONumber": { - "maxLength": 8, - "minLength": 7, - "pattern": "^\\d{7,8}$", - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.", - "example": "9321483" - }, - "MMSINumber": { - "maxLength": 9, - "minLength": 9, - "pattern": "^\\d{9}$", - "type": "string", - "description": "Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.", - "example": "278111222" - }, - "name": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.", - "example": "King of the Seas" - }, - "flag": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "type": "string", - "description": "The flag of the nation whose laws the vessel is registered under. This is the [ISO 3166](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) two-letter country code.", - "example": "DE" - }, - "callSign": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.", - "example": "NCVV" - }, - "operatorCarrierCode": { - "maxLength": 10, - "type": "string", - "description": "The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.", - "example": "MAEU" - }, - "operatorCarrierCodeListProvider": { - "type": "string", - "description": "Identifies the code list provider used for the operator and partner carriercodes.", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - } - } - }, - "Barge": { - "title": "Barge", - "type": "object", - "properties": { - "vesselIMONumber": { - "maxLength": 8, - "minLength": 7, - "pattern": "^\\d{7,8}$", - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel.", - "example": "9321483" - }, - "MMSINumber": { - "maxLength": 9, - "minLength": 9, - "pattern": "^\\d{9}$", - "type": "string", - "description": "Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.", - "example": "278111222" - }, - "name": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.", - "example": "King of the Seas" - }, - "flag": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "type": "string", - "description": "The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code.", - "example": "DE" - }, - "callSign": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a three letter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.", - "example": "NCVV" - }, - "operatorCarrierCode": { - "maxLength": 10, - "type": "string", - "description": "The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists.", - "example": "MAEU" - }, - "operatorCarrierCodeListProvider": { - "type": "string", - "description": "Identifies the code list provider used for the operator and partner carriercodes.", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - } - } - }, - "VesselTransport": { - "title": "Vessel Transport", - "required": [ - "modeOfTransport" - ], - "type": "object", - "properties": { - "modeOfTransport": { - "type": "string", - "description": "The mode of transport as defined by DCSA. For the Vessel Transport mode this needs to be `VESSEL`.", - "example": "VESSEL", - "enum": [ - "VESSEL" - ] - }, - "portVisitReference": { - "maxLength": 50, - "type": "string", - "description": "The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.", - "example": "NLAMS1234589" - }, - "transportCallReference": { - "maxLength": 100, - "type": "string", - "description": "The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.", - "example": "SR11111X-9321483-2107W-NLAMS-ACT-1-1" - }, - "servicePartners": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServicePartner" - } - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "universalImportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - } - }, - "description": "Transport mode Vessel." - }, - "BargeTransport": { - "title": "Barge Transport", - "required": [ - "modeOfTransport" - ], - "type": "object", - "properties": { - "modeOfTransport": { - "type": "string", - "description": "The mode of transport as defined by DCSA. For the Barge Transport mode this needs to be `BARGE`.", - "example": "BARGE", - "enum": [ - "BARGE" - ] - }, - "portVisitReference": { - "maxLength": 50, - "type": "string", - "description": "The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call.", - "example": "NLAMS1234589" - }, - "transportCallReference": { - "maxLength": 100, - "type": "string", - "description": "The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.", - "example": "SR11111X-9321483-2107W-NLAMS-ACT-1-1" - }, - "servicePartners": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServicePartner" - } - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5` digits, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "universalImportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage.The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "barge": { - "$ref": "#/components/schemas/Barge" - } - }, - "description": "Transport mode Barge." - }, - "OtherTransport": { - "title": "Other Transport", - "required": [ - "modeOfTransport" - ], - "type": "object", - "properties": { - "modeOfTransport": { - "type": "string", - "description": "The mode of transport as defined by DCSA. The allowed values for the Other Transport mode are:\n- `RAIL` (When the transport mode is Rail)\n- `TRUCK`(When the transport mode is Truck)\n- `RAIL_TRUCK`(When rail and truck are expected to be the mode of transport in a leg of a proposed routing)\n- `BARGE_TRUCK`(When barge and truck are expected to be the mode of transport in a leg of a proposed routing)\n- `BARGE_RAIL`(When barge and rail are expected to be the mode of transport in a leg of a proposed routing)\n- `MULTIMODAL`(When mode of transport is not really defined or unknown at this stage)\n", - "example": "RAIL", - "enum": [ - "RAIL_TRUCK", - "BARGE_TRUCK", - "BARGE_RAIL", - "MULTIMODAL", - "RAIL", - "TRUCK" - ] - } - }, - "additionalProperties": false, - "description": "Other Transport modes." - }, - "Facility": { - "title": "Facility", - "required": [ - "facilityCode", - "facilityCodeListProvider" - ], - "type": "object", - "properties": { - "facilityCode": { - "maxLength": 6, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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:\n - for `SMDG` - the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)\n - for `BIC` - the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)\n", - "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`.\n- `BIC` (Requires a UN Location Code) \n- `SMDG` (Requires a UN Location Code)\n", - "example": "SMDG", - "enum": [ - "BIC", - "SMDG" - ] - } - }, - "description": "A way to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute." - }, - "ServicePartner": { - "title": "Service Partner", - "type": "object", - "properties": { - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The carrier code based on either the SMDG or SCAC code lists.", - "example": "MAEU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "Identifies the code list provider used for the `carrierCode`.", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the service.", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier-specific code of the service for which the schedule details are published.", - "example": "FE1" - }, - "carrierImportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an import voyage. The carrier-specific identifier of the import Voyage.", - "example": "2103S" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.", - "example": "2103N" - } - }, - "description": "The service code and voyage number as identified by the carriers that are partners in the service." - }, - "ServicePartnerSchedule": { - "title": "Service Partner Schedule", - "required": [ - "carrierExportVoyageNumber", - "carrierImportVoyageNumber", - "carrierServiceCode", - "carrierServiceName" - ], - "type": "object", - "properties": { - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The carrier code based on either the SMDG or SCAC code lists.", - "example": "MAEU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "Identifies the code list provider used for the `carrierCode`.", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the service.", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier-specific code of the service for which the schedule details are published.", - "example": "FE1" - }, - "carrierImportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an import voyage. The carrier-specific identifier of the import Voyage.", - "example": "2103S" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.", - "example": "2103N" - } - }, - "description": "The service code and voyage number as identified by the carriers that are partners in the service." - }, - "Leg": { - "title": "Leg", - "required": [ - "arrival", - "departure" - ], - "type": "object", - "properties": { - "sequenceNumber": { - "type": "integer", - "description": "Sequence number of the leg.", - "format": "int32", - "example": 1 - }, - "transport": { - "description": "The mode of transport as defined by DCSA.", - "oneOf": [ - { - "$ref": "#/components/schemas/VesselTransport" - }, - { - "$ref": "#/components/schemas/BargeTransport" - }, - { - "$ref": "#/components/schemas/OtherTransport" - } - ] - }, - "departure": { - "$ref": "#/components/schemas/PlaceOfDeparture" - }, - "arrival": { - "$ref": "#/components/schemas/PlaceOfArrival" - } - }, - "description": "Leg of the Point-to-Point routing. The property `Leg` can be conformed by as many leg as needed and this leg must be identified with a sequence number." - }, - "Location": { - "title": "Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "An optional name for the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - } - }, - "description": "The location can be specified using **any** of the nested structures:\n - `Address` (used to specify the location via an Address)\n - `UNLocationCode`\n - `Facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`)\n\n It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location.\n" - }, - "TransportCallLocation": { - "title": "TransportCall Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "An optional name for the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\n More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "facilitySMDGCode": { - "maxLength": 6, - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\nThe codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)", - "example": "ACT" - } - }, - "description": "General purpose object to capture location-related data, the location can be specified in **any** of the following ways:\n - `Address` (used to specify the location via an Address)\n - `UNLocationCode`\n - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`)\n It is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location.\n" - }, - "PortScheduleLocation": { - "title": "Port Schedule Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "An optional name for the location.", - "example": "Port of Amsterdam" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\n More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "facilitySMDGCode": { - "maxLength": 6, - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\nThe codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/)", - "example": "ACT" - } - }, - "description": "General purpose object to capture location-related data, the location can be specified in **any** of the following ways:\n - `UNLocationCode`\n - `FacilitySMDGCode` (used to specify a location using a `facilitySMDGCode`)\n\n It is expected that if a location is specified in multiple ways (both as a `UNLocationCode` and as a `facilitySMDGCode`) that both ways point to the same location.\n" - }, - "DetailedError": { - "title": "Detailed Error", - "required": [ - "errorCodeMessage", - "errorCodeText" - ], - "type": "object", - "properties": { - "errorCode": { - "maximum": 9999, - "minimum": 7000, - "type": "integer", - "description": "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n", - "format": "int32", - "example": 7003 - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error.", - "example": "facilityCode" - }, - "value": { - "maxLength": 500, - "type": "string", - "description": "The value of the property causing the error serialised as a string exactly as in the original request.", - "example": "SG SIN WHS" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).", - "example": "$.location.facilityCode" - }, - "errorCodeText": { - "maxLength": 100, - "type": "string", - "description": "A standard short description corresponding to the `errorCode`.", - "example": "invalidData" - }, - "errorCodeMessage": { - "maxLength": 5000, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.", - "example": "Spaces not allowed in facility code" - } - }, - "description": "A detailed description of what has caused the error." - } - }, - "parameters": { - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "1" - } - } - } - } -} diff --git a/core/pom.xml b/core/pom.xml index f3255b93..98ee4ad9 100644 --- a/core/pom.xml +++ b/core/pom.xml @@ -21,7 +21,7 @@ com.networknt json-schema-validator - 1.1.0 + 1.5.3 org.apache.commons diff --git a/core/src/main/java/org/dcsa/conformance/core/check/JsonSchemaValidator.java b/core/src/main/java/org/dcsa/conformance/core/check/JsonSchemaValidator.java index a05e8f15..b0006b7c 100644 --- a/core/src/main/java/org/dcsa/conformance/core/check/JsonSchemaValidator.java +++ b/core/src/main/java/org/dcsa/conformance/core/check/JsonSchemaValidator.java @@ -2,26 +2,36 @@ import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; -import com.fasterxml.jackson.core.JsonFactory; import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.networknt.schema.*; -import java.io.InputStream; -import java.util.Arrays; +import com.networknt.schema.oas.OpenApi30; import java.util.HashMap; import java.util.Map; import java.util.Set; import java.util.TreeSet; import java.util.stream.Collectors; +import java.util.stream.Stream; +import lombok.NonNull; import lombok.SneakyThrows; import lombok.extern.slf4j.Slf4j; @Slf4j public class JsonSchemaValidator { private static final Map> INSTANCES = new HashMap<>(); - private static final ObjectMapper JSON_FACTORY_OBJECT_MAPPER = - new ObjectMapper(new JsonFactory()); + + private static final Map NON_VALIDATION_KEYWORDS = + Stream.of( + "example", + "exclusiveMinimum", + "openapi", + "tags", + "servers", + "paths", + "components", + "info") + .map(NonValidationKeyword::new) + .collect(Collectors.toMap(NonValidationKeyword::getValue, keyword -> keyword)); public static synchronized JsonSchemaValidator getInstance(String filePath, String schemaName) { return INSTANCES @@ -31,45 +41,28 @@ public static synchronized JsonSchemaValidator getInstance(String filePath, Stri private final JsonSchema jsonSchema; - @SneakyThrows private JsonSchemaValidator(String filePath, String schemaName) { log.info("Loading schema: {} with schemaName: {}", filePath, schemaName); - // https://github.com/networknt/json-schema-validator/issues/579#issuecomment-1488269135 - JsonSchemaFactory jsonSchemaFactory = - JsonSchemaFactory.builder(JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V7)) - .objectMapper(JSON_FACTORY_OBJECT_MAPPER) - .build(); - SchemaValidatorsConfig schemaValidatorsConfig = new SchemaValidatorsConfig(); - schemaValidatorsConfig.setTypeLoose(false); + // Prevent warnings on unknown keywords + OpenApi30.getInstance().getKeywords().putAll(NON_VALIDATION_KEYWORDS); - JsonSchema rootJsonSchema; - try (InputStream schemaFileInputStream = - JsonSchemaValidator.class.getResourceAsStream(filePath)) { + JsonSchemaFactory jsonSchemaFactory = + JsonSchemaFactory.getInstance( + SpecVersion.VersionFlag.V7, + builder -> + builder + .metaSchema(OpenApi30.getInstance()) + .defaultMetaSchemaIri(OpenApi30.getInstance().getIri()) + .metaSchemaFactory(DisallowUnknownJsonMetaSchemaFactory.getInstance())); - if (schemaFileInputStream == null || schemaFileInputStream.available() == 0) { - throw new IllegalArgumentException("Schema file not found: " + filePath); - } - rootJsonSchema = jsonSchemaFactory.getSchema(schemaFileInputStream, schemaValidatorsConfig); - } + SchemaValidatorsConfig config = SchemaValidatorsConfig.builder().typeLoose(false).build(); - ValidationContext validationContext = - new ValidationContext( - jsonSchemaFactory.getUriFactory(), - null, - JsonMetaSchema.getV4(), - jsonSchemaFactory, - schemaValidatorsConfig); - // Prevent warnings on unknown keywords - Map keywords = validationContext.getMetaSchema().getKeywords(); - Arrays.asList("example", "discriminator", "exclusiveMinimum") - .forEach(keyword -> keywords.put(keyword, new NonValidationKeyword(keyword))); jsonSchema = - jsonSchemaFactory.create( - validationContext, - "#/components/schemas/" + schemaName, - rootJsonSchema.getSchemaNode().get("components").get("schemas").get(schemaName), - rootJsonSchema); + jsonSchemaFactory.getSchema( + SchemaLocation.of("classpath:" + filePath + "#/components/schemas/" + schemaName), + config); + jsonSchema.initializeValidators(); } @@ -84,7 +77,7 @@ public Set validate(String jsonString) { } } - public Set validate(JsonNode jsonNode) { + public Set validate(@NonNull JsonNode jsonNode) { Set validationMessageSet = jsonSchema.validate(jsonNode); return validationMessageSet.stream() .map(ValidationMessage::toString) diff --git a/core/src/test/java/org/dcsa/conformance/core/check/JsonSchemaValidatorTest.java b/core/src/test/java/org/dcsa/conformance/core/check/JsonSchemaValidatorTest.java index 2ab009bc..5f876ce6 100644 --- a/core/src/test/java/org/dcsa/conformance/core/check/JsonSchemaValidatorTest.java +++ b/core/src/test/java/org/dcsa/conformance/core/check/JsonSchemaValidatorTest.java @@ -1,5 +1,6 @@ package org.dcsa.conformance.core.check; +import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertTrue; import java.io.IOException; @@ -10,15 +11,38 @@ class JsonSchemaValidatorTest { + private static final Path REQUEST_NORMAL = Path.of("src/test/resources/examples/booking-request.json"); + private static final Path REQUEST_WITH_ERRORS = Path.of("src/test/resources/examples/booking-request_with_errors.json"); + @Test - void validateJsonSchemaValidator() throws IOException { + void validateJsonSchemaNormalInput() throws IOException { JsonSchemaValidator validator = - JsonSchemaValidator.getInstance("/schemas/booking-api-v20.json", "CreateBooking"); + JsonSchemaValidator.getInstance("/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json", "CreateBooking"); - Path path = Path.of("src/test/resources/examples/booking-request.json"); - assertTrue(Files.exists(path)); - String read = String.join("\n", Files.readAllLines(path)); - Set validate = validator.validate(read); + Set validate = validateInput(validator, REQUEST_NORMAL); assertTrue(validate.isEmpty()); } + + @Test + void validateJsonWithErrorInput() throws IOException { + JsonSchemaValidator validator = + JsonSchemaValidator.getInstance("/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json", "CreateBooking"); + + Set validate = validateInput(validator, REQUEST_WITH_ERRORS); + assertEquals(4, validate.size()); + } + + @Test + void validateYamlSchemaWithErrorInput() throws IOException { + JsonSchemaValidator validator = JsonSchemaValidator.getInstance("/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.yaml", "CreateBooking"); + + Set validate = validateInput(validator, REQUEST_WITH_ERRORS); + assertEquals(4, validate.size()); + } + + private static Set validateInput(JsonSchemaValidator validator, Path requestPath) throws IOException { + assertTrue(Files.exists(requestPath)); + String read = String.join("\n", Files.readAllLines(requestPath)); + return validator.validate(read); + } } diff --git a/core/src/test/resources/examples/booking-request.json b/core/src/test/resources/examples/booking-request.json index bf2ab9b3..75cd0b8a 100644 --- a/core/src/test/resources/examples/booking-request.json +++ b/core/src/test/resources/examples/booking-request.json @@ -23,10 +23,8 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", - "communicationChannelCode": "AO", "isEquipmentSubstitutionAllowed": false, "references": [ { @@ -77,13 +75,15 @@ "requestedEquipments": [ { "isShipperOwned": false, - "ISOEquipmentCode": "42GP", + "ISOEquipmentCode": "42G1", "units": 3, "commodities": [ { "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" + "cargoGrossWeight": { + "value": 36000, + "unit": "KGM" + } } ] } diff --git a/core/src/test/resources/examples/booking-request_with_errors.json b/core/src/test/resources/examples/booking-request_with_errors.json new file mode 100644 index 00000000..2afe85c1 --- /dev/null +++ b/core/src/test/resources/examples/booking-request_with_errors.json @@ -0,0 +1,88 @@ +{ + "receiptTypeAtOrigin": "MessingUpSomeStuff", + "deliveryTypeAtDestination": "CY", + "cargoMovementTypeAtOrigin": "FCL", + "serviceContractReference": "HHL51800000", + "freightPaymentTermCode": "PRE", + "originChargesPaymentTerm": { + "haulageChargesPaymentTermCode": "PRE", + "portChargesPaymentTermCode": "PRE" + }, + "destinationChargesPaymentTerm": { + "haulageChargesPaymentTermCode": "COL", + "portChargesPaymentTermCode": "PRE", + "otherChargesPaymentTermCode": "PRE" + }, + "contractQuotationReference": "HHL1401", + "vessel": { + "name": "MAERSK IOWA", + "vesselIMONumber": "9298686" + }, + "carrierServiceCode": "TA1", + "carrierExportVoyageNumber": "403W", + "isPartialLoadAllowed": false, + "isExportDeclarationRequired": false, + "expectedDepartureDate": "2024-01-20", + "incoTerms": "EXW", + "isEquipmentSubstitutionAllowed": false, + "references": [ + { + "type": "CR", + "value": "KN-00103004" + } + ], + "documentParties": { + "bookingAgent": { + "partyName": "KN Bremerhaven", + "address": { + "street": "Amerikaring", + "streetNumber": "40", + "postCode": "27568", + "city": "Bremerhaven", + "countryCode": "DE" + }, + "partyContactDetails": [ + { + "name": "Export operations department", + "phone": "+49 471 945410" + } + ] + } + }, + "partyContactDetails": [ + { + "name": "Diane", + "phone": "+49 471 945410" + } + ], + "shipmentLocations": [ + { + "location": { + "locationName": "Bremerhaven", + "UNLocationCode": "DEBRV" + }, + "locationTypeCode": "POL" + }, + { + "location": { + "locationName": "Norfolk", + "UNLocationCode": "USORF" + }, + "locationTypeCode": "POD" + } + ], + "requestedEquipments": [ + { + "isShipperOwned": false, + "ISOEquipmentCode": "42G1", + "units": 3, + "commodities": [ + { + "commodityType": "Dry cargo, Freight all kinds", + "cargoGrossWeight": 36000, + "cargoGrossWeightUnit": "KGM" + } + ] + } + ] +} diff --git a/core/src/test/resources/schemas/booking-api-v20.json b/core/src/test/resources/schemas/booking-api-v20.json deleted file mode 100644 index ef1e117f..00000000 --- a/core/src/test/resources/schemas/booking-api-v20.json +++ /dev/null @@ -1,7620 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA OpenAPI specification for Booking", - "description": "API specification issued by DCSA.org.\n\nFor explanation of specific values or objects please refer to the [Information Model 2024.Q1](https://dcsa-website.cdn.prismic.io/dcsa-website/ZhlC9TjCgu4jzyW5_20240402-DCSA-Information-Model-2024.Q1-ReleaseCandidate_01.pdf). This API specification does not define the allowable updates and their timing in accordance with the established business rules. Refer to the [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2) to address this. **All use cases mentioned in this API specification refer to use cases defined in this Booking IFS**.\n\nAll other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/)\n\n### Booking (Implemented by provider)\n\nIt is possible to use the Booking API as a standalone API. In that case poll on the following endPoints:\n\n GET /v2/bookings/{bookingReference}\n\nin order to poll information about status changes.\n\n**Note:** All `/v2/bookings` endPoints must be implmented by the provider.\n\n### Notifications (Implemented by consumer)\nIt is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification).\n\n POST /v2/booking-notifications\n\nThe endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to.\n\nSigning up for notifications is defined outside the scope of this API specification.\n\n**Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events.\n\n### Stats API\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Booking API. Further details can be found [here](https://labs.dcsa.org/#/http/guides/api-guides/stats-api/introduction)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v200). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "2.0.0" - }, - "servers": [ - { - "url": "/" - } - ], - "tags": [ - { - "name": "Booking", - "description": "Booking endPoints to be implemented by **providers** of the Booking API" - }, - { - "name": "Notifications", - "description": "Notifications to be implemented by the **consumers** of the Booking API" - } - ], - "paths": { - "/v2/bookings": { - "post": { - "tags": [ - "Booking" - ], - "summary": "Creates a new Booking\n", - "description": "Creates a new booking request. This endPoint corresponds with **UseCase 1 - Submit booking request**.\n\n## Precondition\nThe consumer has information for a `Booking Request`\n\n## Postcondition\nThe provider has received the `Booking Request`. \n\nThe consumer will receive a `201` (Created) or a `202` (Accepted) if the request payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for a `201` (Created) response\nThe following occurs when a provider receives a `Booking Request`:\n\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type.\n\n A `carrierBookingRequestReference` (as a reference to the `Booking Request`) is created and linked to the payload in the provider system.\n \n **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference`**\n3. A `201` (Created) response is returned with a payload containing both the `carrierBookingRequestReference` and the `bookingStatus`:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'RECEIVED'\n }\n ```\n4. All '_relevant_' subscribers will be notified via a [Booking Notification](#/BookingNotification).\n\nFor `POST` `Booking Request` responding with `201` (Created) the process ends here. The `Booking Request`\n - is now stored in the provider system\n - has status `RECEIVED` and the status can be queried (a subsequent `GET` request will retrieve the payload)\n - a `201` (Created) response is sent to the consumer with a payload containing the `carrierBookingRequestReference` and `bookingStatus='RECEIVED'`\n - awaits further processing by the provider\n - '_relevant_' subscribers have been notified.\n\nThe provider will now start asynchronous processing. Once processed, the new status of the `Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the\n\n GET /v2/bookings/{bookingReference}\n \nendPoint to check if the `bookingStatus` of the `Booking Request` has changed.\n## Flow for a `202` (Accepted) response\nThe following occurs when a provider receives a `Booking Request`:\n\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type.\n\n A `carrierBookingRequestReference` (as a reference to the `Booking Request`) is created and linked to the payload in the provider system.\n \n **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference`**\n\n3. A `202` (Accepted) response is returned with a payload containing **only** the `carrierBookingRequestReference`:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123'\n }\n ```\n\nFor `POST` `Booking Request` responding with `202` (Accepted) the process ends here. The `Booking Request`:\n - is now accepted by the provider system\n - the `Booking Request` does not yet have any status and cannot be queried (no `GET` request is possible until the `Booking Request` is further processed in the provider system)\n - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `carrierBookingRequestReference`\n - awaits further processing by the provider\n\nThe provider will now start asynchronous processing. Once processed, the status `RECEIVED` of the `Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the\n\n GET /v2/bookings/{bookingReference}\n \nendPoint to check if the `bookingStatus` of the `Booking Request` has changed.\n\nAfter the status has changed to `RECEIVED` further processing can continue and will be communicated via a [Booking Notification](#/BookingNotification).\n", - "operationId": "create-bookings", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - } - ], - "requestBody": { - "description": "The payload used to create a `Booking Request`", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateBooking" - }, - "examples": { - "dryExample": { - "summary": "Standard dry cargo Booking\n", - "description": "Make a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "reeferExample": { - "summary": "Reefer cargo Booking (Apple Juice)\n", - "description": "Make a `Booking Request` with reefer requirements (1° celcius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "45R1", - "units": 3, - "isNonOperatingReefer": false, - "activeReeferSettings": { - "temperatureSetpoint": 1, - "temperatureUnit": "CEL", - "isVentilationOpen": true, - "isDrainholesOpen": false, - "isGeneratorSetRequired": true - }, - "commodities": [ - { - "commodityType": "Apple juice", - "HSCodes": [ - "20097919" - ], - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "norExample": { - "summary": "Standard dry cargo Booking using a Reefer Container\n", - "description": "Make a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "45R1", - "isNonOperatingReefer": true, - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "dgExample": { - "summary": "Dangerous Goods (DG) cargo Booking\n", - "description": "Make a `Booking Request` with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Environmentally hazardous substance, liquid, N.O.S (Propiconazole)", - "HSCodes": [ - "293499" - ], - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM", - "outerPackaging": { - "imoPackagingCode": "3A1", - "numberOfPackages": 100, - "description": "Jerrican, steel", - "dangerousGoods": [ - { - "unNumber": "3082", - "properShippingName": "Environmentally hazardous substance, liquid, N.O.S\n", - "imoClass": "9", - "isMarinePollutant": false, - "packingGroup": 3, - "isLimitedQuantity": false, - "isExceptedQuantity": false, - "isSalvagePackings": false, - "isEmptyUncleanedResidue": false, - "isWaste": false, - "isHot": false, - "isCompetentAuthorityApprovalRequired": false, - "emergencyContactDetails": { - "contact": "John Doe", - "phone": "+1 123062970" - }, - "EMSNumber": "F-A S-F", - "isReportableQuantity": false, - "grossWeight": { - "value": 12000, - "unit": "KGM" - } - } - ] - } - } - ] - } - ] - } - } - } - } - }, - "required": true - }, - "responses": { - "201": { - "description": "`Booking Request` has been successfully created in the provider system. The status of the `Booking Request` is now `RECEIVED`. The consumer is now awaiting provider to process the `Booking Request` asynchronously.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_201" - }, - "examples": { - "receivedExample": { - "summary": "Booking request received\n", - "description": "A `Booking Request` has been received (`bookingStatus='RECEIVED'`), schema validated and stored in provider system\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "bookingStatus": "RECEIVED" - } - } - } - } - } - }, - "202": { - "description": "`Booking Request` has been successfully accepted by the provider. The `Booking Request` does not yet have a `bookingStatus` - it is not possible to call the `GET` endPoint until the `Booking Request` is further processed in provider system. The consumer is now awaiting provider to process the `Booking Request` asynchronously.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_202" - }, - "examples": { - "acceptedExample": { - "summary": "Booking request accepted\n", - "description": "A `Booking Request` has been accepted (no `bookingStatus`) and schema validated by provider\n", - "value": { - "carrierBookingRequestReference": "cbrr-123" - } - } - } - } - } - }, - "400": { - "description": "In case the `Booking Request` does not schema validate a `400` (Bad Request) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Booking missing receiptTypeAtOrigin\n", - "description": "`receiptTypeAtOrigin` is a mandatory property in the `Booking Request`. This is an example of how the error object would look in case this property is missing\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/bookings", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "receiptTypeAtOrigin not found - it is a mandatory property in Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "property": "receiptTypeAtOrigin", - "errorCodeText": "mandatory property missing", - "errorCodeMessage": "receiptTypeAtOrigin must be provided as part of a Booking request\n" - } - ] - } - } - } - } - } - }, - "500": { - "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while processing Booking Request\n", - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/bookings", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Making too many Bookings Requests\n", - "description": "Calling the endPoint\n\n POST /v2/bookings\n\ntoo many times within a timeperiod.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/bookings", - "statusCode": 429, - "statusCodeText": "Too Many Requests", - "statusCodeMessage": "Too many request to create a booking has been requested. Please try again in 1 hour\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Max Booking requests reached", - "errorCodeMessage": "A maximum of 10 Bookings can be created per hour" - } - ] - } - } - } - } - } - } - } - } - }, - "/v2/bookings/{bookingReference}": { - "get": { - "tags": [ - "Booking" - ], - "summary": "Gets the Booking\n", - "description": "Retrieves the `Booking Request` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the Booking is confirmed - it is **only** possible to use the `carrierBookingReference`. It is recommended to use this endPoint to `GET` data before an update is made to make sure latest version is being updated.\n\nThe default payload when calling this endPoint is the \"original\" `Booking`. It is also possible to get the latest amendment to a `Booking` called the `Amended Booking`. In order to get the `Amended Booking`, it is necessary to use the query parameter `amendedContent` and set it to `true`.\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n\nThe `status` of the \"original\" `Booking` is included in both payloads as `bookingStatus`. `amendedBookingStatus` and related content is only available after the provider has approved the `Booking` via **UseCase 5: Confirm Booking request** and until:\n- the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessable.\n- the consumer submits a new amendment (**UseCase 7: Request amendment to confirmed Booking**) in which case the \"new update\" provided **replaces** the \"old update\".\n- the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the \"old update\" is no longer accessable.\n\nIf `amendedContent=true` is requested but no amendment has yet been provided by the consumer **or** the state of the \"original\" `Booking` is `PENDING AMENDMENT`, then a `404` (Not Found) is returned.\n\nIf the provider is requesting changes to the `Booking`, the `feedbacks` object is used to inform the consumer what needs to change.\n\nIn case no subscription (`Notification`) has been set up - it is possible to use this endPoint to poll on in order to detect if `bookingStatus` and/or `amendedBookingStatus` has changed.\n\nIn 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.\n", - "operationId": "get-bookings", - "parameters": [ - { - "name": "bookingReference", - "in": "path", - "description": "This can be one of:\n- `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking)\n- `carrierBookingReference`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "CBR001" - } - }, - { - "name": "amendedContent", - "in": "query", - "description": "Controls wether the content of this payload is the amendmended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`).\n\nIf `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "boolean", - "example": false, - "default": false - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - } - ], - "responses": { - "200": { - "description": "Request successful", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Booking" - }, - "examples": { - "dryNotConfirmedExample": { - "summary": "Standard dry cargo Booking (not confirmed)\n", - "description": "Gets a `Booking Request` with standard Dry cargo which has not yet been confirmed. The `Booking` is in state `PENDING UPDATE` and requires some changes (specified in the `feedbacks` property)\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "bookingStatus": "PENDING UPDATE", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ], - "feedbacks": [ - { - "severity": "ERROR", - "code": "PROPERTY_VALUE_MUST_CHANGE", - "message": "Not enough available \"42GP\" equipment. Please change to \"22G1\" instead\n", - "jsonPath": "$.requestedEquipment.units", - "property": "units" - } - ] - } - }, - "dryConfirmedExample": { - "summary": "Gets a confirmed Standard dry cargo Booking\n", - "description": "Gets a `Confirmed Booking` with standard Dry cargo. In this example the `Booking` has previously received an amendment which was confirmed (`amendedBookingStatus='AMENDMENT CONFIRMED'`)\n\nAs part of the confirmation the `Booking` is enriched with a `transportPlan`, `shipmentCutOffTimes`, `carrierClauses` and in this example also an `advanceManifestFiling` since the `Booking` is arriving in US.\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT CONFIRMED", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ], - "confirmedEquipments": [ - { - "ISOEquipmentCode": "42GP", - "units": 3 - } - ], - "transportPlan": [ - { - "transportPlanStage": "MNC", - "transportPlanStageSequenceNumber": 1, - "loadLocation": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "dischargeLocation": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "plannedDepartureDate": "2024-01-20", - "plannedArrivalDate": "2024-01-31", - "modeOfTransport": "VESSEL", - "vesselName": "MAERSK IOWA", - "vesselIMONumber": "9298686", - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W" - } - ], - "shipmentCutOffTimes": [ - { - "cutOffDateTimeCode": "DCO", - "cutOffDateTime": "2024-01-17T22:30:00.000" - }, - { - "cutOffDateTimeCode": "VCO", - "cutOffDateTime": "2024-01-18T22:30:00.000" - }, - { - "cutOffDateTimeCode": "FCO", - "cutOffDateTime": "2024-01-19T13:30:00.000" - } - ], - "advanceManifestFilings": [ - { - "manifestTypeCode": "ACE", - "countryCode": "US" - } - ], - "carrierClauses": [ - "The date of shipment, the carrying vessel and theschedule are not guaranteed and are always subject tochanges.", - "Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.", - "Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).", - "In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee." - ] - } - } - } - } - } - }, - "202": { - "description": "The `Booking` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Booking`.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - } - }, - "404": { - "description": "In case the consumer is requesting the `Amended Booking` by calling:\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n \nbut:\n- the `Booking` has not yet been confirmed\n- the `Booking` has been confirmed but no amendment has yet been provided by the consumer\n- the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessable.\n\na `404` (Not Found) is returned.\n\nA `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "Not Found request\n", - "description": "The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "bookingReference not found\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "bookingReference Not Found", - "errorCodeMessage": "The Booking does not exist\n" - } - ] - } - }, - "notFoundAmendmentExample": { - "summary": "Missing amended Booking\n", - "description": "The `Amended Booking` response is requested - but no `Amended Booking` exists.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123?amendedContent=true", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "No amended booking exists", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "No amended booking", - "errorCodeMessage": "No amended booking available" - } - ] - } - } - } - } - } - }, - "409": { - "description": "In case the provider is processing the `Booking request` - it is possible for the provider to reject new incomming requests by returning a `409` (Conflict)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Conflicting request\n", - "description": "The provider is already processing a request and needs to finish this process before any new requests are processed\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 409, - "statusCodeText": "Conflict", - "statusCodeMessage": "Previous request is being processed. Please try again\nlater\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Conflicting request is being processed", - "errorCodeMessage": "The Booking cannot be updated/amended while it is being processed. Please try again later\n" - } - ] - } - } - } - } - } - }, - "500": { - "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while processing Booking request\n", - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Internal Error occurred", - "errorCodeMessage": "Internal Error occurred" - } - ] - } - } - } - } - } - }, - "default": { - "description": "Unexpected error\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "getError": { - "summary": "GET non-existing Booking Request\n", - "description": "Calling\n\n GET /v2/bookings/cbrr-123\n \nresults in an error as booking `cbrr-123` does not exist.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "The requested carrierBookingRequestReference does not exist\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Non existent carrierBookingRequestReference", - "errorCodeMessage": "carrierBookingRequestReference `cbrr-123` does not exist\n" - } - ] - } - } - } - } - } - } - } - }, - "put": { - "tags": [ - "Booking" - ], - "summary": "Updates the Booking\n", - "description": "Updates the `Booking Request` with the `bookingReference`. The path can contain either a `carrierBookingRequestReference` or a `carrierBookingReference`. Once a Booking has been `CONFIRMED` the `carrierBookingReference` **MUST** always be used. This endPoint corresponds with either\n- **UseCase 3 - Submit updated Booking request**\n- **UseCase 7 - Request amendments to confirmed Booking**\n\nThis endPoint is to be used in response to\n- **UseCase 2 - Request to update Booking request**\n- **UseCase 6 - Request to amend confirmed Booking**\n\nthe endPoint can also be used in case `bookingStatus='RECEIVED'` and the consumer has an update to the `Booking Request`.\n\n## Precondition\nIn order to update a `Booking Request`, the status of the `Booking Request` needs to be in state\n- `RECEIVED` in case the consumer has updated information for the `Booking Request`\n- `PENDING UPDATE` in case the provider has requested the consumer to update the `Booking Request` (a result of **UseCase 2 - Request to update Booking request**)\n- `UPDATE RECEIVED` in case the consumer has additional changes to an already sent update\n- `PENDING AMENDMENT` in case the provider has requested the consumer to amend the `Booking Request` (a result of **UseCase 6 - Request to amend confirmed Booking**)\n- `CONFIRMED` in case the consumer has an amendment to the `Booking Request`\n\n## Postcondition\nThe provider has received an update (**UseCase 3 - Submit updated Booking request**) or an amendment (**UseCase 7 - Request amendments to confirmed Booking**) to the `Booking Request`.\n\nIn case an amendment was received to the `Booking Request` (**UseCase 7 - Request to amend confirmed Booking**) - the amendment will be called `Amended Booking`. The `Amended Booking` and the \"original\" `Booking Request` will **co-exist** until a new amendment is submitted by the consumer (via **UseCase 7: Request amendments to confirmed Booking**) or until the provider requests an update (sets the `bookingStatus='PENDING AMENDMENT'` via **UseCase 6: Request to amend confirmed Booking**). If the `amendedBookingStatus` is present it always represents the latest version of an amendment received by the provider.\n\nThe consumer will receive a `200` (OK) or a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for a `200` (OK) response\nThe following occurs when a provider receives an **update** (or an **amendment**) to a `Booking Request`\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type\n \n **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference` in case the Booking has not yet been `CONFIRMED` and the value `cbr-987` will be used as `carrierBookingReference` in case the Booking has been `CONFIRMED`.**\n3. The response depends on which useCase is the reason for calling this endPoint (what the `bookingStatus` is):\n - If `bookingStatus` **is** `RECEIVED` then this endPoint is being used in addition to **UseCase 1 - Submit booking request**. In this case the consumer would like to make an update to an already sent `Booking Request` - this is done via **UseCase 3 - Submit updated Booking Request**. The `bookingStatus` now changes to `UPDATE RECEIVED`.\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'UPDATE RECEIVED'\n }\n ```\n - If `bookingStatus` is `PENDING UPDATE` then this endPoint is being used as a reponse to **UseCase 2 - Request to update Booking request** in this case the provider has requested an update to a `Booking Request`. The `bookingStatus` now changes to `UPDATE RECEIVED`.\n\n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'UPDATE RECEIVED'\n }\n ```\n - If `bookingStatus` is `UPDATE RECEIVED` then this endPoint is being used to update an already sent update. The `bookingStatus` stays as `UPDATE RECEIVED`.\n\n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'UPDATE RECEIVED'\n }\n ```\n - If `bookingStatus` is `PENDING AMENDMENT` then this endPoint is being used as a response to **UseCase 6 - Request to amend Confirmed Booking**, in this case the provider has requested an amendment to a `Confirmed Booking`. The `bookingStatus` stays `PENDING AMENDMENT` and `amendedBookingStatus` is set to `AMENDMENT RECEVIED`.\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'PENDING AMENDMENT',\n amendedBookingStatus: 'AMENDMENT RECEIVED'\n }\n ```\n - If `bookingStatus` is `CONFIRMED` then this endPoint is being used in order to request an amendment to a `Confirmed Booking`. This is done via **UseCase 7 - Request Amendments to Confirmed Booking**. The `bookingStatus` stays `CONFIRMED` and `amendedBookingStatus` is set to `AMENDMENT RECEIVED`.\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'CONFIRMED',\n amendedBookingStatus: 'AMENDMENT RECEIVED'\n }\n ```\n4. All '_relevant_' subscribers will be notified via a [Booking Notification](#/BookingNotification).\n\nFor `PUT` `Booking Request` responding with `200` (OK) the process ends here. The updated `Booking Request`:\n - is now stored in the provider system\n - a `200` (OK) response is sent to the consumer with the status of the `Booking` (and possibly also with the `amendedBookingStatus`) with one of the following values (depending on the useCase):\n - `bookingStatus='UPDATE RECEIVED'` (if endPoint used before a `Booking`has been confirmed)\n - `bookingStatus='PENDING AMENDMENT'` and `amendedBookingStatus='AMENDMENT RECEIVED'` (if endPoint used as a response to **UseCase 6 - Request to amend Confirmed Booking**)\n - `bookingStatus='CONFIRMED'` and `amendedBookingStatus='AMENDMENT RECEIVED'` (if consumer is requesting an amendment to a `Confirmed Booking`)\n\n A subsequent `GET` request to the `Booking Request` will fetch the status along with the `Booking Request`\n - awaits further processing by the provider\n - '_relevant_' subscribers have been notified.\n\nThe provider will now start asynchronous processing. Once processed, the new status of the `Booking` and `Amended Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the\n\n GET /v2/bookings/{bookingReference}\n\nendPoint to check if the `bookingStatus` and `amendedBookingStatus` of the `Booking` has changed.\n \nIf the consumer wants to get the content of the `Amended Booking` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter:\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n\nIt is possible to `GET` the content of the `Amended Booking` via the example above until either:\n\n- the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessible\n- the consumer submits a new update (**UseCase 7: Request amendment to confirmed Booking**) in which case the \"new amendment\" provided **replaces** the \"old amendment\".\n- the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the \"old update\" is no longer accessable.\n\n## Flow for a `202` (Accepted) response\nThe following occurs when a provider receives an **update** (or an **amendment**) to a `Booking Request`\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type\n3. An empty response is returned and the consumer now awaits further processing by the provider.\n\nFor `POST` `Booking Request` responding with `202` (Accepted) the process ends here. The Booking Request:\n - is now accepted by the provider system\n - the status of the `Booking Request` is unchanged.\n - a 202 (Accepted) response is sent with an empty payload\n - awaits further processing by the provider\n\nThe provider will now start asynchronous processing. Once processed, the state will change to one of the following values depending on the UseCase for calling the `PUT` endPoint:\n - `UPDATE RECEIVED` in case this endPoint has been used to:\n - send an update to a newly created Booking (precondition: `bookingStatus='RECEIVED'`)\n - send an update to a Booking because of a request from provider via **UseCase 2 - Request to update Booking request** (precondition: `bookingStatus='PENDING UPDATE'`)\n - send an additional update to a Booking that has already received an update (precondition: `bookingStatus='UPDATE RECEIVED'`)\n - `bookingStatus` will stay as `PENDING AMENDMENT` but `amendedBookingStatus` will change to `AMENDMENT RECEVIED` in case this endPoint is being used in response to a request from provider via **UseCase 6 - Request to amend Confirmed Booking** (precondition: `bookingStatus='PENDING AMENDMENT'`)\n - `bookingStatus` will stay as `CONFIRMED` but `amendedBookingStatus` will change to `AMENDMENT RECEVIED` in case this endPoint is being used to update an already confirmed Booking via **UseCase 7 - Request Amendments to Confirmed Booking** (precondition: `bookingStatus='CONFIRMED'`)\n\nThe new state will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the \n\n GET /v2/bookings/{bookingReference}\n \nendPoint to check if the `bookingStatus` and `amendedBookingStatus` of the `Booking` has changed.\n\nIf the consumer wants to get the content of the `Amended Booking` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter:\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n\nIt is possible to `GET` the content of the `Amended Booking` via the example above until either:\n\n- the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessible\n- the consumer submits a new update (**UseCase 7: Request amendment to confirmed Booking**) in which case the \"new amendment\" provided **replaces** the \"old amendment\".\n- the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the \"old update\" is no longer accessable.\n", - "operationId": "update-bookings", - "parameters": [ - { - "name": "bookingReference", - "in": "path", - "description": "This can be one of:\n- `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking)\n- `carrierBookingReference`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "CBR001" - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - } - ], - "requestBody": { - "description": "Parameters used to update the `Booking request`\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateBooking" - }, - "examples": { - "dryExample": { - "summary": "Standard dry cargo Booking\n", - "description": "Updating a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "reeferExample": { - "summary": "Reefer cargo Booking (Apple Juice)\n", - "description": "Updating a `Booking Request` with reefer requirements (2° celcius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "45R1", - "units": 3, - "isNonOperatingReefer": false, - "activeReeferSettings": { - "temperatureSetpoint": 2, - "temperatureUnit": "CEL", - "isVentilationOpen": true, - "isDrainholesOpen": false, - "isGeneratorSetRequired": true - }, - "commodities": [ - { - "commodityType": "Apple juice", - "HSCodes": [ - "20097919" - ], - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "norExample": { - "summary": "Standard dry cargo Booking using a Reefer Container\n", - "description": "Update a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "45R1", - "isNonOperatingReefer": true, - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - }, - "dgExample": { - "summary": "Dangerous Goods (DG) cargo Booking\n", - "description": "Update a `Confirmed Booking` (a `Booking` with `carrierBookingReference='cbr-987'`) with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Environmentally hazardous substance, liquid, N.O.S (Propiconazole)", - "HSCodes": [ - "293499" - ], - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM", - "outerPackaging": { - "imoPackagingCode": "3A1", - "numberOfPackages": 100, - "description": "Jerrican, steel", - "dangerousGoods": [ - { - "unNumber": "3082", - "properShippingName": "Environmentally hazardous substance, liquid, N.O.S\n", - "imoClass": "9", - "isMarinePollutant": false, - "packingGroup": 3, - "isLimitedQuantity": false, - "isExceptedQuantity": false, - "isSalvagePackings": false, - "isEmptyUncleanedResidue": false, - "isWaste": false, - "isHot": false, - "isCompetentAuthorityApprovalRequired": false, - "emergencyContactDetails": { - "contact": "John Doe", - "phone": "+1 123062970" - }, - "EMSNumber": "F-A S-F", - "isReportableQuantity": false, - "grossWeight": { - "value": 12000, - "unit": "KGM" - } - } - ] - } - } - ] - } - ] - } - } - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "The `Booking request` has been successfully updated in the provider system with one of the following combinations (depending on the use case):\n- `bookingStatus='PENDING UPDATE'` in case the consumer has provided an update to a `Booking request` and is awaiting the provider to take action\n- `bookingStatus='PENDING AMENDMENT'` and `amendedBookingStatus='AMENDMENT RECEIVED'` in case the provider has requested an amendment and the consumer has provided an amendment to a `Confirmed Booking` and is awaiting the provider to take action\n- `bookingStatus='CONFIRMED'` and `amendedBookingStatus='AMENDMENT RECEIVED'` in case the consumer has provided an amendment to a `Confirmed Booking` and is awaiting the provider to take action\n\nThe status of the `Booking` can be monitored on the\n\n GET /v2/bookings/{bookingReference}\n\nendPoint by the consumer. If the consumer wants to get the content of the `Amended Booking` the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter:\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BookingRefStatus" - }, - "examples": { - "updateReceivedExample": { - "summary": "Booking request updated\n", - "description": "An updated `Booking request` received, schema validated and stored in provider system - the `Booking` now awaits provider action\n `bookingStatus='UPDATE RECEIVED'`\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "bookingStatus": "UPDATE RECEIVED" - } - }, - "pendingAmendmentApprovalExample": { - "summary": "Confirmed Booking amendment\n", - "description": "An amendment to a `Confirmed Booking` received, schema validated and stored in provider system - the `Booking` now awaits provider action\n `bookingStatus='CONFIRMED'`\n `amendedBookingStatus: 'AMENDMENT RECEIVED'`\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT RECEIVED" - } - }, - "pendingAmendmentExample": { - "summary": "Confirm requested Booking amendment\n", - "description": "A requested amendment to a `Confirmed Booking` by the provider has been received, schema validated and stored in provider system. The `Booking` now awaits provider action\n `bookingStatus='PENDING AMENDMENT'`\n `amendedBookingStatus: 'AMENDMENT RECEIVED'`\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "PENDING AMENDMENT", - "amendedBookingStatus": "AMENDMENT RECEIVED" - } - } - } - } - } - }, - "202": { - "description": "The `Booking request` update has been successfully accepted by the provider. `bookingStatus` does not change and response payload is empty. Further processing will be done by provider.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "examples": { - "noContentExample": { - "summary": "Booking request updated with no content\n", - "description": "An updated `Booking request` received, schema validated and accepted by provider - the `Booking` now awaits provider action, `bookingStatus` does not change\n" - } - } - } - } - }, - "400": { - "description": "In case the updated/amended `Booking request` does not schema validate a `400` (Bad Request) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Booking missing receiptTypeAtOrigin\n", - "description": "`receiptTypeAtOrigin` is a mandatory property in the `Booking request`. This is an example of how the error object would look in case this property is missing\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PUT", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "receiptTypeAtOrigin not found - it is a mandatory property in Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "property": "receiptTypeAtOrigin", - "errorCodeText": "mandatory property missing", - "errorCodeMessage": "receiptTypeAtOrigin must be provided as part of a Booking request\n" - } - ] - } - } - } - } - } - }, - "404": { - "description": "In case the provider does not know of the `bookingReference` used in the request (this could be because of a `POST` request that has not finished processing or simply because the resource does not exist) - it is possible for the provider to reject the requests by returning a `404` (Not Found)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "Not Found request\n", - "description": "The provided `bookingReference` cannot be found. This can be because a `Post` request has not been finished processing or because the `bookingReference` does not exist in the provider system.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PUT", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "bookingReference not found\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "bookingReference Not Found", - "errorCodeMessage": "The Booking does not exist\n" - } - ] - } - } - } - } - } - }, - "409": { - "description": "In case the provider is processing the `Booking request` - it is possible for the provider to reject new incomming requests by returning a `409` (Conflict)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Conflicting request\n", - "description": "The provider is already processing a request and needs to finish this process before any new requests are processed\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PUT", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 409, - "statusCodeText": "Conflict", - "statusCodeMessage": "Previous request is being processed. Please try again\nlater\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Conflicting request is being processed", - "errorCodeMessage": "The Booking cannot be updated/amended while it is being processed. Please try again later\n" - } - ] - } - } - } - } - } - }, - "500": { - "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while processing Booking request\n", - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PUT", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Updating too many Bookings requests\n", - "description": "Calling the endPoint\n\n GET /v2/bookings/cbrr-123\n \ntoo many times within a timeperiod.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PUT", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 429, - "statusCodeText": "Too Many Requests", - "statusCodeMessage": "Too many request to update a booking has been requested. Please try again in 1 hour\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Max Booking requests reached", - "errorCodeMessage": "A maximum of 10 Bookings can be updated per hour" - } - ] - } - } - } - } - } - } - } - }, - "patch": { - "tags": [ - "Booking" - ], - "summary": "Cancels the Booking or cancels an Amendment\n", - "description": "A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the `Booking` is confirmed - it is **only** possible to use the `carrierBookingReference`.\n\nThis endPoint corresponds with **UseCase 11 - Cancel Booking Request by shipper**, **UseCase 9 - Cancel amendment to confirmed Booking** or **UseCase 13 - Cancel confirmed Booking by shipper**.\n\n## Precondition\nIn order to cancel a `Booking`, the `bookingStatus` must be either\n- `RECEIVED`\n- `PENDING UPDATE`\n- `UPDATE RECEIVED`\n- `CONFIRMED`\n- `PENDING AMENDMENT`\n\nIn order to cancel a `Booking Amendment`, the status of the `Booking Amendment` must be\n- `AMENDMENT RECEIVED`\n\n## Postcondition\nThe provider has received a cancellation from the consumer for a `Booking` or for a `Booking Amendment`.\n\nThe consumer will receive a `200` (OK) or a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for a `200` (OK) response\nThe following occurs when a provider receives a cancellation request:\n1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided.\n - all values provided have correct data type.\n3. Depending on the paylod of the request - either:\n - the `Booking Request` is cancelled. This is the case when the payload contains `bookingStatus='CANCELLED'`. It is only possible to use this payload in combination with `carrierBookingRequestReference` being used in the path (as the `bookingReference`)\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'CANCELLED'\n }\n ```\n\n **If** the `Booking` is confirmed a `409` (Conflict) should be used as a response\n\n - only the amendment to the `Booking` is cancelled (in this case the `Booking` continues and `bookingStatus` stays unchanged). This is the case when the payload contains `amendedBookingStatus='AMENDMENT CANCELLED'`.\n \n **If** no amendment is being requested prior to this call (`amendedBookingStatus` is **not** `AMENDMENT RECEIVED`) then a `404` (Not Found) is returned\n\n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'PENDING AMENDMENT',\n amendedBookingStatus: 'AMENDMENT CANCELLED'\n }\n ```\n or\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'CONFIRMED',\n amendedBookingStatus: 'AMENDMENT CANCELLED'\n }\n ```\n if the amendment was not requested by the provider.\n - the confirmed `Booking` is requesting to be cancelled. This is the case when the payload contains `bookingCancellationStatus='CANCELLATION RECEIVED'`. It is only possible to use this payload in combination with `carrierBookingReference` being used in the path (as the `bookingReference`)\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'CONFIRMED',\n bookingCancellationStatus: 'CANCELLATION RECEIVED'\n }\n ```\n or\n ```\n {\n carrierBookingReference: 'cbr-987',\n carrierBookingRequestReference: 'cbrr-123',\n bookingStatus: 'CONFIRMED',\n amendedBookingStatus: 'AMENDMENT RECEIVED',\n bookingCancellationStatus: 'CANCELLATION RECEIVED'\n }\n ```\n in case an ongoing amendment is being processed.\n\n When cancelling a Confirmed Booking - the amendment will also be Cancelled in case the cancellation is confirmed.\n\n **If** the `Booking` is **not** yet confirmed a `409` (Conflict) should be used as a response\n\n4. All '_relevant_' subscribers will be notified via a [Booking Notification](#/BookingNotification).\n\n## Flow for a `202` (Accepted) response\nThe following occurs when a provider receives a cancellation request:\n1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided.\n - all values provided have correct data type.\n3. An empty response is returned and the consumer now awaits further processing by the provider.\n\nOnce processed, the `Booking` or `Amended Booking` is cancelled and a [Booking Notification](#/BookingNotification) is sent. In case of a Confirmed Booking - the provider has the opportunity to decline the Cancellation of the Booking (in which case the `bookingCancellationStatus='CANCELLATION DECLINED'`).\n", - "operationId": "cancel-booking", - "parameters": [ - { - "name": "bookingReference", - "in": "path", - "description": "This can be one of:\n- `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking)\n- `carrierBookingReference`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "CBR001" - } - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/bookings_bookingReference_body" - }, - "examples": { - "bookingCancelledExample": { - "summary": "Booking Request cancelled\n", - "description": "The consumer wants to cancel the `Booking Request`. This is done by setting the `bookingStatus` to `CANCELLED` and provide an optional `reason`.\n", - "value": { - "bookingStatus": "CANCELLED", - "reason": "Customer cancelled order" - } - }, - "amendmentCancelledExample": { - "summary": "Amendment cancelled\n", - "description": "The consumer wants to **only** cancel the amendment (and keep the confirmed `Booking`). This is done by setting the `amendedBookingStatus` to `AMENDMENT CANCELLED`.\n", - "value": { - "amendedBookingStatus": "AMENDMENT CANCELLED" - } - }, - "requestConfirmedBookingCancelledExample": { - "summary": "Request to cancel a Confirmed Booking\n", - "description": "The consumer requests to cancel a `Confirmed Booking`. This is done by setting the `bookingCancellationStatus` to `CANCELLATION RECEIVED` and provide an optional `reason`.\n", - "value": { - "bookingCancellationStatus": "CANCELLATION RECEIVED", - "reason": "Customer cancelled order" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Booking has been cancelled\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BookingRefStatus" - }, - "examples": { - "bookingRequestCancelledExample": { - "summary": "Entire Booking cancelled\n", - "description": "The consumer has requested that the `Booking Request` should be cancelled. `bookingStatus` is set to `CANCELLED`.\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "bookingStatus": "CANCELLED" - } - }, - "amendmentCancelled1Example": { - "summary": "Amendment cancelled on a confirmed Booking\n", - "description": "The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The status of the `Booking` stays as `CONFIRMED`. The `amendedBookingStatus` is set to `AMENDMENT CANCELLED`.\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT CANCELLED" - } - }, - "amendmentCancelled2Example": { - "summary": "Amendment requested by provider cancelled by consumer\n", - "description": "The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The status of the `Booking` stays as `PENDING AMENDMENT`. The `amendedBookingStatus` is set to `AMENDMENT CANCELLED`.\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "PENDING AMENDMENT", - "amendedBookingStatus": "AMENDMENT CANCELLED" - } - }, - "requestConfirmedBookingCancellationExample": { - "summary": "Request to Cancel a Confirmed Booking\n", - "description": "The consumer has requested that a confirmed `Booking` is to be cancelled. The status of the `Booking` stays as is (in the below payload this is `PENDING AMENDMENT`. The `amendedBookingStatus` stays as is (in the below payload this is `AMENDMENT CONFIRMED`.\n", - "value": { - "carrierBookingRequestReference": "cbrr-123", - "carrierBookingReference": "cbr-987", - "bookingStatus": "PENDING AMENDMENT", - "amendedBookingStatus": "AMENDMENT CONFIRMED", - "bookingCancellationStatus": "CANCELLATION RECEIVED" - } - } - } - } - } - }, - "202": { - "description": "Booking cancellation has been accepted\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "examples": { - "bookingCancelledExample": { - "summary": "Booking Request cancelled\n", - "description": "The consumer has requested that the `Booking Request` should be cancelled. The cancellation has been accepted and is now awaiting further processing by the provider\n" - }, - "amendmentCancelledExample": { - "summary": "Amendment cancellation on a confirmed Booking accepted\n", - "description": "The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation has been accepted and is now awaiting further processing by the provider\n" - }, - "confirmedBookingCancellationExample": { - "summary": "Request to Cancel a confirmed Booking accepted\n", - "description": "The consumer has requested to cancel a confirmed `Booking`. The cancellation has been accepted and is now awaiting further processing by the provider\n" - } - } - } - } - }, - "400": { - "description": "In case the cancel payload does not schema validate a `400` (Bad Request) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Wrong `amendedBookingStatus`\n", - "description": "`APPROVE` is not a possible value when PATCHING a `Booking`.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "value": { - "httpMethod": "PATCH", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "APPROVE is not a valid status to set", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-10-03T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "property": "amendedBookingStatus", - "value": "APPROVE", - "errorCodeText": "incorrect value", - "errorCodeMessage": "Only AMENDMENT CANCELLED is an allowed value: APPROVE was inserted" - } - ] - } - } - } - } - } - }, - "404": { - "description": "In case the consumer is cancelling the `Amended Booking` by setting:\n\n `amendedBookingStatus='AMENDMENT CANCELLED'`\n \nbut:\n- the `Booking` has not yet been confirmed\n- the `Booking` has been confirmed but no amendment has yet been provided by the consumer\n- the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessable.\n\na `404` (Not Found) is returned.\n\nA `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "Not Found request\n", - "description": "The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "bookingReference not found\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "bookingReference Not Found", - "errorCodeMessage": "The Booking does not exist\n" - } - ] - } - }, - "notFoundAmendmentExample": { - "summary": "Missing amended Booking\n", - "description": "Cancelling the `Amendment` is requested - but no `Amended Booking` exists.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "GET", - "requestUri": "/v2/bookings/cbrr-123?amendedContent=true", - "statusCode": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "No amended booking exists", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "No amended booking", - "errorCodeMessage": "No amended booking available" - } - ] - } - } - } - } - } - }, - "409": { - "description": "In case the provider is processing a `Booking request` - it is possible for the provider to reject the cancellation by returning a `409` (Conflict). This is also to be used in case a cancellation to a Confirmed Booking is done via the `carrierBookingRequestReference`.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Conflicting request\n", - "description": "The provider is already processing a request and needs to finish this process.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PATCH", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 409, - "statusCodeText": "Conflict", - "statusCodeMessage": "Previous request is being processed. Please try again later\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Conflicting request is being processed", - "errorCodeMessage": "Conflicting request is being processed" - } - ] - } - } - } - } - } - }, - "500": { - "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while processing Booking request\n", - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PATCH", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Updating too many Bookings requests\n", - "description": "Calling the endPoint\n\n PATCH /v2/bookings/cbrr-123\n\ntoo many times within a timeperiod.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "PATCH", - "requestUri": "/v2/bookings/cbrr-123", - "statusCode": 429, - "statusCodeText": "Too Many Requests", - "statusCodeMessage": "Too many request to cancel a booking has been requested. Please try again in 1 hour\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Max Booking requests reached", - "errorCodeMessage": "A maximum of 10 Bookings can be cancelled per hour" - } - ] - } - } - } - } - } - } - } - } - }, - "/v2/booking-notifications": { - "post": { - "tags": [ - "Notifications" - ], - "summary": "Send a new Booking Notification", - "description": "Creates a new [`Booking Notification`](#/BookingNotification). This endPoint is called whenever a `Booking` that a consumer has subscribed to changes state or is updated.\n\n**This endPoint is to be implemented by a consumer of the Booking API in order to receive Notifications**\n", - "operationId": "booking-notifications", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - } - ], - "requestBody": { - "description": "The payload used to create a [`Booking Notification`](#/BookingNotification)\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BookingNotification" - }, - "examples": { - "receivedLightweightExample": { - "summary": "Booking request received (Lightweight)\n", - "description": "A lightweight notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`).\n", - "value": { - "specversion": "1.0", - "id": "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source": "https://member.com/", - "type": "org.dcsa.booking.v2", - "time": "2018-04-05T17:31:00Z", - "datacontenttype": "application/json", - "subscriptionReference": "BKG001", - "data": { - "bookingStatus": "RECEIVED", - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - } - } - }, - "receivedFullStateTransferExample": { - "summary": "Booking request received (Full State Transfer)\n", - "description": "A full state transfer notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`).\n", - "value": { - "specversion": "1.0", - "id": "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source": "https://member.com/", - "type": "org.dcsa.booking.v2", - "time": "2018-04-05T17:31:00Z", - "datacontenttype": "application/json", - "subscriptionReference": "BKG001", - "data": { - "bookingStatus": "RECEIVED", - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "booking": { - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "bookingStatus": "RECEIVED", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "PRE" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - } - } - }, - "declinedLightweightExample": { - "summary": "Booking amendment declined (Lightweight)\n", - "description": "A lightweight notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT DECLINED'`)\n", - "value": { - "specversion": "1.0", - "id": "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source": "https://member.com/", - "type": "org.dcsa.booking.v2", - "time": "2018-04-05T17:31:00Z", - "datacontenttype": "application/json", - "subscriptionReference": "BKG001", - "data": { - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT DECLINED", - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "carrierBookingReference": "ABC709951", - "feedbacks": [ - { - "severity": "INFO", - "code": "INFORMATIONAL_MESSAGE", - "message": "Declined because of no equipment availability" - } - ] - } - } - }, - "declinedFullStateTransferExample": { - "summary": "Booking amendment declined (Full State Transfer)\n", - "description": "A full state transfer notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT DECLINED'`). The notification both contains the Booking from before the amendment (in the `booking` property) it also contains the amended booking (in the `amendedBooking` property).\n", - "value": { - "specversion": "1.0", - "id": "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source": "https://member.com/", - "type": "org.dcsa.booking.v2", - "time": "2018-04-05T17:31:00Z", - "datacontenttype": "application/json", - "subscriptionReference": "BKG001", - "data": { - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT DECLINED", - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "carrierBookingReference": "ABC709951", - "feedbacks": [ - { - "severity": "INFO", - "code": "INFORMATIONAL_MESSAGE", - "message": "Declined because of no equipment availability" - } - ], - "booking": { - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "carrierBookingReference": "ABC709951", - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT DECLINED", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 3, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ], - "confirmedEquipments": [ - { - "ISOEquipmentCode": "42GP", - "units": 3 - } - ], - "transportPlan": [ - { - "transportPlanStage": "MNC", - "transportPlanStageSequenceNumber": 1, - "loadLocation": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "dischargeLocation": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "plannedDepartureDate": "2024-01-20", - "plannedArrivalDate": "2024-01-31", - "modeOfTransport": "VESSEL", - "vesselName": "MAERSK IOWA", - "vesselIMONumber": "9298686", - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W" - } - ], - "shipmentCutOffTimes": [ - { - "cutOffDateTimeCode": "DCO", - "cutOffDateTime": "2024-01-17T22:30:00.000" - }, - { - "cutOffDateTimeCode": "VCO", - "cutOffDateTime": "2024-01-18T22:30:00.000" - }, - { - "cutOffDateTimeCode": "FCO", - "cutOffDateTime": "2024-01-19T13:30:00.000" - } - ], - "advanceManifestFilings": [ - { - "manifestTypeCode": "ACE", - "countryCode": "US" - } - ], - "carrierClauses": [ - "The date of shipment, the carrying vessel and theschedule are not guaranteed and are always subject tochanges.", - "Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration.", - "Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014).", - "In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee." - ] - }, - "amendedBooking": { - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "carrierBookingReference": "ABC709951", - "bookingStatus": "CONFIRMED", - "amendedBookingStatus": "AMENDMENT DECLINED", - "receiptTypeAtOrigin": "CY", - "deliveryTypeAtDestination": "CY", - "cargoMovementTypeAtOrigin": "FCL", - "cargoMovementTypeAtDestination": "FCL", - "serviceContractReference": "HHL51800000", - "freightPaymentTermCode": "PRE", - "originChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "PRE", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "destinationChargesPaymentTerm": { - "haulageChargesPaymentTermCode": "COL", - "portChargesPaymentTermCode": "PRE", - "otherChargesPaymentTermCode": "COL" - }, - "contractQuotationReference": "HHL1401", - "vessel": { - "name": "MAERSK IOWA", - "vesselIMONumber": "9298686" - }, - "carrierServiceCode": "TA1", - "carrierExportVoyageNumber": "403W", - "isPartialLoadAllowed": false, - "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, - "expectedDepartureDate": "2024-01-20", - "incoTerms": "EXW", - "communicationChannelCode": "AO", - "isEquipmentSubstitutionAllowed": false, - "references": [ - { - "type": "CR", - "value": "KN-00103004" - } - ], - "documentParties": { - "bookingAgent": { - "partyName": "KN Bremerhaven", - "address": { - "street": "Amerikaring", - "streetNumber": "40", - "postCode": "27568", - "city": "Bremerhaven", - "countryCode": "DE" - }, - "partyContactDetails": [ - { - "name": "Export operations department", - "phone": "+49 471 945410" - } - ] - } - }, - "partyContactDetails": [ - { - "name": "Diane", - "phone": "+49 471 945410" - } - ], - "shipmentLocations": [ - { - "location": { - "locationName": "Bremerhaven", - "UNLocationCode": "DEBRV" - }, - "locationTypeCode": "POL" - }, - { - "location": { - "locationName": "Norfolk", - "UNLocationCode": "USORF" - }, - "locationTypeCode": "POD" - } - ], - "requestedEquipments": [ - { - "isShipperOwned": false, - "ISOEquipmentCode": "42GP", - "units": 30, - "commodities": [ - { - "commodityType": "Dry cargo, Freight all kinds", - "cargoGrossWeight": 36000, - "cargoGrossWeightUnit": "KGM" - } - ] - } - ] - } - } - } - }, - "cancelConfirmedBookingLightweightExample": { - "summary": "Confirmed Booking cancelled (Lightweight)\n", - "description": "A lightweight notification explaining that a confirmed `Booking` has been cancelled (`bookingCancellationStatus='CANCELLATION CONFIRMED'`)\n", - "value": { - "specversion": "1.0", - "id": "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source": "https://member.com/", - "type": "org.dcsa.booking.v2", - "time": "2018-04-05T17:31:00Z", - "datacontenttype": "application/json", - "subscriptionReference": "BKG001", - "data": { - "bookingStatus": "CANCELLED", - "amendedBookingStatus": "AMENDMENT CANCELLED", - "bookingCancellationStatus": "CANCELLATION CONFIRMED", - "carrierBookingRequestReference": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa", - "carrierBookingReference": "ABC709951" - } - } - } - } - } - } - }, - "responses": { - "204": { - "description": "No Content\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - } - }, - "400": { - "description": "In case the `Notification` does not schema validate a `400` (Bad Request) is returned\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Booking missing carrierBookingReference or carrierBookingRequestReference\n", - "description": "`carrierBookingReference` or `carrierBookingRequestReference` is a conditionary property in the `Notification` (at least one of them must be present). This is an example of how the error object would look in case this property is missing\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/booking-notifications", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "carrierBookingReference or carrierBookingRequestReference not found - one of them is a mandatory to provide in a Notification\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "property": "carrierBookingReference or carrierBookingRequestReference", - "errorCodeText": "mandatory property missing", - "errorCodeMessage": "carrierBookingReference or carrierBookingRequestReference must be provided as part of a Notification\n" - } - ] - } - } - } - } - } - }, - "500": { - "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "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\n", - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/booking-notifications", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Booking request\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Making too many Notifications\n", - "description": "Calling the endPoint\n\n POST /v2/booking-notifications\n\ntoo many times within a timeperiod.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "value": { - "httpMethod": "POST", - "requestUri": "/v2/booking-notifications", - "statusCode": 429, - "statusCodeText": "Too Many Requests", - "statusCodeMessage": "Too many request to create a Notification has been requested. Please try again in 1 hour\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2023-04-13T07:41:00+08:30", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Max Notifications reached", - "errorCodeMessage": "A maximum of 10 Notifications can be created per hour" - } - ] - } - } - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "BookingNotification": { - "title": "Booking Notification", - "required": [ - "data", - "datacontenttype", - "id", - "source", - "specversion", - "subscriptionReference", - "time", - "type" - ], - "type": "object", - "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.\n\nCurrently, 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.\n", - "example": "1.0", - "enum": [ - "1.0" - ] - }, - "id": { - "maxLength": 100, - "type": "string", - "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.\n", - "example": "3cecb101-7a1a-43a4-9d62-e88a131651e2" - }, - "source": { - "maxLength": 4096, - "type": "string", - "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.\n\nProducers MUST ensure that `source` + `id` is unique for each distinct event.\n\nAn 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.\n\nA 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.\n", - "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.\n", - "example": "org.dcsa.booking.v2", - "enum": [ - "org.dcsa.booking.v2" - ] - }, - "time": { - "type": "string", - "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.\n", - "format": "date-time", - "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).\n\nFor 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.\n\nIn 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\"`.\n\nWhen 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.\n", - "example": "application/json", - "enum": [ - "application/json" - ] - }, - "subscriptionReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference of the subscription that has triggered this event\n", - "example": "30675492-50ff-4e17-a7df-7a487a8ad343" - }, - "data": { - "$ref": "#/components/schemas/BookingNotification_data" - } - }, - "description": "`CloudEvent` specific properties for the `Notification`.\n" - }, - "Feedback": { - "title": "Feedback", - "required": [ - "code", - "message", - "severity" - ], - "type": "object", - "properties": { - "severity": { - "maxLength": 50, - "type": "string", - "description": "The severity of the feedback. Possible values are:\n- `INFO` (Information - \"Your reefer container will use renewable energy\", \"This earlier / premium service is available\")\n- `WARN` (Warning - \"I'm going to replace\" / \"Ignore this value\" / \"Use another value instead\")\n- `ERROR` (Error - \"This must be changed!\")\n", - "example": "WARN" - }, - "code": { - "maxLength": 50, - "type": "string", - "description": "A code used to describe the feedback. Possible values are:\n- `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) \n- `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values)\n- `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided)\n- `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention)\n- `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future)\n- `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention)\n", - "example": "PROPERTY_WILL_BE_IGNORED" - }, - "message": { - "maxLength": 5000, - "type": "string", - "description": "A description with additional information.\n", - "example": "Spaces not allowed in facility code" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example": "$.location.facilityCode" - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error/warning.\n", - "example": "facilityCode" - } - }, - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n" - }, - "ErrorResponse": { - "title": "Error Response", - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "example": "POST", - "enum": [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ] - }, - "requestUri": { - "type": "string", - "description": "The URI that was requested.\n", - "example": "/v1/events" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code returned.\n", - "format": "int32", - "example": 400 - }, - "statusCodeText": { - "maxLength": 50, - "type": "string", - "description": "A standard short description corresponding to the HTTP status code.\n", - "example": "Bad Request" - }, - "statusCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the HTTP status code with additional information.\n", - "example": "The supplied data could not be accepted" - }, - "providerCorrelationReference": { - "maxLength": 100, - "type": "string", - "description": "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example": "4426d965-0dd8-4005-8c63-dc68b01c4962" - }, - "errorDateTime": { - "type": "string", - "description": "The DateTime corresponding to the error occurring. Must be formatted using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n", - "format": "date-time", - "example": "2019-11-12T07:41:00+08:30" - }, - "errors": { - "minItems": 1, - "type": "array", - "description": "An array of errors providing more detail about the root cause.\n", - "items": { - "$ref": "#/components/schemas/DetailedError" - } - } - }, - "description": "Unexpected error" - }, - "DetailedError": { - "title": "Detailed Error", - "required": [ - "errorCodeMessage", - "errorCodeText" - ], - "type": "object", - "properties": { - "errorCode": { - "maximum": 9999, - "minimum": 7000, - "type": "integer", - "description": "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://dcsa.atlassian.net/wiki/spaces/DTG/pages/197132308/Standard+Error+Codes).\n", - "format": "int32", - "example": 7003 - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error.\n", - "example": "facilityCode" - }, - "value": { - "maxLength": 500, - "type": "string", - "description": "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example": "SG SIN WHS" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example": "$.location.facilityCode" - }, - "errorCodeText": { - "maxLength": 100, - "type": "string", - "description": "A standard short description corresponding to the `errorCode`.\n", - "example": "invalidData" - }, - "errorCodeMessage": { - "maxLength": 5000, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.\n", - "example": "Spaces not allowed in facility code" - } - }, - "description": "A detailed description of what has caused the error.\n" - }, - "Address": { - "title": "Address", - "required": [ - "city", - "countryCode", - "street" - ], - "type": "object", - "properties": { - "street": { - "maxLength": 70, - "type": "string", - "description": "The name of the street of the party's address.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street of the party's address.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The floor of the party's street number.\n", - "example": "2nd" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code of the party's address.", - "example": "1047 HM" - }, - "PObox": { - "maxLength": 20, - "type": "string", - "description": "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example": "123" - }, - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The city name of the party's address.\n", - "example": "Amsterdam" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The state/region of the party's address.", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing address related information\n" - }, - "Facility": { - "title": "Facility", - "required": [ - "facilityCode", - "facilityCodeListProvider" - ], - "type": "object", - "properties": { - "facilityCode": { - "maxLength": 6, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\n\nThe definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used:\n\n- for `SMDG` - the codeList used is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx) \n- for `BIC` - the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/)\n", - "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`\n- `BIC` (Requires a UN Location Code)\n- `SMDG` (Requires a UN Location Code)\n", - "example": "SMDG", - "enum": [ - "BIC", - "SMDG" - ] - } - }, - "description": "An object used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute.\n" - }, - "GeoCoordinate": { - "title": "Geo Coordinate", - "required": [ - "latitude", - "longitude" - ], - "type": "object", - "properties": { - "latitude": { - "maxLength": 10, - "type": "string", - "description": "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", - "example": "48.8585500" - }, - "longitude": { - "maxLength": 11, - "type": "string", - "description": "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", - "example": "2.294492036" - } - }, - "description": "An object used to express a location using `latitude` and `longitude`.\n" - }, - "CreateBooking": { - "title": "Create Booking", - "required": [ - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "communicationChannelCode", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "isPartialLoadAllowed", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `NMFTA` or `SMDG` code of the carrier the booking request is intended for.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the carrier code. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n", - "example": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular\nshipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival.\n", - "example": "XYZ987987" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [ICC](https://iccwbo.org/business-solutions/incoterms-rules/). A list of possible values:\n- `EXW` (Ex-Works)\n- `FCA` (Free Carrier)\n- `FAS` (Free Alongside Ship)\n- `FOB` (Free On Board)\n- `CFR` (Cost and Freight)\n- `CIF` (Cost, Insurance and Freight)\n- `CPT` (Carriage Paid To)\n- `CIP` (Carriage And Insurance Paid To)\n- `DAP` (Delivered At Place)\n- `DPU` (Delivered At Place Unloaded)\n- `DDP` (Delivered Duty Paid)\n", - "example": "FCA" - }, - "communicationChannelCode": { - "maxLength": 2, - "type": "string", - "description": "Specifying which communication channel is to be used for this booking e.g. Possible values are:\n- `EI` (EDI transmission)\n- `EM` (Email)\n- `AO` (API)\n", - "example": "AO" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/ReferenceShipper" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties_1" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipmentShipper" - } - } - } - }, - "UpdateBooking": { - "title": "Update Booking", - "required": [ - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "communicationChannelCode", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "isPartialLoadAllowed", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `NMFTA` or `SMDG` code of the carrier the booking request is intended for.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the carrier code. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n", - "example": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular\nshipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [ICC](https://iccwbo.org/business-solutions/incoterms-rules/). A list of possible values:\n- `EXW` (Ex-Works)\n- `FCA` (Free Carrier)\n- `FAS` (Free Alongside Ship)\n- `FOB` (Free On Board)\n- `CFR` (Cost and Freight)\n- `CIF` (Cost, Insurance and Freight)\n- `CPT` (Carriage Paid To)\n- `CIP` (Carriage And Insurance Paid To)\n- `DAP` (Delivered At Place)\n- `DPU` (Delivered At Place Unloaded)\n- `DDP` (Delivered Duty Paid)\n", - "example": "FCA" - }, - "communicationChannelCode": { - "maxLength": 2, - "type": "string", - "description": "Specifying which communication channel is to be used for this booking e.g. Possible values are:\n- `EI` (EDI transmission)\n- `EM` (Email)\n- `AO` (API)\n", - "example": "AO" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/ReferenceShipper" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties_1" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipmentShipper" - } - } - } - }, - "Booking": { - "title": "Booking", - "required": [ - "bookingStatus", - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "communicationChannelCode", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "isPartialLoadAllowed", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING UPDATE` (An update is required to the Booking)\n- `UPDATE RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION RECEIVED" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `NMFTA` or `SMDG` code of the carrier the booking request is intended for.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the carrier code. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n", - "example": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [ICC](https://iccwbo.org/business-solutions/incoterms-rules/). A list of possible values:\n- `EXW` (Ex-Works)\n- `FCA` (Free Carrier)\n- `FAS` (Free Alongside Ship)\n- `FOB` (Free On Board)\n- `CFR` (Cost and Freight)\n- `CIF` (Cost, Insurance and Freight)\n- `CPT` (Carriage Paid To)\n- `CIP` (Carriage And Insurance Paid To)\n- `DAP` (Delivered At Place)\n- `DPU` (Delivered At Place Unloaded)\n- `DDP` (Delivered Duty Paid)\n", - "example": "FCA" - }, - "communicationChannelCode": { - "maxLength": 2, - "type": "string", - "description": "Specifying which communication channel is to be used for this booking e.g. Possible values are:\n- `EI` (EDI transmission)\n- `EM` (Email)\n- `AO` (API)\n", - "example": "AO" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipment" - } - }, - "confirmedEquipments": { - "type": "array", - "description": "A list of `Confirmed Equipments`\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ConfirmedEquipment" - } - }, - "transportPlan": { - "type": "array", - "description": "A list of `Transport` objects (legs) describing the entire transport plan including transshipments.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/Transport" - } - }, - "shipmentCutOffTimes": { - "type": "array", - "description": "A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ShipmentCutOffTime" - } - }, - "advanceManifestFilings": { - "type": "array", - "description": "A list of `Advance Manifest Filings` provided by the carrier\n", - "items": { - "$ref": "#/components/schemas/AdvanceManifestFiling" - } - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "carrierClauses": { - "type": "array", - "description": "Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - } - }, - "BookingRefStatus": { - "title": "Booking Response", - "required": [ - "bookingStatus" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING UPDATE` (An update is required to the Booking)\n- `UPDATE RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION RECEIVED" - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "The `carrierBookingReference` or `carrierBookingRequestReference` along with the statuses and a possible list of **Feedbacks**.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n" - }, - "ActiveReeferSettings": { - "title": "Active Reefer Settings", - "required": [ - "temperatureSetpoint", - "temperatureUnit" - ], - "type": "object", - "properties": { - "temperatureSetpoint": { - "type": "number", - "description": "Target value of the temperature for the Reefer based on the cargo requirement.\n", - "format": "float", - "example": -15 - }, - "temperatureUnit": { - "type": "string", - "description": "The unit for temperature in Celsius or Fahrenheit\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", - "example": "CEL", - "enum": [ - "CEL", - "FAH" - ] - }, - "o2Setpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere CO2 target value\n", - "format": "float", - "example": 25 - }, - "co2Setpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere CO2 target value\n", - "format": "float", - "example": 25 - }, - "humiditySetpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere humidity target value\n", - "format": "float", - "example": 95.6 - }, - "airExchangeSetpoint": { - "minimum": 0, - "type": "number", - "description": "Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container\n", - "format": "float", - "example": 15.4 - }, - "airExchangeUnit": { - "type": "string", - "description": "The unit for `airExchange` in metrics- or imperial- units per hour\n- `MQH` (Cubic metre per hour)\n- `FQH` (Cubic foot per hour)\n\n**Condition:** Mandatory to provide if `airExchange` is provided\n", - "example": "MQH", - "enum": [ - "MQH", - "FQH" - ] - }, - "isVentilationOpen": { - "type": "boolean", - "description": "If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed`\n", - "example": true - }, - "isDrainholesOpen": { - "type": "boolean", - "description": "Is drainholes open on the container\n", - "example": true - }, - "isBulbMode": { - "type": "boolean", - "description": "Is special container setting for handling flower bulbs active\n", - "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\n", - "example": true - }, - "isControlledAtmosphereRequired": { - "type": "boolean", - "description": "Indicator of whether cargo requires Controlled Atmosphere.\n", - "example": true - }, - "isPreCoolingRequired": { - "type": "boolean", - "description": "Indicator whether reefer container should be pre-cooled to the temperature setting required at time of release from depot\n", - "example": true - }, - "isGeneratorSetRequired": { - "type": "boolean", - "description": "Indicator whether reefer container should have a generator set attached at time of release from depot\n", - "example": true - } - }, - "description": "The specifications for a Reefer equipment.\n\n**Condition:** Only applicable when `isNonOperatingReefer` is set to `false`\n" - }, - "PartyAddress": { - "title": "Party Address", - "required": [ - "city", - "countryCode", - "street" - ], - "type": "object", - "properties": { - "street": { - "maxLength": 70, - "type": "string", - "description": "The name of the street of the party's address.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street of the party's address.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The floor of the party's street number.\n", - "example": "2nd" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code of the party's address.", - "example": "1047 HM" - }, - "PObox": { - "maxLength": 20, - "type": "string", - "description": "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example": "123" - }, - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The city name of the party's address.\n", - "example": "Amsterdam" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The state/region of the party's address.", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing address related information\n" - }, - "OtherDocumentParty": { - "title": "Other Document Party", - "required": [ - "party", - "partyFunction" - ], - "type": "object", - "properties": { - "party": { - "$ref": "#/components/schemas/Party" - }, - "partyFunction": { - "maxLength": 3, - "type": "string", - "description": "Specifies the role of the party in a given context. Possible values are:\n\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `COW` (Invoice payer on behalf of the consignor (shipper))\n- `COX` (Invoice payer on behalf of the consignee)\n- `N1` (First Notify Party)\n- `N2` (Second Notify Party)\n- `NI` (Other Notify Party)\n", - "example": "DDS" - } - }, - "description": "A list of document parties that can be optionally provided at booking stage\n" - }, - "BookingAgent": { - "title": "Booking Agent", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Booking Agent`.\n", - "example": "HHL007" - } - }, - "description": "The party placing the booking request on behalf of the customer.\n" - }, - "Shipper": { - "title": "Shipper", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Shipper`.\n", - "example": "HHL007" - }, - "purchaseOrderReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A purchase order reference linked to the `Shipper`.\n", - "example": "HHL007" - } - }, - "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.\n" - }, - "Consignee": { - "title": "Consignee", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Consignee`.\n", - "example": "HHL007" - }, - "purchaseOrderReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A purchase order reference linked to the `Consignee`.\n", - "example": "HHL007" - } - }, - "description": "The party to which goods are consigned in the Master Bill of Lading.\n" - }, - "ServiceContractOwner": { - "title": "Service Contract Owner", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Service Contract Owner`.\n", - "example": "HHL007" - } - }, - "description": "The party signing the service contract with the carrier.\n" - }, - "CarrierBookingOffice": { - "title": "Carrier Booking Office", - "required": [ - "UNLocationCode", - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - } - }, - "description": "The carrier office responsible for processing the booking.\n" - }, - "Party": { - "title": "Party", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Party`.\n", - "example": "HHL007" - } - }, - "description": "Refers to a company or a legal entity.\n" - }, - "PartyContactDetail": { - "title": "Party Contact Detail", - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the contact\n", - "example": "Henrik" - } - }, - "description": "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`.\n", - "example": { - "name": "Henrik", - "phone": "+45 51801234" - }, - "anyOf": [ - { - "title": "Phone required", - "required": [ - "phone" - ], - "type": "object", - "properties": { - "phone": { - "maxLength": 30, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Phone number for the contact\n", - "example": "+45 70262970" - } - }, - "description": "`Phone` is mandatory to provide\n" - }, - { - "title": "Email required", - "required": [ - "email" - ], - "type": "object", - "properties": { - "email": { - "maxLength": 100, - "pattern": "^.+@\\S+$", - "type": "string", - "description": "`E-mail` address to be used\n", - "example": "info@dcsa.org" - } - }, - "description": "`Email` is mandatory to provide\n" - } - ] - }, - "IdentifyingCode": { - "title": "Identifying Code", - "required": [ - "codeListProvider", - "partyCode" - ], - "type": "object", - "properties": { - "codeListProvider": { - "maxLength": 100, - "type": "string", - "description": "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", - "example": "W3C" - }, - "partyCode": { - "maxLength": 150, - "type": "string", - "description": "Code to identify the party as provided by the code list provider\n", - "example": "MSK" - }, - "codeListName": { - "maxLength": 100, - "type": "string", - "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", - "example": "DID" - } - } - }, - "TaxLegalReference": { - "title": "Tax & Legal Reference", - "required": [ - "countryCode", - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference type code as defined by the relevant tax and/or legal authority.\n", - "example": "PAN" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "DK" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `taxLegalReference`\n", - "example": "AAAAA0000A" - } - }, - "description": "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA list of examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n\nAllowed combinations of `type` and `country` are maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/taxandlegalreferences-v300.csv).\n" - }, - "ReferenceShipper": { - "title": "Reference (Shipper)", - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 3, - "type": "string", - "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer's Reference)\n- `AKG` (Vehicle Identification Number)\n- `AEF` (Customer Load Reference)\n", - "example": "CR" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the reference. \n", - "example": "HHL00103004" - } - }, - "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.\n" - }, - "Reference": { - "title": "Reference", - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 3, - "type": "string", - "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer's Reference)\n- `ECR` (Empty container release reference)\n- `AKG` (Vehicle Identification Number)\n- `AEF` (Customer Load Reference)\n", - "example": "CR" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the reference. \n", - "example": "HHL00103004" - } - }, - "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.\n" - }, - "CustomsReference": { - "title": "Customs Reference", - "required": [ - "countryCode", - "type", - "values" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference type code as defined in the relevant customs jurisdiction.\n", - "example": "ACID" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - }, - "values": { - "minItems": 1, - "type": "array", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `customsReference`\n", - "example": "4988470982020120017" - } - } - }, - "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA (small) list of examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n\nAllowed combinations of `type` and `country` are maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/customsreferences-v300.csv).\n" - }, - "ShipmentLocation": { - "title": "Shipment Location", - "required": [ - "location", - "locationTypeCode" - ], - "type": "object", - "properties": { - "location": { - "$ref": "#/components/schemas/Location" - }, - "locationTypeCode": { - "maxLength": 3, - "type": "string", - "description": "Links to the Location Type Code defined by DCSA. Possible values are:\n- `PRE` (Place of Receipt)\n- `POL` (Port of Loading)\n- `POD` (Port of Discharge)\n- `PDE` (Place of Delivery)\n- `PCF` (Pre-carriage From)\n- `OIR` (Onward In-land Routing)\n- `ORI` (Origin of goods)\n- `IEL` (Container intermediate export stop off location)\n- `PTP` (Prohibited transshipment port)\n- `RTP` (Requested transshipment port)\n- `FCD` (Full container drop-off location)\n", - "example": "PRE" - } - }, - "description": "Maps the relationship between `Shipment` and `Location`, e.g., the `Place of Receipt` and the `Place of Delivery` for a specific shipment. This is a reusable object between `Booking` and `Transport Document`\n" - }, - "Location": { - "title": "Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "geoCoordinate": { - "$ref": "#/components/schemas/GeoCoordinate" - } - }, - "description": "The location can be specified using **any** of the nested structures:\n- `address` (used to specify the location via an Address)\n- `UNLocationCode`\n- `facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`)\n- `geoCoordinate` (used to specify a location using `latitude` and `longitude`)\n\nIt is expected that if a location is specified in multiple ways (both as an `Address` and as a `Facility`) that both ways point to the same location.\n", - "example": { - "locationName": "CMP Container Terminal Copenhagen", - "UNLocationCode": "DKCPH", - "facility": { - "facilityCode": "CMPDK", - "facilityCodeListProvider": "SMDG" - } - } - }, - "RequestedEquipment": { - "title": "Requested Equipment", - "required": [ - "ISOEquipmentCode", - "units" - ], - "type": "object", - "properties": { - "ISOEquipmentCode": { - "maxLength": 4, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346) standard.\n", - "example": "22RT" - }, - "units": { - "minimum": 1, - "type": "integer", - "description": "Number of requested equipment units.\n", - "format": "int32", - "example": 3 - }, - "containerPositionings": { - "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", - "items": { - "$ref": "#/components/schemas/ContainerPositioning" - } - }, - "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" - }, - "equipmentReferences": { - "type": "array", - "description": "A list of equipments to be used by the shipper if known at the time of booking\n", - "items": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\n\nAccording to [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346), 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).\n\nIf a container does not comply with [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n", - "example": "APZU4812090" - } - }, - "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.\n\n**Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type.\n", - "example": false - }, - "activeReeferSettings": { - "$ref": "#/components/schemas/ActiveReeferSettings" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "commodities": { - "type": "array", - "description": "A list of `Commodities`\n", - "items": { - "$ref": "#/components/schemas/Commodity" - } - } - }, - "description": "If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting).\n", - "discriminator": { - "propertyName": "isShipperOwned", - "mapping": { - "true": "#/components/schemas/SocEquipment", - "false": "#/components/schemas/CocEquipment" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/SocEquipment" - }, - { - "$ref": "#/components/schemas/CocEquipment" - } - ] - }, - "RequestedEquipmentShipper": { - "title": "Requested Equipment (Shipper)", - "required": [ - "ISOEquipmentCode", - "units" - ], - "type": "object", - "properties": { - "ISOEquipmentCode": { - "maxLength": 4, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346) standard.\n", - "example": "22RT" - }, - "units": { - "minimum": 1, - "type": "integer", - "description": "Number of requested equipment units.\n", - "format": "int32", - "example": 3 - }, - "containerPositionings": { - "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", - "items": { - "$ref": "#/components/schemas/ContainerPositioning" - } - }, - "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" - }, - "equipmentReferences": { - "type": "array", - "description": "A list of equipments to be used by the shipper if known at the time of booking\n", - "items": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\n\nAccording to [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346), 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).\n\nIf a container does not comply with [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n", - "example": "APZU4812090" - } - }, - "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.\n\n**Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type.\n", - "example": false - }, - "activeReeferSettings": { - "$ref": "#/components/schemas/ActiveReeferSettings" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/ReferenceShipper" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "commodities": { - "type": "array", - "description": "A list of `Commodities`\n", - "items": { - "$ref": "#/components/schemas/CommodityShipper" - } - } - }, - "description": "If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting).\n", - "discriminator": { - "propertyName": "isShipperOwned", - "mapping": { - "true": "#/components/schemas/SocEquipment", - "false": "#/components/schemas/CocEquipment" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/SocEquipment" - }, - { - "$ref": "#/components/schemas/CocEquipment" - } - ] - }, - "SocEquipment": { - "title": "Shipper owned Equipment", - "required": [ - "isShipperOwned", - "tareWeight", - "tareWeightUnit" - ], - "type": "object", - "properties": { - "tareWeight": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "tareWeightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - }, - "isShipperOwned": { - "type": "boolean", - "description": "Indicates whether the container is shipper owned (`SOC`).\n", - "example": true - } - } - }, - "CocEquipment": { - "title": "Carrier owned Equipment", - "required": [ - "isShipperOwned" - ], - "type": "object", - "properties": { - "isShipperOwned": { - "type": "boolean", - "description": "Indicates whether the container is shipper owned (`SOC`).\n", - "example": false - } - } - }, - "ContainerPositioning": { - "title": "Container Positioning", - "required": [ - "location" - ], - "type": "object", - "properties": { - "dateTime": { - "type": "string", - "description": "The date and time requested by the shipper for the positioning of the container(s) at the Container positioning location (`CPO`), if provided, or the Place of Receipt (`PRE`) if `CPO` location is not provided.\n", - "format": "date-time", - "example": "2024-07-05T09:03:00-02:00" - }, - "location": { - "$ref": "#/components/schemas/ContainerPositioningLocation" - } - }, - "description": "An object to capture the `Location` together with an optional `Date and Time`.\n" - }, - "ContainerPositioningEstimated": { - "title": "Container Positioning Estimated", - "required": [ - "location" - ], - "type": "object", - "properties": { - "estimatedDateTime": { - "type": "string", - "description": "The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n", - "format": "date-time", - "example": "2024-07-05T09:03:00-02:00" - }, - "location": { - "$ref": "#/components/schemas/ContainerPositioningLocation" - } - }, - "description": "An object to capture the `Location` together with an optional `Date and Time`.\n" - }, - "ContainerPositioningLocation": { - "title": "Container Positioning Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Shanghai Shengdong International Container Terminal" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "geoCoordinate": { - "$ref": "#/components/schemas/GeoCoordinate" - } - }, - "description": "An object to capture the `Container Positioning Location`.\n\nThe location of the customer facility where the container(s) will be loaded.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n\nThe location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.\n", - "example": { - "locationName": "Shanghai Shengdong International Container Terminal", - "UNLocationCode": "CNSGH", - "facility": { - "facilityCode": "SHENG", - "facilityCodeListProvider": "SMDG" - } - } - }, - "EmptyContainerDepotReleaseLocation": { - "title": "Empty Container Depot Release Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Shanghai Shengdong International Container Terminal" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "geoCoordinate": { - "$ref": "#/components/schemas/GeoCoordinate" - } - }, - "description": "An object to capture the `Empty Container Depot Release Location`.\n\nThe location of the depot from which the empty container(s) will be released from\n\nThe location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.\n", - "example": { - "locationName": "Shanghai Shengdong International Container Terminal", - "UNLocationCode": "CNSGH", - "facility": { - "facilityCode": "SHENG", - "facilityCodeListProvider": "SMDG" - } - } - }, - "CommodityShipper": { - "title": "Commodity (Shipper)", - "required": [ - "cargoGrossWeight", - "cargoGrossWeightUnit", - "commodityType" - ], - "type": "object", - "properties": { - "commodityType": { - "maxLength": 550, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by \"description of goods\" upon submission of `Shipping Instructions`\n", - "example": "Mobile phones" - }, - "HSCodes": { - "type": "array", - "description": "A list of `HS Codes` that apply to this `commodity`\n", - "items": { - "maxLength": 10, - "minLength": 6, - "pattern": "^\\d{6,10}$", - "type": "string", - "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.\n\nMore information can be found here: [HS Nomenclature 2022 edition](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools/hs-nomenclature-2022-edition/hs-nomenclature-2022-edition.aspx).\n\nThis standard is based on the 2022 revision.\n", - "example": "851713" - } - }, - "nationalCommodityCodes": { - "type": "array", - "description": "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items": { - "$ref": "#/components/schemas/NationalCommodityCode" - } - }, - "cargoGrossWeight": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", - "format": "float", - "example": 36000 - }, - "cargoGrossWeightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - }, - "cargoGrossVolume": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The grand total volume of the commodity\n", - "format": "float", - "example": 360 - }, - "cargoGrossVolumeUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n\n**Condition:** If the `cargoGrossVolume` is populated then the `cargoGrossVolumeUnit` is required\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - }, - "exportLicenseIssueDate": { - "type": "string", - "description": "Issue date of the export license applicable to the booking. Mandatory to provide in booking request for specific commodities\n", - "format": "date", - "example": "2021-05-14" - }, - "exportLicenseExpiryDate": { - "type": "string", - "description": "Expiry date of the export license applicable to the booking.\n\nMandatory to provide in booking request for specific commodities.\n", - "format": "date", - "example": "2021-05-21" - }, - "outerPackaging": { - "$ref": "#/components/schemas/OuterPackaging" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/ReferenceShipper" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "description": "Type of goods, defined by its commodity type\n" - }, - "Commodity": { - "title": "Commodity", - "required": [ - "cargoGrossWeight", - "cargoGrossWeightUnit", - "commodityType" - ], - "type": "object", - "properties": { - "commoditySubreference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking.\n\n**Conditional:** Mandatory to provide for `CONFIRMED` bookings\n", - "example": "COM-001" - }, - "commodityType": { - "maxLength": 550, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by \"description of goods\" upon submission of `Shipping Instructions`\n", - "example": "Mobile phones" - }, - "HSCodes": { - "type": "array", - "description": "A list of `HS Codes` that apply to this `commodity`\n", - "items": { - "maxLength": 10, - "minLength": 6, - "pattern": "^\\d{6,10}$", - "type": "string", - "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.\n\nMore information can be found here: [HS Nomenclature 2022 edition](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools/hs-nomenclature-2022-edition/hs-nomenclature-2022-edition.aspx).\n\nThis standard is based on the 2022 revision.\n", - "example": "851713" - } - }, - "nationalCommodityCodes": { - "type": "array", - "description": "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items": { - "$ref": "#/components/schemas/NationalCommodityCode" - } - }, - "cargoGrossWeight": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", - "format": "float", - "example": 36000 - }, - "cargoGrossWeightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - }, - "cargoGrossVolume": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The grand total volume of the commodity\n", - "format": "float", - "example": 360 - }, - "cargoGrossVolumeUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n\n**Condition:** If the `cargoGrossVolume` is populated then the `cargoGrossVolumeUnit` is required\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - }, - "exportLicenseIssueDate": { - "type": "string", - "description": "Issue date of the export license applicable to the booking. Mandatory to provide in booking request for specific commodities\n", - "format": "date", - "example": "2021-05-14" - }, - "exportLicenseExpiryDate": { - "type": "string", - "description": "Expiry date of the export license applicable to the booking.\n\nMandatory to provide in booking request for specific commodities.\n", - "format": "date", - "example": "2021-05-21" - }, - "outerPackaging": { - "$ref": "#/components/schemas/OuterPackaging" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "description": "Type of goods, defined by its commodity type\n" - }, - "NationalCommodityCode": { - "title": "National Commodity Code", - "required": [ - "countryCode", - "type", - "values" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", - "example": "NCM" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "BR" - }, - "values": { - "minItems": 1, - "type": "array", - "description": "A list of `national commodity codes` values.\n", - "example": [ - "1515", - "2106", - "2507", - "2512" - ], - "items": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `National Commodity Code`\n", - "example": "1515" - } - } - }, - "description": "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n" - }, - "OuterPackaging": { - "title": "Outer Packaging", - "type": "object", - "properties": { - "packageCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z0-9]{2}$", - "type": "string", - "description": "A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21 - Revision 12 Annexes V and VI](https://unece.org/sites/default/files/2021-06/rec21_Rev12e_Annex-V-VI_2021.xls)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example": "5H" - }, - "imoPackagingCode": { - "maxLength": 5, - "minLength": 1, - "pattern": "^[A-Z0-9]{1,5}$", - "type": "string", - "description": "The code of the packaging as per IMO.\n\n**Condition:** only applicable to dangerous goods if specified in the IMO IMDG code amendment version 41-22. If not available, the `packageCode` as per UN recommendation 21 should be used.\n", - "example": "1A2" - }, - "numberOfPackages": { - "minimum": 1, - "type": "integer", - "description": "Specifies the number of outer packagings/overpacks associated with this `Commodity`.\n\n**Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide\n", - "format": "int32", - "example": 18 - }, - "description": { - "maxLength": 100, - "type": "string", - "description": "Description of the outer packaging/overpack.\n", - "example": "Drum, steel" - }, - "dangerousGoods": { - "type": "array", - "description": "A list of `Dangerous Goods` related to the `Commodity`\n", - "items": { - "$ref": "#/components/schemas/DangerousGoods" - } - } - }, - "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.\n\n**Condition:** Mandatory for DG (Dangerous Goods) cargo.\n" - }, - "DangerousGoods": { - "title": "Dangerous Goods", - "required": [ - "emergencyContactDetails", - "grossWeight", - "imoClass", - "isCompetentAuthorityApprovalRequired", - "isEmptyUncleanedResidue", - "isExceptedQuantity", - "isHot", - "isLimitedQuantity", - "isMarinePollutant", - "isReportableQuantity", - "isSalvagePackings", - "isWaste", - "properShippingName" - ], - "type": "object", - "properties": { - "codedVariantList": { - "maxLength": 4, - "minLength": 4, - "pattern": "^[0-3][0-9A-Z]{3}$", - "type": "string", - "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", - "example": "2200" - }, - "properShippingName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "Chromium Trioxide, anhydrous" - }, - "technicalName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "xylene and benzene" - }, - "imoClass": { - "maxLength": 4, - "type": "string", - "description": "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n\nThe value must comply with one of the values in the [DG IMO Class value table](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/dcsa/reference-data/imoclasses-v3.1.0.csv)\n", - "example": "1.4S" - }, - "subsidiaryRisk1": { - "maxLength": 3, - "minLength": 1, - "pattern": "^[0-9](\\.[0-9])?$", - "type": "string", - "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example": "1.2" - }, - "subsidiaryRisk2": { - "maxLength": 3, - "minLength": 1, - "pattern": "^[0-9](\\.[0-9])?$", - "type": "string", - "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example": "1.2" - }, - "isMarinePollutant": { - "type": "boolean", - "description": "Indicates if the goods belong to the classification of Marine Pollutant.\n", - "example": false - }, - "packingGroup": { - "maximum": 3, - "minimum": 1, - "type": "integer", - "description": "The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code.\n", - "format": "int32", - "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.\n", - "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.\n", - "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.\n", - "example": false - }, - "isEmptyUncleanedResidue": { - "type": "boolean", - "description": "Indicates if the cargo is residue.\n", - "example": false - }, - "isWaste": { - "type": "boolean", - "description": "Indicates if waste is being shipped\n", - "example": false - }, - "isHot": { - "type": "boolean", - "description": "Indicates if high temperature cargo is shipped.\n", - "example": false - }, - "isCompetentAuthorityApprovalRequired": { - "type": "boolean", - "description": "Indicates if the cargo require approval from authorities\n", - "example": false - }, - "competentAuthorityApproval": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name and reference number of the competent authority providing the approval.\n", - "example": "{Name and reference...}" - }, - "segregationGroups": { - "type": "array", - "description": "List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code.\n\n**Condition:** only applicable to specific hazardous goods.\n", - "items": { - "maxLength": 2, - "type": "string", - "description": "Grouping of Dangerous Goods having certain similar chemical properties. Possible values are:\n- `1` (Acids)\n- `2` (Ammonium Compounds)\n- `3` (Bromates)\n- `4` (Chlorates)\n- `5` (Chlorites)\n- `6` (Cyanides)\n- `7` (Heavy metals and their salts)\n- `8` (Hypochlorites)\n- `9` (Lead and its compounds)\n- `10` (Liquid halogenated hydrocarbons)\n- `11` (Mercury and mercury compounds)\n- `12` (Nitrites and their mixtures)\n- `13` (Perchlorates)\n- `14` (Permanganates)\n- `15` (Powdered metals)\n- `16` (Peroxides),\n- `17` (Azides)\n- `18` (Alkalis)\n", - "example": "12" - } - }, - "innerPackagings": { - "type": "array", - "description": "A list of `Inner Packings` contained inside this `outer packaging/overpack`.\n", - "items": { - "$ref": "#/components/schemas/InnerPackaging" - } - }, - "emergencyContactDetails": { - "$ref": "#/components/schemas/EmergencyContactDetails" - }, - "EMSNumber": { - "maxLength": 7, - "type": "string", - "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.\n", - "example": "F-A S-Q" - }, - "endOfHoldingTime": { - "type": "string", - "description": "Date by when the refrigerated liquid needs to be delivered.\n", - "format": "date", - "example": "2021-09-03" - }, - "fumigationDateTime": { - "type": "string", - "description": "Date & time when the container was fumigated\n", - "format": "date-time", - "example": "2021-09-03T09:03:00-02:00" - }, - "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.\n", - "example": false - }, - "inhalationZone": { - "maxLength": 1, - "minLength": 1, - "type": "string", - "description": "The zone classification of the toxicity of the inhalant. Possible values are:\n- `A` (Hazard Zone A) can be asigned to specific gases and liquids\n- `B` (Hazard Zone B) can be asigned to specific gases and liquids\n- `C` (Hazard Zone C) can **only** be asigned to specific gases\n- `D` (Hazard Zone D) can **only** be asigned to specific gases\n", - "example": "A" - }, - "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" - }, - "netWeight": { - "$ref": "#/components/schemas/Net Weight" - }, - "netExplosiveContent": { - "$ref": "#/components/schemas/Net Explosive Content" - }, - "volume": { - "$ref": "#/components/schemas/Volume" - }, - "limits": { - "$ref": "#/components/schemas/Limits" - }, - "specialCertificateNumber": { - "maxLength": 255, - "type": "string", - "description": "Text field to indicate certificate number & segment for specific stowage requirements overulling IMDG code\n", - "example": "22663:3" - }, - "additionalContainerCargoHandling": { - "maxLength": 255, - "type": "string", - "description": "Text field to provide cargo handling information already known at the booking stage.\n", - "example": "To be handled with extreme care" - } - }, - "description": "Specification for `Dangerous Goods`. It is mandatory to either provide the `unNumber` or the `naNumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", - "oneOf": [ - { - "title": "UN Number", - "required": [ - "unNumber" - ], - "type": "object", - "properties": { - "unNumber": { - "maxLength": 4, - "minLength": 4, - "pattern": "^\\d{4}$", - "type": "string", - "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.\n", - "example": "1463" - } - } - }, - { - "title": "NA Number", - "required": [ - "naNumber" - ], - "type": "object", - "properties": { - "naNumber": { - "maxLength": 4, - "minLength": 4, - "pattern": "^\\d{4}$", - "type": "string", - "description": "Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation.\n", - "example": "9037" - } - } - } - ] - }, - "InnerPackaging": { - "title": "Inner Packaging", - "required": [ - "description", - "material", - "quantity" - ], - "type": "object", - "properties": { - "quantity": { - "type": "integer", - "description": "Count of `Inner Packagings` of the referenced `Dangerous Goods`.\n", - "format": "int32", - "example": 20 - }, - "material": { - "maxLength": 100, - "type": "string", - "description": "The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`.\n", - "example": "Plastic" - }, - "description": { - "maxLength": 100, - "type": "string", - "description": "Description of the packaging.\n", - "example": "Wowen plastic water resistant Bag" - } - }, - "description": "Object for inner packaging specification\n" - }, - "EmergencyContactDetails": { - "title": "Emergency Contact Details", - "required": [ - "contact", - "phone" - ], - "type": "object", - "properties": { - "contact": { - "maxLength": 255, - "type": "string", - "description": "Name of the Contact person during an emergency.\n", - "example": "Henrik Larsen" - }, - "provider": { - "maxLength": 255, - "type": "string", - "description": "Name of the third party vendor providing emergency support\n", - "example": "GlobeTeam" - }, - "phone": { - "maxLength": 30, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Phone number for the contact\n", - "example": "+45 70262970" - }, - "referenceNumber": { - "maxLength": 255, - "type": "string", - "description": "Contract reference for the emergency support provided by an external third party vendor.\n", - "example": "12234" - } - }, - "description": "24 hr emergency contact details\n" - }, - "Limits": { - "title": "Limits", - "required": [ - "temperatureUnit" - ], - "type": "object", - "properties": { - "temperatureUnit": { - "type": "string", - "description": "The unit for **all attributes in the limits structure** in Celsius or Fahrenheit\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n", - "example": "CEL", - "enum": [ - "CEL", - "FAH" - ] - }, - "flashPoint": { - "type": "number", - "description": "Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air.\n\n**Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code amendment version 41-22.\n", - "format": "float", - "example": 42 - }, - "transportControlTemperature": { - "type": "number", - "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.\n", - "format": "float", - "example": 24.1 - }, - "transportEmergencyTemperature": { - "type": "number", - "description": "Temperature at which emergency procedures shall be implemented\n", - "format": "float", - "example": 74.1 - }, - "SADT": { - "type": "number", - "description": "Lowest temperature in which self-accelerating decomposition may occur in a substance\n", - "format": "float", - "example": 54.1 - }, - "SAPT": { - "type": "number", - "description": "Lowest temperature in which self-accelerating polymerization may occur in a substance\n", - "format": "float", - "example": 70 - } - }, - "description": "Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure.\n" - }, - "ConfirmedEquipment": { - "title": "Confirmed Equipment", - "required": [ - "ISOEquipmentCode", - "units" - ], - "type": "object", - "properties": { - "ISOEquipmentCode": { - "maxLength": 4, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://en.wikipedia.org/wiki/ISO_6346) standard.\n", - "example": "22GP" - }, - "units": { - "minimum": 1, - "type": "integer", - "description": "Number of confirmed equipment units\n", - "format": "int32", - "example": 3 - }, - "containerPositionings": { - "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated).\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", - "items": { - "$ref": "#/components/schemas/ContainerPositioningEstimated" - } - }, - "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" - } - }, - "description": "The confirmed equipments for the booking\n" - }, - "Transport": { - "title": "Transport", - "required": [ - "dischargeLocation", - "loadLocation", - "plannedArrivalDate", - "plannedDepartureDate", - "transportPlanStage", - "transportPlanStageSequenceNumber" - ], - "type": "object", - "properties": { - "transportPlanStage": { - "type": "string", - "description": "Code qualifying a specific stage of transport e.g. pre-carriage, main carriage transport or on-carriage transport\n- `PRC` (Pre-Carriage)\n- `MNC` (Main Carriage Transport)\n- `ONC` (On-Carriage Transport)\n", - "example": "PRC", - "enum": [ - "PRC", - "MNC", - "ONC" - ] - }, - "transportPlanStageSequenceNumber": { - "type": "integer", - "description": "Sequence number of the transport plan stage\n", - "format": "int32", - "example": 5 - }, - "loadLocation": { - "$ref": "#/components/schemas/LoadLocation" - }, - "dischargeLocation": { - "$ref": "#/components/schemas/DischargeLocation" - }, - "plannedDepartureDate": { - "type": "string", - "description": "The planned date of departure.\n", - "format": "date", - "example": "2021-05-17" - }, - "plannedArrivalDate": { - "type": "string", - "description": "The planned date of arrival.\n", - "format": "date", - "example": "2021-05-19" - }, - "modeOfTransport": { - "maxLength": 50, - "type": "string", - "description": "The mode of transport as defined by DCSA. The currently supported values include:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example": "VESSEL" - }, - "vesselName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.\n", - "example": "King of the Seas" - }, - "vesselIMONumber": { - "maxLength": 8, - "minLength": 7, - "pattern": "^\\d{7,8}$", - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel\n", - "example": "9321483" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier-specific code of the service for which the schedule details are published.\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierImportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an import voyage. The carrier-specific identifier of the import Voyage.\n", - "example": "2103N" - }, - "universalImportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - } - }, - "description": "A single `leg` of the `Transport Plan`\n" - }, - "LoadLocation": { - "title": "Load Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "description": "An object to capture the `Load Location`.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n", - "example": { - "locationName": "Shanghai Shengdong International Container Terminal", - "UNLocationCode": "CNSGH", - "facility": { - "facilityCode": "SHENG", - "facilityCodeListProvider": "SMDG" - } - } - }, - "DischargeLocation": { - "title": "Discharge Location", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "description": "An object to capture the `Discharge Location`.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n", - "example": { - "locationName": "Transnet Port Terminals Cape Town", - "UNLocationCode": "ZACPT", - "facility": { - "facilityCode": "TNCT", - "facilityCodeListProvider": "SMDG" - } - } - }, - "ShipmentCutOffTime": { - "title": "Shipment Cut-Off Time", - "required": [ - "cutOffDateTime", - "cutOffDateTimeCode" - ], - "type": "object", - "properties": { - "cutOffDateTimeCode": { - "maxLength": 3, - "type": "string", - "description": "Code for the cut-off time. Possible values are:\n- `DCO` (Documentation cut-off)\n- `VCO` (VGM cut-off)\n- `FCO` (FCL delivery cut-off)\n- `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS`\n- `EFC` (Earliest full-container delivery date)\n", - "example": "DCO" - }, - "cutOffDateTime": { - "type": "string", - "description": "Actual cut-off time\n", - "format": "date-time", - "example": "2019-11-12T07:41:00-08:30" - } - }, - "description": "`Cut off times` defined by the carrier\n" - }, - "AdvanceManifestFiling": { - "title": "Advance Manifest Filing", - "required": [ - "countryCode", - "manifestTypeCode" - ], - "type": "object", - "properties": { - "manifestTypeCode": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The Manifest type code as defined by the provider. A list of `manifestTypeCodes` together with `countryCode` is maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/advancemanifestfilings-v300.csv)\n", - "example": "ACE" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "DK" - } - }, - "description": "An Advance Maifest Filing defined by a Manifest type code in combination with a country code.\n\nA list of `manifestTypeCodes` together with `countryCode` is maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/advancemanifestfilings-v300.csv). A (small) subset can be seen here:\n\n| manifestTypeCode | countryCode | Description |\n|-----------------------|:-------------:|-------------|\n|ACI|EG|Advance Cargo Information in Egypt|\n|ACE|US|Automated Commercial Environment in the United States|\n|AFR|JP|Cargo Summary Notification (CSN)|\n", - "example": { - "manifestTypeCode": "ACE", - "countryCode": "US" - } - }, - "Charge": { - "title": "Charge", - "required": [ - "calculationBasis", - "chargeName", - "currencyAmount", - "currencyCode", - "paymentTermCode", - "quantity", - "unitPrice" - ], - "type": "object", - "properties": { - "chargeName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Free text field describing the charge to apply\n", - "example": "Documentation fee - Destination" - }, - "currencyAmount": { - "minimum": 0, - "type": "number", - "description": "The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals.\n", - "format": "float", - "example": 1012.12 - }, - "currencyCode": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency for the charge, using a 3-character code ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)).\n", - "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).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "calculationBasis": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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.\n", - "example": "Per day" - }, - "unitPrice": { - "minimum": 0, - "type": "number", - "description": "The unit price of this charge item in the currency of the charge.\n", - "format": "float", - "example": 3456.6 - }, - "quantity": { - "minimum": 0, - "type": "number", - "description": "The amount of unit for this charge item.\n", - "format": "float", - "example": 34.4 - } - }, - "description": "Addresses the monetary value of freight and other service charges for a `Booking`.\n" - }, - "inline_response_201": { - "required": [ - "bookingStatus", - "carrierBookingRequestReference" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n", - "example": "RECEIVED" - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "The `carrierBookingRequestReference` along with the `bookingStatus` and an optional `feedbacks` is returned.\n" - }, - "inline_response_202": { - "required": [ - "carrierBookingRequestReference" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - } - }, - "description": "**Only** the `carrierBookingRequestReference` is returned.\n" - }, - "bookings_bookingReference_body": { - "type": "object", - "properties": { - "reason": { - "maxLength": 5000, - "type": "string", - "description": "An optional property where a reason for cancelling the booking or the amendment can be given.\n", - "example": "Booking cancelled due to internal problems" - } - }, - "oneOf": [ - { - "title": "Cancel Booking Request (prior to Booking Confirmation)", - "required": [ - "bookingStatus" - ], - "type": "object", - "properties": { - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider.\n\n**Conditional:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLED`.\n", - "example": "CANCELLED" - } - } - }, - { - "title": "Only cancel the amendment to a Confirmed Booking", - "required": [ - "amendedBookingStatus" - ], - "type": "object", - "properties": { - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `amendedBookingStatus` to `AMENDMENT CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`.\n\n**Conditional:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned.\n\nOnly possible value to set is `AMENDMENT CANCELLED`.\n", - "example": "AMENDMENT CANCELLED" - } - } - }, - { - "title": "Request to cancel a Confirmed Booking", - "required": [ - "bookingCancellationStatus" - ], - "type": "object", - "properties": { - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `bookingCancellationStatus` to `CANCELLATION RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon recieving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider.\n\n**Conditional:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLATION RECEIVED`.\n", - "example": "CANCELLATION RECEIVED" - } - } - } - ] - }, - "Origin Charges Payment Term": { - "title": "Origin Charges Payment Term", - "type": "object", - "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`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "portChargesPaymentTermCode": { - "type": "string", - "description": "An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "otherChargesPaymentTermCode": { - "type": "string", - "description": "An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - } - }, - "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).\n" - }, - "Destination Charges Payment Term": { - "title": "Destination Charges Payment Term", - "type": "object", - "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`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "portChargesPaymentTermCode": { - "type": "string", - "description": "An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "otherChargesPaymentTermCode": { - "type": "string", - "description": "An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - } - }, - "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).\n" - }, - "Vessel": { - "title": "Vessel", - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.\n", - "example": "King of the Seas" - }, - "vesselIMONumber": { - "maxLength": 8, - "minLength": 7, - "pattern": "^\\d{7,8}$", - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel\n", - "example": "9321483" - } - }, - "description": "Vessels related to this booking request.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and `carrierServiceCode` or `carrierServiceName` are blank.\n" - }, - "Invoice Payable At": { - "title": "Invoice Payable At", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "description": "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location must be provided as a `UN Location Code`\n" - }, - "Place of BL Issue": { - "title": "Place of B/L Issue", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - } - }, - "description": "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", - "oneOf": [ - { - "title": "UN Location Code", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - } - }, - { - "title": "Country Code", - "required": [ - "countryCode" - ], - "type": "object", - "properties": { - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "DK" - } - } - } - ] - }, - "Document Parties": { - "title": "Document Parties", - "type": "object", - "properties": { - "bookingAgent": { - "$ref": "#/components/schemas/BookingAgent" - }, - "shipper": { - "$ref": "#/components/schemas/Shipper" - }, - "consignee": { - "$ref": "#/components/schemas/Consignee" - }, - "serviceContractOwner": { - "$ref": "#/components/schemas/ServiceContractOwner" - }, - "carrierBookingOffice": { - "$ref": "#/components/schemas/CarrierBookingOffice" - }, - "other": { - "type": "array", - "description": "A list of document parties that can be optionally provided at booking stage.", - "items": { - "$ref": "#/components/schemas/OtherDocumentParty" - } - } - }, - "description": "All `Parties` with associated roles.\n" - }, - "Booking_1": { - "title": "Booking", - "required": [ - "bookingStatus", - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "communicationChannelCode", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "isPartialLoadAllowed", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING UPDATE` (An update is required to the Booking)\n- `UPDATE RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION RECEIVED" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `NMFTA` or `SMDG` code of the carrier the booking request is intended for.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the carrier code. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n", - "example": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [ICC](https://iccwbo.org/business-solutions/incoterms-rules/). A list of possible values:\n- `EXW` (Ex-Works)\n- `FCA` (Free Carrier)\n- `FAS` (Free Alongside Ship)\n- `FOB` (Free On Board)\n- `CFR` (Cost and Freight)\n- `CIF` (Cost, Insurance and Freight)\n- `CPT` (Carriage Paid To)\n- `CIP` (Carriage And Insurance Paid To)\n- `DAP` (Delivered At Place)\n- `DPU` (Delivered At Place Unloaded)\n- `DDP` (Delivered Duty Paid)\n", - "example": "FCA" - }, - "communicationChannelCode": { - "maxLength": 2, - "type": "string", - "description": "Specifying which communication channel is to be used for this booking e.g. Possible values are:\n- `EI` (EDI transmission)\n- `EM` (Email)\n- `AO` (API)\n", - "example": "AO" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipment" - } - }, - "confirmedEquipments": { - "type": "array", - "description": "A list of `Confirmed Equipments`\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ConfirmedEquipment" - } - }, - "transportPlan": { - "type": "array", - "description": "A list of `Transport` objects (legs) describing the entire transport plan including transshipments.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/Transport" - } - }, - "shipmentCutOffTimes": { - "type": "array", - "description": "A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ShipmentCutOffTime" - } - }, - "advanceManifestFilings": { - "type": "array", - "description": "A list of `Advance Manifest Filings` provided by the carrier\n", - "items": { - "$ref": "#/components/schemas/AdvanceManifestFiling" - } - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "carrierClauses": { - "type": "array", - "description": "Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking.\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored.\n" - }, - "Amended Booking": { - "title": "Amended Booking", - "required": [ - "bookingStatus", - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "communicationChannelCode", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "isPartialLoadAllowed", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING UPDATE` (An update is required to the Booking)\n- `UPDATE RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION RECEIVED" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency used for the declared value, using the 3-character code defined by [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `NMFTA` or `SMDG` code of the carrier the booking request is intended for.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the carrier code. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n", - "example": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [ICC](https://iccwbo.org/business-solutions/incoterms-rules/). A list of possible values:\n- `EXW` (Ex-Works)\n- `FCA` (Free Carrier)\n- `FAS` (Free Alongside Ship)\n- `FOB` (Free On Board)\n- `CFR` (Cost and Freight)\n- `CIF` (Cost, Insurance and Freight)\n- `CPT` (Carriage Paid To)\n- `CIP` (Carriage And Insurance Paid To)\n- `DAP` (Delivered At Place)\n- `DPU` (Delivered At Place Unloaded)\n- `DDP` (Delivered Duty Paid)\n", - "example": "FCA" - }, - "communicationChannelCode": { - "maxLength": 2, - "type": "string", - "description": "Specifying which communication channel is to be used for this booking e.g. Possible values are:\n- `EI` (EDI transmission)\n- `EM` (Email)\n- `AO` (API)\n", - "example": "AO" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipment" - } - }, - "confirmedEquipments": { - "type": "array", - "description": "A list of `Confirmed Equipments`\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ConfirmedEquipment" - } - }, - "transportPlan": { - "type": "array", - "description": "A list of `Transport` objects (legs) describing the entire transport plan including transshipments.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/Transport" - } - }, - "shipmentCutOffTimes": { - "type": "array", - "description": "A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ShipmentCutOffTime" - } - }, - "advanceManifestFilings": { - "type": "array", - "description": "A list of `Advance Manifest Filings` provided by the carrier\n", - "items": { - "$ref": "#/components/schemas/AdvanceManifestFiling" - } - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "carrierClauses": { - "type": "array", - "description": "Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "This property contains the amended booking in case:\n - an amendment is currently active\n - the subscriber is subscribing to the `Full State Transfer` of the Booking\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored.\n" - }, - "BookingNotification_data": { - "required": [ - "bookingStatus" - ], - "type": "object", - "properties": { - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n\n- `RECEIVED` (Booking request has been received)\n- `PENDING UPDATE` (An update is required to the Booking)\n- `UPDATE RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-Edocumentation/blob/master/edocumentation-domain/src/main/resources/validations/bookingstatuses.csv).\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are:\n\n- `AMENDMENT RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT CANCELLED` (Amendment discontinued by consumer)\n\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-Edocumentation/blob/master/edocumentation-domain/src/main/resources/validations/bookingstatuses.csv).\n", - "example": "AMENDMENT RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION RECEIVED" - }, - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", - "example": "ABC709951" - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - }, - "booking": { - "$ref": "#/components/schemas/Booking_1" - }, - "amendedBooking": { - "$ref": "#/components/schemas/Amended Booking" - } - }, - "description": "`Booking` specific properties for the `Notification`\n" - }, - "Document Parties_1": { - "title": "Document Parties", - "required": [ - "bookingAgent" - ], - "type": "object", - "properties": { - "bookingAgent": { - "$ref": "#/components/schemas/BookingAgent" - }, - "shipper": { - "$ref": "#/components/schemas/Shipper" - }, - "consignee": { - "$ref": "#/components/schemas/Consignee" - }, - "serviceContractOwner": { - "$ref": "#/components/schemas/ServiceContractOwner" - }, - "carrierBookingOffice": { - "$ref": "#/components/schemas/CarrierBookingOffice" - }, - "other": { - "type": "array", - "description": "A list of document parties that can be optionally provided at booking stage.", - "items": { - "$ref": "#/components/schemas/OtherDocumentParty" - } - } - }, - "description": "All `Parties` with associated roles.\n" - }, - "Empty Container Pickup": { - "title": "Empty Container Pickup", - "type": "object", - "properties": { - "dateTime": { - "type": "string", - "description": "The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided.\n", - "format": "date-time", - "example": "2024-07-05T09:03:00-02:00" - }, - "depotReleaseLocation": { - "$ref": "#/components/schemas/EmptyContainerDepotReleaseLocation" - } - }, - "description": "The date and time and location for the empty container pick-up.\n\n**Condition:** Only applicable to merchange haulage service at origin (`Receipt type at origin = 'CY'`).\n" - }, - "Gross Weight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "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.\n", - "format": "float", - "example": 12000.3 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, including packaging.\n" - }, - "Net Weight": { - "title": "Net Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, excluding packaging.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netWeight`. Possible values are\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, excluding packaging.\n" - }, - "Net Explosive Content": { - "title": "Net Explosive Content", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The total weight of the explosive substances, without the packaging's, casings, etc.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR", - "GRM", - "ONZ" - ] - } - }, - "description": "The total weight of the explosive substances, without the packaging's, casings, etc.\n" - }, - "Volume": { - "title": "Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The volume of the referenced dangerous goods.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ", - "LTR" - ] - } - }, - "description": "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n" - } - }, - "parameters": { - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2" - } - }, - "amendedContent": { - "name": "amendedContent", - "in": "query", - "description": "Controls wether the content of this payload is the amendmended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`).\n\nIf `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found\n", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "boolean", - "example": false, - "default": false - } - }, - "bookingReferencePathParam": { - "name": "bookingReference", - "in": "path", - "description": "This can be one of:\n- `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking)\n- `carrierBookingReference`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "CBR001" - } - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "2.0.0" - } - } - } - } -} diff --git a/booking/src/main/resources/standards/booking/schemas/booking-api-v20.json b/core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json similarity index 84% rename from booking/src/main/resources/standards/booking/schemas/booking-api-v20.json rename to core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json index 257a1048..3cef1bce 100644 --- a/booking/src/main/resources/standards/booking/schemas/booking-api-v20.json +++ b/core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.json @@ -1,8 +1,8 @@ { "openapi": "3.0.3", "info": { - "title": "DCSA OpenAPI specification for Booking", - "description": "API specification issued by DCSA.org.\n\nFor explanation of specific values or objects please refer to the [Information Model 2024.Q1](https://dcsa-website.cdn.prismic.io/dcsa-website/ZhlC9TjCgu4jzyW5_20240402-DCSA-Information-Model-2024.Q1-ReleaseCandidate_01.pdf). This API specification does not define the allowable updates and their timing in accordance with the established business rules. Refer to the [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2) to address this. **All use cases mentioned in this API specification refer to use cases defined in this Booking IFS**.\n\nAll other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/)\n\n### Booking (Implemented by provider)\n\nIt is possible to use the Booking API as a standalone API. In that case poll on the following endPoints:\n\n GET /v2/bookings/{bookingReference}\n\nin order to poll information about status changes.\n\n**Note:** All `/v2/bookings` endPoints must be implemented by the provider.\n\n### Notifications (Implemented by consumer)\nIt is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification).\n\n POST /v2/booking-notifications\n\nThe endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to.\n\nSigning up for notifications is defined outside the scope of this API specification.\n\n**Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v200). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n", + "title": "DCSA Booking API", + "description": "

DCSA OpenAPI specification for the Booking process

\n\nThis API is intended as an API between a carrier and anyone creating a `Booking`. The process includes:\n\n- Booking request\n- Booking update\n- Booking confirmation\n- Booking amendment\n- Booking cancellation\n- Booking rejection\n\nFor explanation of specific values or objects please refer to the [Information Model](https://developer.dcsa.org/documentation/information_models). This API specification does not define the allowable updates and their timing in accordance with the established business rules. **All use cases mentioned in this API specification refer to use cases defined in [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2)**.\n\nAll other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/)\n\n### Booking (Implemented by provider)\n\nIt is possible to use the Booking API as a standalone API. In that case poll on the following endPoints:\n\n GET /v2/bookings/{bookingReference}\n\nin order to poll information about status changes.\n\n**Note:** All `/v2/bookings` endPoints must be implemented by the provider.\n\n### Notifications (Implemented by consumer)\nIt is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification).\n\n POST /v2/booking-notifications\n\nThe endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to.\n\nSigning up for notifications is defined outside the scope of this API specification.\n\n**Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v200). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n\nAPI specification issued by [DCSA.org](https://dcsa.org/).\n", "contact": { "name": "Digital Container Shipping Association (DCSA)", "url": "https://dcsa.org", @@ -16,7 +16,8 @@ }, "servers": [ { - "url": "/" + "url": "https://virtserver.swaggerhub.com/dcsaorg/DCSA_BKG/2.0.0", + "description": "SwaggerHub API Auto Mocking" } ], "tags": [ @@ -88,7 +89,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -184,7 +184,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -291,7 +290,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -387,7 +385,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -458,7 +455,7 @@ "description": "Jerrican, steel", "dangerousGoods": [ { - "unNumber": "3082", + "UNNumber": "3082", "properShippingName": "Environmentally hazardous substance, liquid, N.O.S\n", "imoClass": "9", "isMarinePollutant": false, @@ -505,7 +502,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/inline_response_202" + "$ref": "#/components/schemas/CreateBookingResponse" }, "examples": { "acceptedExample": { @@ -727,7 +724,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -837,7 +833,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -1212,7 +1207,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -1310,7 +1304,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -1417,7 +1410,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -1516,7 +1508,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -1587,7 +1578,7 @@ "description": "Jerrican, steel", "dangerousGoods": [ { - "unNumber": "3082", + "UNNumber": "3082", "properShippingName": "Environmentally hazardous substance, liquid, N.O.S\n", "imoClass": "9", "isMarinePollutant": false, @@ -1869,7 +1860,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/bookings_bookingReference_body" + "$ref": "#/components/schemas/CancelBookingRequest" }, "examples": { "bookingCancelledExample": { @@ -1912,15 +1903,15 @@ "examples": { "bookingCancelledExample": { "summary": "Booking Request cancelled\n", - "description": "The consumer has requested that the `Booking Request` should be cancelled. The cancellation has been accepted and is now awaiting further processing by the provider\n" + "description": "The consumer has requested that the `Booking Request` should be cancelled. The cancellation request has been accepted and is now awaiting further processing by the provider\n" }, "amendmentCancelledExample": { "summary": "Amendment cancellation on a confirmed Booking accepted\n", - "description": "The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation has been accepted and is now awaiting further processing by the provider\n" + "description": "The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation request as been accepted and is now awaiting further processing by the provider\n" }, "confirmedBookingCancellationExample": { "summary": "Request to Cancel a confirmed Booking accepted\n", - "description": "The consumer has requested to cancel a confirmed `Booking`. The cancellation has been accepted and is now awaiting further processing by the provider\n" + "description": "The consumer has requested to cancel a confirmed `Booking`. The cancellation request has been accepted and is now awaiting further processing by the provider\n" } } } @@ -2224,7 +2215,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -2373,7 +2363,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -2523,7 +2512,6 @@ "carrierExportVoyageNumber": "403W", "isPartialLoadAllowed": false, "isExportDeclarationRequired": false, - "isImportLicenseRequired": false, "expectedDepartureDate": "2024-01-20", "incoTerms": "EXW", "isEquipmentSubstitutionAllowed": false, @@ -2744,6 +2732,82 @@ }, "components": { "schemas": { + "CreateBookingResponse": { + "title": "Create Booking Response", + "required": [ + "carrierBookingRequestReference" + ], + "type": "object", + "properties": { + "carrierBookingRequestReference": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference to the booking during the booking request phase.\n", + "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" + } + }, + "description": "**Only** the `carrierBookingRequestReference` is returned.\n" + }, + "CancelBookingRequest": { + "title": "Cancel Booking Request", + "type": "object", + "properties": { + "reason": { + "maxLength": 5000, + "type": "string", + "description": "An optional property where a reason for cancelling the booking or the amendment can be given.\n", + "example": "Booking cancelled due to internal problems" + } + }, + "oneOf": [ + { + "title": "Cancel Booking Request (prior to Booking Confirmation)", + "required": [ + "bookingStatus" + ], + "type": "object", + "properties": { + "bookingStatus": { + "maxLength": 50, + "type": "string", + "description": "Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider.\n\n**Condition:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLED`.\n", + "example": "CANCELLED" + } + } + }, + { + "title": "Only cancel the amendment to a Confirmed Booking", + "required": [ + "amendedBookingStatus" + ], + "type": "object", + "properties": { + "amendedBookingStatus": { + "maxLength": 50, + "type": "string", + "description": "Setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`.\n\n**Condition:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT_RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned.\n\nOnly possible value to set is `AMENDMENT_CANCELLED`.\n", + "example": "AMENDMENT_CANCELLED" + } + } + }, + { + "title": "Request to cancel a Confirmed Booking", + "required": [ + "bookingCancellationStatus" + ], + "type": "object", + "properties": { + "bookingCancellationStatus": { + "maxLength": 50, + "type": "string", + "description": "Setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon receiving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider.\n\n**Condition:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLATION_RECEIVED`.\n", + "example": "CANCELLATION_RECEIVED" + } + } + } + ] + }, "BookingNotification": { "title": "Booking Notification", "required": [ @@ -2808,11 +2872,86 @@ "example": "30675492-50ff-4e17-a7df-7a487a8ad343" }, "data": { - "$ref": "#/components/schemas/Data" + "$ref": "#/components/schemas/BookingNotificationData" } }, "description": "`CloudEvent` specific properties for the `Notification`.\n" }, + "BookingNotificationData": { + "title": "Data", + "required": [ + "bookingStatus" + ], + "type": "object", + "properties": { + "bookingStatus": { + "maxLength": 50, + "type": "string", + "description": "The status of the `Booking`. Possible values are:\n\n- `RECEIVED` (Booking request has been received)\n- `PENDING_UPDATE` (An update is required to the Booking)\n- `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING_AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", + "example": "RECEIVED" + }, + "amendedBookingStatus": { + "maxLength": 50, + "type": "string", + "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are:\n\n- `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT_CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT_DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT_CANCELLED` (Amendment discontinued by consumer)\n", + "example": "AMENDMENT_RECEIVED" + }, + "bookingCancellationStatus": { + "maxLength": 50, + "type": "string", + "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", + "example": "CANCELLATION_RECEIVED" + }, + "carrierBookingRequestReference": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", + "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" + }, + "carrierBookingReference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", + "example": "ABC709951" + }, + "feedbacks": { + "type": "array", + "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", + "items": { + "$ref": "#/components/schemas/Feedback" + } + }, + "booking": { + "$ref": "#/components/schemas/BookingFullNotification" + }, + "amendedBooking": { + "$ref": "#/components/schemas/AmendedBookingFullNotification" + } + }, + "description": "`Booking` specific properties for the `Notification`\n" + }, + "BookingFullNotification": { + "title": "Booking", + "type": "object", + "description": "This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking.\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored.\n", + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + } + ] + }, + "AmendedBookingFullNotification": { + "title": "Amended Booking", + "type": "object", + "description": "This property contains the amended booking in case:\n - an amendment is currently active\n - the subscriber is subscribing to the `Full State Transfer` of the Booking\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored.\n", + "allOf": [ + { + "$ref": "#/components/schemas/Booking" + } + ] + }, "Feedback": { "title": "Feedback", "required": [ @@ -3098,8 +3237,6 @@ "deliveryTypeAtDestination", "documentParties", "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", "receiptTypeAtOrigin", "requestedEquipments", "shipmentLocations" @@ -3241,34 +3378,21 @@ }, "isPartialLoadAllowed": { "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n\n**Note:** If this property is omitted it is considered that 'Partial Load **is** allowed' by default\n", - "example": true, - "default": true + "description": "Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off.\n\n**Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", + "example": true }, "isExportDeclarationRequired": { "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", + "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n\n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", "example": true }, "exportDeclarationReference": { "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure.\n", + "description": "Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country.\n", "example": "ABC123123" }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular\nshipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival.\n", - "example": "XYZ987987" - }, "expectedDepartureDate": { "type": "string", "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", @@ -3322,10 +3446,10 @@ "example": true }, "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" + "$ref": "#/components/schemas/InvoicePayableAt" }, "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" + "$ref": "#/components/schemas/PlaceOfBLIssue" }, "references": { "type": "array", @@ -3342,7 +3466,7 @@ } }, "documentParties": { - "$ref": "#/components/schemas/Document Parties_1" + "$ref": "#/components/schemas/DocumentPartiesReq" }, "partyContactDetails": { "type": "array", @@ -3377,8 +3501,6 @@ "deliveryTypeAtDestination", "documentParties", "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", "receiptTypeAtOrigin", "requestedEquipments", "shipmentLocations" @@ -3534,32 +3656,19 @@ }, "isPartialLoadAllowed": { "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n\n**Note:** If this property is omitted it is considered that 'Partial Load **is** allowed' by default\n", - "example": true, - "default": true + "description": "Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off.\n\n**Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", + "example": true }, "isExportDeclarationRequired": { "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", + "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n\n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", "example": true }, "exportDeclarationReference": { "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular\nshipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", + "description": "Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country.\n", "example": "ABC123123" }, "expectedDepartureDate": { @@ -3615,10 +3724,10 @@ "example": true }, "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" + "$ref": "#/components/schemas/InvoicePayableAt" }, "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" + "$ref": "#/components/schemas/PlaceOfBLIssue" }, "references": { "type": "array", @@ -3635,7 +3744,7 @@ } }, "documentParties": { - "$ref": "#/components/schemas/Document Parties_1" + "$ref": "#/components/schemas/DocumentPartiesReq" }, "partyContactDetails": { "type": "array", @@ -3662,6 +3771,38 @@ } } }, + "DocumentPartiesReq": { + "title": "Document Parties", + "required": [ + "bookingAgent" + ], + "type": "object", + "properties": { + "bookingAgent": { + "$ref": "#/components/schemas/BookingAgent" + }, + "shipper": { + "$ref": "#/components/schemas/Shipper" + }, + "consignee": { + "$ref": "#/components/schemas/Consignee" + }, + "serviceContractOwner": { + "$ref": "#/components/schemas/ServiceContractOwner" + }, + "carrierBookingOffice": { + "$ref": "#/components/schemas/CarrierBookingOffice" + }, + "other": { + "type": "array", + "description": "A list of document parties that can be optionally provided at booking stage.", + "items": { + "$ref": "#/components/schemas/OtherDocumentParty" + } + } + }, + "description": "All `Parties` with associated roles.\n" + }, "Booking": { "title": "Booking", "required": [ @@ -3671,8 +3812,6 @@ "deliveryTypeAtDestination", "documentParties", "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", "receiptTypeAtOrigin", "requestedEquipments", "shipmentLocations" @@ -3846,32 +3985,19 @@ }, "isPartialLoadAllowed": { "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n\n**Note:** If this property is omitted it is considered that 'Partial Load **is** allowed' by default\n", - "example": true, - "default": true + "description": "Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off.\n\n**Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", + "example": true }, "isExportDeclarationRequired": { "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", + "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n\n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", "example": true }, "exportDeclarationReference": { "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", + "description": "Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country.\n", "example": "ABC123123" }, "expectedDepartureDate": { @@ -3933,10 +4059,10 @@ "example": "Any reference in..." }, "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" + "$ref": "#/components/schemas/InvoicePayableAt" }, "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" + "$ref": "#/components/schemas/PlaceOfBLIssue" }, "references": { "type": "array", @@ -3953,7 +4079,7 @@ } }, "documentParties": { - "$ref": "#/components/schemas/Document Parties" + "$ref": "#/components/schemas/DocumentParties" }, "partyContactDetails": { "type": "array", @@ -4033,36 +4159,133 @@ } } }, - "ActiveReeferSettings": { - "title": "Active Reefer Settings", + "InvoicePayableAt": { + "title": "Invoice Payable At", "required": [ - "temperatureSetpoint", - "temperatureUnit" + "UNLocationCode" ], "type": "object", "properties": { - "temperatureSetpoint": { - "type": "number", - "description": "Target value of the temperature for the Reefer based on the cargo requirement.\n", - "format": "float", - "example": -15 - }, - "temperatureUnit": { + "UNLocationCode": { + "maxLength": 5, + "minLength": 5, + "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "type": "string", - "description": "The unit for temperature in Celsius or Fahrenheit\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", - "example": "CEL", - "enum": [ - "CEL", - "FAH" - ] - }, - "o2Setpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere CO2 target value\n", - "format": "float", - "example": 25 + "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", + "example": "NLAMS" + } + }, + "description": "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location must be provided as a `UN Location Code`\n" + }, + "PlaceOfBLIssue": { + "title": "Place of B/L Issue", + "type": "object", + "properties": { + "locationName": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The name of the location.", + "example": "Port of Amsterdam" + } + }, + "description": "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", + "oneOf": [ + { + "title": "UN Location Code", + "required": [ + "UNLocationCode" + ], + "type": "object", + "properties": { + "UNLocationCode": { + "maxLength": 5, + "minLength": 5, + "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", + "type": "string", + "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", + "example": "NLAMS" + } + } + }, + { + "title": "Country Code", + "required": [ + "countryCode" + ], + "type": "object", + "properties": { + "countryCode": { + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z]{2}$", + "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)\n", + "example": "DK" + } + } + } + ] + }, + "DocumentParties": { + "title": "Document Parties", + "type": "object", + "properties": { + "bookingAgent": { + "$ref": "#/components/schemas/BookingAgent" + }, + "shipper": { + "$ref": "#/components/schemas/Shipper" + }, + "consignee": { + "$ref": "#/components/schemas/Consignee" + }, + "serviceContractOwner": { + "$ref": "#/components/schemas/ServiceContractOwner" + }, + "carrierBookingOffice": { + "$ref": "#/components/schemas/CarrierBookingOffice" + }, + "other": { + "type": "array", + "description": "A list of document parties that can be optionally provided at booking stage.", + "items": { + "$ref": "#/components/schemas/OtherDocumentParty" + } + } + }, + "description": "All `Parties` with associated roles.\n" + }, + "ActiveReeferSettings": { + "title": "Active Reefer Settings", + "required": [ + "temperatureSetpoint", + "temperatureUnit" + ], + "type": "object", + "properties": { + "temperatureSetpoint": { + "type": "number", + "description": "Target value of the temperature for the Reefer based on the cargo requirement.\n", + "format": "float", + "example": -15 + }, + "temperatureUnit": { + "type": "string", + "description": "The unit for temperature in Celsius or Fahrenheit\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", + "example": "CEL", + "enum": [ + "CEL", + "FAH" + ] + }, + "o2Setpoint": { + "maximum": 100, + "minimum": 0, + "type": "number", + "description": "The percentage of the controlled atmosphere CO2 target value\n", + "format": "float", + "example": 25 }, "co2Setpoint": { "maximum": 100, @@ -4557,7 +4780,7 @@ "maxLength": 30, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "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).\n", + "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).\n", "example": "+45 70262970" } }, @@ -4593,7 +4816,7 @@ "codeListProvider": { "maxLength": 100, "type": "string", - "description": "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", + "description": "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (Enigio trace:original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `ZZZ` (Mutually defined)\n", "example": "W3C" }, "partyCode": { @@ -4605,7 +4828,7 @@ "codeListName": { "maxLength": 100, "type": "string", - "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", + "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n", "example": "DID" } } @@ -4814,13 +5037,13 @@ }, "containerPositionings": { "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", + "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", "items": { "$ref": "#/components/schemas/ContainerPositioning" } }, "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" + "$ref": "#/components/schemas/EmptyContainerPickup" }, "equipmentReferences": { "type": "array", @@ -4834,7 +5057,10 @@ } }, "tareWeight": { - "$ref": "#/components/schemas/Tare Weight" + "$ref": "#/components/schemas/TareWeight" + }, + "cargoGrossWeight": { + "$ref": "#/components/schemas/CargoGrossWeightReq" }, "isShipperOwned": { "type": "boolean", @@ -4898,13 +5124,13 @@ }, "containerPositionings": { "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", + "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", "items": { "$ref": "#/components/schemas/ContainerPositioning" } }, "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" + "$ref": "#/components/schemas/EmptyContainerPickup" }, "equipmentReferences": { "type": "array", @@ -4918,7 +5144,10 @@ } }, "tareWeight": { - "$ref": "#/components/schemas/Tare Weight_1" + "$ref": "#/components/schemas/TareWeight" + }, + "cargoGrossWeight": { + "$ref": "#/components/schemas/CargoGrossWeightReq" }, "isShipperOwned": { "type": "boolean", @@ -4957,6 +5186,34 @@ }, "description": "If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting).\n" }, + "TareWeight": { + "title": "Tare Weight", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The weight of an empty container (gross container weight).\n", + "format": "float", + "example": 4000 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "The weight of an empty container (gross container weight).\n\n**Condition:** In case of Shipper Owned Containers (`SOC`) this is a required property\n" + }, "ContainerPositioning": { "title": "Container Positioning", "required": [ @@ -4985,7 +5242,7 @@ "properties": { "estimatedDateTime": { "type": "string", - "description": "The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n", + "description": "The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n", "format": "date-time", "example": "2024-09-04T09:41:00Z" }, @@ -5024,7 +5281,7 @@ "$ref": "#/components/schemas/GeoCoordinate" } }, - "description": "An object to capture the `Container Positioning Location`.\n\nThe location of the customer facility where the container(s) will be loaded.\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n\nThe location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.\n\n**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.\n", + "description": "An object to capture the `Container Positioning Location`.\n\nThe location of the customer facility where the container(s) will be loaded.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`).\n\nThe location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`.\n\n**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.\n", "example": { "locationName": "Shanghai Shengdong International Container Terminal", "UNLocationCode": "CNSGH", @@ -5076,7 +5333,6 @@ "CommodityShipper": { "title": "Commodity (Shipper)", "required": [ - "cargoGrossWeight", "commodityType" ], "type": "object", @@ -5108,28 +5364,22 @@ } }, "cargoGrossWeight": { - "$ref": "#/components/schemas/Cargo Gross Weight" + "$ref": "#/components/schemas/CargoGrossWeight" }, "cargoGrossVolume": { - "$ref": "#/components/schemas/Cargo Gross Volume" + "$ref": "#/components/schemas/CargoGrossVolume" }, "cargoNetWeight": { - "$ref": "#/components/schemas/Cargo Net Weight" + "$ref": "#/components/schemas/CargoNetWeight" }, "cargoNetVolume": { - "$ref": "#/components/schemas/Cargo Net Volume" + "$ref": "#/components/schemas/CargoNetVolume" }, - "exportLicenseIssueDate": { - "type": "string", - "description": "Issue date of the export license applicable to the booking. Mandatory to provide in booking request for specific commodities\n", - "format": "date", - "example": "2021-05-14" + "exportLicense": { + "$ref": "#/components/schemas/ExportLicense" }, - "exportLicenseExpiryDate": { - "type": "string", - "description": "Expiry date of the export license applicable to the booking.\n\nMandatory to provide in booking request for specific commodities.\n", - "format": "date", - "example": "2021-05-21" + "importLicense": { + "$ref": "#/components/schemas/ImportLicense" }, "outerPackaging": { "$ref": "#/components/schemas/OuterPackaging" @@ -5154,16 +5404,15 @@ "Commodity": { "title": "Commodity", "required": [ - "cargoGrossWeight", "commodityType" ], "type": "object", "properties": { - "commoditySubreference": { + "commoditySubReference": { "maxLength": 100, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking.\n\n**Conditional:** Mandatory to provide for `CONFIRMED` bookings\n", + "description": "A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking.\n\n**Condition:** Mandatory to provide for `CONFIRMED` bookings\n", "example": "COM-001" }, "commodityType": { @@ -5193,28 +5442,22 @@ } }, "cargoGrossWeight": { - "$ref": "#/components/schemas/Cargo Gross Weight" + "$ref": "#/components/schemas/CargoGrossWeight" }, "cargoGrossVolume": { - "$ref": "#/components/schemas/Cargo Gross Volume" + "$ref": "#/components/schemas/CargoGrossVolume" }, "cargoNetWeight": { - "$ref": "#/components/schemas/Cargo Net Weight" + "$ref": "#/components/schemas/CargoNetWeight" }, "cargoNetVolume": { - "$ref": "#/components/schemas/Cargo Net Volume" + "$ref": "#/components/schemas/CargoNetVolume" }, - "exportLicenseIssueDate": { - "type": "string", - "description": "Issue date of the export license applicable to the booking. Mandatory to provide in booking request for specific commodities\n", - "format": "date", - "example": "2021-05-14" + "exportLicense": { + "$ref": "#/components/schemas/ExportLicense" }, - "exportLicenseExpiryDate": { - "type": "string", - "description": "Expiry date of the export license applicable to the booking.\n\nMandatory to provide in booking request for specific commodities.\n", - "format": "date", - "example": "2021-05-21" + "importLicense": { + "$ref": "#/components/schemas/ImportLicense" }, "outerPackaging": { "$ref": "#/components/schemas/OuterPackaging" @@ -5236,146 +5479,347 @@ }, "description": "Type of goods, defined by its commodity type\n" }, - "NationalCommodityCode": { - "title": "National Commodity Code", - "required": [ - "countryCode", - "type", - "values" - ], + "ExportLicense": { + "title": "Export License", "type": "object", "properties": { - "type": { - "maxLength": 10, + "isRequired": { + "type": "boolean", + "description": "Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", + "example": true + }, + "reference": { + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", - "example": "NCM" + "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.\n", + "example": "EMC007123" }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", + "issueDate": { "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)\n", - "example": "BR" + "description": "Issue date of the `Export License` applicable to the booking.\n", + "format": "date", + "example": "2024-09-14" }, - "values": { - "minItems": 1, - "type": "array", - "description": "A list of `national commodity codes` values.\n", - "example": [ - "1515", - "2106", - "2507", - "2512" - ], - "items": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `National Commodity Code`\n", - "example": "1515" - } + "expiryDate": { + "type": "string", + "description": "Expiry date of the `Export License` applicable to the booking.\n", + "format": "date", + "example": "2024-09-21" } }, - "description": "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n" + "description": "`Export License` required for this commodity\n" }, - "OuterPackaging": { - "title": "Outer Packaging", + "ImportLicense": { + "title": "Import License", "type": "object", "properties": { - "packageCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z0-9]{2}$", - "type": "string", - "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example": "5H" + "isRequired": { + "type": "boolean", + "description": "Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n", + "example": true }, - "imoPackagingCode": { - "maxLength": 5, - "minLength": 1, - "pattern": "^[A-Z0-9]{1,5}$", + "reference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "The code of the packaging as per IMO.\n\n**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.\n", - "example": "1A2" - }, - "numberOfPackages": { - "maximum": 99999999, - "minimum": 1, - "type": "integer", - "description": "Specifies the number of outer packagings/overpacks associated with this `Commodity`.\n\n**Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide\n", - "format": "int32", - "example": 18 + "description": "Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that athorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival.\n", + "example": "EMC007123" }, - "description": { - "maxLength": 100, + "issueDate": { "type": "string", - "description": "Description of the outer packaging/overpack.\n", - "example": "Drum, steel" + "description": "Issue date of the `Import License` applicable to the booking.\n", + "format": "date", + "example": "2024-09-14" }, - "dangerousGoods": { - "type": "array", - "description": "A list of `Dangerous Goods` related to the `Commodity`\n", - "items": { - "$ref": "#/components/schemas/DangerousGoods" - } + "expiryDate": { + "type": "string", + "description": "Expiry date of the `Import License` applicable to the booking.\n", + "format": "date", + "example": "2024-09-21" } }, - "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.\n\n**Condition:** Mandatory for DG (Dangerous Goods) cargo.\n" + "description": "`Import License` required for this commodity\n" }, - "DangerousGoods": { - "title": "Dangerous Goods", + "CargoGrossWeightReq": { + "title": "Cargo Gross Weight (Requested Equipment)", "required": [ - "emergencyContactDetails", - "grossWeight", - "imoClass", - "isCompetentAuthorityApprovalRequired", - "isEmptyUncleanedResidue", - "isExceptedQuantity", - "isHot", - "isLimitedQuantity", - "isMarinePollutant", - "isReportableQuantity", - "isSalvagePackings", - "isWaste", - "properShippingName" + "unit", + "value" ], "type": "object", "properties": { - "codedVariantList": { - "maxLength": 4, - "minLength": 4, - "pattern": "^[0-3][0-9A-Z]{3}$", - "type": "string", - "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", - "example": "2200" - }, - "properShippingName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "Chromium Trioxide, anhydrous" - }, - "technicalName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "xylene and benzene" - }, - "imoClass": { - "maxLength": 4, - "type": "string", - "description": "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n", - "example": "1.4S" + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", + "format": "float", + "example": 36000 }, - "subsidiaryRisk1": { - "maxLength": 3, - "minLength": 1, - "pattern": "^[0-9](\\.[0-9])?$", + "unit": { "type": "string", - "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", + "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n\n**Condition:** Mandatory if not provided on `Commodity` level\n" + }, + "CargoGrossWeight": { + "title": "Cargo Gross Weight", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", + "format": "float", + "example": 36000 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n\n**Condition:** Mandatory if not provided on `Requested Equipment` level.\n" + }, + "CargoGrossVolume": { + "title": "Cargo Gross Volume", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The estimated grand total volume of the cargo.\n", + "format": "float", + "example": 360 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", + "example": "MTQ", + "enum": [ + "MTQ", + "FTQ" + ] + } + }, + "description": "The estimated grand total volume of the cargo.\n" + }, + "CargoNetWeight": { + "title": "Cargo Net Weight", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", + "format": "float", + "example": 36000 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n" + }, + "CargoNetVolume": { + "title": "Cargo Net Volume", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The estimated net total volume of the cargo.\n", + "format": "float", + "example": 360 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", + "example": "MTQ", + "enum": [ + "MTQ", + "FTQ" + ] + } + }, + "description": "The estimated net total volume of the cargo.\n" + }, + "NationalCommodityCode": { + "title": "National Commodity Code", + "required": [ + "type", + "values" + ], + "type": "object", + "properties": { + "type": { + "maxLength": 10, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", + "example": "NCM" + }, + "countryCode": { + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z]{2}$", + "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)\n", + "example": "BR" + }, + "values": { + "minItems": 1, + "type": "array", + "description": "A list of `national commodity codes` values.\n", + "example": [ + "1515", + "2106", + "2507", + "2512" + ], + "items": { + "maxLength": 10, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The value of the `National Commodity Code`\n", + "example": "1515" + } + } + }, + "description": "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n" + }, + "OuterPackaging": { + "title": "Outer Packaging", + "type": "object", + "properties": { + "packageCode": { + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z0-9]{2}$", + "type": "string", + "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", + "example": "5H" + }, + "imoPackagingCode": { + "maxLength": 5, + "minLength": 1, + "pattern": "^[A-Z0-9]{1,5}$", + "type": "string", + "description": "The code of the packaging as per IMO.\n\n**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.\n", + "example": "1A2" + }, + "numberOfPackages": { + "maximum": 99999999, + "minimum": 1, + "type": "integer", + "description": "Specifies the number of outer packagings/overpacks associated with this `Commodity`.\n\n**Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide\n", + "format": "int32", + "example": 18 + }, + "description": { + "maxLength": 100, + "type": "string", + "description": "Description of the outer packaging/overpack.\n", + "example": "Drum, steel" + }, + "dangerousGoods": { + "type": "array", + "description": "A list of `Dangerous Goods` related to the `Commodity`\n", + "items": { + "$ref": "#/components/schemas/DangerousGoods" + } + } + }, + "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.\n\n**Condition:** Mandatory for DG (Dangerous Goods) cargo.\n" + }, + "DangerousGoods": { + "title": "Dangerous Goods", + "required": [ + "emergencyContactDetails", + "grossWeight", + "imoClass", + "isCompetentAuthorityApprovalRequired", + "isEmptyUncleanedResidue", + "isExceptedQuantity", + "isHot", + "isLimitedQuantity", + "isMarinePollutant", + "isReportableQuantity", + "isSalvagePackings", + "isWaste", + "properShippingName" + ], + "type": "object", + "properties": { + "codedVariantList": { + "maxLength": 4, + "minLength": 4, + "pattern": "^[0-3][0-9A-Z]{3}$", + "type": "string", + "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", + "example": "2200" + }, + "properShippingName": { + "maxLength": 250, + "type": "string", + "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.\n", + "example": "Chromium Trioxide, anhydrous" + }, + "technicalName": { + "maxLength": 250, + "type": "string", + "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.\n", + "example": "xylene and benzene" + }, + "imoClass": { + "maxLength": 4, + "type": "string", + "description": "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n", + "example": "1.4S" + }, + "subsidiaryRisk1": { + "maxLength": 3, + "minLength": 1, + "pattern": "^[0-9](\\.[0-9])?$", + "type": "string", + "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", "example": "1.2" }, "subsidiaryRisk2": { @@ -5492,16 +5936,16 @@ "example": "A" }, "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" + "$ref": "#/components/schemas/GrossWeight" }, "netWeight": { - "$ref": "#/components/schemas/Net Weight" + "$ref": "#/components/schemas/NetWeight" }, "netExplosiveContent": { - "$ref": "#/components/schemas/Net Explosive Content" + "$ref": "#/components/schemas/NetExplosiveContent" }, "netVolume": { - "$ref": "#/components/schemas/Net Volume" + "$ref": "#/components/schemas/NetVolume" }, "limits": { "$ref": "#/components/schemas/Limits" @@ -5519,16 +5963,16 @@ "example": "To be handled with extreme care" } }, - "description": "Specification for `Dangerous Goods`. It is mandatory to either provide the `unNumber` or the `naNumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", + "description": "Specification for `Dangerous Goods`. It is mandatory to either provide the `UNNumber` or the `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", "oneOf": [ { "title": "UN Number", "required": [ - "unNumber" + "UNNumber" ], "type": "object", "properties": { - "unNumber": { + "UNNumber": { "maxLength": 4, "minLength": 4, "pattern": "^\\d{4}$", @@ -5541,11 +5985,11 @@ { "title": "NA Number", "required": [ - "naNumber" + "NANumber" ], "type": "object", "properties": { - "naNumber": { + "NANumber": { "maxLength": 4, "minLength": 4, "pattern": "^\\d{4}$", @@ -5557,7 +6001,122 @@ } ] }, - "InnerPackaging": { + "GrossWeight": { + "title": "Gross Weight", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "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.\n", + "format": "float", + "example": 12000.3 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in imperial or metric terms\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "Total weight of the goods carried, including packaging.\n" + }, + "NetWeight": { + "title": "Net Weight", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "Total weight of the goods carried, excluding packaging.\n", + "format": "float", + "example": 2.4 + }, + "unit": { + "type": "string", + "description": "Unit of measure used to describe the `netWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR" + ] + } + }, + "description": "Total weight of the goods carried, excluding packaging.\n" + }, + "NetExplosiveContent": { + "title": "Net Explosive Content", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", + "format": "float", + "example": 2.4 + }, + "unit": { + "type": "string", + "description": "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", + "example": "KGM", + "enum": [ + "KGM", + "LBR", + "GRM", + "ONZ" + ] + } + }, + "description": "The total weight of the explosive substances, without the packaging’s, casings, etc.\n" + }, + "NetVolume": { + "title": "Net Volume", + "required": [ + "unit", + "value" + ], + "type": "object", + "properties": { + "value": { + "minimum": 0, + "exclusiveMinimum": true, + "type": "number", + "description": "The volume of the referenced dangerous goods.\n", + "format": "float", + "example": 2.4 + }, + "unit": { + "type": "string", + "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", + "example": "MTQ", + "enum": [ + "MTQ", + "FTQ", + "LTR" + ] + } + }, + "description": "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n" + }, + "InnerPackaging": { "title": "Inner Packaging", "required": [ "description", @@ -5611,7 +6170,7 @@ "maxLength": 30, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "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).\n", + "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).\n", "example": "+45 70262970" }, "referenceNumber": { @@ -5696,17 +6255,33 @@ }, "containerPositionings": { "type": "array", - "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated).\n\n**Conditional:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", + "description": "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated).\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n", "items": { "$ref": "#/components/schemas/ContainerPositioningEstimated" } }, "emptyContainerPickup": { - "$ref": "#/components/schemas/Empty Container Pickup" + "$ref": "#/components/schemas/EmptyContainerPickup" } }, "description": "The confirmed equipments for the booking\n" }, + "EmptyContainerPickup": { + "title": "Empty Container Pickup", + "type": "object", + "properties": { + "dateTime": { + "type": "string", + "description": "The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided.\n", + "format": "date-time", + "example": "2024-09-04T09:41:00Z" + }, + "depotReleaseLocation": { + "$ref": "#/components/schemas/EmptyContainerDepotReleaseLocation" + } + }, + "description": "The date and time and location for the empty container pick-up.\n\n**Condition:** Only applicable to merchant haulage service at origin (`Receipt type at origin = 'CY'`).\n" + }, "Transport": { "title": "Transport", "required": [ @@ -5920,7 +6495,6 @@ "AdvanceManifestFiling": { "title": "Advance Manifest Filing", "required": [ - "countryCode", "manifestTypeCode" ], "type": "object", @@ -6107,1307 +6681,6 @@ } }, "description": "Vessels related to this booking request.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and `carrierServiceCode` or `carrierServiceName` are blank.\n" - }, - "inline_response_202": { - "required": [ - "carrierBookingRequestReference" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - } - }, - "description": "**Only** the `carrierBookingRequestReference` is returned.\n" - }, - "bookings_bookingReference_body": { - "type": "object", - "properties": { - "reason": { - "maxLength": 5000, - "type": "string", - "description": "An optional property where a reason for cancelling the booking or the amendment can be given.\n", - "example": "Booking cancelled due to internal problems" - } - }, - "oneOf": [ - { - "title": "Cancel Booking Request (prior to Booking Confirmation)", - "required": [ - "bookingStatus" - ], - "type": "object", - "properties": { - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider.\n\n**Conditional:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLED`.\n", - "example": "CANCELLED" - } - } - }, - { - "title": "Only cancel the amendment to a Confirmed Booking", - "required": [ - "amendedBookingStatus" - ], - "type": "object", - "properties": { - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`.\n\n**Conditional:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT_RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned.\n\nOnly possible value to set is `AMENDMENT_CANCELLED`.\n", - "example": "AMENDMENT_CANCELLED" - } - } - }, - { - "title": "Request to cancel a Confirmed Booking", - "required": [ - "bookingCancellationStatus" - ], - "type": "object", - "properties": { - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "Setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon receiving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider.\n\n**Conditional:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned.\n\nOnly possible value to set is `CANCELLATION_RECEIVED`.\n", - "example": "CANCELLATION_RECEIVED" - } - } - } - ] - }, - "Invoice Payable At": { - "title": "Invoice Payable At", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "description": "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location must be provided as a `UN Location Code`\n" - }, - "Place of BL Issue": { - "title": "Place of B/L Issue", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - } - }, - "description": "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", - "oneOf": [ - { - "title": "UN Location Code", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - } - }, - { - "title": "Country Code", - "required": [ - "countryCode" - ], - "type": "object", - "properties": { - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "DK" - } - } - } - ] - }, - "Document Parties": { - "title": "Document Parties", - "type": "object", - "properties": { - "bookingAgent": { - "$ref": "#/components/schemas/BookingAgent" - }, - "shipper": { - "$ref": "#/components/schemas/Shipper" - }, - "consignee": { - "$ref": "#/components/schemas/Consignee" - }, - "serviceContractOwner": { - "$ref": "#/components/schemas/ServiceContractOwner" - }, - "carrierBookingOffice": { - "$ref": "#/components/schemas/CarrierBookingOffice" - }, - "other": { - "type": "array", - "description": "A list of document parties that can be optionally provided at booking stage.", - "items": { - "$ref": "#/components/schemas/OtherDocumentParty" - } - } - }, - "description": "All `Parties` with associated roles.\n" - }, - "Booking_1": { - "title": "Booking", - "required": [ - "bookingStatus", - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING_UPDATE` (An update is required to the Booking)\n- `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING_AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT_CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT_DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT_CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT_RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION_RECEIVED" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/OriginChargesPaymentTerm" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/DestinationChargesPaymentTerm" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "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).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the `carrierCode`. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n\n**Note:** If this property is omitted it is considered that 'Partial Load **is** allowed' by default\n", - "example": true, - "default": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/).\n", - "example": "FCA" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipment" - } - }, - "confirmedEquipments": { - "type": "array", - "description": "A list of `Confirmed Equipments`\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ConfirmedEquipment" - } - }, - "transportPlan": { - "type": "array", - "description": "A list of `Transport` objects (legs) describing the entire transport plan including transshipments.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/Transport" - } - }, - "shipmentCutOffTimes": { - "type": "array", - "description": "A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ShipmentCutOffTime" - } - }, - "advanceManifestFilings": { - "type": "array", - "description": "A list of `Advance Manifest Filings` provided by the carrier\n", - "items": { - "$ref": "#/components/schemas/AdvanceManifestFiling" - } - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "carrierClauses": { - "type": "array", - "description": "Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking.\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored.\n" - }, - "Amended Booking": { - "title": "Amended Booking", - "required": [ - "bookingStatus", - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "deliveryTypeAtDestination", - "documentParties", - "isEquipmentSubstitutionAllowed", - "isExportDeclarationRequired", - "isImportLicenseRequired", - "receiptTypeAtOrigin", - "requestedEquipments", - "shipmentLocations" - ], - "type": "object", - "properties": { - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided\n", - "example": "ABC709951" - }, - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n- `RECEIVED` (Booking request has been received)\n- `PENDING_UPDATE` (An update is required to the Booking)\n- `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING_AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are:\n- `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT_CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT_DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT_CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT_RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION_RECEIVED" - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n\n**Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided.\n", - "example": "HHL51800000" - }, - "freightPaymentTermCode": { - "type": "string", - "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/OriginChargesPaymentTerm" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/DestinationChargesPaymentTerm" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n\n**Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided.\n", - "example": "HHL1401" - }, - "vessel": { - "$ref": "#/components/schemas/Vessel" - }, - "carrierServiceName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of a service as specified by the carrier.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank\n", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific code of the service for which the schedule details are published.\n\n**Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank\n", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "minLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.\n", - "example": "SR12345A" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The carrier specific identifier of the export Voyage.\n\n**Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "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).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the `carrierCode`. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "isPartialLoadAllowed": { - "type": "boolean", - "description": "Indication whether the shipper agrees to load part of the shipment in case where not all of the cargo is delivered within cut-off.\n\n**Note:** If this property is omitted it is considered that 'Partial Load **is** allowed' by default\n", - "example": true, - "default": true - }, - "isExportDeclarationRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "exportDeclarationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A government document permitting designated goods to be shipped out of the country. Reference number assigned by an issuing authority to an Export License. The export license must be valid at time of departure. Required if Export declaration required is `True`.\n", - "example": "ABC123123" - }, - "isImportLicenseRequired": { - "type": "boolean", - "description": "Information provided by the shipper whether an import permit or license is required for this particular shipment/commodity/destination.\n", - "example": true - }, - "importLicenseReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A certificate, issued by countries exercising import controls, that permits importation of the articles stated in the license. Reference number assigned by an issuing authority to an Import License. The import license number must be valid at time of arrival. Required if import license required is ‘True’.\n", - "example": "ABC123123" - }, - "expectedDepartureDate": { - "type": "string", - "description": "The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryStartDate": { - "type": "string", - "description": "The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-17" - }, - "expectedArrivalAtPlaceOfDeliveryEndDate": { - "type": "string", - "description": "The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`.\n\n**Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided.\n", - "format": "date", - "example": "2021-05-19" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the `Transport Document`. Possible values are:\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns.\n", - "example": "reserved-HHL123" - }, - "bookingChannelReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other.\n\n**Condition:** a booking channel is being used\n", - "example": "Inttra reference" - }, - "incoTerms": { - "maxLength": 3, - "type": "string", - "description": "Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/).\n", - "example": "FCA" - }, - "isEquipmentSubstitutionAllowed": { - "type": "boolean", - "description": "Indicates if an alternate equipment type can be provided by the carrier.\n", - "example": true - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "placeOfBLIssue": { - "$ref": "#/components/schemas/Place of BL Issue" - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "partyContactDetails": { - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "shipmentLocations": { - "minItems": 1, - "type": "array", - "description": "A list of `Shipment Locations`\n", - "items": { - "$ref": "#/components/schemas/ShipmentLocation" - } - }, - "requestedEquipments": { - "minItems": 1, - "type": "array", - "description": "List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit.\n\n**Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined.\n", - "items": { - "$ref": "#/components/schemas/RequestedEquipment" - } - }, - "confirmedEquipments": { - "type": "array", - "description": "A list of `Confirmed Equipments`\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ConfirmedEquipment" - } - }, - "transportPlan": { - "type": "array", - "description": "A list of `Transport` objects (legs) describing the entire transport plan including transshipments.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/Transport" - } - }, - "shipmentCutOffTimes": { - "type": "array", - "description": "A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking.\n\n**Condition:** Mandatory and non-empty for a `CONFIRMED` Booking\n", - "items": { - "$ref": "#/components/schemas/ShipmentCutOffTime" - } - }, - "advanceManifestFilings": { - "type": "array", - "description": "A list of `Advance Manifest Filings` provided by the carrier\n", - "items": { - "$ref": "#/components/schemas/AdvanceManifestFiling" - } - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "carrierClauses": { - "type": "array", - "description": "Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - } - }, - "description": "This property contains the amended booking in case:\n - an amendment is currently active\n - the subscriber is subscribing to the `Full State Transfer` of the Booking\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored.\n" - }, - "Data": { - "title": "Data", - "required": [ - "bookingStatus" - ], - "type": "object", - "properties": { - "bookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Booking`. Possible values are:\n\n- `RECEIVED` (Booking request has been received)\n- `PENDING_UPDATE` (An update is required to the Booking)\n- `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed)\n- `CONFIRMED` (Booking has been Confirmed)\n- `PENDING_AMENDMENT` (An amendment is required to the Booking)\n- `REJECTED` (Booking discontinued by carrier before it has been Confirmed)\n- `DECLINED` (Booking discontinued by carrier after it has been Confirmed)\n- `CANCELLED` (Booking discontinued by consumer)\n- `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery)\n", - "example": "RECEIVED" - }, - "amendedBookingStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are:\n\n- `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed)\n- `AMENDMENT_CONFIRMED` (Amendment is confirmed)\n- `AMENDMENT_DECLINED` (Amendment discontinued by provider)\n- `AMENDMENT_CANCELLED` (Amendment discontinued by consumer)\n", - "example": "AMENDMENT_RECEIVED" - }, - "bookingCancellationStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are:\n- `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed)\n- `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider)\n- `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider)\n", - "example": "CANCELLATION_RECEIVED" - }, - "carrierBookingRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference to the booking during the booking request phase.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", - "example": "24595eb0-5cfc-4381-9c3a-cedc1975e9aa" - }, - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment.\n\n**Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide\n", - "example": "ABC709951" - }, - "feedbacks": { - "type": "array", - "description": "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items": { - "$ref": "#/components/schemas/Feedback" - } - }, - "booking": { - "$ref": "#/components/schemas/Booking_1" - }, - "amendedBooking": { - "$ref": "#/components/schemas/Amended Booking" - } - }, - "description": "`Booking` specific properties for the `Notification`\n" - }, - "Document Parties_1": { - "title": "Document Parties", - "required": [ - "bookingAgent" - ], - "type": "object", - "properties": { - "bookingAgent": { - "$ref": "#/components/schemas/BookingAgent" - }, - "shipper": { - "$ref": "#/components/schemas/Shipper" - }, - "consignee": { - "$ref": "#/components/schemas/Consignee" - }, - "serviceContractOwner": { - "$ref": "#/components/schemas/ServiceContractOwner" - }, - "carrierBookingOffice": { - "$ref": "#/components/schemas/CarrierBookingOffice" - }, - "other": { - "type": "array", - "description": "A list of document parties that can be optionally provided at booking stage.", - "items": { - "$ref": "#/components/schemas/OtherDocumentParty" - } - } - }, - "description": "All `Parties` with associated roles.\n" - }, - "Empty Container Pickup": { - "title": "Empty Container Pickup", - "type": "object", - "properties": { - "dateTime": { - "type": "string", - "description": "The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided.\n", - "format": "date-time", - "example": "2024-09-04T09:41:00Z" - }, - "depotReleaseLocation": { - "$ref": "#/components/schemas/EmptyContainerDepotReleaseLocation" - } - }, - "description": "The date and time and location for the empty container pick-up.\n\n**Condition:** Only applicable to merchant haulage service at origin (`Receipt type at origin = 'CY'`).\n" - }, - "Tare Weight": { - "title": "Tare Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4000 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The weight of an empty container (gross container weight).\n\n**Conditional:** In case of Shipper Owned Containers (`SOC`) this is a required property\n" - }, - "Tare Weight_1": { - "title": "Tare Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The weight of an empty container (gross container weight).\n\n**Conditional:** In case of Shipper Owned Containers (`SOC`) this is a required property\n" - }, - "Cargo Gross Weight": { - "title": "Cargo Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", - "format": "float", - "example": 36000 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n" - }, - "Cargo Gross Volume": { - "title": "Cargo Gross Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated grand total volume of the cargo.\n", - "format": "float", - "example": 360 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - } - }, - "description": "The estimated grand total volume of the cargo.\n" - }, - "Cargo Net Weight": { - "title": "Cargo Net Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n", - "format": "float", - "example": 36000 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper.\n" - }, - "Cargo Net Volume": { - "title": "Cargo Net Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The estimated net total volume of the cargo.\n", - "format": "float", - "example": 360 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - } - }, - "description": "The estimated net total volume of the cargo.\n" - }, - "Gross Weight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "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.\n", - "format": "float", - "example": 12000.3 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, including packaging.\n" - }, - "Net Weight": { - "title": "Net Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, excluding packaging.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netWeight`. Possible values are\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, excluding packaging.\n" - }, - "Net Explosive Content": { - "title": "Net Explosive Content", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The total weight of the explosive substances, without the packaging's, casings, etc.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR", - "GRM", - "ONZ" - ] - } - }, - "description": "The total weight of the explosive substances, without the packaging's, casings, etc.\n" - }, - "Net Volume": { - "title": "Net Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The volume of the referenced dangerous goods.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ", - "LTR" - ] - } - }, - "description": "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n" } }, "parameters": { @@ -7463,4 +6736,4 @@ } } } -} +} \ No newline at end of file diff --git a/core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.yaml b/core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.yaml new file mode 100644 index 00000000..52365564 --- /dev/null +++ b/core/src/test/resources/schemas/dcsaorg-DCSA_BKG-2.0.0-resolved.yaml @@ -0,0 +1,6376 @@ +openapi: 3.0.3 +info: + title: DCSA Booking API + description: | +

DCSA OpenAPI specification for the Booking process

+ + This API is intended as an API between a carrier and anyone creating a `Booking`. The process includes: + + - Booking request + - Booking update + - Booking confirmation + - Booking amendment + - Booking cancellation + - Booking rejection + + For explanation of specific values or objects please refer to the [Information Model](https://developer.dcsa.org/documentation/information_models). This API specification does not define the allowable updates and their timing in accordance with the established business rules. **All use cases mentioned in this API specification refer to use cases defined in [DCSA Interface Standard for the Booking process 2.0](https://dcsa.org/standards/booking/documentation-booking-2)**. + + All other documents related to the Booking publication can be found [here](https://dcsa.org/standards/booking-process/) + + ### Booking (Implemented by provider) + + It is possible to use the Booking API as a standalone API. In that case poll on the following endPoints: + + GET /v2/bookings/{bookingReference} + + in order to poll information about status changes. + + **Note:** All `/v2/bookings` endPoints must be implemented by the provider. + + ### Notifications (Implemented by consumer) + It is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [Booking Notification endPoint](#/BookingNotification). + + POST /v2/booking-notifications + + The endPoints support both a **Lightweight Notification** and a **Full State Transfer**. How much data is sent via this Notification endPoint depends on what kind of Notification is being subscribed to. + + Signing up for notifications is defined outside the scope of this API specification. + + **Note:** This endPoint is to be implemented by the consumers of the `Booking API` in order to receive push events. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design) + + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/bkg/v2#v200). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + contact: + name: Digital Container Shipping Association (DCSA) + url: https://dcsa.org + email: info@dcsa.org + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + version: 2.0.0 +servers: +- url: https://virtserver.swaggerhub.com/dcsaorg/DCSA_BKG/2.0.0 + description: SwaggerHub API Auto Mocking +tags: +- name: Booking + description: Booking endPoints to be implemented by **providers** of the Booking API +- name: Notifications + description: Notifications to be implemented by the **consumers** of the Booking API +paths: + /v2/bookings: + post: + tags: + - Booking + summary: | + Creates a new Booking + description: "Creates a new booking request. This endPoint corresponds with **UseCase 1 - Submit booking request**.\n\n## Precondition\nThe consumer has information for a `Booking Request`\n\n## Postcondition\nThe provider has received the `Booking Request`. \n\nThe consumer will receive a `202` (Accepted) if the request payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives a `Booking Request`:\n\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type.\n\n A `carrierBookingRequestReference` (as a reference to the `Booking Request`) is created and linked to the payload in the provider system.\n\n **For the rest of this description and in all examples the value `cbrr-123` will be used as `carrierBookingRequestReference`**\n\n3. A `202` (Accepted) response is returned with a payload containing **only** the `carrierBookingRequestReference`:\n ```\n {\n carrierBookingRequestReference: 'cbrr-123'\n }\n ```\n\nFor `POST` `Booking Request` the process ends here. The `Booking Request`:\n - is now accepted by the provider system\n - the `Booking Request` does not yet have any status and cannot be queried (no `GET` request is possible until the `Booking Request` is further processed in the provider system)\n - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `carrierBookingRequestReference`\n - awaits further processing by the provider\n\nThe provider will now start asynchronous processing. Once processed, the status `RECEIVED` of the `Booking Request` will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the\n\n GET /v2/bookings/{bookingReference}\n\nendPoint to check if the `bookingStatus` of the `Booking Request` has changed.\n\nAfter the status has changed to `RECEIVED` further processing can continue by provider and will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll the above endPoint.\n" + operationId: create-bookings + parameters: + - name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + requestBody: + description: The payload used to create a `Booking Request` + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Make a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Make a `Booking Request` with reefer requirements (1° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 1 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - "20097919" + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Make a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Make a `Booking Request` with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Environmentally hazardous substance, liquid, N.O.S (Propiconazole)" + HSCodes: + - "293499" + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: "Jerrican, steel" + dangerousGoods: + - UNNumber: "3082" + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: "9" + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + required: true + responses: + "202": + description: | + `Booking Request` has been successfully accepted by the provider. The `Booking Request` does not yet have a `bookingStatus` - it is not possible to call the `GET` endPoint until the `Booking Request` is further processed in provider system. The consumer is now awaiting provider to process the `Booking Request` asynchronously. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBookingResponse' + examples: + acceptedExample: + summary: | + Booking request accepted + description: | + A `Booking Request` has been accepted (no `bookingStatus`) and schema validated by provider + value: + carrierBookingRequestReference: cbrr-123 + "400": + description: | + In case the `Booking Request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking Request`. This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + "500": + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking Request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Bookings Requests + description: | + Calling the endPoint + + POST /v2/bookings + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/bookings + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be created per hour + /v2/bookings/{bookingReference}: + get: + tags: + - Booking + summary: | + Gets the Booking + description: | + Retrieves the `Booking Request` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the Booking is confirmed - it is **only** possible to use the `carrierBookingReference`. It is recommended to use this endPoint to `GET` data before an update is made to make sure latest version is being updated. + + The default payload when calling this endPoint is the "original" `Booking`. It is also possible to get the latest amendment to a `Booking` called the `Amended Booking`. In order to get the `Amended Booking`, it is necessary to use the query parameter `amendedContent` and set it to `true`. + + GET /v2/bookings/{bookingReference}?amendedContent=true + + The `status` of the "original" `Booking` is included in both payloads as `bookingStatus`. `amendedBookingStatus` and related content is only available after the provider has approved the `Booking` via **UseCase 5: Confirm Booking request** and until: + - the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + - the consumer submits a new amendment (**UseCase 7: Request amendment to confirmed Booking**) in which case the "new update" provided **replaces** the "old update". + - the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the "old update" is no longer accessible. + + If `amendedContent=true` is requested but no amendment has yet been provided by the consumer **or** the state of the "original" `Booking` is `PENDING_AMENDMENT`, then a `404` (Not Found) is returned. + + If the provider is requesting changes to the `Booking`, the `Feedback` object is used to inform the consumer what needs to change. + + In case no subscription (`Notification`) has been set up - it is possible to use this endPoint to poll on in order to detect if `bookingStatus` and/or `amendedBookingStatus` has changed. + + In case a previous request is being processed by the provider - a `202` (Accepted) with **no payload** can be used as a response until the processing is finished. + operationId: get-bookings + parameters: + - name: bookingReference + in: path + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + required: true + style: simple + explode: false + schema: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + example: CBR001 + - name: amendedContent + in: query + description: | + Controls whether the content of this payload is the amended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`). + + If `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found + required: false + style: form + explode: true + schema: + type: boolean + example: false + default: false + - name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + responses: + "200": + description: Request successful + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/Booking' + examples: + dryNotConfirmedExample: + summary: | + Standard dry cargo Booking (not confirmed) + description: | + Gets a `Booking Request` with standard Dry cargo which has not yet been confirmed. The `Booking` is in state `PENDING_UPDATE` and requires some changes (specified in the `feedbacks` property) + value: + carrierBookingRequestReference: cbrr-123 + bookingStatus: PENDING_UPDATE + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + feedbacks: + - severity: ERROR + code: PROPERTY_VALUE_MUST_CHANGE + message: | + Not enough available "42G1" equipment. Please change to "22G1" instead + jsonPath: $.requestedEquipment.units + property: units + dryConfirmedExample: + summary: | + Gets a confirmed Standard dry cargo Booking + description: | + Gets a `Confirmed Booking` with standard Dry cargo. In this example the `Booking` has previously received an amendment which was confirmed (`amendedBookingStatus='AMENDMENT_CONFIRMED'`) + + As part of the confirmation the `Booking` is enriched with a `transportPlan`, `shipmentCutOffTimes`, `carrierClauses` and in this example also an `advanceManifestFiling` since the `Booking` is arriving in US. + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_CONFIRMED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: 2024-01-20 + plannedArrivalDate: 2024-01-31 + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: 2024-01-17T22:30:00Z + - cutOffDateTimeCode: VCO + cutOffDateTime: 2024-01-18T22:30:00Z + - cutOffDateTimeCode: FCO + cutOffDateTime: 2024-01-19T13:30:00Z + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - "The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes." + - "Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration." + - "Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014)." + - "In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee." + "202": + description: | + The `Booking` is currently being processed by the provider. No payload is returned. A new `GET` request has to be made periodically to check if the provider has finished processing the `Booking`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + "404": + description: | + In case the consumer is requesting the `Amended Booking` by calling: + + GET /v2/bookings/{bookingReference}?amendedContent=true + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + The `Amended Booking` response is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + "409": + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + "500": + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + getError: + summary: | + GET non-existing Booking Request + description: | + Calling + + GET /v2/bookings/cbrr-123 + + results in an error as booking `cbrr-123` does not exist. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + The requested carrierBookingRequestReference does not exist + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Non existent carrierBookingRequestReference + errorCodeMessage: | + carrierBookingRequestReference `cbrr-123` does not exist + put: + tags: + - Booking + summary: | + Updates the Booking + description: "Updates the `Booking Request` with the `bookingReference`. The path can contain either a `carrierBookingRequestReference` or a `carrierBookingReference`. Once a Booking has been `CONFIRMED` the `carrierBookingReference` **MUST** always be used. This endPoint corresponds with either\n- **UseCase 3 - Submit updated Booking request**\n- **UseCase 7 - Request amendments to confirmed Booking**\n\nThis endPoint is to be used in response to\n- **UseCase 2 - Request to update Booking request**\n- **UseCase 6 - Request to amend confirmed Booking**\n\nthe endPoint can also be used in case `bookingStatus='RECEIVED'` and the consumer has an update to the `Booking Request`.\n\n## Precondition\nIn order to update a `Booking Request`, the status of the `Booking Request` needs to be in state\n- `RECEIVED` in case the consumer has updated information for the `Booking Request`\n- `PENDING_UPDATE` in case the provider has requested the consumer to update the `Booking Request` (a result of **UseCase 2 - Request to update Booking request**)\n- `UPDATE_RECEIVED` in case the consumer has additional changes to an already sent update\n- `PENDING_AMENDMENT` in case the provider has requested the consumer to amend the `Booking Request` (a result of **UseCase 6 - Request to amend confirmed Booking**)\n- `CONFIRMED` in case the consumer has an amendment to the `Booking Request`\n\n## Postcondition\nThe provider has received an update (**UseCase 3 - Submit updated Booking request**) or an amendment (**UseCase 7 - Request amendments to confirmed Booking**) to the `Booking Request`.\n\nIn case an amendment was received to the `Booking Request` (**UseCase 7 - Request to amend confirmed Booking**) - the amendment will be called `Amended Booking`. The `Amended Booking` and the \"original\" `Booking Request` will **co-exist** until a new amendment is submitted by the consumer (via **UseCase 7: Request amendments to confirmed Booking**) or until the provider requests an update (sets the `bookingStatus='PENDING_AMENDMENT'` via **UseCase 6: Request to amend confirmed Booking**). If the `amendedBookingStatus` is present it always represents the latest version of an amendment received by the provider.\n\nThe consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives an **update** (or an **amendment**) to a `Booking Request`\n1. The payload (`Booking Request`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means\n - all required properties are provided\n - all values provided have correct data type\n3. An empty response along with `202` (Accepted) is returned and the consumer now awaits further processing by the provider.\n\nFor `PUT` `Booking Request` the process ends here. The Booking Request:\n - is now accepted by the provider system\n - the status of the `Booking Request` is unchanged.\n - a `202` (Accepted) response is sent with an empty payload\n - awaits further processing by the provider\n\nThe 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:\n - `UPDATE_RECEIVED` in case this endPoint has been used to:\n - send an update to a newly created Booking (precondition: `bookingStatus='RECEIVED'`)\n - send an update to a Booking because of a request from provider via **UseCase 2 - Request to update Booking request** (precondition: `bookingStatus='PENDING_UPDATE'`)\n - send an additional update to a Booking that has already received an update (precondition: `bookingStatus='UPDATE_RECEIVED'`)\n - `bookingStatus` will stay as `PENDING_AMENDMENT` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used in response to a request from provider via **UseCase 6 - Request to amend Confirmed Booking** (precondition: `bookingStatus='PENDING_AMENDMENT'`)\n - `bookingStatus` will stay as `CONFIRMED` but `amendedBookingStatus` will change to `AMENDMENT_RECEIVED` in case this endPoint is being used to update an already confirmed Booking via **UseCase 7 - Request Amendments to Confirmed Booking** (precondition: `bookingStatus='CONFIRMED'`)\n\nOnce processed, the new state will be communicated via a [Booking Notification](#/BookingNotification). In case the consumer does not subscribe to notifications it is necessary for the consumer to poll on the \n\n GET /v2/bookings/{bookingReference}\n\nendPoint to check if the `bookingStatus` and `amendedBookingStatus` of the `Booking` has changed.\n\nIf the consumer wants to get the content of the `Amended Booking` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?amendedContent=true` queryParameter:\n\n GET /v2/bookings/{bookingReference}?amendedContent=true\n\nIt is possible to `GET` the content of the `Amended Booking` via the example above until either:\n\n- the provider requests for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the \"old update\" is no longer accessible\n- the consumer submits a new update (**UseCase 7: Request amendment to confirmed Booking**) in which case the \"new amendment\" provided **replaces** the \"old amendment\".\n- the provider re-confirms the `Booking` (**UseCase 5: Confirm booking request**) in which case the \"old update\" is no longer accessible.\n" + operationId: update-bookings + parameters: + - name: bookingReference + in: path + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + required: true + style: simple + explode: false + schema: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + example: CBR001 + - name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + requestBody: + description: | + Parameters used to update the `Booking request` + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateBooking' + examples: + dryExample: + summary: | + Standard dry cargo Booking + description: | + Updating a `Booking Request` with standard Dry cargo being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + reeferExample: + summary: | + Reefer cargo Booking (Apple Juice) + description: | + Updating a `Booking Request` with reefer requirements (2° celsius with vents and drain holes open and genset required) sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + units: 3 + isNonOperatingReefer: false + activeReeferSettings: + temperatureSetpoint: 2 + temperatureUnit: CEL + isVentilationOpen: true + isDrainholesOpen: false + isGeneratorSetRequired: true + commodities: + - commodityType: Apple juice + HSCodes: + - "20097919" + cargoGrossWeight: + value: 36000 + unit: KGM + norExample: + summary: | + Standard dry cargo Booking using a Reefer Container + description: | + Update a `Booking Request` with standard Dry cargo using a reefer container being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 45R1 + isNonOperatingReefer: true + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + dgExample: + summary: | + Dangerous Goods (DG) cargo Booking + description: | + Update a `Confirmed Booking` (a `Booking` with `carrierBookingReference='cbr-987'`) with DG cargo (*Environmentally hazardous substance, liquid, N.O.S (Propiconazole)*) being sent from Bremerhaven, Germany to Norfolk, US + value: + carrierBookingRequestReference: cbrr-123 + carrierBookingReference: cbr-987 + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Environmentally hazardous substance, liquid, N.O.S (Propiconazole)" + HSCodes: + - "293499" + cargoGrossWeight: + value: 36000 + unit: KGM + outerPackaging: + imoPackagingCode: 3A1 + numberOfPackages: 100 + description: "Jerrican, steel" + dangerousGoods: + - UNNumber: "3082" + properShippingName: | + Environmentally hazardous substance, liquid, N.O.S + imoClass: "9" + isMarinePollutant: false + packingGroup: 3 + isLimitedQuantity: false + isExceptedQuantity: false + isSalvagePackings: false + isEmptyUncleanedResidue: false + isWaste: false + isHot: false + isCompetentAuthorityApprovalRequired: false + emergencyContactDetails: + contact: John Doe + phone: +1 123062970 + EMSNumber: F-A S-F + isReportableQuantity: false + grossWeight: + value: 12000 + unit: KGM + required: true + responses: + "202": + description: | + The `Booking request` update has been successfully accepted by the provider. `bookingStatus` does not change and response payload is empty. Further processing will be done by provider. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + noContentExample: + summary: | + Booking request updated with no content + description: | + An updated `Booking request` received, schema validated and accepted by provider - the `Booking` now awaits provider action, `bookingStatus` does not change. + "400": + description: | + In case the updated/amended `Booking request` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing receiptTypeAtOrigin + description: | + `receiptTypeAtOrigin` is a mandatory property in the `Booking request`. This is an example of how the error object would look in case this property is missing. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + receiptTypeAtOrigin not found - it is a mandatory property in Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + property: receiptTypeAtOrigin + errorCodeText: mandatory property missing + errorCodeMessage: | + receiptTypeAtOrigin must be provided as part of a Booking request + "404": + description: | + In case the provider does not know of the `bookingReference` used in the request (this could be because of a `POST` request that has not finished processing or simply because the resource does not exist) - it is possible for the provider to reject the requests by returning a `404` (Not Found). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. This can be because a `Post` request has not been finished processing or because the `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + "409": + description: | + In case the provider is processing the `Booking request` - it is possible for the provider to reject new incoming requests by returning a `409` (Conflict) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process before any new requests are processed + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again + later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: | + The Booking cannot be updated/amended while it is being processed. Please try again later + "500": + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + GET /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PUT + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to update a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be updated per hour + patch: + tags: + - Booking + summary: | + Cancels the Booking or cancels an Amendment + description: | + A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. Once the `Booking` is confirmed - it is **only** possible to use the `carrierBookingReference`. + + This endPoint corresponds with **UseCase 11 - Cancel Booking Request by shipper**, **UseCase 9 - Cancel amendment to confirmed Booking** or **UseCase 13 - Cancel confirmed Booking by shipper**. + + ## Precondition + In order to cancel a `Booking`, the `bookingStatus` must be either + - `RECEIVED` + - `PENDING_UPDATE` + - `UPDATE_RECEIVED` + - `CONFIRMED` + - `PENDING_AMENDMENT` + + In order to cancel a `Booking Amendment`, the status of the `Booking Amendment` must be + - `AMENDMENT_RECEIVED` + + ## Postcondition + The provider has received a cancellation from the consumer for a `Booking` or for a `Booking Amendment`. + + The consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not. + + ## Flow for the `202` (Accepted) response + The following occurs when a provider receives a cancellation request: + 1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned. + + **The process stops here!** + 2. The payload is schema-valid which means: + - all required properties are provided. + - all values provided have correct data type. + 3. An empty response is returned and the consumer now awaits further processing by the provider. + + Once processed, the `Booking` or `Amended Booking` is cancelled and a [Booking Notification](#/BookingNotification) is sent. In case of a Confirmed Booking - the provider has the opportunity to decline the Cancellation of the Booking (in which case the `bookingCancellationStatus='CANCELLATION_DECLINED'`). + operationId: cancel-booking + parameters: + - name: bookingReference + in: path + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + required: true + style: simple + explode: false + schema: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + example: CBR001 + - name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CancelBookingRequest' + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer wants to cancel the `Booking Request`. This is done by setting the `bookingStatus` to `CANCELLED` and provide an optional `reason`. + value: + bookingStatus: CANCELLED + reason: Cancelling due to strike + amendmentCancelledExample: + summary: | + Amendment cancelled + description: | + The consumer wants to **only** cancel the amendment (and keep the confirmed `Booking`). This is done by setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED`. + value: + amendedBookingStatus: AMENDMENT_CANCELLED + requestConfirmedBookingCancelledExample: + summary: | + Request to cancel a Confirmed Booking + description: | + The consumer requests to cancel a `Confirmed Booking`. This is done by setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` and provide an optional `reason`. + value: + bookingCancellationStatus: CANCELLATION_RECEIVED + reason: Cancelling due to internal issues + responses: + "202": + description: | + Booking cancellation has been accepted. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + examples: + bookingCancelledExample: + summary: | + Booking Request cancelled + description: | + The consumer has requested that the `Booking Request` should be cancelled. The cancellation request has been accepted and is now awaiting further processing by the provider + amendmentCancelledExample: + summary: | + Amendment cancellation on a confirmed Booking accepted + description: | + The consumer has requested that the amendment to a confirmed `Booking` is to be cancelled. The cancellation request as been accepted and is now awaiting further processing by the provider + confirmedBookingCancellationExample: + summary: | + Request to Cancel a confirmed Booking accepted + description: | + The consumer has requested to cancel a confirmed `Booking`. The cancellation request has been accepted and is now awaiting further processing by the provider + "400": + description: | + In case the cancel payload does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Wrong `amendedBookingStatus` + description: | + `APPROVE` is not a possible value when PATCHING a `Booking`. + + **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example". + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: APPROVE is not a valid status to set + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + property: amendedBookingStatus + value: APPROVE + errorCodeText: incorrect value + errorCodeMessage: "Only AMENDMENT_CANCELLED is an allowed value: APPROVE was inserted" + "404": + description: | + In case the consumer is cancelling the `Amended Booking` by setting: + + `amendedBookingStatus='AMENDMENT_CANCELLED'` + + but: + - the `Booking` has not yet been confirmed + - the `Booking` has been confirmed but no amendment has yet been provided by the consumer + - the provider has requested for a new amendment (**UseCase 6: Request to amend confirmed Booking**) in which case the "old update" is no longer accessible. + + a `404` (Not Found) is returned. + + A `404` (Not Found) can also be sent in case the provider does not know of the `bookingReference` used in the request (the resource does not exist) + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + notFoundExample: + summary: | + Not Found request + description: | + The provided `bookingReference` cannot be found. The `bookingReference` does not exist in the provider system. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123 + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: | + bookingReference not found + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: bookingReference Not Found + errorCodeMessage: | + The Booking does not exist + notFoundAmendmentExample: + summary: | + Missing amended Booking + description: | + Cancelling the `Amendment` is requested - but no `Amended Booking` exists. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: GET + requestUri: /v2/bookings/cbrr-123?amendedContent=true + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: No amended booking exists + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: No amended booking + errorCodeMessage: No amended booking available + "409": + description: | + In case the provider is processing a `Booking request` - it is possible for the provider to reject the cancellation by returning a `409` (Conflict). This is also to be used in case a cancellation to a Confirmed Booking is done via the `carrierBookingRequestReference`. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + conflictExample: + summary: | + Conflicting request + description: | + The provider is already processing a request and needs to finish this process. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 409 + statusCodeText: Conflict + statusCodeMessage: | + Previous request is being processed. Please try again later + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Conflicting request is being processed + errorCodeMessage: Conflicting request is being processed + "500": + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Booking request + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Updating too many Bookings requests + description: | + Calling the endPoint + + PATCH /v2/bookings/cbrr-123 + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: PATCH + requestUri: /v2/bookings/cbrr-123 + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to cancel a booking has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Max Booking requests reached + errorCodeMessage: A maximum of 10 Bookings can be cancelled per hour + /v2/booking-notifications: + post: + tags: + - Notifications + summary: Send a new Booking Notification + description: | + Creates a new [`Booking Notification`](#/BookingNotification). This endPoint is called whenever a `Booking` that a consumer has subscribed to changes state or is updated. + + **This endPoint is to be implemented by a consumer of the Booking API in order to receive Notifications** + operationId: booking-notifications + parameters: + - name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + requestBody: + description: | + The payload used to create a [`Booking Notification`](#/BookingNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/BookingNotification' + examples: + receivedLightweightExample: + summary: | + Booking request received (Lightweight) + description: | + A lightweight notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: "1.0" + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: https://member.com/ + type: org.dcsa.booking.v2 + time: 2018-04-05T17:31:00Z + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + receivedFullStateTransferExample: + summary: | + Booking request received (Full State Transfer) + description: | + A full state transfer notification explaining that a `Booking Request` has been received and stored in provider system (`bookingStatus='RECEIVED'`). + value: + specversion: "1.0" + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: https://member.com/ + type: org.dcsa.booking.v2 + time: 2018-04-05T17:31:00Z + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: RECEIVED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + bookingStatus: RECEIVED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: PRE + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + declinedLightweightExample: + summary: | + Booking amendment declined (Lightweight) + description: | + A lightweight notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`) + value: + specversion: "1.0" + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: https://member.com/ + type: org.dcsa.booking.v2 + time: 2018-04-05T17:31:00Z + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + declinedFullStateTransferExample: + summary: | + Booking amendment declined (Full State Transfer) + description: | + A full state transfer notification explaining that an amendment to a `Booking` has been declined (`amendedBookingStatus='AMENDMENT_DECLINED'`). The notification both contains the Booking from before the amendment (in the `booking` property) it also contains the amended booking (in the `amendedBooking` property). + value: + specversion: "1.0" + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: https://member.com/ + type: org.dcsa.booking.v2 + time: 2018-04-05T17:31:00Z + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + feedbacks: + - severity: INFO + code: INFORMATIONAL_MESSAGE + message: Declined because of no equipment availability + booking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 3 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + confirmedEquipments: + - ISOEquipmentCode: 42G1 + units: 3 + transportPlan: + - transportPlanStage: MNC + transportPlanStageSequenceNumber: 1 + loadLocation: + locationName: Bremerhaven + UNLocationCode: DEBRV + dischargeLocation: + locationName: Norfolk + UNLocationCode: USORF + plannedDepartureDate: 2024-01-20 + plannedArrivalDate: 2024-01-31 + modeOfTransport: VESSEL + vesselName: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + shipmentCutOffTimes: + - cutOffDateTimeCode: DCO + cutOffDateTime: 2024-01-17T22:30:00Z + - cutOffDateTimeCode: VCO + cutOffDateTime: 2024-01-18T22:30:00Z + - cutOffDateTimeCode: FCO + cutOffDateTime: 2024-01-19T13:30:00Z + advanceManifestFilings: + - manifestTypeCode: ACE + countryCode: US + carrierClauses: + - "The date of shipment, the carrying vessel and the schedule are not guaranteed and are always subject to changes." + - "Operations such as lifting, stowage, drayage and customs declaration of containers are based on the description of the nature, quantity, measurement and weight declared by the Shipper. The Shipper shall be liable for any damage, loss, expense and fines incurred by Carrier XYZ or its agents due to incorrectness or incompleteness of such declaration." + - "Warranted shipper must fulfill the requirements of SOLAS regulations and the IMO guidelines regarding the Verified Gross Mass (VGM) of container carrying cargo (msc.1/circ.1474, 9 June 2014)." + - "In accordance with SOLAS regulations and IMO guidelines regarding the VGM (verified gross mass), any expenses incurred because the VGM was submitted late or was not submitted at all will be charged back to the customer with an additional administration fee." + amendedBooking: + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + bookingStatus: CONFIRMED + amendedBookingStatus: AMENDMENT_DECLINED + receiptTypeAtOrigin: CY + deliveryTypeAtDestination: CY + cargoMovementTypeAtOrigin: FCL + cargoMovementTypeAtDestination: FCL + serviceContractReference: HHL51800000 + freightPaymentTermCode: PRE + originChargesPaymentTerm: + haulageChargesPaymentTermCode: PRE + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + destinationChargesPaymentTerm: + haulageChargesPaymentTermCode: COL + portChargesPaymentTermCode: PRE + otherChargesPaymentTermCode: COL + contractQuotationReference: HHL1401 + vessel: + name: MAERSK IOWA + vesselIMONumber: "9298686" + carrierServiceCode: TA1 + carrierExportVoyageNumber: 403W + isPartialLoadAllowed: false + isExportDeclarationRequired: false + expectedDepartureDate: 2024-01-20 + incoTerms: EXW + isEquipmentSubstitutionAllowed: false + references: + - type: CR + value: KN-00103004 + documentParties: + bookingAgent: + partyName: KN Bremerhaven + address: + street: Amerikaring + streetNumber: "40" + postCode: "27568" + city: Bremerhaven + countryCode: DE + partyContactDetails: + - name: Export operations department + phone: +49 471 945410 + partyContactDetails: + - name: Diane + phone: +49 471 945410 + shipmentLocations: + - location: + locationName: Bremerhaven + UNLocationCode: DEBRV + locationTypeCode: POL + - location: + locationName: Norfolk + UNLocationCode: USORF + locationTypeCode: POD + requestedEquipments: + - isShipperOwned: false + ISOEquipmentCode: 42G1 + units: 30 + commodities: + - commodityType: "Dry cargo, Freight all kinds" + cargoGrossWeight: + value: 36000 + unit: KGM + cancelConfirmedBookingLightweightExample: + summary: | + Confirmed Booking cancelled (Lightweight) + description: | + A lightweight notification explaining that a confirmed `Booking` has been cancelled (`bookingCancellationStatus='CANCELLATION_CONFIRMED'`) + value: + specversion: "1.0" + id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + source: https://member.com/ + type: org.dcsa.booking.v2 + time: 2018-04-05T17:31:00Z + datacontenttype: application/json + subscriptionReference: BKG001 + data: + bookingStatus: CANCELLED + amendedBookingStatus: AMENDMENT_CANCELLED + bookingCancellationStatus: CANCELLATION_CONFIRMED + carrierBookingRequestReference: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: ABC709951 + responses: + "204": + description: | + No Content + headers: + API-Version: + $ref: '#/components/headers/API-Version' + "400": + description: | + In case the `Notification` does not schema validate a `400` (Bad Request) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + badRequestExample: + summary: | + Booking missing carrierBookingReference or carrierBookingRequestReference + description: | + `carrierBookingReference` or `carrierBookingRequestReference` is a conditionally property in the `Notification` (at least one of them must be present). This is an example of how the error object would look in case this property is missing + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 400 + statusCodeText: Bad Request + statusCodeMessage: | + carrierBookingReference or carrierBookingRequestReference not found - one of them is a mandatory to provide in a Notification + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + property: carrierBookingReference or carrierBookingRequestReference + errorCodeText: mandatory property missing + errorCodeMessage: | + carrierBookingReference or carrierBookingRequestReference must be provided as part of a Notification + "500": + description: | + In case a server error occurs in provider system a `500` (Internal Server Error) is returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + internalServerErrorExample: + summary: | + Internal Server Error while processing Notification + description: | + An Internal Server Error has occurred - the consumer should contact {provider-support} and provide the `providerCorrelationReference` (in the example this is `4426d965-0dd8-4005-8c63-dc68b01c4962`) + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: | + Internal Server Error occurred while processing Booking request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Internal Error occurred + errorCodeMessage: Internal Error occurred + default: + description: | + For other errors the error object should be populated with relevant information + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + tooManyRequestsExample: + summary: | + Making too many Notifications + description: | + Calling the endPoint + + POST /v2/booking-notifications + + too many times within a time period. + + **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example" + value: + httpMethod: POST + requestUri: /v2/booking-notifications + statusCode: 429 + statusCodeText: Too Many Requests + statusCodeMessage: | + Too many request to create a Notification has been requested. Please try again in 1 hour + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: 2024-09-04T09:41:00Z + errors: + - errorCode: 7003 + errorCodeText: Max Notifications reached + errorCodeMessage: A maximum of 10 Notifications can be created per hour +components: + schemas: + CreateBookingResponse: + title: Create Booking Response + required: + - carrierBookingRequestReference + type: object + properties: + carrierBookingRequestReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference to the booking during the booking request phase. + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + description: | + **Only** the `carrierBookingRequestReference` is returned. + CancelBookingRequest: + title: Cancel Booking Request + type: object + properties: + reason: + maxLength: 5000 + type: string + description: | + An optional property where a reason for cancelling the booking or the amendment can be given. + example: Booking cancelled due to internal problems + oneOf: + - title: Cancel Booking Request (prior to Booking Confirmation) + required: + - bookingStatus + type: object + properties: + bookingStatus: + maxLength: 50 + type: string + description: | + Setting the `bookingStatus` to `CANCELLED` cancels the `Booking Request` (only possible **before** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingRequestReference`). The `Booking Request` will discontinue if the request is accepted by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is NOT** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLED`. + example: CANCELLED + - title: Only cancel the amendment to a Confirmed Booking + required: + - amendedBookingStatus + type: object + properties: + amendedBookingStatus: + maxLength: 50 + type: string + description: | + Setting the `amendedBookingStatus` to `AMENDMENT_CANCELLED` **only** cancels the amendment to a confirmed `Booking`. This is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`. + + **Condition:** It is a precondition that the `amendedBookingStatus` **is** `AMENDMENT_RECEIVED` in order to cancel it. If this is not the case a `404` (Not Found) error response should be returned. + + Only possible value to set is `AMENDMENT_CANCELLED`. + example: AMENDMENT_CANCELLED + - title: Request to cancel a Confirmed Booking + required: + - bookingCancellationStatus + type: object + properties: + bookingCancellationStatus: + maxLength: 50 + type: string + description: | + Setting the `bookingCancellationStatus` to `CANCELLATION_RECEIVED` is a request to cancel a confirmed Booking (only possible **after** it is `CONFIRMED` and using this property is only possible in combination with the `bookingReference` path-property being the `carrierBookingReference`). Upon receiving this request the provider will check if it is possible to cancel the confirmed booking. Further processing is needed by the provider. + + **Condition:** It is a precondition that the `bookingStatus` **is** `CONFIRMED` or `PENDING_AMENDMENT` in order to cancel it. If this is not the case a `409` (Conflict) error response should be returned. + + Only possible value to set is `CANCELLATION_RECEIVED`. + example: CANCELLATION_RECEIVED + BookingNotification: + title: Booking Notification + required: + - data + - datacontenttype + - id + - source + - specversion + - subscriptionReference + - time + - type + type: object + 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. + example: "1.0" + enum: + - "1.0" + id: + maxLength: 100 + type: string + 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: + maxLength: 4096 + type: string + 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. + example: org.dcsa.booking.v2 + enum: + - org.dcsa.booking.v2 + time: + type: string + 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. + format: date-time + 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. + example: application/json + enum: + - application/json + subscriptionReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The reference of the subscription that has triggered this event + example: 30675492-50ff-4e17-a7df-7a487a8ad343 + data: + $ref: '#/components/schemas/BookingNotificationData' + description: | + `CloudEvent` specific properties for the `Notification`. + BookingNotificationData: + title: Data + required: + - bookingStatus + type: object + properties: + bookingStatus: + maxLength: 50 + type: string + description: | + The status of the `Booking`. Possible values are: + + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + maxLength: 50 + type: string + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this property is empty. Possible values are: + + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + maxLength: 50 + type: string + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + carrierBookingRequestReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` is required to provide + example: ABC709951 + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + booking: + $ref: '#/components/schemas/BookingFullNotification' + amendedBooking: + $ref: '#/components/schemas/AmendedBookingFullNotification' + description: | + `Booking` specific properties for the `Notification` + BookingFullNotification: + title: Booking + type: object + description: | + This property contains the booking in case the subscriber is subscribing to the `Full State Transfer` of the Booking. + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + AmendedBookingFullNotification: + title: Amended Booking + type: object + description: | + This property contains the amended booking in case: + - an amendment is currently active + - the subscriber is subscribing to the `Full State Transfer` of the Booking + + In case the subscriber does not subscribe to the `Full State Transfer` of the Booking or no amendment is active - then the content in this property can be ignored. + allOf: + - $ref: '#/components/schemas/Booking' + Feedback: + title: Feedback + required: + - code + - message + - severity + type: object + properties: + severity: + maxLength: 50 + type: string + 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: + maxLength: 50 + type: string + description: "A code used to describe the feedback. Possible values are:\n- `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) \n- `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values)\n- `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided)\n- `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention)\n- `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future)\n- `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention)\n" + example: PROPERTY_WILL_BE_IGNORED + message: + maxLength: 5000 + type: string + description: | + A description with additional information. + example: Spaces not allowed in facility code + jsonPath: + maxLength: 500 + type: string + description: | + A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + property: + maxLength: 100 + type: string + description: | + The name of the property causing the error/warning. + example: facilityCode + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + ErrorResponse: + title: Error Response + required: + - errorDateTime + - errors + - httpMethod + - requestUri + - statusCode + - statusCodeText + type: object + properties: + httpMethod: + type: string + description: | + The HTTP method used to make the request e.g. `GET`, `POST`, etc + example: POST + enum: + - GET + - HEAD + - POST + - PUT + - DELETE + - OPTION + - PATCH + requestUri: + type: string + description: | + The URI that was requested. + example: /v1/events + statusCode: + type: integer + description: | + The HTTP status code returned. + format: int32 + example: 400 + statusCodeText: + maxLength: 50 + type: string + description: | + A standard short description corresponding to the HTTP status code. + example: Bad Request + statusCodeMessage: + maxLength: 200 + type: string + description: | + A long description corresponding to the HTTP status code with additional information. + example: The supplied data could not be accepted + providerCorrelationReference: + maxLength: 100 + type: string + description: | + A unique identifier to the HTTP request within the scope of the API provider. + example: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: + type: string + description: | + The DateTime corresponding to the error occurring. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. + format: date-time + example: 2024-09-04T09:41:00Z + errors: + minItems: 1 + type: array + description: | + An array of errors providing more detail about the root cause. + items: + $ref: '#/components/schemas/DetailedError' + description: Unexpected error + DetailedError: + title: Detailed Error + required: + - errorCodeMessage + - errorCodeText + type: object + properties: + errorCode: + maximum: 9999 + minimum: 7000 + type: integer + description: "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n" + format: int32 + example: 7003 + property: + maxLength: 100 + type: string + description: | + The name of the property causing the error. + example: facilityCode + value: + maxLength: 500 + type: string + description: | + The value of the property causing the error serialised as a string exactly as in the original request. + example: SG SIN WHS + jsonPath: + maxLength: 500 + type: string + description: | + A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath). + example: $.location.facilityCode + errorCodeText: + maxLength: 100 + type: string + description: | + A standard short description corresponding to the `errorCode`. + example: invalidData + errorCodeMessage: + maxLength: 5000 + type: string + description: | + A long description corresponding to the `errorCode` with additional information. + example: Spaces not allowed in facility code + description: | + A detailed description of what has caused the error. + Address: + title: Address + required: + - city + - countryCode + - street + type: object + properties: + street: + maxLength: 70 + type: string + description: The name of the street. + example: Ruijggoordweg + streetNumber: + maxLength: 50 + type: string + description: The number of the street. + example: "100" + floor: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The floor of the street number. + example: 2nd + postCode: + maxLength: 10 + type: string + description: The post code. + example: 1047 HM + POBox: + maxLength: 20 + type: string + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: "123" + city: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of the city. + example: Amsterdam + stateRegion: + maxLength: 65 + type: string + description: The name of the state/region. + example: North Holland + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: NL + description: | + An object for storing address related information + Facility: + title: Facility + required: + - facilityCode + - facilityCodeListProvider + type: object + properties: + facilityCode: + maxLength: 6 + pattern: ^\S(?:.*\S)?$ + type: string + 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) + example: SMDG + enum: + - BIC + - SMDG + description: | + An object used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + GeoCoordinate: + title: Geo Coordinate + required: + - latitude + - longitude + type: object + properties: + latitude: + maxLength: 10 + type: string + description: Geographic coordinate that specifies the north–south position of a point on the Earth's surface. + example: "48.8585500" + longitude: + maxLength: 11 + type: string + description: Geographic coordinate that specifies the east–west position of a point on the Earth's surface. + example: "2.294492036" + description: | + An object used to express a location using `latitude` and `longitude`. + CreateBooking: + title: Create Booking + required: + - cargoMovementTypeAtDestination + - cargoMovementTypeAtOrigin + - deliveryTypeAtDestination + - documentParties + - isEquipmentSubstitutionAllowed + - receiptTypeAtOrigin + - requestedEquipments + - shipmentLocations + type: object + properties: + receiptTypeAtOrigin: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + deliveryTypeAtDestination: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + cargoMovementTypeAtOrigin: + maxLength: 3 + type: string + 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: + maxLength: 3 + type: string + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + maxLength: 30 + type: string + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + maxLength: 8 + minLength: 8 + pattern: "^SR\\d{5}[A-Z]$" + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + example: 2103S + universalExportVoyageReference: + maxLength: 5 + minLength: 5 + pattern: "^\\d{2}[0-9A-Z]{2}[NEWSR]$" + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + declaredValue: + minimum: 0 + type: number + 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. + format: float + example: 1231.1 + declaredValueCurrency: + maxLength: 3 + minLength: 3 + pattern: "^[A-Z]{3}$" + type: string + 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). + example: DKK + carrierCode: + maxLength: 4 + pattern: ^\S+$ + type: string + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-19 + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + example: SWB + enum: + - BOL + - SWB + transportDocumentReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + maxLength: 3 + type: string + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n" + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + minItems: 1 + type: array + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + minItems: 1 + type: array + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + UpdateBooking: + title: Update Booking + required: + - cargoMovementTypeAtDestination + - cargoMovementTypeAtOrigin + - deliveryTypeAtDestination + - documentParties + - isEquipmentSubstitutionAllowed + - receiptTypeAtOrigin + - requestedEquipments + - shipmentLocations + type: object + properties: + carrierBookingRequestReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + receiptTypeAtOrigin: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + deliveryTypeAtDestination: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + cargoMovementTypeAtOrigin: + maxLength: 3 + type: string + 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: + maxLength: 3 + type: string + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + maxLength: 30 + type: string + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + maxLength: 8 + minLength: 8 + pattern: "^SR\\d{5}[A-Z]$" + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + example: 2103S + universalExportVoyageReference: + maxLength: 5 + minLength: 5 + pattern: "^\\d{2}[0-9A-Z]{2}[NEWSR]$" + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + declaredValue: + minimum: 0 + type: number + 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. + format: float + example: 1231.1 + declaredValueCurrency: + maxLength: 3 + minLength: 3 + pattern: "^[A-Z]{3}$" + type: string + 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). + example: DKK + carrierCode: + maxLength: 4 + pattern: ^\S+$ + type: string + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-19 + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + example: SWB + enum: + - BOL + - SWB + transportDocumentReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + maxLength: 3 + type: string + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentPartiesReq' + partyContactDetails: + type: array + description: "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n" + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + minItems: 1 + type: array + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + minItems: 1 + type: array + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipmentShipper' + DocumentPartiesReq: + title: Document Parties + required: + - bookingAgent + type: object + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + other: + type: array + description: A list of document parties that can be optionally provided at booking stage. + items: + $ref: '#/components/schemas/OtherDocumentParty' + description: | + All `Parties` with associated roles. + Booking: + title: Booking + required: + - bookingStatus + - cargoMovementTypeAtDestination + - cargoMovementTypeAtOrigin + - deliveryTypeAtDestination + - documentParties + - isEquipmentSubstitutionAllowed + - receiptTypeAtOrigin + - requestedEquipments + - shipmentLocations + type: object + properties: + carrierBookingRequestReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference to the booking during the booking request phase. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: 24595eb0-5cfc-4381-9c3a-cedc1975e9aa + carrierBookingReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The `carrierBookingReference` if know. Often this will not be known until the booking has been confirmed. Is available during a booking amendment. + + **Condition:** `carrierBookingRequestReference` and/or `carrierBookingReference` must be provided + example: ABC709951 + bookingStatus: + maxLength: 50 + type: string + description: | + The status of the `Booking`. Possible values are: + - `RECEIVED` (Booking request has been received) + - `PENDING_UPDATE` (An update is required to the Booking) + - `UPDATE_RECEIVED` (An update has been received and is awaiting to be processed) + - `CONFIRMED` (Booking has been Confirmed) + - `PENDING_AMENDMENT` (An amendment is required to the Booking) + - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) + - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) + - `CANCELLED` (Booking discontinued by consumer) + - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) + example: RECEIVED + amendedBookingStatus: + maxLength: 50 + type: string + description: | + The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are: + - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) + - `AMENDMENT_CONFIRMED` (Amendment is confirmed) + - `AMENDMENT_DECLINED` (Amendment discontinued by provider) + - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + example: AMENDMENT_RECEIVED + bookingCancellationStatus: + maxLength: 50 + type: string + description: | + The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: + - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + example: CANCELLATION_RECEIVED + receiptTypeAtOrigin: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + deliveryTypeAtDestination: + maxLength: 3 + type: string + 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) + example: CY + enum: + - CY + - SD + - CFS + cargoMovementTypeAtOrigin: + maxLength: 3 + type: string + 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: + maxLength: 3 + type: string + description: | + Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are: + - `FCL` (Full Container Load) + - `LCL` (Less than Container Load) + example: FCL + serviceContractReference: + maxLength: 30 + type: string + description: | + Reference number for agreement between shipper and carrier, which optionally includes a certain minimum quantity commitment (usually referred as “MQC”) of cargo that the shipper commits to over a fixed period, and the carrier commits to a certain rate or rate schedule. + + **Condition:** Either a valid `serviceContractReference` or `contractQuotationReference` must be provided. + example: HHL51800000 + freightPaymentTermCode: + type: string + description: | + An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + originChargesPaymentTerm: + $ref: '#/components/schemas/OriginChargesPaymentTerm' + destinationChargesPaymentTerm: + $ref: '#/components/schemas/DestinationChargesPaymentTerm' + contractQuotationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference. + + **Condition:** Either a valid `contractQuotationReference` or `serviceContractReference` must be provided. + example: HHL1401 + vessel: + $ref: '#/components/schemas/Vessel' + carrierServiceName: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of a service as specified by the carrier. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceCode` are blank + example: Great Lion Service + carrierServiceCode: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific code of the service for which the schedule details are published. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and Vessel details or `carrierServiceName` are blank + example: FE1 + universalServiceReference: + maxLength: 8 + minLength: 8 + pattern: "^SR\\d{5}[A-Z]$" + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierExportVoyageNumber: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier specific identifier of the export Voyage. + + **Condition:** Mandatory if `expectedDepartureDate` or `expectedArrivalAtPlaceOfDeliveryStartDate` and `expectedArrivalAtPlaceOfDeliveryEndDate` is not provided. + example: 2103S + universalExportVoyageReference: + maxLength: 5 + minLength: 5 + pattern: "^\\d{2}[0-9A-Z]{2}[NEWSR]$" + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + declaredValue: + minimum: 0 + type: number + 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. + format: float + example: 1231.1 + declaredValueCurrency: + maxLength: 3 + minLength: 3 + pattern: "^[A-Z]{3}$" + type: string + 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). + example: DKK + carrierCode: + maxLength: 4 + pattern: ^\S+$ + type: string + description: | + The `SCAC` code (provided by [NMFTA](https://nmfta.org/scac/)) or `SMDG` code (provided by [SMDG](https://smdg.org/documents/smdg-code-lists/smdg-liner-code-list/)) of the carrier the booking request is intended for. `carrierCodeListProvider` defines which list the `carrierCode` is based upon. + example: MMCU + carrierCodeListProvider: + type: string + description: | + The code list provider for the `carrierCode`. Possible values are: + - `SMDG` (Ship Message Design Group) + - `NMFTA` (National Motor Freight Traffic Association) + example: NMFTA + enum: + - SMDG + - NMFTA + isPartialLoadAllowed: + type: boolean + description: | + Indicates whether the shipper agrees to load part of the shipment in case not all of the cargo is delivered within cut-off. + + **Note:** The carrier is not liable in case unable to follow the customer's instructions due to operational constraints. If this value is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + isExportDeclarationRequired: + type: boolean + description: | + Information provided by the shipper whether an export declaration is required for this particular shipment/commodity/destination. + + **Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts. + example: true + exportDeclarationReference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Reference number assigned to an Export declaration typically submitted by the exporter (or the freight forwarder on behalf of the exporter) that provides detailed information about the goods being exported. It serves as a record for the exporting country's government and is used for statistical, regulatory, and compliance purposes. The export declaration must typically be submitted to the relevant customs authorities before the goods leave the exporting country. + example: ABC123123 + expectedDepartureDate: + type: string + description: | + The date when the shipment is expected to be loaded on board a vessel as provided by the shipper or its agent. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedArrivalAtPlaceOfDeliveryDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryStartDate: + type: string + description: | + The start date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryEndDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-17 + expectedArrivalAtPlaceOfDeliveryEndDate: + type: string + description: | + The end date (provided as a range together with `expectedArrivalAtPlaceOfDeliveryStartDate`) for when the shipment is expected to arrive at `Place Of Delivery`. + + **Condition:** Mandatory if vessel/voyage/service details or `expectedDepartureDate` is not provided. + format: date + example: 2021-05-19 + transportDocumentTypeCode: + type: string + description: | + Specifies the type of the `Transport Document`. Possible values are: + - `BOL` (Bill of Lading) + - `SWB` (Sea Waybill) + example: SWB + enum: + - BOL + - SWB + transportDocumentReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A unique reference allocated by the shipping line to the `Transport Document` that the booking concerns. + example: reserved-HHL123 + bookingChannelReference: + maxLength: 20 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Identification number provided by the platform/channel used for booking request/confirmation, ex: Inttra booking reference, or GTNexus, other. + + **Condition:** a booking channel is being used + example: Inttra reference + incoTerms: + maxLength: 3 + type: string + description: | + Transport obligations, costs and risks as agreed between buyer and seller as defined by [Incoterms Rules](https://iccwbo.org/business-solutions/incoterms-rules/). + example: FCA + isEquipmentSubstitutionAllowed: + type: boolean + description: | + Indicates if an alternate equipment type can be provided by the carrier. + example: true + termsAndConditions: + maxLength: 50000 + type: string + description: | + Carrier terms and conditions of transport. + example: Any reference in... + invoicePayableAt: + $ref: '#/components/schemas/InvoicePayableAt' + placeOfBLIssue: + $ref: '#/components/schemas/PlaceOfBLIssue' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + documentParties: + $ref: '#/components/schemas/DocumentParties' + partyContactDetails: + type: array + description: "The contact details of the person(s) to contact in relation to the **Booking** (changes, notifications etc.) \n" + items: + $ref: '#/components/schemas/PartyContactDetail' + shipmentLocations: + minItems: 1 + type: array + description: | + A list of `Shipment Locations` + items: + $ref: '#/components/schemas/ShipmentLocation' + requestedEquipments: + minItems: 1 + type: array + description: | + List of `Requested Equipments`. Multiple containers can be requested within the same booking. For each Requested Equipment object with 2 or more units, it is a condition that the commodity (or list of commodities) defined within the same Requested Equipment object is the same for each requested unit. + + **Example:** 2 x 20' containing 50% shoes and 50% t-shirts can be requested within the same Requested Equipment object only if each 20' will contain 50% shoes and 50% t-shirts. If 1 x 20' will contain 100% shoes and the other 20' will be 100% t-shirts, 2 separate Requested Equipment objects must be defined. + items: + $ref: '#/components/schemas/RequestedEquipment' + confirmedEquipments: + type: array + description: | + A list of `Confirmed Equipments` + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ConfirmedEquipment' + transportPlan: + type: array + description: | + A list of `Transport` objects (legs) describing the entire transport plan including transshipments. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/Transport' + shipmentCutOffTimes: + type: array + description: | + A list of cut-off times provided by the carrier in the booking confirmation. A cut-off time indicates the latest deadline within which a task must be completed. The confirmed schedule cannot be guaranteed if a cut-off time is missed. Customs brokers may set additional cut-off times to receive the export customs documentation, which is not included in the shipment cut-off times of a carrier booking. + + **Condition:** Mandatory and non-empty for a `CONFIRMED` Booking + items: + $ref: '#/components/schemas/ShipmentCutOffTime' + advanceManifestFilings: + type: array + description: | + A list of `Advance Manifest Filings` provided by the carrier + items: + $ref: '#/components/schemas/AdvanceManifestFiling' + charges: + type: array + description: | + A list of `Charges` + items: + $ref: '#/components/schemas/Charge' + carrierClauses: + type: array + description: | + Additional clauses for a specific shipment added by the carrier to the Bill of Lading, subject to local rules / guidelines or certain mandatory information required to be shared with the customer. + items: + maxLength: 20000 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The content of the clause. + example: It is not allowed to... + feedbacks: + type: array + description: | + Feedback that can be provided includes, but is not limited to: + - unsupported properties + - changed values + - removed properties + - general information + items: + $ref: '#/components/schemas/Feedback' + InvoicePayableAt: + title: Invoice Payable At + required: + - UNLocationCode + type: object + properties: + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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 + 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` + PlaceOfBLIssue: + title: Place of B/L Issue + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Port of Amsterdam + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + The location can be specified either as a `UN Location Code` or as a `CountryCode`. + oneOf: + - title: UN Location Code + required: + - UNLocationCode + type: object + properties: + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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 + - title: Country Code + required: + - countryCode + type: object + properties: + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: DK + DocumentParties: + title: Document Parties + type: object + properties: + bookingAgent: + $ref: '#/components/schemas/BookingAgent' + shipper: + $ref: '#/components/schemas/Shipper' + consignee: + $ref: '#/components/schemas/Consignee' + serviceContractOwner: + $ref: '#/components/schemas/ServiceContractOwner' + carrierBookingOffice: + $ref: '#/components/schemas/CarrierBookingOffice' + other: + type: array + description: A list of document parties that can be optionally provided at booking stage. + items: + $ref: '#/components/schemas/OtherDocumentParty' + description: | + All `Parties` with associated roles. + ActiveReeferSettings: + title: Active Reefer Settings + required: + - temperatureSetpoint + - temperatureUnit + type: object + properties: + temperatureSetpoint: + type: number + description: | + Target value of the temperature for the Reefer based on the cargo requirement. + format: float + example: -15 + temperatureUnit: + type: string + description: | + The unit for temperature in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + + **Condition:** Mandatory to provide if `temperatureSetpoint` is provided + example: CEL + enum: + - CEL + - FAH + o2Setpoint: + maximum: 100 + minimum: 0 + type: number + description: | + The percentage of the controlled atmosphere CO2 target value + format: float + example: 25 + co2Setpoint: + maximum: 100 + minimum: 0 + type: number + description: | + The percentage of the controlled atmosphere CO2 target value + format: float + example: 25 + humiditySetpoint: + maximum: 100 + minimum: 0 + type: number + description: | + The percentage of the controlled atmosphere humidity target value + format: float + example: 95.6 + airExchangeSetpoint: + minimum: 0 + type: number + description: | + Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container + format: float + 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 to provide if `airExchange` is provided + example: MQH + enum: + - MQH + - FQH + isVentilationOpen: + type: boolean + description: | + If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed` + example: true + isDrainholesOpen: + type: boolean + description: | + Is drain holes open on the container + example: true + isBulbMode: + type: boolean + description: | + Is special container setting for handling flower bulbs active + example: true + isColdTreatmentRequired: + type: boolean + description: | + Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD + example: true + isControlledAtmosphereRequired: + type: boolean + description: | + Indicator of whether cargo requires Controlled Atmosphere. + example: true + isPreCoolingRequired: + type: boolean + description: | + Indicator whether reefer container should be pre-cooled to the temperature setting required at time of release from depot + example: true + isGeneratorSetRequired: + type: boolean + description: | + Indicator whether reefer container should have a generator set attached at time of release from depot + example: true + description: | + The specifications for a Reefer equipment. + + **Condition:** Only applicable when `isNonOperatingReefer` is set to `false` + PartyAddress: + title: Party Address + required: + - city + - countryCode + - street + type: object + properties: + street: + maxLength: 70 + type: string + description: The name of the street of the party's address. + example: Ruijggoordweg + streetNumber: + maxLength: 50 + type: string + description: The number of the street of the party's address. + example: "100" + floor: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The floor of the party's street number. + example: 2nd + postCode: + maxLength: 10 + type: string + description: The post code of the party's address. + example: 1047 HM + POBox: + maxLength: 20 + type: string + description: A numbered box at a post office where a person or business can have mail or parcels delivered. + example: "123" + city: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The city name of the party's address. + example: Amsterdam + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + 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) + example: NLAMS + stateRegion: + maxLength: 65 + type: string + description: The state/region of the party's address. + example: North Holland + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: NL + description: | + An object for storing address related information + OtherDocumentParty: + title: Other Document Party + required: + - party + - partyFunction + type: object + properties: + party: + $ref: '#/components/schemas/Party' + partyFunction: + maxLength: 3 + type: string + description: | + Specifies the role of the party in a given context. Possible values are: + + - `DDR` (Consignor's freight forwarder) + - `DDS` (Consignee's freight forwarder) + - `COW` (Invoice payer on behalf of the consignor (shipper)) + - `COX` (Invoice payer on behalf of the consignee) + - `N1` (First Notify Party) + - `N2` (Second Notify Party) + - `NI` (Other Notify Party) + example: DDS + description: | + A list of document parties that can be optionally provided at booking stage + BookingAgent: + title: Booking Agent + required: + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + type: array + description: | + A list of `Tax References` for a `Party` + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference linked to the `Booking Agent`. + example: HHL007 + description: | + The party placing the booking request on behalf of the customer. + Shipper: + title: Shipper + required: + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + type: array + description: | + A list of `Tax References` for a `Party` + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A purchase order reference linked to the `Shipper`. + example: HHL007 + 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. + Consignee: + title: Consignee + required: + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + type: array + description: | + A list of `Tax References` for a `Party` + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A purchase order reference linked to the `Consignee`. + example: HHL007 + description: | + The party to which goods are consigned in the Master Bill of Lading. + ServiceContractOwner: + title: Service Contract Owner + required: + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + type: array + description: | + A list of `Tax References` for a `Party` + items: + $ref: '#/components/schemas/TaxLegalReference' + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference linked to the `Service Contract Owner`. + example: HHL007 + description: | + The party signing the service contract with the carrier. + CarrierBookingOffice: + title: Carrier Booking Office + required: + - UNLocationCode + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + 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) + example: NLAMS + address: + $ref: '#/components/schemas/Address' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + description: | + The carrier office responsible for processing the booking. + Party: + title: Party + required: + - partyName + type: object + properties: + partyName: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the party. + example: IKEA Denmark + address: + $ref: '#/components/schemas/PartyAddress' + identifyingCodes: + type: array + items: + $ref: '#/components/schemas/IdentifyingCode' + taxLegalReferences: + type: array + description: | + A list of `Tax References` for a `Party` + items: + $ref: '#/components/schemas/TaxLegalReference' + partyContactDetails: + minItems: 1 + type: array + description: | + A list of contact details + items: + $ref: '#/components/schemas/PartyContactDetail' + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A reference linked to the `Party`. + example: HHL007 + description: | + Refers to a company or a legal entity. + PartyContactDetail: + title: Party Contact Detail + required: + - name + type: object + properties: + name: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Name of the contact + example: Henrik + description: | + The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`. + example: + name: Henrik + phone: +45 51801234 + anyOf: + - title: Phone required + required: + - phone + type: object + properties: + phone: + maxLength: 30 + pattern: ^\S(?:.*\S)?$ + type: string + 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 + description: | + `Phone` is mandatory to provide + - title: Email required + required: + - email + type: object + properties: + email: + maxLength: 100 + pattern: ^.+@\S+$ + type: string + description: | + `E-mail` address to be used + example: info@dcsa.org + description: | + `Email` is mandatory to provide + IdentifyingCode: + title: Identifying Code + required: + - codeListProvider + - partyCode + type: object + properties: + codeListProvider: + maxLength: 100 + type: string + 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: + maxLength: 150 + type: string + description: | + Code to identify the party as provided by the code list provider + example: MSK + codeListName: + maxLength: 100 + type: string + 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 + TaxLegalReference: + title: Tax & Legal Reference + required: + - countryCode + - type + - value + type: object + properties: + type: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The reference type code as defined by the relevant tax and/or legal authority. + example: PAN + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: IN + value: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The value of the `taxLegalReference` + example: AAAAA0000A + description: | + Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |PAN|IN|Goods and Services Tax Identification Number in India| + |GSTIN|IN|Goods and Services Tax Identification Number in India| + |IEC|IN|Importer-Exported Code in India| + |RUC|EC|Registro Único del Contribuyente in Ecuador| + |RUC|PE|Registro Único del Contribuyente in Peru| + |NIF|MG|Numéro d'Identification Fiscal in Madagascar| + |NIF|DZ|Numéro d'Identification Fiscal in Algeria| + ReferenceShipper: + title: Reference (Shipper) + required: + - type + - value + type: object + properties: + type: + maxLength: 3 + type: string + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: "The value of the reference. \n" + example: HHL00103004 + 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. + Reference: + title: Reference + required: + - type + - value + type: object + properties: + type: + maxLength: 3 + type: string + description: | + The reference type codes defined by DCSA. Possible values are: + - `CR` (Customer's Reference) + - `ECR` (Empty container release reference) + - `AKG` (Vehicle Identification Number) + - `AEF` (Customer Load Reference) + example: CR + value: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: "The value of the reference. \n" + example: HHL00103004 + 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. + CustomsReference: + title: Customs Reference + required: + - countryCode + - type + - values + type: object + properties: + type: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The reference type code as defined in the relevant customs jurisdiction. + example: ACID + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: EG + values: + minItems: 1 + type: array + items: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The value of the `customsReference` + example: "4988470982020120017" + description: | + Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods. + + A small list of **potential** examples: + + | Type | Country | Description | + |-------|:-------:|-------------| + |ACID|EG|Advance Cargo Information Declaration in Egypt| + |CERS|CA|Canadian Export Reporting System| + |ITN|US|Internal Transaction Number in US| + |PEB|ID|PEB reference number| + |CSN|IN|Cargo Summary Notification (CSN)| + ShipmentLocation: + title: Shipment Location + required: + - location + - locationTypeCode + type: object + properties: + location: + $ref: '#/components/schemas/Location' + locationTypeCode: + maxLength: 3 + type: string + description: | + Links to the Location Type Code defined by DCSA. Possible values are: + - `PRE` (Place of Receipt) + - `POL` (Port of Loading) + - `POD` (Port of Discharge) + - `PDE` (Place of Delivery) + - `PCF` (Pre-carriage From) + - `OIR` (Onward In-land Routing) + - `ORI` (Origin of goods) + - `IEL` (Container intermediate export stop off location) + - `PTP` (Prohibited transshipment port) + - `RTP` (Requested transshipment port) + - `FCD` (Full container drop-off location) + example: PRE + description: | + Maps the relationship between `Shipment` and `Location`, e.g., the `Place of Receipt` and the `Place of Delivery` for a specific shipment. This is a reusable object between `Booking` and `Transport Document` + Location: + title: Location + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Port of Amsterdam + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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' + description: | + The location can be specified using **any** of the nested structures: + - `address` (used to specify the location via an Address) + - `UNLocationCode` + - `facility` (used to specify a location using a `facilityCode` and a `facilityCodeListProvider`) + - `geoCoordinate` (used to specify a location using `latitude` and `longitude`) + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: CMP Container Terminal Copenhagen + UNLocationCode: DKCPH + facility: + facilityCode: CMPDK + facilityCodeListProvider: SMDG + RequestedEquipment: + title: Requested Equipment + required: + - ISOEquipmentCode + - isShipperOwned + - units + type: object + properties: + ISOEquipmentCode: + maxLength: 4 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + minimum: 1 + type: integer + description: | + Number of requested equipment units. + format: int32 + example: 3 + containerPositionings: + type: array + description: "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n" + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + equipmentReferences: + type: array + description: | + A list of equipments to be used by the shipper if known at the time of booking + items: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/Commodity' + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + RequestedEquipmentShipper: + title: Requested Equipment (Shipper) + required: + - ISOEquipmentCode + - isShipperOwned + - units + type: object + properties: + ISOEquipmentCode: + maxLength: 4 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22RT + units: + minimum: 1 + type: integer + description: | + Number of requested equipment units. + format: int32 + example: 3 + containerPositionings: + type: array + description: "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location.\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n" + items: + $ref: '#/components/schemas/ContainerPositioning' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + equipmentReferences: + type: array + description: | + A list of equipments to be used by the shipper if known at the time of booking + items: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + According to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit). + + If a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG. + example: APZU4812090 + tareWeight: + $ref: '#/components/schemas/TareWeight' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeightReq' + isShipperOwned: + type: boolean + description: | + Indicates whether the container is shipper owned (`SOC`). + example: true + isNonOperatingReefer: + type: boolean + description: | + If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container. + + **Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type. + example: false + activeReeferSettings: + $ref: '#/components/schemas/ActiveReeferSettings' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + commodities: + type: array + description: | + A list of `Commodities` + items: + $ref: '#/components/schemas/CommodityShipper' + description: | + If needed - it is **only** possible to specify a single Reefer setting. If multiple settings are required for the same `equipmentSizeType` then multiple `requestedEquipment` should be specified (one for each Reefer setting). + TareWeight: + title: Tare Weight + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The weight of an empty container (gross container weight). + format: float + example: 4000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + The weight of an empty container (gross container weight). + + **Condition:** In case of Shipper Owned Containers (`SOC`) this is a required property + ContainerPositioning: + title: Container Positioning + required: + - location + type: object + properties: + dateTime: + type: string + description: | + The date and time requested by the shipper for the positioning of the container(s) at the Container positioning location (`CPO`), if provided, or the Place of Receipt (`PRE`) if `CPO` location is not provided. + format: date-time + example: 2024-09-04T09:41:00Z + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + description: | + An object to capture the `Location` together with an optional `Date and Time`. + ContainerPositioningEstimated: + title: Container Positioning Estimated + required: + - location + type: object + properties: + estimatedDateTime: + type: string + description: | + The estimated date and time for the positioning of the container(s) at the `Container Positioning Location` (CPO), if provided, or the `Place of Receipt` (PRE) if CPO location is not provided. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + format: date-time + example: 2024-09-04T09:41:00Z + location: + $ref: '#/components/schemas/ContainerPositioningLocation' + description: | + An object to capture the `Location` together with an optional `Date and Time`. + ContainerPositioningLocation: + title: Container Positioning Location + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Shanghai Shengdong International Container Terminal + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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' + description: | + An object to capture the `Container Positioning Location`. + + The location of the customer facility where the container(s) will be loaded. + + **Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + EmptyContainerDepotReleaseLocation: + title: Empty Container Depot Release Location + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Shanghai Shengdong International Container Terminal + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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' + description: | + An object to capture the `Empty Container Depot Release Location`. + + The location of the depot from which the empty container(s) will be released from + + The location can be specified in **any** of the following ways: `Address`, `Facility`, `UN Location Code` or a `GeoCoordinate`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + CommodityShipper: + title: Commodity (Shipper) + required: + - commodityType + type: object + properties: + commodityType: + maxLength: 550 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + maxLength: 10 + minLength: 6 + pattern: "^\\d{6,10}$" + type: string + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: "851713" + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/ReferenceShipper' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + description: | + Type of goods, defined by its commodity type + Commodity: + title: Commodity + required: + - commodityType + type: object + properties: + commoditySubReference: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + A unique reference for this commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link the consignment item to this commodity. A commodity reference is only unique in the context of a booking. + + **Condition:** Mandatory to provide for `CONFIRMED` bookings + example: COM-001 + commodityType: + maxLength: 550 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + High-level description of goods to be shipped which allow the carrier to confirm acceptance and commercial terms. To be replaced by "description of goods" upon submission of `Shipping Instructions` + example: Mobile phones + HSCodes: + type: array + description: | + A list of `HS Codes` that apply to this `commodity` + items: + maxLength: 10 + minLength: 6 + pattern: "^\\d{6,10}$" + type: string + description: | + Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits. + + More information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools). + example: "851713" + nationalCommodityCodes: + type: array + description: | + A list of `National Commodity Codes` that apply to this `commodity` + items: + $ref: '#/components/schemas/NationalCommodityCode' + cargoGrossWeight: + $ref: '#/components/schemas/CargoGrossWeight' + cargoGrossVolume: + $ref: '#/components/schemas/CargoGrossVolume' + cargoNetWeight: + $ref: '#/components/schemas/CargoNetWeight' + cargoNetVolume: + $ref: '#/components/schemas/CargoNetVolume' + exportLicense: + $ref: '#/components/schemas/ExportLicense' + importLicense: + $ref: '#/components/schemas/ImportLicense' + outerPackaging: + $ref: '#/components/schemas/OuterPackaging' + references: + type: array + description: | + A list of `References` + items: + $ref: '#/components/schemas/Reference' + customsReferences: + type: array + description: | + A list of `Customs references` + items: + $ref: '#/components/schemas/CustomsReference' + description: | + Type of goods, defined by its commodity type + ExportLicense: + title: Export License + type: object + 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.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n" + example: true + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + 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 + description: | + Issue date of the `Export License` applicable to the booking. + format: date + example: 2024-09-14 + expiryDate: + type: string + description: | + Expiry date of the `Export License` applicable to the booking. + format: date + example: 2024-09-21 + description: | + `Export License` required for this commodity + ImportLicense: + title: Import License + type: object + 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.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n" + example: true + reference: + maxLength: 35 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that athorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival. + example: EMC007123 + issueDate: + type: string + description: | + Issue date of the `Import License` applicable to the booking. + format: date + example: 2024-09-14 + expiryDate: + type: string + description: | + Expiry date of the `Import License` applicable to the booking. + format: date + example: 2024-09-21 + description: | + `Import License` required for this commodity + CargoGrossWeightReq: + title: Cargo Gross Weight (Requested Equipment) + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + format: float + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Commodity` level + CargoGrossWeight: + title: Cargo Gross Weight + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + format: float + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + The estimated grand total gross weight of the cargo, including packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + + **Condition:** Mandatory if not provided on `Requested Equipment` level. + CargoGrossVolume: + title: Cargo Gross Volume + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The estimated grand total volume of the cargo. + format: float + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + example: MTQ + enum: + - MTQ + - FTQ + description: | + The estimated grand total volume of the cargo. + CargoNetWeight: + title: Cargo Net Weight + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + format: float + example: 36000 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + The estimated grand total net weight of the cargo, excluding packaging items being carried, which can be expressed in imperial or metric terms, as provided by the shipper. + CargoNetVolume: + title: Cargo Net Volume + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The estimated net total volume of the cargo. + format: float + example: 360 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + example: MTQ + enum: + - MTQ + - FTQ + description: | + The estimated net total volume of the cargo. + NationalCommodityCode: + title: National Commodity Code + required: + - type + - values + type: object + properties: + type: + maxLength: 10 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: BR + values: + minItems: 1 + type: array + description: | + A list of `national commodity codes` values. + example: + - "1515" + - "2106" + - "2507" + - "2512" + items: + maxLength: 10 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The value of the `National Commodity Code` + example: "1515" + 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']| + OuterPackaging: + title: Outer Packaging + type: object + properties: + packageCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z0-9]{2}$" + type: string + 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: + maxLength: 5 + minLength: 1 + pattern: "^[A-Z0-9]{1,5}$" + type: string + 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: + maximum: 99999999 + minimum: 1 + type: integer + description: | + Specifies the number of outer packagings/overpacks associated with this `Commodity`. + + **Condition:** In case this `OuterPackaging` includes `Dangerous Goods` the `numberOfPackages` is mandatory to provide + format: int32 + example: 18 + description: + maxLength: 100 + type: string + description: | + Description of the outer packaging/overpack. + example: "Drum, steel" + dangerousGoods: + type: array + description: | + A list of `Dangerous Goods` related to the `Commodity` + items: + $ref: '#/components/schemas/DangerousGoods' + description: | + Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport. + + **Condition:** Mandatory for DG (Dangerous Goods) cargo. + DangerousGoods: + title: Dangerous Goods + required: + - emergencyContactDetails + - grossWeight + - imoClass + - isCompetentAuthorityApprovalRequired + - isEmptyUncleanedResidue + - isExceptedQuantity + - isHot + - isLimitedQuantity + - isMarinePollutant + - isReportableQuantity + - isSalvagePackings + - isWaste + - properShippingName + type: object + properties: + codedVariantList: + maxLength: 4 + minLength: 4 + pattern: "^[0-3][0-9A-Z]{3}$" + type: string + 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: + maxLength: 250 + type: string + 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: + maxLength: 250 + type: string + 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: + maxLength: 4 + type: string + 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: + maxLength: 3 + minLength: 1 + pattern: "^[0-9](\\.[0-9])?$" + type: string + description: | + Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code. + example: "1.2" + subsidiaryRisk2: + maxLength: 3 + minLength: 1 + pattern: "^[0-9](\\.[0-9])?$" + type: string + 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: + maximum: 3 + minimum: 1 + type: integer + description: | + The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code. + format: int32 + 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: + maxLength: 70 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + maxLength: 2 + type: string + 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: + maxLength: 7 + type: string + 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 + description: | + Date by when the refrigerated liquid needs to be delivered. + format: date + example: 2021-09-03 + fumigationDateTime: + type: string + description: | + Date & time when the container was fumigated + format: date-time + 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: + maxLength: 1 + minLength: 1 + type: string + description: | + The zone classification of the toxicity of the inhalant. Possible values are: + - `A` (Hazard Zone A) can be assigned to specific gases and liquids + - `B` (Hazard Zone B) can be assigned to specific gases and liquids + - `C` (Hazard Zone C) can **only** be assigned to specific gases + - `D` (Hazard Zone D) can **only** be assigned to specific gases + example: A + grossWeight: + $ref: '#/components/schemas/GrossWeight' + netWeight: + $ref: '#/components/schemas/NetWeight' + netExplosiveContent: + $ref: '#/components/schemas/NetExplosiveContent' + netVolume: + $ref: '#/components/schemas/NetVolume' + limits: + $ref: '#/components/schemas/Limits' + specialCertificateNumber: + maxLength: 255 + type: string + description: | + Text field to indicate certificate number & segment for specific stowage requirements overruling IMDG code + example: 22663:3 + additionalContainerCargoHandling: + maxLength: 255 + type: string + description: | + Text field to provide cargo handling information already known at the booking stage. + example: To be handled with extreme care + description: | + Specification for `Dangerous Goods`. It is mandatory to either provide the `UNNumber` or the `NANumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**. + oneOf: + - title: UN Number + required: + - UNNumber + type: object + properties: + UNNumber: + maxLength: 4 + minLength: 4 + pattern: "^\\d{4}$" + type: string + 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" + - title: NA Number + required: + - NANumber + type: object + properties: + NANumber: + maxLength: 4 + minLength: 4 + pattern: "^\\d{4}$" + type: string + description: | + Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation. + example: "9037" + GrossWeight: + title: Gross Weight + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + 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. + format: float + example: 12000.3 + unit: + type: string + description: | + The unit of measure which can be expressed in imperial or metric terms + + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + Total weight of the goods carried, including packaging. + NetWeight: + title: Net Weight + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + Total weight of the goods carried, excluding packaging. + format: float + example: 2.4 + unit: + type: string + description: | + Unit of measure used to describe the `netWeight`. Possible values are + + - `KGM` (Kilograms) + - `LBR` (Pounds) + example: KGM + enum: + - KGM + - LBR + description: | + Total weight of the goods carried, excluding packaging. + NetExplosiveContent: + title: Net Explosive Content + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + format: float + example: 2.4 + unit: + type: string + description: | + Unit of measure used to describe the `netExplosiveWeight`. Possible values are + + - `KGM` (Kilograms) + - `LBR` (Pounds) + - `GRM` (Grams) + - `ONZ` (Ounce) + example: KGM + enum: + - KGM + - LBR + - GRM + - ONZ + description: | + The total weight of the explosive substances, without the packaging’s, casings, etc. + NetVolume: + title: Net Volume + required: + - unit + - value + type: object + properties: + value: + minimum: 0 + exclusiveMinimum: true + type: number + description: | + The volume of the referenced dangerous goods. + format: float + example: 2.4 + unit: + type: string + description: | + The unit of measure which can be expressed in either imperial or metric terms + + - `FTQ` (Cubic foot) + - `MTQ` (Cubic meter) + - `LTR` (Litre) + example: MTQ + enum: + - MTQ + - FTQ + - LTR + description: | + The volume of the referenced dangerous goods. + + **Condition:** only applicable to liquids and gas. + InnerPackaging: + title: Inner Packaging + required: + - description + - material + - quantity + type: object + properties: + quantity: + type: integer + description: | + Count of `Inner Packagings` of the referenced `Dangerous Goods`. + format: int32 + example: 20 + material: + maxLength: 100 + type: string + description: | + The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`. + example: Plastic + description: + maxLength: 100 + type: string + description: | + Description of the packaging. + example: Woven plastic water resistant Bag + description: | + Object for inner packaging specification + EmergencyContactDetails: + title: Emergency Contact Details + required: + - contact + - phone + type: object + properties: + contact: + maxLength: 255 + type: string + description: | + Name of the Contact person during an emergency. + example: Henrik Larsen + provider: + maxLength: 255 + type: string + description: | + Name of the third party vendor providing emergency support + example: GlobeTeam + phone: + maxLength: 30 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + maxLength: 255 + type: string + description: | + Contract reference for the emergency support provided by an external third party vendor. + example: "12234" + description: | + 24 hr emergency contact details + Limits: + title: Limits + required: + - temperatureUnit + type: object + properties: + temperatureUnit: + type: string + description: | + The unit for **all attributes in the limits structure** in Celsius or Fahrenheit + - `CEL` (Celsius) + - `FAH` (Fahrenheit) + example: CEL + enum: + - CEL + - FAH + flashPoint: + type: number + 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. + format: float + example: 42 + transportControlTemperature: + type: number + 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. + format: float + example: 24.1 + transportEmergencyTemperature: + type: number + description: | + Temperature at which emergency procedures shall be implemented + format: float + example: 74.1 + SADT: + type: number + description: | + Lowest temperature in which self-accelerating decomposition may occur in a substance + format: float + example: 54.1 + SAPT: + type: number + description: | + Lowest temperature in which self-accelerating polymerization may occur in a substance + format: float + example: 70 + description: | + Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure. + ConfirmedEquipment: + title: Confirmed Equipment + required: + - ISOEquipmentCode + - units + type: object + properties: + ISOEquipmentCode: + maxLength: 4 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard. + example: 22G1 + units: + minimum: 1 + type: integer + description: | + Number of confirmed equipment units + format: int32 + example: 3 + containerPositionings: + type: array + description: "A list of date and time and locations of the customer facility where the container(s) will be loaded. If multiple Container positioning locations (`CPO`) are provided (multi-stop), the first location is where the empty container will be stuffed first. The order in which the `CPO` locations should be visited is implicitly defined by the shipper based on the date and time provided per location (all times are estimated).\n\n**Condition:** Only applicable to carrier haulage service at origin (`Receipt type at origin = 'SD'`). \n" + items: + $ref: '#/components/schemas/ContainerPositioningEstimated' + emptyContainerPickup: + $ref: '#/components/schemas/EmptyContainerPickup' + description: | + The confirmed equipments for the booking + EmptyContainerPickup: + title: Empty Container Pickup + type: object + properties: + dateTime: + type: string + description: | + The date and time for the pick-up of the empty container(s) at the Empty container depot release location, if provided. + format: date-time + example: 2024-09-04T09:41:00Z + depotReleaseLocation: + $ref: '#/components/schemas/EmptyContainerDepotReleaseLocation' + description: | + The date and time and location for the empty container pick-up. + + **Condition:** Only applicable to merchant haulage service at origin (`Receipt type at origin = 'CY'`). + Transport: + title: Transport + required: + - dischargeLocation + - loadLocation + - plannedArrivalDate + - plannedDepartureDate + - transportPlanStage + - transportPlanStageSequenceNumber + type: object + properties: + transportPlanStage: + type: string + description: | + Code qualifying a specific stage of transport e.g. pre-carriage, main carriage transport or on-carriage transport + - `PRC` (Pre-Carriage) + - `MNC` (Main Carriage Transport) + - `ONC` (On-Carriage Transport) + example: PRC + enum: + - PRC + - MNC + - ONC + transportPlanStageSequenceNumber: + type: integer + description: | + Sequence number of the transport plan stage + format: int32 + example: 5 + loadLocation: + $ref: '#/components/schemas/LoadLocation' + dischargeLocation: + $ref: '#/components/schemas/DischargeLocation' + plannedDepartureDate: + type: string + description: | + The planned date of departure. + format: date + example: 2021-05-17 + plannedArrivalDate: + type: string + description: | + The planned date of arrival. + format: date + example: 2021-05-19 + modeOfTransport: + maxLength: 50 + type: string + description: | + The mode of transport as defined by DCSA. The currently supported values include: + - `VESSEL` (Vessel) + - `RAIL` (Rail) + - `TRUCK` (Truck) + - `BARGE` (Barge) + - `MULTIMODAL` (if multiple modes are used) + example: VESSEL + vesselName: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + maxLength: 8 + minLength: 7 + pattern: "^\\d{7,8}$" + type: string + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: "9321483" + carrierServiceCode: + maxLength: 11 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The carrier-specific code of the service for which the schedule details are published. + example: FE1 + universalServiceReference: + maxLength: 8 + minLength: 8 + pattern: "^SR\\d{5}[A-Z]$" + type: string + description: | + A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. + example: SR12345A + carrierImportVoyageNumber: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + example: 2103N + universalImportVoyageReference: + maxLength: 5 + minLength: 5 + pattern: "^\\d{2}[0-9A-Z]{2}[NEWSR]$" + type: string + description: | + A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + carrierExportVoyageNumber: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + example: 2103S + universalExportVoyageReference: + maxLength: 5 + minLength: 5 + pattern: "^\\d{2}[0-9A-Z]{2}[NEWSR]$" + type: string + description: | + A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]` + - `2 digits` for the year + - `2 alphanumeric characters` for the sequence number of the voyage + - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip). + example: 2103N + description: | + A single `leg` of the `Transport Plan` + LoadLocation: + title: Load Location + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Port of Amsterdam + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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 + description: | + An object to capture the `Load Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Shanghai Shengdong International Container Terminal + UNLocationCode: CNSGH + facility: + facilityCode: SHENG + facilityCodeListProvider: SMDG + DischargeLocation: + title: Discharge Location + type: object + properties: + locationName: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + description: The name of the location. + example: Port of Amsterdam + address: + $ref: '#/components/schemas/Address' + facility: + $ref: '#/components/schemas/Facility' + UNLocationCode: + maxLength: 5 + minLength: 5 + pattern: "^[A-Z]{2}[A-Z2-9]{3}$" + type: string + 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 + description: | + An object to capture the `Discharge Location`. + + The location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`. + + **Condition:** It is expected that if a location is specified in multiple ways (e.g. both as an `Address` and as a `Facility`) that both ways point to the same location. + example: + locationName: Transnet Port Terminals Cape Town + UNLocationCode: ZACPT + facility: + facilityCode: TNCT + facilityCodeListProvider: SMDG + ShipmentCutOffTime: + title: Shipment Cut-Off Time + required: + - cutOffDateTime + - cutOffDateTimeCode + type: object + properties: + cutOffDateTimeCode: + maxLength: 3 + type: string + description: | + Code for the cut-off time. Possible values are: + - `DCO` (Documentation cut-off) + - `VCO` (VGM cut-off) + - `FCO` (FCL delivery cut-off) + - `LCO` (LCL delivery cut-off) **Condition:** only when the `Receipt Type at Origin` is `CFS` + - `EFC` (Earliest full-container delivery date) + example: DCO + cutOffDateTime: + type: string + description: | + Actual cut-off time + format: date-time + example: 2024-09-04T09:41:00Z + description: | + `Cut off times` defined by the carrier + AdvanceManifestFiling: + title: Advance Manifest Filing + required: + - manifestTypeCode + type: object + properties: + manifestTypeCode: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The Manifest type code as defined by the provider. + example: ACE + countryCode: + maxLength: 2 + minLength: 2 + pattern: "^[A-Z]{2}$" + 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) + example: US + 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)| + example: + manifestTypeCode: ACE + countryCode: US + Charge: + title: Charge + required: + - calculationBasis + - chargeName + - currencyAmount + - currencyCode + - paymentTermCode + - quantity + - unitPrice + type: object + properties: + chargeName: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + Free text field describing the charge to apply + example: Documentation fee - Destination + currencyAmount: + minimum: 0 + type: number + description: | + The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals. + format: float + example: 1012.12 + currencyCode: + maxLength: 3 + minLength: 3 + pattern: "^[A-Z]{3}$" + type: string + description: | + The currency for the charge, using a 3-character code according to [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). + example: DKK + paymentTermCode: + type: string + description: | + An indicator of whether a charge is prepaid (PRE) or collect (COL). When prepaid, the charge is the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charge is the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + calculationBasis: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + 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: + minimum: 0 + type: number + description: | + The unit price of this charge item in the currency of the charge. + format: float + example: 3456.6 + quantity: + minimum: 0 + type: number + description: | + The amount of unit for this charge item. + format: float + example: 34.4 + description: | + Addresses the monetary value of freight and other service charges for a `Booking`. + OriginChargesPaymentTerm: + title: Origin Charges Payment Term + type: object + 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) + example: PRE + enum: + - PRE + - COL + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + 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). + DestinationChargesPaymentTerm: + title: Destination Charges Payment Term + type: object + 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) + example: PRE + enum: + - PRE + - COL + portChargesPaymentTermCode: + type: string + description: | + An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + otherChargesPaymentTermCode: + type: string + description: | + An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`). + + - `PRE` (Prepaid) + - `COL` (Collect) + example: PRE + enum: + - PRE + - COL + 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). + Vessel: + title: Vessel + required: + - name + type: object + properties: + name: + maxLength: 50 + pattern: ^\S(?:.*\S)?$ + type: string + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselIMONumber: + maxLength: 8 + minLength: 7 + pattern: "^\\d{7,8}$" + type: string + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: "9321483" + description: | + Vessels related to this booking request. + + **Condition:** Mandatory if `carrierExportVoyageNumber` is provided and `carrierServiceCode` or `carrierServiceName` are blank. + parameters: + Api-Version-Major: + name: API-Version + in: header + 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. + required: false + style: simple + explode: false + schema: + type: string + example: "2" + amendedContent: + name: amendedContent + in: query + description: | + Controls whether the content of this payload is the amended Booking (`amendedContent=true`) or the confirmed Booking (`amendedContent=false`). + + If `amendedContent=true` and no amendment has been requested or if the provider is not able to send the amendment - the response will be a `404` Not Found + required: false + style: form + explode: true + schema: + type: boolean + example: false + default: false + bookingReferencePathParam: + name: bookingReference + in: path + description: | + This can be one of: + - `carrierBookingRequestReference` (in case no carrierBookingReference has yet been appointed to the booking) + - `carrierBookingReference` + required: true + style: simple + explode: false + schema: + maxLength: 100 + pattern: ^\S(?:.*\S)?$ + type: string + example: CBR001 + headers: + API-Version: + description: | + SemVer used to indicate the version of the contract (API version) returned. + style: simple + explode: false + schema: + type: string + example: 2.0.0 diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/EblIssuanceComponentFactory.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/EblIssuanceComponentFactory.java index 4b293f09..c8a753a3 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/EblIssuanceComponentFactory.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/EblIssuanceComponentFactory.java @@ -102,7 +102,7 @@ public Set getReportRoleNames( public JsonSchemaValidator getMessageSchemaValidator(String apiProviderRole, boolean forRequest, boolean issuanceManifest) { String schemaFilePath = - "/standards/eblissuance/schemas/eblissuance-v%s.json" + "/standards/eblissuance/schemas/EBL_ISS_v%s.yaml" .formatted(standardVersion); String schemaName = EblIssuanceRole.isCarrier(apiProviderRole) ? (forRequest ? "IssuanceRequest" : null) diff --git a/ebl-issuance/src/main/resources/standards/eblissuance/schemas/EBL_ISS_v3.0.0.yaml b/ebl-issuance/src/main/resources/standards/eblissuance/schemas/EBL_ISS_v3.0.0.yaml new file mode 100644 index 00000000..116aa7c4 --- /dev/null +++ b/ebl-issuance/src/main/resources/standards/eblissuance/schemas/EBL_ISS_v3.0.0.yaml @@ -0,0 +1,3458 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_ISS/3.0.0' +info: + version: 3.0.0 + title: DCSA eBL Issuance API + description: | +

DCSA OpenAPI specification for the issuance of an electronic Bill of Lading (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.0) API. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design) + + For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/issuance#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'http://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 DCSA_EBL_ISS_RSP API 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.0 + 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 + 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 to provide if `temperatureSetpoint` is provided + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 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 to provide if `airExchange` is provided + 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` 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 + 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` 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 + 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 + 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 + + 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 + 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 + + 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. + + The location can be specified as one of `UN Location Code` or `CountryCode`. + 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 athorizes 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-issuance/src/main/resources/standards/eblissuance/schemas/eblissuance-v3.0.0.json b/ebl-issuance/src/main/resources/standards/eblissuance/schemas/eblissuance-v3.0.0.json deleted file mode 100644 index b64ff8d9..00000000 --- a/ebl-issuance/src/main/resources/standards/eblissuance/schemas/eblissuance-v3.0.0.json +++ /dev/null @@ -1,3154 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA eBL Issuance API", - "description": "

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

\n\nThis API is intended as an API between a carrier and a EBL Solution Platform.\n\nThe EBL Solution Provider is to implement\n\n PUT /v3/ebl-issuance-requests\n\nfor the carrier to call and the carrier is to implement\n\n POST /v3/ebl-issuance-responses\n\nfor the EBL Solution Provider to call.\n\nWhen 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.0) API.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/issuance#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n\nAPI specification issued by [DCSA.org](https://dcsa.org/).\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "3.0.0" - }, - "servers": [ - { - "url": "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_ISS/3.0.0", - "description": "SwaggerHub API Auto Mocking" - } - ], - "tags": [ - { - "name": "Issuance EBL", - "description": "Issuance EBL **implemented** by EBL Solution Platform\n" - }, - { - "name": "Issuance Response", - "description": "Issuance Response **implemented** by carrier\n" - } - ], - "paths": { - "/v3/ebl-issuance-requests": { - "put": { - "tags": [ - "Issuance EBL" - ], - "summary": "Request issuance of an EBL", - "description": "Submit a transport document (EBL) for issuance\n\n**This endPoint is to be implemented by an EBL Solution Provider for the carrier to call**\n", - "operationId": "put-ebl-issuance-requests", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IssuanceRequest" - } - } - }, - "required": true - }, - "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.\n\nNote 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.\n", - "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. \n\nThe 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 DCSA_EBL_ISS_RSP API 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.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "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" - ], - "summary": "Respond to a transport document issuance request", - "description": "Submit a response to a carrier issuance request.\n\n**This endPoint is to be implemented by a carrier for the EBL Solution Provider to call**\n", - "operationId": "create-ebl-issuance-response", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IssuanceResponse" - } - } - }, - "required": true - }, - "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": { - "schemas": { - "ErrorResponse": { - "title": "Error Response", - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "example": "POST", - "enum": [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ] - }, - "requestUri": { - "type": "string", - "description": "The URI that was requested.\n", - "example": "/v1/events" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code returned.\n", - "format": "int32", - "example": 400 - }, - "statusCodeText": { - "maxLength": 50, - "type": "string", - "description": "A standard short description corresponding to the HTTP status code.\n", - "example": "Bad Request" - }, - "statusCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the HTTP status code with additional information.\n", - "example": "The supplied data could not be accepted" - }, - "providerCorrelationReference": { - "maxLength": 100, - "type": "string", - "description": "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example": "4426d965-0dd8-4005-8c63-dc68b01c4962" - }, - "errorDateTime": { - "type": "string", - "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.\n", - "format": "date-time", - "example": "2024-09-04T09:41:00Z" - }, - "errors": { - "minItems": 1, - "type": "array", - "description": "An array of errors providing more detail about the root cause.\n", - "items": { - "$ref": "#/components/schemas/DetailedError" - } - } - }, - "description": "Unexpected error" - }, - "DetailedError": { - "title": "Detailed Error", - "required": [ - "errorCodeMessage", - "errorCodeText" - ], - "type": "object", - "properties": { - "errorCode": { - "maximum": 9999, - "minimum": 7000, - "type": "integer", - "description": "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n", - "format": "int32", - "example": 7003 - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error.\n", - "example": "facilityCode" - }, - "value": { - "maxLength": 500, - "type": "string", - "description": "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example": "SG SIN WHS" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example": "$.location.facilityCode" - }, - "errorCodeText": { - "maxLength": 100, - "type": "string", - "description": "A standard short description corresponding to the `errorCode`.\n", - "example": "invalidData" - }, - "errorCodeMessage": { - "maxLength": 5000, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.\n", - "example": "Spaces not allowed in facility code" - } - }, - "description": "A detailed description of what has caused the error.\n" - }, - "IssuanceRequest": { - "title": "Issuance Request", - "required": [ - "document", - "issuanceManifestSignedContent", - "issueTo" - ], - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/TransportDocument" - }, - "issueTo": { - "$ref": "#/components/schemas/IssueToParty" - }, - "eBLVisualisationByCarrier": { - "$ref": "#/components/schemas/SupportingDocument" - }, - "issuanceManifestSignedContent": { - "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type": "string", - "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).\nThis attribute is used to provide integrity of various parts of the payload that enable parties to\nvalidate whether a payload matches what the carrier issued originally. Accordingly, the payload is\nsigned by the carrier.\n", - "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA" - } - }, - "description": "Details of the eBL that the carrier requests to have issued.\n\nThe `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).\n" - }, - "SupportingDocument": { - "title": "Supporting Document", - "required": [ - "content", - "name" - ], - "type": "object", - "properties": { - "name": { - "maxLength": 100, - "type": "string", - "example": "Carrier rendered copy of the EBL.pdf" - }, - "content": { - "type": "string", - "description": "The actual contents of the visual rendering.", - "format": "byte", - "example": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAGaSURBVDhPnZO/S0JRFMe/zygxwgqcfZtz0N7SFNgPaKlJpTFLCqwotV9qRYN/gIOL1FK22NISWENT0BTUkNLgIL2iHxYRnc697/kKzdA+cOD8uOec77uXB/oHngMPnd2eSb/pAf5DP2EWhGlQ8ChIikiiQa7vruFacwHdHHwC9nY7mhqgRBTdsbDdA/nVvHQbYnxvHHhnp4XtFZjon4DapTam4Lx4jt7NXlO6WEsreltDA5RFlt4qHDaWXlgrwNnplDX5CcWnIo5vjmWimsGdQV7HjjjJ0gMDAbNZopU1wgwfmQSlL9JCkEkunyMEuLbMFgZZ161G5RsFES5WNrC8lC8Fb49XDlcWWLNVOHqttFGCo90haxUsyeEk8GhEfEm+lA/ZqyyGdof0ocJegMhIpKZZIC8xfhLH0v6SfstCzRubeK42tg9Od3RDm9c4qMV8hWguinAmDHTJvC5bVB6A8nYZtlabTFcjX0EQ6gshNhqTDSbPQGIsUbdZIhT8ZOt0izDFu+dAakI1svX59W/MXGbIveM2or8g+gL+Fn3DwcYf+gAAAABJRU5ErkJggg==" - }, - "contentType": { - "maxLength": 100, - "type": "string", - "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).\n\n**Condition:** This property is mandatory to provide if it differs from `application/pdf`\n", - "example": "application/msword", - "default": "application/pdf" - } - } - }, - "IssuanceManifest": { - "title": "Issuance Manifest", - "required": [ - "documentChecksum", - "issueToChecksum" - ], - "type": "object", - "properties": { - "documentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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.\n", - "example": "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f" - }, - "eBLVisualisationByCarrierChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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.\n", - "example": "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f" - }, - "issueToChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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.\n", - "example": "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f" - } - }, - "description": "Checksums of the carrier provided documents from the issuance time.\n" - }, - "IssueToParty": { - "title": "Issue To Party", - "required": [ - "partyName", - "sendToPlatform" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Globeteam" - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The EBL platform of the transaction party. \nThe value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n", - "example": "BOLE" - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - } - }, - "description": "The party to whom the electronic Bill of Lading (eBL) must be issued.\n" - }, - "IdentifyingCode": { - "title": "Identifying Code", - "required": [ - "codeListProvider", - "partyCode" - ], - "type": "object", - "properties": { - "codeListProvider": { - "maxLength": 100, - "type": "string", - "description": "A list of codes identifying a party. Possible values are:\n\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", - "example": "W3C" - }, - "partyCode": { - "maxLength": 150, - "type": "string", - "description": "Code to identify the party as provided by the code list provider\n", - "example": "MSK" - }, - "codeListName": { - "maxLength": 100, - "type": "string", - "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", - "example": "DID" - } - } - }, - "TaxLegalReference": { - "title": "Tax & Legal Reference", - "required": [ - "countryCode", - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference type code as defined by the relevant tax and/or legal authority.\n", - "example": "PAN" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "IN" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `taxLegalReference`\n", - "example": "AAAAA0000A" - } - }, - "description": "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n" - }, - "TransportDocument": { - "title": "Transport Document", - "required": [ - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "carrierCode", - "carrierCodeListProvider", - "consignmentItems", - "deliveryTypeAtDestination", - "documentParties", - "invoicePayableAt", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "receiptTypeAtOrigin", - "termsAndConditions", - "transportDocumentReference", - "transportDocumentStatus", - "transportDocumentTypeCode", - "transports", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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.\n", - "example": "HHL71800000" - }, - "shippingInstructionsReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example": "e0559d83-00e2-438e-afd9-fdd610c1a008" - }, - "transportDocumentStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Transport Document`. Possible values are:\n- DRAFT\n- APPROVED\n- ISSUED\n- PENDING_SURRENDER_FOR_AMENDMENT\n- SURRENDERED_FOR_AMENDMENT\n- PENDING_SURRENDER_FOR_DELIVERY\n- SURRENDERED_FOR_DELIVERY\n- VOIDED\n", - "example": "DRAFT" - }, - "transportDocumentTypeCode": { - "type": "string", - "description": "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "isShippedOnBoardType": { - "type": "boolean", - "description": "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example": false - }, - "numberOfCopiesWithCharges": { - "minimum": 0, - "type": "integer", - "description": "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "format": "int32", - "example": 2 - }, - "numberOfCopiesWithoutCharges": { - "minimum": 0, - "type": "integer", - "description": "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "format": "int32", - "example": 2 - }, - "numberOfOriginalsWithCharges": { - "minimum": 0, - "type": "integer", - "description": "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n\n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "format": "int32", - "example": 1 - }, - "numberOfOriginalsWithoutCharges": { - "minimum": 0, - "type": "integer", - "description": "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n\n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "format": "int32", - "example": 1 - }, - "displayedNameForPlaceOfReceipt": { - "maxItems": 5, - "type": "array", - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "displayedNameForPortOfLoad": { - "maxItems": 5, - "type": "array", - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "displayedNameForPortOfDischarge": { - "maxItems": 5, - "type": "array", - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "displayedNameForPlaceOfDelivery": { - "maxItems": 5, - "type": "array", - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "shippedOnBoardDate": { - "type": "string", - "description": "Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document.\n\nWhen provided on a transport document, the transportDocument is a `Shipped On Board` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "format": "date", - "example": "2020-12-12" - }, - "displayedShippedOnBoardReceivedForShipment": { - "maxLength": 250, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board.\n", - "example": "Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier" - }, - "termsAndConditions": { - "maxLength": 50000, - "type": "string", - "description": "Carrier terms and conditions of transport.\n", - "example": "Any reference in..." - }, - "receiptTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "deliveryTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Indicates the type of service offered at `Destination`. The options are:\n\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "example": "CY", - "enum": [ - "CY", - "SD", - "CFS" - ] - }, - "cargoMovementTypeAtOrigin": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "cargoMovementTypeAtDestination": { - "maxLength": 3, - "type": "string", - "description": "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example": "FCL" - }, - "issueDate": { - "type": "string", - "description": "Local date when the transport document has been issued.\n\nCan be omitted on draft transport documents, but must be provided when the document has been issued.\n", - "format": "date", - "example": "2020-12-12" - }, - "receivedForShipmentDate": { - "type": "string", - "description": "Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel).\n\nWhen provided on a transport document, the transportDocument is a `Received For Shipment` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "format": "date", - "example": "2020-12-12" - }, - "serviceContractReference": { - "maxLength": 30, - "type": "string", - "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.\n", - "example": "HHL51800000" - }, - "contractQuotationReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n", - "example": "HHL1401" - }, - "declaredValue": { - "minimum": 0, - "type": "number", - "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.\n\n**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).\n", - "format": "float", - "example": 1231.1 - }, - "declaredValueCurrency": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "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).\n", - "example": "DKK" - }, - "carrierCode": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "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.\n", - "example": "MMCU" - }, - "carrierCodeListProvider": { - "type": "string", - "description": "The code list provider for the `carrierCode`. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "example": "NMFTA", - "enum": [ - "SMDG", - "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.\n", - "items": { - "maxLength": 20000, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The content of the clause.\n", - "example": "It is not allowed to..." - } - }, - "numberOfRiderPages": { - "minimum": 0, - "type": "integer", - "description": "The number of additional pages required to contain the goods description on a transport document. Only applicable for physical transport documents.\n", - "format": "int32", - "example": 2 - }, - "transports": { - "$ref": "#/components/schemas/Transports" - }, - "charges": { - "type": "array", - "description": "A list of `Charges`\n", - "items": { - "$ref": "#/components/schemas/Charge" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/PlaceOfIssue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/InvoicePayableAt" - }, - "partyContactDetails": { - "minItems": 1, - "type": "array", - "description": "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "documentParties": { - "$ref": "#/components/schemas/DocumentParties" - }, - "routingOfConsignmentCountries": { - "type": "array", - "description": "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "consignmentItems": { - "minItems": 1, - "type": "array", - "description": "A list of `ConsignmentItems`\n", - "items": { - "$ref": "#/components/schemas/ConsignmentItem" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipment" - } - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "description": "The document that governs the terms of carriage between shipper and carrier for maritime transportation. Two distinct types of transport documents exist:\n- Bill of Lading\n- Sea Waybill. \n" - }, - "PartyContactDetail": { - "title": "Party Contact Detail", - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the contact\n", - "example": "Henrik" - } - }, - "description": "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`.\n", - "example": { - "name": "Henrik", - "phone": "+45 51801234" - }, - "anyOf": [ - { - "title": "Phone required", - "required": [ - "phone" - ], - "type": "object", - "properties": { - "phone": { - "maxLength": 30, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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).\n", - "example": "+45 70262970" - } - }, - "description": "`Phone` is mandatory to provide\n" - }, - { - "title": "Email required", - "required": [ - "email" - ], - "type": "object", - "properties": { - "email": { - "maxLength": 100, - "pattern": "^.+@\\S+$", - "type": "string", - "description": "`E-mail` address to be used\n", - "example": "info@dcsa.org" - } - }, - "description": "`Email` is mandatory to provide\n" - } - ] - }, - "Reference": { - "title": "Reference", - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 3, - "type": "string", - "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n", - "example": "CR" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the reference. \n", - "example": "HHL00103004" - } - }, - "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.\n" - }, - "ReferenceConsignmentItem": { - "title": "Reference (Consignment Item)", - "required": [ - "type", - "values" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 3, - "type": "string", - "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n- `SPO` (Shipper's Purchase Order)\n- `CPO` (Consignee's Purchase Order)\n", - "example": "CR" - }, - "values": { - "minItems": 1, - "type": "array", - "description": "List of `referenceValues` for a given `referenceType`.\n", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the reference. \n", - "example": "HHL00103004" - } - } - }, - "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.\n" - }, - "ConsignmentItem": { - "title": "Consignment Item", - "required": [ - "HSCodes", - "cargoItems", - "carrierBookingReference", - "descriptionOfGoods" - ], - "type": "object", - "properties": { - "carrierBookingReference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The associated booking number provided by the carrier for this `Consignment Item`.\n\nWhen multiple `carrierBookingReferences` are used then the bookings referred to must all contain the same:\n- transportPlan\n- shipmentLocations\n- receiptTypeAtOrigin\n- deliveryTypeAtDestination\n- cargoMovementTypeAtOrigin\n- cargoMovementTypeAtDestination\n- serviceContractReference\n- termsAndConditions\n- Place of B/L Issue (if provided)\n", - "example": "ABC709951" - }, - "descriptionOfGoods": { - "maxItems": 150, - "type": "array", - "description": "An array of lines accurately and properly describing the cargo being shipped in the container(s) as provided by the shipper.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A line describing the cargo", - "example": "blue shoes size 47" - } - }, - "HSCodes": { - "minItems": 1, - "type": "array", - "description": "A list of `HS Codes` that apply to this `consignmentItem`\n", - "items": { - "maxLength": 10, - "minLength": 6, - "pattern": "^\\d{6,10}$", - "type": "string", - "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.\n\nMore information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools).\n", - "example": "851713" - } - }, - "nationalCommodityCodes": { - "type": "array", - "description": "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items": { - "$ref": "#/components/schemas/NationalCommodityCode" - } - }, - "shippingMarks": { - "maxItems": 50, - "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example": "Made in China" - } - }, - "cargoItems": { - "minItems": 1, - "type": "array", - "description": "A list of all `cargoItems`\n", - "items": { - "$ref": "#/components/schemas/CargoItem" - } - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/ReferenceConsignmentItem" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "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`\n" - }, - "NationalCommodityCode": { - "title": "National Commodity Code", - "required": [ - "countryCode", - "type", - "values" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", - "example": "NCM" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "BR" - }, - "values": { - "minItems": 1, - "type": "array", - "description": "A list of `national commodity codes` values.\n", - "example": [ - "1515", - "2106", - "2507", - "2512" - ], - "items": { - "maxLength": 10, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `National Commodity Code`\n", - "example": "1515" - } - } - }, - "description": "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n" - }, - "CustomsReference": { - "title": "Customs Reference", - "required": [ - "countryCode", - "type", - "values" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference type code as defined in the relevant customs jurisdiction.\n", - "example": "ACID" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "EG" - }, - "values": { - "minItems": 1, - "type": "array", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `customsReference`\n", - "example": "4988470982020120017" - } - } - }, - "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n" - }, - "CargoItem": { - "title": "Cargo Item", - "required": [ - "cargoGrossWeight", - "equipmentReference", - "outerPackaging" - ], - "type": "object", - "properties": { - "equipmentReference": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example": "APZU4812090" - }, - "cargoGrossWeight": { - "$ref": "#/components/schemas/CargoGrossWeight" - }, - "cargoGrossVolume": { - "$ref": "#/components/schemas/CargoGrossVolume" - }, - "cargoNetWeight": { - "$ref": "#/components/schemas/CargoNetWeight" - }, - "cargoNetVolume": { - "$ref": "#/components/schemas/CargoNetVolume" - }, - "outerPackaging": { - "$ref": "#/components/schemas/OuterPackaging" - }, - "nationalCommodityCodes": { - "type": "array", - "description": "A list of `National Commodity Codes` that apply to this `cargoItem`\n", - "items": { - "$ref": "#/components/schemas/NationalCommodityCode" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "description": "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n" - }, - "CargoGrossWeight": { - "title": "Cargo Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "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.\n", - "format": "float", - "example": 2400 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container.\n" - }, - "CargoGrossVolume": { - "title": "Cargo Gross Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - } - }, - "description": "Calculated by multiplying the width, height, and length of the packed cargo.\n" - }, - "CargoNetWeight": { - "title": "Cargo Net Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "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.\n", - "format": "float", - "example": 2400 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container.\n" - }, - "CargoNetVolume": { - "title": "Cargo Net Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ" - ] - } - }, - "description": "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n" - }, - "OuterPackaging": { - "title": "Outer Packaging", - "required": [ - "description", - "numberOfPackages" - ], - "type": "object", - "properties": { - "packageCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z0-9]{2}$", - "type": "string", - "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example": "5H" - }, - "imoPackagingCode": { - "maxLength": 5, - "minLength": 1, - "pattern": "^[A-Z0-9]{1,5}$", - "type": "string", - "description": "The code of the packaging as per IMO.\n\n**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.\n", - "example": "1A2" - }, - "numberOfPackages": { - "maximum": 99999999, - "minimum": 1, - "type": "integer", - "description": "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n", - "format": "int32", - "example": 18 - }, - "description": { - "maxLength": 100, - "type": "string", - "description": "Description of the outer packaging/overpack.\n", - "example": "Drum, steel" - }, - "woodDeclaration": { - "maxLength": 30, - "type": "string", - "description": "Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include:\n- `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped)\n- `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate)\n- `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)\n- `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate)\n", - "example": "TREATED_AND_CERTIFIED" - }, - "dangerousGoods": { - "type": "array", - "description": "A list of `Dangerous Goods`\n", - "items": { - "$ref": "#/components/schemas/DangerousGoods" - } - } - }, - "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.\n" - }, - "DangerousGoods": { - "title": "Dangerous Goods", - "required": [ - "imoClass", - "properShippingName" - ], - "type": "object", - "properties": { - "codedVariantList": { - "maxLength": 4, - "minLength": 4, - "pattern": "^[0-3][0-9A-Z]{3}$", - "type": "string", - "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", - "example": "2200" - }, - "properShippingName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "Chromium Trioxide, anhydrous" - }, - "technicalName": { - "maxLength": 250, - "type": "string", - "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.\n", - "example": "xylene and benzene" - }, - "imoClass": { - "maxLength": 4, - "type": "string", - "description": "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n", - "example": "1.4S" - }, - "subsidiaryRisk1": { - "maxLength": 3, - "minLength": 1, - "pattern": "^[0-9](\\.[0-9])?$", - "type": "string", - "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example": "1.2" - }, - "subsidiaryRisk2": { - "maxLength": 3, - "minLength": 1, - "pattern": "^[0-9](\\.[0-9])?$", - "type": "string", - "description": "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example": "1.2" - }, - "isMarinePollutant": { - "type": "boolean", - "description": "Indicates if the goods belong to the classification of Marine Pollutant.\n", - "example": false - }, - "packingGroup": { - "maximum": 3, - "minimum": 1, - "type": "integer", - "description": "The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code.\n", - "format": "int32", - "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.\n", - "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.\n", - "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.\n", - "example": false - }, - "isEmptyUncleanedResidue": { - "type": "boolean", - "description": "Indicates if the cargo is residue.\n", - "example": false - }, - "isWaste": { - "type": "boolean", - "description": "Indicates if waste is being shipped\n", - "example": false - }, - "isHot": { - "type": "boolean", - "description": "Indicates if high temperature cargo is shipped.\n", - "example": false - }, - "isCompetentAuthorityApprovalRequired": { - "type": "boolean", - "description": "Indicates if the cargo require approval from authorities\n", - "example": false - }, - "competentAuthorityApproval": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name and reference number of the competent authority providing the approval.\n", - "example": "{Name and reference...}" - }, - "segregationGroups": { - "type": "array", - "description": "List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code.\n\n**Condition:** only applicable to specific hazardous goods.\n", - "items": { - "maxLength": 2, - "type": "string", - "description": "Grouping of Dangerous Goods having certain similar chemical properties. Possible values are:\n\n- `1` (Acids)\n- `2` (Ammonium Compounds)\n- `3` (Bromates)\n- `4` (Chlorates)\n- `5` (Chlorites)\n- `6` (Cyanides)\n- `7` (Heavy metals and their salts)\n- `8` (Hypochlorites)\n- `9` (Lead and its compounds)\n- `10` (Liquid halogenated hydrocarbons)\n- `11` (Mercury and mercury compounds)\n- `12` (Nitrites and their mixtures)\n- `13` (Perchlorates)\n- `14` (Permanganates)\n- `15` (Powdered metals)\n- `16` (Peroxides),\n- `17` (Azides)\n- `18` (Alkalis)\n", - "example": "12" - } - }, - "innerPackagings": { - "type": "array", - "description": "A list of `Inner Packings` contained inside this `outer packaging/overpack`.\n", - "items": { - "$ref": "#/components/schemas/InnerPackaging" - } - }, - "emergencyContactDetails": { - "$ref": "#/components/schemas/EmergencyContactDetails" - }, - "EMSNumber": { - "maxLength": 7, - "type": "string", - "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.\n", - "example": "F-A S-Q" - }, - "endOfHoldingTime": { - "type": "string", - "description": "Date by when the refrigerated liquid needs to be delivered.\n", - "format": "date", - "example": "2021-09-03" - }, - "fumigationDateTime": { - "type": "string", - "description": "Date & time when the container was fumigated\n", - "format": "date-time", - "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.\n", - "example": false - }, - "inhalationZone": { - "maxLength": 1, - "minLength": 1, - "type": "string", - "description": "The zone classification of the toxicity of the inhalant. Possible values are:\n\n- `A` (Hazard Zone A) can be assigned to specific gases and liquids\n- `B` (Hazard Zone B) can be assigned to specific gases and liquids\n- `C` (Hazard Zone C) can **only** be assigned to specific gases\n- `D` (Hazard Zone D) can **only** be assigned to specific gases\n", - "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" - } - }, - "description": "Specification for `Dangerous Goods`. It is mandatory to either provide the `unNumber` or the `naNumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", - "oneOf": [ - { - "title": "UN Number", - "required": [ - "unNumber" - ], - "type": "object", - "properties": { - "unNumber": { - "maxLength": 4, - "minLength": 4, - "pattern": "^\\d{4}$", - "type": "string", - "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.\n", - "example": "1463" - } - } - }, - { - "title": "NA Number", - "required": [ - "naNumber" - ], - "type": "object", - "properties": { - "naNumber": { - "maxLength": 4, - "minLength": 4, - "pattern": "^\\d{4}$", - "type": "string", - "description": "Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation.\n", - "example": "9037" - } - } - } - ] - }, - "GrossWeight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "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.\n", - "format": "float", - "example": 12000.3 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, including packaging.\n" - }, - "NetWeight": { - "title": "Net Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, excluding packaging.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, excluding packaging.\n" - }, - "NetExplosiveContent": { - "title": "Net Explosive Content", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR", - "GRM", - "ONZ" - ] - } - }, - "description": "The total weight of the explosive substances, without the packaging’s, casings, etc.\n" - }, - "NetVolume": { - "title": "Net Volume", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The volume of the referenced dangerous goods.\n", - "format": "float", - "example": 2.4 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ", - "LTR" - ] - } - }, - "description": "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n" - }, - "InnerPackaging": { - "title": "Inner Packaging", - "required": [ - "description", - "material", - "quantity" - ], - "type": "object", - "properties": { - "quantity": { - "type": "integer", - "description": "Count of `Inner Packagings` of the referenced `Dangerous Goods`.\n", - "format": "int32", - "example": 20 - }, - "material": { - "maxLength": 100, - "type": "string", - "description": "The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`.\n", - "example": "Plastic" - }, - "description": { - "maxLength": 100, - "type": "string", - "description": "Description of the packaging.\n", - "example": "Woven plastic water resistant Bag" - } - }, - "description": "Object for inner packaging specification\n" - }, - "EmergencyContactDetails": { - "title": "Emergency Contact Details", - "required": [ - "contact", - "phone" - ], - "type": "object", - "properties": { - "contact": { - "maxLength": 255, - "type": "string", - "description": "Name of the Contact person during an emergency.\n", - "example": "Henrik Larsen" - }, - "provider": { - "maxLength": 255, - "type": "string", - "description": "Name of the third party vendor providing emergency support\n", - "example": "GlobeTeam" - }, - "phone": { - "maxLength": 30, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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).\n", - "example": "+45 70262970" - }, - "referenceNumber": { - "maxLength": 255, - "type": "string", - "description": "Contract reference for the emergency support provided by an external third party vendor.\n", - "example": "12234" - } - }, - "description": "24 hr emergency contact details\n" - }, - "Limits": { - "title": "Limits", - "required": [ - "temperatureUnit" - ], - "type": "object", - "properties": { - "temperatureUnit": { - "type": "string", - "description": "The unit for **all attributes in the limits structure** in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n", - "example": "CEL", - "enum": [ - "CEL", - "FAH" - ] - }, - "flashPoint": { - "type": "number", - "description": "Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air.\n\n**Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code.\n", - "format": "float", - "example": 42 - }, - "transportControlTemperature": { - "type": "number", - "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.\n", - "format": "float", - "example": 24.1 - }, - "transportEmergencyTemperature": { - "type": "number", - "description": "Temperature at which emergency procedures shall be implemented\n", - "format": "float", - "example": 74.1 - }, - "SADT": { - "type": "number", - "description": "Lowest temperature in which self-accelerating decomposition may occur in a substance\n", - "format": "float", - "example": 54.1 - }, - "SAPT": { - "type": "number", - "description": "Lowest temperature in which self-accelerating polymerization may occur in a substance\n", - "format": "float", - "example": 70 - } - }, - "description": "Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure.\n" - }, - "UtilizedTransportEquipment": { - "title": "Utilized Transport Equipment", - "required": [ - "equipment", - "isShipperOwned", - "seals" - ], - "type": "object", - "properties": { - "equipment": { - "$ref": "#/components/schemas/Equipment" - }, - "isShipperOwned": { - "type": "boolean", - "description": "Indicates whether the container is shipper owned (SOC).\n", - "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.\n\n**Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type.\n", - "example": false - }, - "activeReeferSettings": { - "$ref": "#/components/schemas/ActiveReeferSettings" - }, - "shippingMarks": { - "maxItems": 50, - "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example": "Made in China" - } - }, - "seals": { - "minItems": 1, - "type": "array", - "description": "A list of `Seals`\n", - "items": { - "$ref": "#/components/schemas/Seal" - } - }, - "references": { - "type": "array", - "description": "A list of `References`\n", - "items": { - "$ref": "#/components/schemas/Reference" - } - }, - "customsReferences": { - "type": "array", - "description": "A list of `Customs references`\n", - "items": { - "$ref": "#/components/schemas/CustomsReference" - } - } - }, - "description": "Specifies the container (`equipment`), the total `weight`, total `volume`, possible `ActiveReeferSettings`, `seals` and `references`\n" - }, - "Equipment": { - "title": "Equipment", - "required": [ - "equipmentReference" - ], - "type": "object", - "properties": { - "equipmentReference": { - "maxLength": 11, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example": "APZU4812090" - }, - "ISOEquipmentCode": { - "maxLength": 4, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n", - "example": "22G1" - }, - "tareWeight": { - "$ref": "#/components/schemas/TareWeight" - } - }, - "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.\n" - }, - "TareWeight": { - "title": "Tare Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "unit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "The weight of an empty container (gross container weight).\n" - }, - "Seal": { - "title": "Seal", - "required": [ - "number" - ], - "type": "object", - "properties": { - "number": { - "maxLength": 15, - "type": "string", - "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.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n\n**Condition:** Seal source may be required depending on the type of commodity being shipped.\n", - "example": "CUS", - "enum": [ - "CAR", - "SHI", - "VET", - "CUS" - ] - } - }, - "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.\n" - }, - "ActiveReeferSettings": { - "title": "Active Reefer Settings", - "type": "object", - "properties": { - "temperatureSetpoint": { - "type": "number", - "description": "Target value of the temperature for the Reefer based on the cargo requirement.\n", - "format": "float", - "example": -15 - }, - "temperatureUnit": { - "type": "string", - "description": "The unit for temperature in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", - "example": "CEL", - "enum": [ - "CEL", - "FAH" - ] - }, - "o2Setpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere CO2 target value\n", - "format": "float", - "example": 25 - }, - "co2Setpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere CO2 target value\n", - "format": "float", - "example": 25 - }, - "humiditySetpoint": { - "maximum": 100, - "minimum": 0, - "type": "number", - "description": "The percentage of the controlled atmosphere humidity target value\n", - "format": "float", - "example": 95.6 - }, - "airExchangeSetpoint": { - "minimum": 0, - "type": "number", - "description": "Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container\n", - "format": "float", - "example": 15.4 - }, - "airExchangeUnit": { - "type": "string", - "description": "The unit for `airExchange` in metrics- or imperial- units per hour\n- `MQH` (Cubic metre per hour)\n- `FQH` (Cubic foot per hour)\n\n**Condition:** Mandatory to provide if `airExchange` is provided\n", - "example": "MQH", - "enum": [ - "MQH", - "FQH" - ] - }, - "isVentilationOpen": { - "type": "boolean", - "description": "If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed`\n", - "example": true - }, - "isDrainholesOpen": { - "type": "boolean", - "description": "Is drain holes open on the container\n", - "example": true - }, - "isBulbMode": { - "type": "boolean", - "description": "Is special container setting for handling flower bulbs active\n", - "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\n", - "example": true - }, - "isControlledAtmosphereRequired": { - "type": "boolean", - "description": "Indicator of whether cargo requires Controlled Atmosphere.\n", - "example": true - } - }, - "description": "The specifications for a Reefer equipment.\n\n**Condition:** Only applicable when `isNonOperatingReefer` is set to `false`\n" - }, - "Transports": { - "title": "Transports", - "required": [ - "plannedArrivalDate", - "plannedDepartureDate", - "portOfDischarge", - "portOfLoading", - "vesselVoyages" - ], - "type": "object", - "properties": { - "plannedArrivalDate": { - "type": "string", - "description": "The planned date of arrival.\n", - "format": "date", - "example": "2024-06-07" - }, - "plannedDepartureDate": { - "type": "string", - "description": "The planned date of departure.\n", - "format": "date", - "example": "2024-06-03" - }, - "preCarriageBy": { - "maxLength": 50, - "type": "string", - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example": "RAIL" - }, - "onCarriageBy": { - "maxLength": 50, - "type": "string", - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "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": { - "minItems": 1, - "type": "array", - "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.\n", - "items": { - "$ref": "#/components/schemas/VesselVoyage" - } - } - } - }, - "VesselVoyage": { - "title": "Vessel/Voyage", - "required": [ - "carrierExportVoyageNumber", - "vesselName" - ], - "type": "object", - "properties": { - "vesselName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the first sea going Vessel on board which the cargo is loaded or intended to be loaded\n", - "example": "King of the Seas" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.\n", - "example": "2103S" - }, - "universalExportVoyageReference": { - "maxLength": 5, - "minLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example": "2103N" - } - }, - "description": "Vessel and export voyage" - }, - "PlaceOfReceipt": { - "title": "Place of Receipt", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "geoCoordinate": { - "$ref": "#/components/schemas/GeoCoordinate" - } - }, - "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.\n\n**Condition:** Only when pre-carriage is done by the carrier.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "PortOfLoading": { - "title": "Port of Loading", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "city": { - "$ref": "#/components/schemas/City" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "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.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "PortOfDischarge": { - "title": "Port of Discharge", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "city": { - "$ref": "#/components/schemas/City" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "description": "An object to capture `Port of Discharge` location specified as: the location where the cargo is discharged from the last sea-going vessel.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "PlaceOfDelivery": { - "title": "Place of Delivery", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "geoCoordinate": { - "$ref": "#/components/schemas/GeoCoordinate" - } - }, - "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.\n\n**Condition:** Only when onward transport is done by the carrier\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "OnwardInlandRouting": { - "title": "Onward Inland Routing", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "facility": { - "$ref": "#/components/schemas/Facility" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - } - }, - "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).\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "Charge": { - "title": "Charge", - "required": [ - "calculationBasis", - "chargeName", - "currencyAmount", - "currencyCode", - "paymentTermCode", - "quantity", - "unitPrice" - ], - "type": "object", - "properties": { - "chargeName": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Free text field describing the charge to apply\n", - "example": "Documentation fee - Destination" - }, - "currencyAmount": { - "minimum": 0, - "type": "number", - "description": "The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals.\n", - "format": "float", - "example": 1012.12 - }, - "currencyCode": { - "maxLength": 3, - "minLength": 3, - "pattern": "^[A-Z]{3}$", - "type": "string", - "description": "The currency for the charge, using a 3-character code ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)).\n", - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "example": "PRE", - "enum": [ - "PRE", - "COL" - ] - }, - "calculationBasis": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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.\n", - "example": "Per day" - }, - "unitPrice": { - "minimum": 0, - "type": "number", - "description": "The unit price of this charge item in the currency of the charge.\n", - "format": "float", - "example": 3456.6 - }, - "quantity": { - "minimum": 0, - "type": "number", - "description": "The amount of unit for this charge item.\n", - "format": "float", - "example": 34.4 - } - }, - "description": "Addresses the monetary value of freight and other service charges for a `Booking`.\n" - }, - "Address": { - "title": "Address", - "required": [ - "city", - "countryCode", - "street" - ], - "type": "object", - "properties": { - "street": { - "maxLength": 70, - "type": "string", - "description": "The name of the street.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The floor of the street number.\n", - "example": "N/A" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code.", - "example": "1047 HM" - }, - "POBox": { - "maxLength": 20, - "type": "string", - "description": "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example": "123" - }, - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the city.\n", - "example": "Amsterdam" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The name of the state/region.", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing address related information\n" - }, - "City": { - "title": "City", - "required": [ - "city", - "countryCode" - ], - "type": "object", - "properties": { - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the city.\n", - "example": "Amsterdam" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The name of the state/region.\n", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing city, state/region and country related information\n" - }, - "Facility": { - "title": "Facility", - "required": [ - "facilityCode", - "facilityCodeListProvider" - ], - "type": "object", - "properties": { - "facilityCode": { - "maxLength": 6, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\nThe definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used:\n- `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/))\n- `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`\n- `BIC` (Requires a UN Location Code)\n- `SMDG` (Requires a UN Location Code)\n", - "example": "SMDG", - "enum": [ - "BIC", - "SMDG" - ] - } - }, - "description": "An interface used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute.\n" - }, - "GeoCoordinate": { - "title": "Geo Coordinate", - "required": [ - "latitude", - "longitude" - ], - "type": "object", - "properties": { - "latitude": { - "maxLength": 10, - "type": "string", - "description": "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", - "example": "48.8585500" - }, - "longitude": { - "maxLength": 11, - "type": "string", - "description": "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", - "example": "2.294492036" - } - }, - "description": "An object used to express a location using `latitude` and `longitude`.\n" - }, - "OtherDocumentParty": { - "title": "Other Document Party", - "required": [ - "party", - "partyFunction" - ], - "type": "object", - "properties": { - "party": { - "$ref": "#/components/schemas/Party" - }, - "partyFunction": { - "maxLength": 3, - "type": "string", - "description": "Specifies the role of the party in a given context. Possible values are:\n\n- `SCO` (Service Contract Owner)\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `COW` (Invoice payer on behalf of the consignor (shipper))\n- `COX` (Invoice payer on behalf of the consignee)\n", - "example": "DDS" - } - }, - "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n" - }, - "PartyAddress": { - "title": "Party Address", - "required": [ - "city", - "countryCode", - "street" - ], - "type": "object", - "properties": { - "street": { - "maxLength": 70, - "type": "string", - "description": "The name of the street of the party’s address.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street of the party’s address.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The floor of the party’s street number.\n", - "example": "2nd" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code of the party’s address.", - "example": "1047 HM" - }, - "POBox": { - "maxLength": 20, - "type": "string", - "description": "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example": "123" - }, - "city": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The city name of the party’s address.\n", - "example": "Amsterdam" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example": "NLAMS" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The state/region of the party’s address.", - "example": "North Holland" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - }, - "description": "An object for storing address related information\n" - }, - "Shipper": { - "title": "Shipper", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "typeOfPerson": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example": "NATURAL_PERSON" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "displayedAddress": { - "maxItems": 6, - "type": "array", - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A single address line\n", - "example": "Strawinskylaan 4117" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Shipper`.\n", - "example": "HHL007" - }, - "purchaseOrderReferences": { - "type": "array", - "description": "A list of `Purchase Order Reference`s linked to the `Shipper`.\n", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A purchase order reference linked to the `Shipper`.\n", - "example": "HHL007" - } - } - }, - "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.\n\n**Condition:** Either the `address` or the `displayedAddress` must be included in the `Transport Document`.\n" - }, - "Consignee": { - "title": "Consignee", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "typeOfPerson": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example": "NATURAL_PERSON" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "displayedAddress": { - "maxItems": 6, - "type": "array", - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A single address line\n", - "example": "Strawinskylaan 4117" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Consignee`.\n", - "example": "HHL007" - }, - "purchaseOrderReferences": { - "type": "array", - "description": "A list of `Purchase Order Reference`s linked to the `Consignee`.\n", - "items": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A purchase order reference linked to the `Consignee`.\n", - "example": "HHL007" - } - } - }, - "description": "The party to which goods are consigned in the `Master Bill of Lading`.\n\n**Condition:** Mandatory for non-negotiable BL (`isToOrder=false`)\n" - }, - "Endorsee": { - "title": "Endorsee", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "displayedAddress": { - "maxItems": 6, - "type": "array", - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A single address line\n", - "example": "Strawinskylaan 4117" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - } - }, - "description": "The party to whom the title to the goods is transferred by means of endorsement.\n\n**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.\n" - }, - "CarriersAgentAtDestination": { - "title": "Carrier's Agent At Destination", - "required": [ - "address", - "partyContactDetails", - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - } - }, - "description": "The party on the import side assigned by the carrier to whom the customer need to reach out to for cargo release.\n" - }, - "NotifyParty": { - "title": "Notify Party", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "IKEA Denmark" - }, - "typeOfPerson": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example": "NATURAL_PERSON" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "displayedAddress": { - "maxItems": 6, - "type": "array", - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items": { - "maxLength": 35, - "type": "string", - "description": "A single address line\n", - "example": "Strawinskylaan 4117" - } - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `NotifyParty`.\n", - "example": "HHL007" - } - }, - "description": "The person to be notified when a shipment arrives at its destination.\n" - }, - "Party": { - "title": "Party", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Asseco Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - }, - "reference": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A reference linked to the `Party`.\n", - "example": "HHL007" - } - }, - "description": "Refers to a company or a legal entity.\n" - }, - "IssuingParty": { - "title": "Issuing Party", - "required": [ - "address", - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Asseco Denmark" - }, - "address": { - "$ref": "#/components/schemas/PartyAddress" - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - }, - "partyContactDetails": { - "type": "array", - "description": "A list of contact details\n", - "items": { - "$ref": "#/components/schemas/PartyContactDetail" - } - } - }, - "description": "Refers to a company or a legal entity.\n" - }, - "IssuanceError": { - "title": "Issuance Error", - "type": "object", - "properties": { - "reason": { - "maxLength": 255, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Human readable description of the rationale for an unsuccessful issuance.\n\nThe `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`.\n", - "example": "Cannot get..." - }, - "errorCode": { - "maxLength": 50, - "pattern": "^\\S+$", - "type": "string", - "description": "A vendor provided error code.\n\nThe meaning of each code is agreed bilaterally between the vendor.\n", - "example": "ERR-1234" - } - } - }, - "IssuanceResponse": { - "title": "Issuance Response", - "required": [ - "issuanceResponseCode", - "transportDocumentReference" - ], - "type": "object", - "properties": { - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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.\n", - "example": "HHL71800000" - }, - "issuanceResponseCode": { - "type": "string", - "description": "The platforms verdict on the issuance of the EBL identified by the `transportDocumentReference`\n\nOptions are:\n - `ISSU`: The document was successfully `ISSU` and successfully delivered to the initial possessor.\n - `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.\n - `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.\n\nRegardless 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.\n", - "example": "ISSU", - "enum": [ - "ISSU", - "BREQ", - "REFU" - ] - }, - "reason": { - "maxLength": 255, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Human readable description of the rationale for an unsuccessful issuance.\n\nThe `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`.\n", - "example": "Cannot get..." - }, - "errors": { - "maxItems": 255, - "type": "array", - "description": "A list of errors if the issuance failed for some reason.\n", - "items": { - "$ref": "#/components/schemas/IssuanceError" - } - } - } - }, - "PlaceOfIssue": { - "title": "Place of Issue", - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - } - }, - "description": "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", - "oneOf": [ - { - "title": "UN Location Code", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example": "NLAMS" - } - } - }, - { - "title": "Country Code", - "required": [ - "countryCode" - ], - "type": "object", - "properties": { - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "NL" - } - } - } - ] - }, - "InvoicePayableAt": { - "title": "Invoice Payable At", - "type": "object", - "description": "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location can be provided as a `UN Location Code` or as a fallback - a `freeText` field\n", - "oneOf": [ - { - "title": "UN Location Code", - "required": [ - "UNLocationCode" - ], - "type": "object", - "properties": { - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example": "NLAMS" - } - } - }, - { - "title": "Free text", - "required": [ - "freeText" - ], - "type": "object", - "properties": { - "freeText": { - "maxLength": 35, - "type": "string", - "description": "The name of the location where payment will be rendered by the customer.\n", - "example": "DCSA Headquarters" - } - } - } - ] - }, - "DocumentParties": { - "title": "Document Parties", - "required": [ - "issuingParty", - "shipper" - ], - "type": "object", - "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": { - "maxItems": 3, - "type": "array", - "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`).\n\n**Conditions:** If provided:\n - mandatory for To Order BLs, `isToOrder=true`\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "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" - } - } - }, - "description": "All `Parties` with associated roles.\n" - } - }, - "parameters": { - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3.0.0" - } - } - } - } -} diff --git a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/EblSurrenderComponentFactory.java b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/EblSurrenderComponentFactory.java index c22602e0..5338884b 100644 --- a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/EblSurrenderComponentFactory.java +++ b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/EblSurrenderComponentFactory.java @@ -99,7 +99,7 @@ public Set getReportRoleNames( public JsonSchemaValidator getMessageSchemaValidator(String apiProviderRole, boolean forRequest) { String schemaFilePath = - "/standards/eblsurrender/schemas/eblsurrender-v%s.json".formatted(standardVersion); + "/standards/eblsurrender/schemas/EBL_SUR_v%s.yaml".formatted(standardVersion); String schemaName = EblSurrenderRole.isCarrier(apiProviderRole) ? (forRequest ? "SurrenderRequestDetails" : null) diff --git a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderCarrier.java b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderCarrier.java index 508d1717..83d33a46 100644 --- a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderCarrier.java +++ b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderCarrier.java @@ -82,12 +82,26 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { String tdr = UUID.randomUUID().toString().replace("-", "").substring(0, 20); eblStatesById.put(tdr, EblSurrenderState.AVAILABLE_FOR_SURRENDER); persistentMap.save("response", actionPrompt.get("response")); + + var identifyingCodes = + OBJECT_MAPPER + .createArrayNode() + .add( + OBJECT_MAPPER + .createObjectNode() + .put("codeListProvider", "WAVE") + .put("partyCode", "MSK") + .put("codeListName", "DID")); + var issueToParty = OBJECT_MAPPER.createObjectNode(); + issueToParty.set("identifyingCodes", identifyingCodes); issueToParty.put("partyName", "Issue To name").put("eblPlatform", "WAVE"); var carrierParty = OBJECT_MAPPER.createObjectNode(); + carrierParty.set("identifyingCodes", identifyingCodes); carrierParty.put("partyName", "Carrier name").put("eblPlatform", "WAVE"); var surrendereeParty = OBJECT_MAPPER.createObjectNode(); + surrendereeParty.set("identifyingCodes", identifyingCodes); surrendereeParty.put("partyName", "Surrenderee name").put("eblPlatform", "BOLE"); SuppliedScenarioParameters suppliedScenarioParameters = diff --git a/ebl-surrender/src/main/resources/standards/eblsurrender/schemas/EBL_SUR_v3.0.0.yaml b/ebl-surrender/src/main/resources/standards/eblsurrender/schemas/EBL_SUR_v3.0.0.yaml new file mode 100644 index 00000000..7564d8b6 --- /dev/null +++ b/ebl-surrender/src/main/resources/standards/eblsurrender/schemas/EBL_SUR_v3.0.0.yaml @@ -0,0 +1,557 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_SUR/3.0.0' +info: + version: 3.0.0 + title: DCSA eBL Surrender API + description: | +

DCSA OpenAPI specification for the surrender of an electronic Bill of Lading (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.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design) + + For a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/surrender#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'http://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.0 + 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 puprpose 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-surrender/src/main/resources/standards/eblsurrender/schemas/eblsurrender-v3.0.0.json b/ebl-surrender/src/main/resources/standards/eblsurrender/schemas/eblsurrender-v3.0.0.json deleted file mode 100644 index 2bb0f50d..00000000 --- a/ebl-surrender/src/main/resources/standards/eblsurrender/schemas/eblsurrender-v3.0.0.json +++ /dev/null @@ -1,535 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA eBL Surrender API", - "description": "

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

\n\nThis API is intended as an API between a carrier and an EBL Solution Platform.\n\nThe EBL Solution Platform will submit surrender requests to the carrier, via\n\n POST /v3/ebl-surrender-requests\n\nwhich will be processed asynchronously. Responses to the surrender requests will be submitted by the carrier via \n\n POST /v3/ebl-surrender-responses\n\nWhen the platform submits a surrender request, the platform guarantees *all* of the following:\n\n1) The surrender request was submitted by the sole possessor of the EBL.\n2) Depending on the eBL type:\n * For non-negotiable (\"straight\") eBLs, the surrender request was submitted by either the original shipper OR the consignee.\n * For negotiable eBLs with a named titleholder, the surrender request was submitted by the named titleholder.\n * For negotiable eBLs without a named titleholder / blank eBLs, possession is sufficient for the entity surrendering the eBL.\n3) The platform has the EBL in custody while the carrier is evaluating this surrender request. I.e., neither possession nor title holder changes can occur until the carrier responds to this surrender request.\n\nPlease see the [Surrender Request](#/surrenderRequestDetails) for details on what data the platform will provide.\n\nThe 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.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3/surrender#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n\nAPI specification issued by [DCSA.org](https://dcsa.org/).\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "3.0.0" - }, - "servers": [ - { - "url": "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_SUR/3.0.0", - "description": "SwaggerHub API Auto Mocking" - } - ], - "tags": [ - { - "name": "Surrender Requests", - "description": "The Surrender Requests implemented\n" - }, - { - "name": "Surrender Request responses", - "description": "The Surrender Request responses\n" - } - ], - "paths": { - "/v3/ebl-surrender-requests": { - "post": { - "tags": [ - "Surrender Requests" - ], - "summary": "Creates a Surrender Request\n", - "description": "The EBL Solution Platform uses this endpoint to submit a surrender request.\n\nThe carrier's answer to the surrender request will be returned via a callback response (see the `Callbacks` tab)\n", - "operationId": "create-surrender-request", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SurrenderRequestDetails" - } - } - } - }, - "responses": { - "204": { - "description": "Submission registered successfully.\n\nThe carrier will later follow up via the callback with a response.\n", - "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" - ], - "description": "The carrier uses this endpoint to inform the EBL Solution Platform about the verdict for a given surrender request.\n", - "operationId": "post-ebl-surrender-responses", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SurrenderRequestAnswer" - } - } - }, - "required": true - }, - "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.\n", - "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": { - "schemas": { - "TransactionParty": { - "title": "Transaction Party", - "required": [ - "eblPlatform", - "partyName" - ], - "type": "object", - "properties": { - "eblPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "The EBL platform of the transaction party. The value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (Enigio trace:original)\n- `BRIT` (BRITC eBL)\n", - "example": "BOLE" - }, - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Globeteam" - }, - "identifyingCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IdentifyingCode" - } - }, - "taxLegalReferences": { - "type": "array", - "description": "A list of `Tax References` for a `Party`\n", - "items": { - "$ref": "#/components/schemas/TaxLegalReference" - } - } - }, - "description": "Refers to a company or a legal entity." - }, - "EndorsementChainLink": { - "title": "Endorsement Chain Link", - "required": [ - "actionCode", - "actionDateTime", - "actor", - "recipient" - ], - "type": "object", - "properties": { - "actionDateTime": { - "type": "string", - "description": "Date time when the action occurred.", - "format": "date-time", - "example": "2024-09-04T09:41:00Z" - }, - "actionCode": { - "maxLength": 50, - "type": "string", - "description": "The action performed by the party. This should be one of:\n- `ISSUE` (The actor issued the document to the recipient)\n- `ENDORSE` (The actor endorsed the document to the recipient)\n- `SIGN` (The actor signed or performed an \"assignment\" to the recipient)\n- `SURRENDER_FOR_DELIVERY` (The actor requested this surrender request for delivery to the recipient)\n- `SURRENDER_FOR_AMENDMENT` (The actor requested this surrender request for amendment to the recipient)\nNot all actions are applicable to all surrender requests.\n", - "example": "ISSUE" - }, - "actor": { - "$ref": "#/components/schemas/TransactionParty" - }, - "recipient": { - "$ref": "#/components/schemas/TransactionParty" - } - }, - "description": "Entry in the endorsement chain.\n" - }, - "SurrenderRequestDetails": { - "title": "Surrender Request Details", - "required": [ - "surrenderRequestCode", - "surrenderRequestReference", - "transportDocumentReference" - ], - "type": "object", - "properties": { - "surrenderRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A server defined reference for a concrete surrender request. Surrender request references MUST NOT be reused.\n", - "example": "Z12345" - }, - "transportDocumentReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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.\n", - "example": "HHL71800000" - }, - "surrenderRequestCode": { - "type": "string", - "description": "Surrender Request codes:\n- `SREQ` (Requested to surrender for Delivery)\n- `AREQ` (Requested to surrender for Amendment)\n\nThe 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.\n\nNote that \"Switch to paper\" is considered an amendment in how it is modelled via the DCSA eBL data standard.\n", - "example": "SREQ", - "enum": [ - "SREQ", - "AREQ" - ] - }, - "reasonCode": { - "maxLength": 4, - "type": "string", - "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": { - "maxLength": 255, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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:\n\n - **Issue:** The act of issuing an eBL i.e. making the eBL available to the receiver.\n - **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`).\n - **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.\n - **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 puprpose of amending the eBL.\n - **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.\n\n **Note:** DCSA member carriers have agreed that the name `endorsementChain` is still the correct name for this list of actions.\n", - "items": { - "$ref": "#/components/schemas/EndorsementChainLink" - } - } - }, - "description": "A concrete surrender request related to a transport document.\n\nThe platform guarantees *all* of the following:\n\n 1) The surrender request was submitted by the sole possessor of the EBL.\n 2) Depending on the eBL type:\n * For non-negotiable (\"straight\") eBLs, the surrender request was submitted by either the original shipper OR the consignee.\n * For negotiable eBLs with a named titleholder, the surrender request was submitted by the named titleholder.\n * For negotiable eBLs without a named titleholder / blank eBLs, possession is sufficient for the entity surrendering the eBL.\n 3) The platform has the EBL in custody while the carrier is evaluating this surrender request. I.e., neither possession nor title holder changes can occur until the carrier responds to this surrender request.\n" - }, - "IdentifyingCode": { - "title": "Identifying Code", - "required": [ - "codeListProvider", - "partyCode" - ], - "type": "object", - "properties": { - "codeListProvider": { - "maxLength": 100, - "type": "string", - "description": "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (Enigio trace:original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", - "example": "W3C" - }, - "partyCode": { - "maxLength": 150, - "type": "string", - "description": "Code to identify the party as provided by the `codeListProvider`\n", - "example": "MSK" - }, - "codeListName": { - "maxLength": 100, - "type": "string", - "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", - "example": "DID" - } - } - }, - "TaxLegalReference": { - "title": "Tax & Legal Reference", - "required": [ - "countryCode", - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The reference type code as defined by the relevant tax and/or legal authority.\n", - "example": "PAN" - }, - "countryCode": { - "maxLength": 2, - "minLength": 2, - "pattern": "^[A-Z]{2}$", - "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)\n", - "example": "IN" - }, - "value": { - "maxLength": 35, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `taxLegalReference`\n", - "example": "AAAAA0000A" - } - }, - "description": "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n" - }, - "ErrorResponse": { - "title": "Error Response", - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "example": "POST", - "enum": [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ] - }, - "requestUri": { - "type": "string", - "description": "The URI that was requested.\n", - "example": "/v1/events" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code returned.\n", - "format": "int32", - "example": 400 - }, - "statusCodeText": { - "maxLength": 50, - "type": "string", - "description": "A standard short description corresponding to the HTTP status code.\n", - "example": "Bad Request" - }, - "statusCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the HTTP status code with additional information.\n", - "example": "The supplied data could not be accepted" - }, - "providerCorrelationReference": { - "maxLength": 100, - "type": "string", - "description": "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example": "4426d965-0dd8-4005-8c63-dc68b01c4962" - }, - "errorDateTime": { - "type": "string", - "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.\n", - "format": "date-time", - "example": "2024-09-04T09:41:00Z" - }, - "errors": { - "minItems": 1, - "type": "array", - "description": "An array of errors providing more detail about the root cause.\n", - "items": { - "$ref": "#/components/schemas/DetailedError" - } - } - }, - "description": "Unexpected error" - }, - "DetailedError": { - "title": "Detailed Error", - "required": [ - "errorCodeMessage", - "errorCodeText" - ], - "type": "object", - "properties": { - "errorCode": { - "maximum": 9999, - "minimum": 7000, - "type": "integer", - "description": "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n", - "format": "int32", - "example": 7003 - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error.\n", - "example": "facilityCode" - }, - "value": { - "maxLength": 500, - "type": "string", - "description": "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example": "SG SIN WHS" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example": "$.location.facilityCode" - }, - "errorCodeText": { - "maxLength": 100, - "type": "string", - "description": "A standard short description corresponding to the `errorCode`.\n", - "example": "invalidData" - }, - "errorCodeMessage": { - "maxLength": 5000, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.\n", - "example": "Spaces not allowed in facility code" - } - }, - "description": "A detailed description of what has caused the error.\n" - }, - "SurrenderRequestAnswer": { - "title": "Surrender Request Answer", - "required": [ - "action", - "surrenderRequestReference" - ], - "type": "object", - "properties": { - "surrenderRequestReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The surrender request provided by the EBL solution in the surrender request.\n", - "example": "Z12345" - }, - "action": { - "type": "string", - "description": "Action performed:\n- `SURR` (Surrendered)\n- `SREJ` (Surrender rejected)\n\nWhen 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.\n\nWhen the carrier rejects the surrender (`SREJ`), the EBL is returned to the party that submitted the surrender request.\n", - "example": "SURR", - "enum": [ - "SURR", - "SREJ" - ] - }, - "comments": { - "maxLength": 255, - "pattern": "^\\S(?:.*\\S)?$", - "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.", - "example": "Comments..." - } - } - } - }, - "parameters": { - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3.0.0" - } - } - } - } -} diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/EblScenarioListBuilder.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/EblScenarioListBuilder.java index d7096503..b0ad9d77 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/EblScenarioListBuilder.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/EblScenarioListBuilder.java @@ -1097,8 +1097,7 @@ private static JsonSchemaValidator resolveMessageSchemaValidator(String apiName, if (schemaValidator != null) { return schemaValidator; } - String schemaFilePath = "/standards/ebl/schemas/ebl-%s-%s.json" - .formatted(apiName, standardVersion.toLowerCase()); + String schemaFilePath = "/standards/ebl/schemas/EBL_v%s.yaml".formatted(standardVersion); schemaValidator = JsonSchemaValidator.getInstance(schemaFilePath, schema); SCHEMA_CACHE.put(schemaKey, schemaValidator); diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/models/CarrierShippingInstructions.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/models/CarrierShippingInstructions.java index 395f5bd3..3a56c460 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/models/CarrierShippingInstructions.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/models/CarrierShippingInstructions.java @@ -235,7 +235,7 @@ public void provideField(JsonNode source, ObjectNode dest, String standardsVersi .put("imoPackagingCode", "3A1") .put("numberOfPackages", 400); var dg = outerPackaging.putArray("dangerousGoods").addObject(); - dg.put("unNumber", "3082") + dg.put("UNNumber", "3082") .put("properShippingName", "Environmentally hazardous substance, liquid, N.O.S") .put("imoClass", "9") .put("packingGroup", 3) diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u1e.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u1e.json index 256aaffb..55bc3777 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u1e.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u1e.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -90,6 +91,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u2e.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u2e.json index f7e1b75a..b431c610 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u2e.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-2c2u2e.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -113,6 +114,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-amf.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-amf.json index e3f854b2..dc6de090 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-amf.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-amf.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -77,6 +78,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-clad.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-clad.json index 48f0c573..7259d224 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-clad.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-clad.json @@ -8,6 +8,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -68,6 +69,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-dg.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-dg.json index f25af9a5..715332dc 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-dg.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-dg.json @@ -1,4 +1,5 @@ { + "NANumber": "9037", "transportDocumentTypeCode": "TRANSPORT_DOCUMENT_TYPE_CODE_PLACEHOLDER", "isElectronic": true, "isToOrder": false, @@ -7,6 +8,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -57,6 +59,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-negotiable-bl.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-negotiable-bl.json index 1ae3b50e..420e2f92 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-negotiable-bl.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-negotiable-bl.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -70,6 +71,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-no-commodity-subreference.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-no-commodity-subreference.json index 55447e37..1ed729fe 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-no-commodity-subreference.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-no-commodity-subreference.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -66,6 +67,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-request.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-request.json index 860b127a..8be238f2 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-request.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-request.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -71,6 +72,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-soc-references.json b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-soc-references.json index 503f4185..d7e93c47 100644 --- a/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-soc-references.json +++ b/ebl/src/main/resources/standards/ebl/messages/ebl-api-3.0.0-soc-references.json @@ -7,6 +7,7 @@ "invoicePayableAt": { "UNLocationCode": "INVOICE_PAYABLE_AT_UNLOCATION_CODE" }, + "isCargoDeliveredInICS2Zone": false, "partyContactDetails": [ { "name": "DCSA test person", @@ -75,6 +76,13 @@ "issueTo": { "partyName": "DCSA CTK", "sendToPlatform": "BOLE", + "identifyingCodes" : [ + { + "codeListProvider": "W3C", + "codeListName": "LCL", + "partyCode": "MSC" + } + ], "partyContactDetails": [ { "name": "DCSA test person", diff --git a/ebl/src/main/resources/standards/ebl/schemas/EBL_v3.0.0.yaml b/ebl/src/main/resources/standards/ebl/schemas/EBL_v3.0.0.yaml new file mode 100644 index 00000000..a69a00aa --- /dev/null +++ b/ebl/src/main/resources/standards/ebl/schemas/EBL_v3.0.0.yaml @@ -0,0 +1,8473 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL/3.0.0' +info: + version: 3.0.0 + 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 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.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](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#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'http://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**) + + ## Postcondition + The provider has received an update to the `Shipping Instructions` (**UseCase 3 - Submit updated Shipping Instructions**), from now on called the `Updated Shipping Instructions`. + + 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**) 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: + '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 Jarricans. + + 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: 'Jerrican, 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: + '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: SMDG + codeListName: LCL + partyCode: MSC + 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: SMDG + codeListName: LCL + partyCode: MSC + 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 Jarricans. + 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: SMDG + codeListName: LCL + partyCode: HLC + 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: 'Jerrican, 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: + '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 timeperiod. + + **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 cosumer 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: SMDG + codeListName: LCL + partyCode: MSC + 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: SMDG + codeListName: LCL + partyCode: MSC + 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.0 + 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: 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 + 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: 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 + 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: + 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 + 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. 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 + + ################## + # 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/)) + nullable: false + 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 `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) + - `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 `Shipping Instructions` and `Transport Document`. + 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:** 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:** 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. + 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. + 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 + + 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 + + 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 to provide if `temperatureSetpoint` is provided + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 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 to provide if `airExchange` is provided + 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 + - 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 + 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` 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 + 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` 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 + 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. + + The location can be specified as one of `UN Location Code` or `CountryCode`. + 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 + 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 + 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/Consignee' + endorsee: + $ref: '#/components/schemas/Endorsee' + 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' + 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 + + ############################ + # Document Parties House B/L + ############################ + DocumentPartiesHouseBL: + type: object + title: Document Parties + 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/Seller' + buyer: + $ref: '#/components/schemas/Buyer' + 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 athorizes 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 athorizes 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/src/main/resources/standards/ebl/schemas/ebl-api-3.0.0.json b/ebl/src/main/resources/standards/ebl/schemas/ebl-api-3.0.0.json deleted file mode 100644 index a8e4d50e..00000000 --- a/ebl/src/main/resources/standards/ebl/schemas/ebl-api-3.0.0.json +++ /dev/null @@ -1,7982 +0,0 @@ -{ - "components" : { - "headers" : { - "API-Version" : { - "description" : "SemVer used to indicate the version of the contract (API version) returned.\n", - "explode" : false, - "schema" : { - "example" : "3.0.0", - "type" : "string" - }, - "style" : "simple" - } - }, - "parameters" : { - "Api-Version-Major" : { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - }, - "documentReference" : { - "description" : "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "explode" : false, - "in" : "path", - "name" : "documentReference", - "required" : true, - "schema" : { - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - "updatedContent" : { - "description" : "If set to `true`, the payload returned is the content of the `Updated Shipping Instructions`.\n\nDefault value is `false` in which case the content of the \"original\" `Shipping Instructions` is returned.\n\n**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\n", - "explode" : true, - "in" : "query", - "name" : "updatedContent", - "required" : false, - "schema" : { - "default" : false, - "example" : false, - "type" : "boolean" - }, - "style" : "form" - } - }, - "schemas" : { - "ActiveReeferSettings" : { - "description" : "The specifications for a Reefer equipment.\n\n**Condition:** Only applicable when `isNonOperatingReefer` is set to `false`\n", - "properties" : { - "airExchangeSetpoint" : { - "description" : "Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container\n", - "example" : 15.4, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "airExchangeUnit" : { - "description" : "The unit for `airExchange` in metrics- or imperial- units per hour\n- `MQH` (Cubic metre per hour)\n- `FQH` (Cubic foot per hour)\n\n**Condition:** Mandatory to provide if `airExchange` is provided\n", - "enum" : [ - "MQH", - "FQH" - ], - "example" : "MQH", - "type" : "string" - }, - "co2Setpoint" : { - "description" : "The percentage of the controlled atmosphere CO2 target value\n", - "example" : 25, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "humiditySetpoint" : { - "description" : "The percentage of the controlled atmosphere humidity target value\n", - "example" : 95.6, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "isBulbMode" : { - "description" : "Is special container setting for handling flower bulbs active\n", - "example" : true, - "type" : "boolean" - }, - "isColdTreatmentRequired" : { - "description" : "Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD\n", - "example" : true, - "type" : "boolean" - }, - "isControlledAtmosphereRequired" : { - "description" : "Indicator of whether cargo requires Controlled Atmosphere.\n", - "example" : true, - "type" : "boolean" - }, - "isDrainholesOpen" : { - "description" : "Is drain holes open on the container\n", - "example" : true, - "type" : "boolean" - }, - "isVentilationOpen" : { - "description" : "If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed`\n", - "example" : true, - "type" : "boolean" - }, - "o2Setpoint" : { - "description" : "The percentage of the controlled atmosphere CO2 target value\n", - "example" : 25, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "temperatureSetpoint" : { - "description" : "Target value of the temperature for the Reefer based on the cargo requirement.\n", - "example" : -15, - "format" : "float", - "type" : "number" - }, - "temperatureUnit" : { - "description" : "The unit for temperature in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", - "enum" : [ - "CEL", - "FAH" - ], - "example" : "CEL", - "type" : "string" - } - }, - "title" : "Active Reefer Settings", - "type" : "object" - }, - "Address" : { - "description" : "An object for storing address related information\n", - "properties" : { - "POBox" : { - "description" : "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example" : "123", - "maxLength" : 20, - "type" : "string" - }, - "city" : { - "description" : "The name of the city.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "floor" : { - "description" : "The floor of the street number.\n", - "example" : "N/A", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "postCode" : { - "description" : "The post code of the address.", - "example" : "1047 HM", - "maxLength" : 10, - "type" : "string" - }, - "stateRegion" : { - "description" : "The name of the state/region.", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - }, - "street" : { - "description" : "The name of the street.", - "example" : "Ruijggoordweg", - "maxLength" : 70, - "type" : "string" - }, - "streetNumber" : { - "description" : "The number of the street.", - "example" : "100", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode", - "street" - ], - "title" : "Address", - "type" : "object" - }, - "AdvanceManifestFiling" : { - "description" : "An Advance Manifest Filing defined by a Manifest type code in combination with a country code.\n\nA small list of **potential** examples:\n\n| manifestTypeCode | countryCode | Description |\n|-----------------------|:-------------:|-------------|\n|ACI|EG|Advance Cargo Information in Egypt|\n|ACE|US|Automated Commercial Environment in the United States|\n|AFR|JP|Cargo Summary Notification (CSN)|\n|ENS|NL|Entry Summary Declaration|\n", - "example" : { - "advanceManifestFilingsHouseBLPerformedBy" : "SELF", - "countryCode" : "US", - "manifestTypeCode" : "ACE", - "selfFilerCode" : "FLXP123" - }, - "properties" : { - "advanceManifestFilingsHouseBLPerformedBy" : { - "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:\n\n- `SELF` (filing done by the House filer)\n- `CARRIER` (the carrier does the filing)\n\nIn case of self-filing (`SELF`), the shipper can provide their `selfFilerCode` for each manifest.\n\n**Condition:** The `selfFilerCode` must be provided when `manifestTypeCode` is either `ACE` (US) or `ACI` (CA) and the `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`.\n", - "enum" : [ - "SELF", - "CARRIER" - ], - "example" : "SELF", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "manifestTypeCode" : { - "description" : "The Manifest type code as defined by the provider.\n", - "example" : "ENS", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "selfFilerCode" : { - "description" : "Code identifying the party who will submit the advance manifest filing(s) for the House BL.\n\n**Mandatory** if `manifestTypeCode` is either `ACE` (US) or `ACI` (CA) and `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`.\n", - "example" : "FLXP", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "supplementaryDeclarantEORINumber" : { - "description" : "The Economic Operators Registration and Identification (EORI) number of the house filer responsible for the `ENS` filing.\n\n**Condition:** Only applicable if `manifestTypeCode` is `ENS`.\n", - "example" : "FLXP-123321", - "maxLength" : 17, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "advanceManifestFilingsHouseBLPerformedBy", - "countryCode", - "manifestTypeCode" - ], - "title" : "Advance Manifest Filing", - "type" : "object" - }, - "ApproveTransportDocument" : { - "properties" : { - "transportDocumentStatus" : { - "description" : "The status of the `Transport Document`. It can only be `APPROVED`\n", - "example" : "APPROVED", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "transportDocumentStatus" - ], - "title" : "Approve Transport Document", - "type" : "object" - }, - "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.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Buyer", - "type" : "object" - }, - "CancelShippingInstructionsUpdate" : { - "properties" : { - "updatedShippingInstructionsStatus" : { - "description" : "The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED`\n", - "example" : "UPDATE_CANCELLED", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "updatedShippingInstructionsStatus" - ], - "title" : "Cancel Shipping Instructions Update", - "type" : "object" - }, - "CargoGrossVolume" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "enum" : [ - "MTQ", - "FTQ" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Gross Volume", - "type" : "object" - }, - "CargoGrossWeight" : { - "description" : "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 2400, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Gross Weight", - "type" : "object" - }, - "CargoItem" : { - "description" : "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", - "properties" : { - "cargoGrossVolume" : { - "$ref" : "#/components/schemas/CargoGrossVolume" - }, - "cargoGrossWeight" : { - "$ref" : "#/components/schemas/CargoGrossWeight" - }, - "cargoNetVolume" : { - "$ref" : "#/components/schemas/CargoNetVolume" - }, - "cargoNetWeight" : { - "$ref" : "#/components/schemas/CargoNetWeight" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `cargoItem`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "outerPackaging" : { - "$ref" : "#/components/schemas/OuterPackaging" - } - }, - "required" : [ - "cargoGrossWeight", - "equipmentReference", - "outerPackaging" - ], - "title" : "Cargo Item", - "type" : "object" - }, - "CargoItemShipper" : { - "description" : "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", - "properties" : { - "cargoGrossVolume" : { - "$ref" : "#/components/schemas/CargoGrossVolume" - }, - "cargoGrossWeight" : { - "$ref" : "#/components/schemas/CargoGrossWeight" - }, - "cargoNetVolume" : { - "$ref" : "#/components/schemas/CargoNetVolume" - }, - "cargoNetWeight" : { - "$ref" : "#/components/schemas/CargoNetWeight" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "houseBillOfLadingReference" : { - "description" : "Link to the House Bill of Lading this cargoItem is connected to.\n", - "example" : "ABC123", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `cargoItem`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "outerPackaging" : { - "$ref" : "#/components/schemas/OuterPackagingShipper" - } - }, - "required" : [ - "cargoGrossWeight", - "equipmentReference" - ], - "title" : "Cargo Item (Shipper)", - "type" : "object" - }, - "CargoNetVolume" : { - "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "enum" : [ - "MTQ", - "FTQ" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Net Volume", - "type" : "object" - }, - "CargoNetWeight" : { - "description" : "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 2400, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Net Weight", - "type" : "object" - }, - "CarriersAgentAtDestination" : { - "description" : "The party on the import side assigned by the carrier to whom the customer need to reach out to for cargo release.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "address", - "partyContactDetails", - "partyName" - ], - "title" : "Carrier's Agent At Destination", - "type" : "object" - }, - "Charge" : { - "description" : "Addresses the monetary value of freight and other service charges for a `Booking`.\n", - "properties" : { - "calculationBasis" : { - "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.\n", - "example" : "Per day", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "chargeName" : { - "description" : "Free text field describing the charge to apply\n", - "example" : "Documentation fee - Destination", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "currencyAmount" : { - "description" : "The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals.\n", - "example" : 1012.12, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "currencyCode" : { - "description" : "The currency for the charge, using a 3-character code ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)).\n", - "example" : "DKK", - "maxLength" : 3, - "minLength" : 3, - "pattern" : "^[A-Z]{3}$", - "type" : "string" - }, - "paymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "quantity" : { - "description" : "The amount of unit for this charge item.\n", - "example" : 34.4, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "unitPrice" : { - "description" : "The unit price of this charge item in the currency of the charge.\n", - "example" : 3456.6, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "calculationBasis", - "chargeName", - "currencyAmount", - "currencyCode", - "paymentTermCode", - "quantity", - "unitPrice" - ], - "title" : "Charge", - "type" : "object" - }, - "City" : { - "description" : "An object for storing city, state/region and country related information\n", - "properties" : { - "city" : { - "description" : "The name of the city.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "stateRegion" : { - "description" : "The name of the state/region.\n", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode" - ], - "title" : "City", - "type" : "object" - }, - "Consignee" : { - "description" : "The party to which goods are consigned in the `Master Bill of Lading`.\n\n**Condition:** Mandatory for non-negotiable BL (`isToOrder=false`)\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "purchaseOrderReferences" : { - "description" : "A list of `Purchase Order Reference`s linked to the `Consignee`.\n", - "items" : { - "description" : "A purchase order reference linked to the `Consignee`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "reference" : { - "description" : "A reference linked to the `Consignee`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Consignee", - "type" : "object" - }, - "ConsigneeHBL" : { - "description" : "The ultimate recipient of the cargo. It must be different from the freight forwarder, (de)consolidator, postal operator, or customs agent.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Consignee", - "type" : "object" - }, - "ConsignmentItem" : { - "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`\n", - "properties" : { - "HSCodes" : { - "description" : "A list of `HS Codes` that apply to this `consignmentItem`\n", - "items" : { - "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.\n\nMore information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools).\n", - "example" : "851713", - "maxLength" : 10, - "minLength" : 6, - "pattern" : "^\\d{6,10}$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - }, - "cargoItems" : { - "description" : "A list of all `cargoItems`\n", - "items" : { - "$ref" : "#/components/schemas/CargoItem" - }, - "minItems" : 1, - "type" : "array" - }, - "carrierBookingReference" : { - "description" : "The associated booking number provided by the carrier for this `Consignment Item`.\n\nWhen multiple `carrierBookingReferences` are used then the bookings referred to must all contain the same:\n- transportPlan\n- shipmentLocations\n- receiptTypeAtOrigin\n- deliveryTypeAtDestination\n- cargoMovementTypeAtOrigin\n- cargoMovementTypeAtDestination\n- serviceContractReference\n- termsAndConditions\n- Place of B/L Issue (if provided)\n", - "example" : "ABC709951", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "descriptionOfGoods" : { - "description" : "An array of lines accurately and properly describing the cargo being shipped in the container(s) as provided by the shipper.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line describing the cargo", - "example" : "blue shoes size 47", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "maxItems" : 150, - "type" : "array" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/ReferenceConsignmentItem" - }, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "HSCodes", - "cargoItems", - "carrierBookingReference", - "descriptionOfGoods" - ], - "title" : "Consignment Item", - "type" : "object" - }, - "ConsignmentItemShipper" : { - "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`\n", - "properties" : { - "HSCodes" : { - "description" : "A list of `HS Codes` that apply to this `consignmentItem`\n", - "items" : { - "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.\n\nMore information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools).\n", - "example" : "851713", - "maxLength" : 10, - "minLength" : 6, - "pattern" : "^\\d{6,10}$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - }, - "cargoItems" : { - "description" : "A list of all `cargoItems`\n", - "items" : { - "$ref" : "#/components/schemas/CargoItemShipper" - }, - "minItems" : 1, - "type" : "array" - }, - "carrierBookingReference" : { - "description" : "The associated booking number provided by the carrier for this `Consignment Item`.\n\nWhen multiple `carrierBookingReferences` are used then the bookings referred to must all contain the same:\n- transportPlan\n- shipmentLocations\n- receiptTypeAtOrigin\n- deliveryTypeAtDestination\n- cargoMovementTypeAtOrigin\n- cargoMovementTypeAtDestination\n- serviceContractReference\n- termsAndConditions\n- Place of B/L Issue (if provided)\n", - "example" : "ABC709951", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "commoditySubreference" : { - "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.\n", - "example" : "COM-001", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "descriptionOfGoods" : { - "description" : "An array of lines accurately and properly describing the cargo being shipped in the container(s) as provided by the shipper.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line describing the cargo", - "example" : "blue shoes size 47", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "maxItems" : 150, - "type" : "array" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/ReferenceConsignmentItem" - }, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "HSCodes", - "cargoItems", - "carrierBookingReference", - "descriptionOfGoods" - ], - "title" : "Consignment Item (Shipper)", - "type" : "object" - }, - "CreateShippingInstructions" : { - "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`.\n", - "properties" : { - "advanceManifestFilings" : { - "description" : "A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing\n", - "items" : { - "$ref" : "#/components/schemas/AdvanceManifestFiling" - }, - "type" : "array" - }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItemShipper" - }, - "minItems" : 1, - "type" : "array" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "destinationChargesPaymentTerm" : { - "$ref" : "#/components/schemas/DestinationChargesPaymentTerm" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "documentParties" : { - "$ref" : "#/components/schemas/DocumentPartiesShippingInstructions" - }, - "freightPaymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "houseBillOfLadings" : { - "description" : "A list of `House Bill of Ladings` specified by the Shipper.\n", - "items" : { - "$ref" : "#/components/schemas/HouseBillOfLading" - }, - "type" : "array" - }, - "invoicePayableAt" : { - "$ref" : "#/components/schemas/InvoicePayableAtShippingInstructions" - }, - "isCarriersAgentAtDestinationRequired" : { - "description" : "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example" : false, - "type" : "boolean" - }, - "isElectronic" : { - "description" : "An indicator whether the transport document is electronically transferred.\n", - "example" : true, - "type" : "boolean" - }, - "isHBLIssued" : { - "description" : "Indicates whether one or more `House Bill of Lading(s)` have been issued. This property is used by the carrier to identify which `ENS` filing type must be submitted (`F10` or `F11`, `F12` or `F13`) to comply with `ICS2` customs regulations\n", - "example" : true, - "type" : "boolean" - }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" - }, - "isToOrder" : { - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example" : false, - "type" : "boolean" - }, - "methodOfPayment" : { - "description" : "Method used for the payment of prepaid charges. It can be one of the following values: \n- `A` (Cash)\n- `B` (Credit Card)\n- `C` (Cheque)\n- `D` (Other)\n- `H` (Electronic funds transfer)\n- `Y` (Account holder with carrier)\n- `Z` (Not prepaid)\n", - "example" : "A", - "maxLength" : 1, - "type" : "string" - }, - "numberOfCopiesWithCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfCopiesWithoutCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithoutCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "originChargesPaymentTerm" : { - "$ref" : "#/components/schemas/OriginChargesPaymentTerm" - }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "minItems" : 1, - "type" : "array" - }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/PlaceOfIssue" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "requestedCarrierCertificates" : { - "description" : "Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack\n", - "items" : { - "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:\n- `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1)\n- `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2)\n- `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3)\n- `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4)\n- `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5)\n- `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6)\n- `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7)\n- `VESSEL_PARTICULARS_1` (Vessel Particulars 1)\n- `VESSEL_PARTICULARS_2` (Vessel Particulars 2)\n- `VESSEL_PARTICULARS_3` (Vessel Particulars 3)\n- `VESSEL_PARTICULARS_4` (Vessel Particulars 4)\n- `VESSEL_PARTICULARS_5` (Vessel Particulars 5)\n- `VESSEL_PARTICULARS_6` (Vessel Particulars 6)\n- `VESSEL_PARTICULARS_7` (Vessel Particulars 7)\n- `VESSEL_PARTICULARS_8` (Vessel Particulars 8)\n- `VESSEL_PARTICULARS_9` (Vessel Particulars 9)\n- `VESSEL_PARTICULARS_10` (Vessel Particulars 10)\n- `VESSEL_PARTICULARS_11` (Vessel Particulars 11)\n- `VESSEL_PARTICULARS_12` (Vessel Particulars 12)\n- `VESSEL_PARTICULARS_13` (Vessel Particulars 13)\n- `VESSEL_PARTICULARS_14` (Vessel Particulars 14)\n- `VESSEL_PARTICULARS_15` (Vessel Particulars 15)\n- `VESSEL_PARTICULARS_16` (Vessel Particulars 16)\n- `VESSEL_PARTICULARS_17` (Vessel Particulars 17)\n- `VESSEL_PARTICULARS_18` (Vessel Particulars 18)\n", - "example" : "VESSEL_PARTICULARS_1", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "requestedCarrierClauses" : { - "description" : "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items" : { - "description" : "A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa.org/wp-content/uploads/2023/12/202312-Standardised-Clauses-BL.pdf). Possible values are:\n- `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics)\n- `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific)\n- `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container)\n- `CARGO_CARGOVALUE` (Cargo/Cargo value)\n- `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature)\n- `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads)\n", - "example" : "CARGO_CARGOSPECIFICS", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "routingOfConsignmentCountries" : { - "description" : "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : "array" - }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "enum" : [ - "BOL", - "SWB" - ], - "example" : "SWB", - "type" : "string" - }, - "utilizedTransportEquipments" : { - "description" : "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items" : { - "$ref" : "#/components/schemas/UtilizedTransportEquipmentShipper" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "title" : "Create Shipping Instructions", - "type" : "object" - }, - "CreateShippingInstructionsResponse" : { - "description" : "**Only** the `shippingInstructionsReference` is returned.\n", - "properties" : { - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "shippingInstructionsReference" - ], - "title" : "Create Shipping Instructions Response", - "type" : "object" - }, - "CustomsReference" : { - "description" : "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "EG", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The reference type code as defined in the relevant customs jurisdiction.\n", - "example" : "ACID", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "values" : { - "items" : { - "description" : "The value of the `customsReference`\n", - "example" : "4988470982020120017", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "countryCode", - "type", - "values" - ], - "title" : "Customs Reference", - "type" : "object" - }, - "DangerousGoods" : { - "description" : "Specification for `Dangerous Goods`. It is mandatory to either provide the `unNumber` or the `naNumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", - "oneOf" : [ - { - "properties" : { - "unNumber" : { - "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.\n", - "example" : "1463", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^\\d{4}$", - "type" : "string" - } - }, - "required" : [ - "unNumber" - ], - "title" : "UN Number", - "type" : "object" - }, - { - "properties" : { - "naNumber" : { - "description" : "Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation.\n", - "example" : "9037", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^\\d{4}$", - "type" : "string" - } - }, - "required" : [ - "naNumber" - ], - "title" : "NA Number", - "type" : "object" - } - ], - "properties" : { - "EMSNumber" : { - "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.\n", - "example" : "F-A S-Q", - "maxLength" : 7, - "type" : "string" - }, - "codedVariantList" : { - "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", - "example" : "2200", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^[0-3][0-9A-Z]{3}$", - "type" : "string" - }, - "competentAuthorityApproval" : { - "description" : "Name and reference number of the competent authority providing the approval.\n", - "example" : "{Name and reference...}", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "emergencyContactDetails" : { - "$ref" : "#/components/schemas/EmergencyContactDetails" - }, - "endOfHoldingTime" : { - "description" : "Date by when the refrigerated liquid needs to be delivered.\n", - "example" : "2021-09-03", - "format" : "date", - "type" : "string" - }, - "fumigationDateTime" : { - "description" : "Date & time when the container was fumigated\n", - "example" : "2024-09-04T09:41:00Z", - "format" : "date-time", - "type" : "string" - }, - "grossWeight" : { - "$ref" : "#/components/schemas/GrossWeight" - }, - "imoClass" : { - "description" : "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n", - "example" : "1.4S", - "maxLength" : 4, - "type" : "string" - }, - "inhalationZone" : { - "description" : "The zone classification of the toxicity of the inhalant. Possible values are:\n\n- `A` (Hazard Zone A) can be assigned to specific gases and liquids\n- `B` (Hazard Zone B) can be assigned to specific gases and liquids\n- `C` (Hazard Zone C) can **only** be assigned to specific gases\n- `D` (Hazard Zone D) can **only** be assigned to specific gases\n", - "example" : "A", - "maxLength" : 1, - "minLength" : 1, - "type" : "string" - }, - "innerPackagings" : { - "description" : "A list of `Inner Packings` contained inside this `outer packaging/overpack`.\n", - "items" : { - "$ref" : "#/components/schemas/InnerPackaging" - }, - "type" : "array" - }, - "isCompetentAuthorityApprovalRequired" : { - "description" : "Indicates if the cargo require approval from authorities\n", - "example" : false, - "type" : "boolean" - }, - "isEmptyUncleanedResidue" : { - "description" : "Indicates if the cargo is residue.\n", - "example" : false, - "type" : "boolean" - }, - "isExceptedQuantity" : { - "description" : "Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code.\n", - "example" : false, - "type" : "boolean" - }, - "isHot" : { - "description" : "Indicates if high temperature cargo is shipped.\n", - "example" : false, - "type" : "boolean" - }, - "isLimitedQuantity" : { - "description" : "Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code.\n", - "example" : false, - "type" : "boolean" - }, - "isMarinePollutant" : { - "description" : "Indicates if the goods belong to the classification of Marine Pollutant.\n", - "example" : false, - "type" : "boolean" - }, - "isReportableQuantity" : { - "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.\n", - "example" : false, - "type" : "boolean" - }, - "isSalvagePackings" : { - "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.\n", - "example" : false, - "type" : "boolean" - }, - "isWaste" : { - "description" : "Indicates if waste is being shipped\n", - "example" : false, - "type" : "boolean" - }, - "limits" : { - "$ref" : "#/components/schemas/Limits" - }, - "netExplosiveContent" : { - "$ref" : "#/components/schemas/NetExplosiveContent" - }, - "netVolume" : { - "$ref" : "#/components/schemas/NetVolume" - }, - "netWeight" : { - "$ref" : "#/components/schemas/NetWeight" - }, - "packingGroup" : { - "description" : "The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code.\n", - "example" : 3, - "format" : "int32", - "maximum" : 3, - "minimum" : 1, - "type" : "integer" - }, - "properShippingName" : { - "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.\n", - "example" : "Chromium Trioxide, anhydrous", - "maxLength" : 250, - "type" : "string" - }, - "segregationGroups" : { - "description" : "List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code.\n\n**Condition:** only applicable to specific hazardous goods.\n", - "items" : { - "description" : "Grouping of Dangerous Goods having certain similar chemical properties. Possible values are:\n\n- `1` (Acids)\n- `2` (Ammonium Compounds)\n- `3` (Bromates)\n- `4` (Chlorates)\n- `5` (Chlorites)\n- `6` (Cyanides)\n- `7` (Heavy metals and their salts)\n- `8` (Hypochlorites)\n- `9` (Lead and its compounds)\n- `10` (Liquid halogenated hydrocarbons)\n- `11` (Mercury and mercury compounds)\n- `12` (Nitrites and their mixtures)\n- `13` (Perchlorates)\n- `14` (Permanganates)\n- `15` (Powdered metals)\n- `16` (Peroxides),\n- `17` (Azides)\n- `18` (Alkalis)\n", - "example" : "12", - "maxLength" : 2, - "type" : "string" - }, - "type" : "array" - }, - "subsidiaryRisk1" : { - "description" : "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example" : "1.2", - "maxLength" : 3, - "minLength" : 1, - "pattern" : "^[0-9](\\.[0-9])?$", - "type" : "string" - }, - "subsidiaryRisk2" : { - "description" : "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example" : "1.2", - "maxLength" : 3, - "minLength" : 1, - "pattern" : "^[0-9](\\.[0-9])?$", - "type" : "string" - }, - "technicalName" : { - "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.\n", - "example" : "xylene and benzene", - "maxLength" : 250, - "type" : "string" - } - }, - "required" : [ - "imoClass", - "properShippingName" - ], - "title" : "Dangerous Goods", - "type" : "object" - }, - "DestinationChargesPaymentTerm" : { - "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).\n", - "properties" : { - "haulageChargesPaymentTermCode" : { - "description" : "An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "otherChargesPaymentTermCode" : { - "description" : "An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "portChargesPaymentTermCode" : { - "description" : "An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - } - }, - "title" : "Destination Charges Payment Term", - "type" : "object" - }, - "DetailedError" : { - "description" : "A detailed description of what has caused the error.\n", - "properties" : { - "errorCode" : { - "description" : "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n", - "example" : 7003, - "format" : "int32", - "maximum" : 9999, - "minimum" : 7000, - "type" : "integer" - }, - "errorCodeMessage" : { - "description" : "A long description corresponding to the `errorCode` with additional information.\n", - "example" : "Spaces not allowed in facility code", - "maxLength" : 5000, - "type" : "string" - }, - "errorCodeText" : { - "description" : "A standard short description corresponding to the `errorCode`.\n", - "example" : "invalidData", - "maxLength" : 100, - "type" : "string" - }, - "jsonPath" : { - "description" : "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example" : "$.location.facilityCode", - "maxLength" : 500, - "type" : "string" - }, - "property" : { - "description" : "The name of the property causing the error.\n", - "example" : "facilityCode", - "maxLength" : 100, - "type" : "string" - }, - "value" : { - "description" : "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example" : "SG SIN WHS", - "maxLength" : 500, - "type" : "string" - } - }, - "required" : [ - "errorCodeMessage", - "errorCodeText" - ], - "title" : "Detailed Error", - "type" : "object" - }, - "DocumentParties" : { - "description" : "All `Parties` with associated roles.\n", - "properties" : { - "carriersAgentAtDestination" : { - "$ref" : "#/components/schemas/CarriersAgentAtDestination" - }, - "consignee" : { - "$ref" : "#/components/schemas/Consignee" - }, - "endorsee" : { - "$ref" : "#/components/schemas/Endorsee" - }, - "issuingParty" : { - "$ref" : "#/components/schemas/IssuingParty" - }, - "notifyParties" : { - "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`).\n\n**Condition:** If provided:\n - Mandatory for To Order BLs, `isToOrder=true`\n - The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "$ref" : "#/components/schemas/NotifyParty" - }, - "maxItems" : 3, - "type" : "array" - }, - "other" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", - "items" : { - "$ref" : "#/components/schemas/OtherDocumentParty" - }, - "type" : "array" - }, - "shipper" : { - "$ref" : "#/components/schemas/Shipper" - } - }, - "required" : [ - "issuingParty", - "shipper" - ], - "title" : "Document Parties", - "type" : "object" - }, - "DocumentPartiesHouseBL" : { - "description" : "All `Parties` with associated roles for this `House Bill of Lading`.\n", - "properties" : { - "buyer" : { - "$ref" : "#/components/schemas/Buyer" - }, - "consignee" : { - "$ref" : "#/components/schemas/ConsigneeHBL" - }, - "notifyParty" : { - "$ref" : "#/components/schemas/NotifyPartyHBL" - }, - "other" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", - "items" : { - "$ref" : "#/components/schemas/OtherDocumentPartyHBL" - }, - "type" : "array" - }, - "seller" : { - "$ref" : "#/components/schemas/Seller" - }, - "shipper" : { - "$ref" : "#/components/schemas/ShipperHBL" - } - }, - "title" : "Document Parties", - "type" : "object" - }, - "DocumentPartiesShippingInstructions" : { - "description" : "All `Parties` with associated roles.\n", - "properties" : { - "buyer" : { - "$ref" : "#/components/schemas/Buyer" - }, - "consignee" : { - "$ref" : "#/components/schemas/Consignee" - }, - "endorsee" : { - "$ref" : "#/components/schemas/Endorsee" - }, - "issueTo" : { - "$ref" : "#/components/schemas/IssueToParty" - }, - "notifyParties" : { - "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`).\n\n**Condition:** If provided:\n - Mandatory for To Order BLs, `isToOrder=true`\n - The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "$ref" : "#/components/schemas/NotifyParty" - }, - "maxItems" : 3, - "type" : "array" - }, - "other" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", - "items" : { - "$ref" : "#/components/schemas/OtherDocumentParty" - }, - "type" : "array" - }, - "seller" : { - "$ref" : "#/components/schemas/Seller" - }, - "shipper" : { - "$ref" : "#/components/schemas/Shipper" - } - }, - "required" : [ - "shipper" - ], - "title" : "Document Parties", - "type" : "object" - }, - "EmergencyContactDetails" : { - "description" : "24 hr emergency contact details\n", - "properties" : { - "contact" : { - "description" : "Name of the Contact person during an emergency.\n", - "example" : "Henrik Larsen", - "maxLength" : 255, - "type" : "string" - }, - "phone" : { - "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).\n", - "example" : "+45 70262970", - "maxLength" : 30, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "provider" : { - "description" : "Name of the third party vendor providing emergency support\n", - "example" : "GlobeTeam", - "maxLength" : 255, - "type" : "string" - }, - "referenceNumber" : { - "description" : "Contract reference for the emergency support provided by an external third party vendor.\n", - "example" : "12234", - "maxLength" : 255, - "type" : "string" - } - }, - "required" : [ - "contact", - "phone" - ], - "title" : "Emergency Contact Details", - "type" : "object" - }, - "Endorsee" : { - "description" : "The party to whom the title to the goods is transferred by means of endorsement.\n\n**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.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "partyName" - ], - "title" : "Endorsee", - "type" : "object" - }, - "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.\n", - "properties" : { - "ISOEquipmentCode" : { - "description" : "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n", - "example" : "22G1", - "maxLength" : 4, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "tareWeight" : { - "$ref" : "#/components/schemas/TareWeight" - } - }, - "required" : [ - "equipmentReference" - ], - "title" : "Equipment", - "type" : "object" - }, - "ErrorResponse" : { - "description" : "Unexpected error", - "properties" : { - "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.\n", - "example" : "2024-09-04T09:41:00Z", - "format" : "date-time", - "type" : "string" - }, - "errors" : { - "description" : "An array of errors providing more detail about the root cause.\n", - "items" : { - "$ref" : "#/components/schemas/DetailedError" - }, - "minItems" : 1, - "type" : "array" - }, - "httpMethod" : { - "description" : "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "enum" : [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ], - "example" : "POST", - "type" : "string" - }, - "providerCorrelationReference" : { - "description" : "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "maxLength" : 100, - "type" : "string" - }, - "requestUri" : { - "description" : "The URI that was requested.\n", - "example" : "/v1/events", - "type" : "string" - }, - "statusCode" : { - "description" : "The HTTP status code returned.\n", - "example" : 400, - "format" : "int32", - "type" : "integer" - }, - "statusCodeMessage" : { - "description" : "A long description corresponding to the HTTP status code with additional information.\n", - "example" : "The supplied data could not be accepted", - "maxLength" : 200, - "type" : "string" - }, - "statusCodeText" : { - "description" : "A standard short description corresponding to the HTTP status code.\n", - "example" : "Bad Request", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "title" : "Error Response", - "type" : "object" - }, - "Facility" : { - "description" : "An object used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute.\n", - "properties" : { - "facilityCode" : { - "description" : "The code used for identifying the specific facility. This code does not include the UN Location Code.\nThe definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used:\n- `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/))\n- `BIC` (the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/))", - "example" : "ADT", - "maxLength" : 6, - "nullable" : false, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "facilityCodeListProvider" : { - "description" : "The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code`\n- `BIC` (Requires a UN Location Code)\n- `SMDG` (Requires a UN Location Code)\n", - "enum" : [ - "BIC", - "SMDG" - ], - "example" : "SMDG", - "type" : "string" - } - }, - "required" : [ - "facilityCode", - "facilityCodeListProvider" - ], - "title" : "Facility", - "type" : "object" - }, - "Feedback" : { - "description" : "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "properties" : { - "code" : { - "description" : "A code used to describe the feedback. Possible values are:\n- `INFORMATIONAL_MESSAGE` (INFO - to be used when providing extra information) \n- `PROPERTY_WILL_BE_IGNORED` (WARN - to be used for unsupported properties/values)\n- `PROPERTY_VALUE_MUST_CHANGE` (ERROR - to be used when a wrong property/value is provided)\n- `PROPERTY_VALUE_HAS_BEEN_CHANGED` (WARN - when something has been auto-updated without consumer intervention)\n- `PROPERTY_VALUE_MAY_CHANGE` (WARN - when something is likely to change in the future)\n- `PROPERTY_HAS_BEEN_DELETED` (WARN - when something has been auto-deleted without consumer intervention)\n", - "example" : "PROPERTY_WILL_BE_IGNORED", - "maxLength" : 50, - "type" : "string" - }, - "jsonPath" : { - "description" : "A path to the property, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example" : "$.location.facilityCode", - "maxLength" : 500, - "type" : "string" - }, - "message" : { - "description" : "A description with additional information.\n", - "example" : "Spaces not allowed in facility code", - "maxLength" : 5000, - "type" : "string" - }, - "property" : { - "description" : "The name of the property causing the error/warning.\n", - "example" : "facilityCode", - "maxLength" : 100, - "type" : "string" - }, - "severity" : { - "description" : "The severity of the feedback. Possible values are:\n- `INFO` (Information - \"Your reefer container will use renewable energy\", \"This earlier / premium service is available\")\n- `WARN` (Warning - \"I'm going to replace\" / \"Ignore this value\" / \"Use another value instead\")\n- `ERROR` (Error - \"This must be changed!\")\n", - "example" : "WARN", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "code", - "message", - "severity" - ], - "title" : "Feedback", - "type" : "object" - }, - "GeoCoordinate" : { - "description" : "An object used to express a location using `latitude` and `longitude`.\n", - "properties" : { - "latitude" : { - "description" : "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", - "example" : "48.8585500", - "maxLength" : 10, - "type" : "string" - }, - "longitude" : { - "description" : "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", - "example" : "2.294492036", - "maxLength" : 11, - "type" : "string" - } - }, - "required" : [ - "latitude", - "longitude" - ], - "title" : "Geo Coordinate", - "type" : "object" - }, - "GrossWeight" : { - "description" : "Total weight of the goods carried, including packaging.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 12000.3, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Gross Weight", - "type" : "object" - }, - "HouseBillOfLading" : { - "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.\n", - "properties" : { - "documentParties" : { - "$ref" : "#/components/schemas/DocumentPartiesHouseBL" - }, - "houseBillOfLadingReference" : { - "description" : "A unique number allocated by the Ocean Transport Intermediary (OTI) to the `House Bill of Lading`.\n", - "example" : "HBOL001", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "isToOrder" : { - "description" : "Indicates whether the `House Bill of Lading` (HBL) is issued `to order` or not. If `true`, `Notify party` at `HBL` level is mandatory\n", - "example" : false, - "type" : "boolean" - }, - "methodOfPayment" : { - "description" : "Method used for the payment of prepaid charges. It can be one of the following values: \n- `A` (Cash)\n- `B` (Credit Card)\n- `C` (Cheque)\n- `D` (Other)\n- `H` (Electronic funds transfer)\n- `Y` (Account holder with carrier)\n- `Z` (Not prepaid)\n", - "example" : "A", - "maxLength" : 1, - "type" : "string" - }, - "placeOfAcceptance" : { - "$ref" : "#/components/schemas/PlaceOfAcceptance" - }, - "placeOfFinalDelivery" : { - "$ref" : "#/components/schemas/PlaceOfFinalDelivery" - } - }, - "required" : [ - "houseBillOfLadingReference" - ], - "title" : "House Bill of Lading", - "type" : "object" - }, - "IdentifyingCode" : { - "properties" : { - "codeListName" : { - "description" : "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", - "example" : "DID", - "maxLength" : 100, - "type" : "string" - }, - "codeListProvider" : { - "description" : "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", - "example" : "W3C", - "maxLength" : 100, - "type" : "string" - }, - "partyCode" : { - "description" : "Code to identify the party as provided by the code list provider\n", - "example" : "MSK", - "maxLength" : 150, - "type" : "string" - } - }, - "required" : [ - "codeListProvider", - "partyCode" - ], - "title" : "Identifying Code", - "type" : "object" - }, - "InnerPackaging" : { - "description" : "Object for inner packaging specification\n", - "properties" : { - "description" : { - "description" : "Description of the packaging.\n", - "example" : "Woven plastic water resistant Bag", - "maxLength" : 100, - "type" : "string" - }, - "material" : { - "description" : "The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`.\n", - "example" : "Plastic", - "maxLength" : 100, - "type" : "string" - }, - "quantity" : { - "description" : "Count of `Inner Packagings` of the referenced `Dangerous Goods`.\n", - "example" : 20, - "format" : "int32", - "type" : "integer" - } - }, - "required" : [ - "description", - "material", - "quantity" - ], - "title" : "Inner Packaging", - "type" : "object" - }, - "InvoicePayableAt" : { - "description" : "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location can be provided as a `UN Location Code` or as a fallback - a `freeText` field\n", - "oneOf" : [ - { - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - } - }, - "required" : [ - "UNLocationCode" - ], - "title" : "UN Location Code", - "type" : "object" - }, - { - "properties" : { - "freeText" : { - "description" : "The name of the location where payment will be rendered by the customer.\n", - "example" : "DCSA Headquarters", - "maxLength" : 35, - "type" : "string" - } - }, - "required" : [ - "freeText" - ], - "title" : "Free text", - "type" : "object" - } - ], - "title" : "Invoice Payable At", - "type" : "object" - }, - "InvoicePayableAtShippingInstructions" : { - "description" : "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location must be provided as a `UN Location Code`\n", - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - } - }, - "required" : [ - "UNLocationCode" - ], - "title" : "Invoice Payable At", - "type" : "object" - }, - "IssueToParty" : { - "description" : "The party to whom the `Bill of Lading` must be issued.\n", - "properties" : { - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Globeteam", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "sendToPlatform" : { - "description" : "The EBL platform of the transaction party. \nThe value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Only applicable when `isElectronic=true` and `transportDocumentTypeCode=BOL`. The property **MUST** be absent for paper B/Ls (`isElectronic=false`)\n", - "example" : "BOLE", - "maxLength" : 4, - "pattern" : "^\\S+$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "partyName" - ], - "title" : "Issue To Party", - "type" : "object" - }, - "IssuingParty" : { - "description" : "Refers to a company or a legal entity.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Asseco Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "address", - "partyName" - ], - "title" : "Issuing Party", - "type" : "object" - }, - "Limits" : { - "description" : "Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure.\n", - "properties" : { - "SADT" : { - "description" : "Lowest temperature in which self-accelerating decomposition may occur in a substance\n", - "example" : 54.1, - "format" : "float", - "type" : "number" - }, - "SAPT" : { - "description" : "Lowest temperature in which self-accelerating polymerization may occur in a substance\n", - "example" : 70, - "format" : "float", - "type" : "number" - }, - "flashPoint" : { - "description" : "Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air.\n\n**Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code.\n", - "example" : 42, - "format" : "float", - "type" : "number" - }, - "temperatureUnit" : { - "description" : "The unit for **all attributes in the limits structure** in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n", - "enum" : [ - "CEL", - "FAH" - ], - "example" : "CEL", - "type" : "string" - }, - "transportControlTemperature" : { - "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.\n", - "example" : 24.1, - "format" : "float", - "type" : "number" - }, - "transportEmergencyTemperature" : { - "description" : "Temperature at which emergency procedures shall be implemented\n", - "example" : 74.1, - "format" : "float", - "type" : "number" - } - }, - "required" : [ - "temperatureUnit" - ], - "title" : "Limits", - "type" : "object" - }, - "NationalCommodityCode" : { - "description" : "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "BR", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", - "example" : "NCM", - "maxLength" : 10, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "values" : { - "description" : "A list of `national commodity codes` values.\n", - "example" : [ - "1515", - "2106", - "2507", - "2512" - ], - "items" : { - "description" : "The value of the `National Commodity Code`\n", - "example" : "1515", - "maxLength" : 10, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "countryCode", - "type", - "values" - ], - "title" : "National Commodity Code", - "type" : "object" - }, - "NetExplosiveContent" : { - "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", - "properties" : { - "unit" : { - "description" : "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "enum" : [ - "KGM", - "LBR", - "GRM", - "ONZ" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Explosive Content", - "type" : "object" - }, - "NetVolume" : { - "description" : "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "enum" : [ - "MTQ", - "FTQ", - "LTR" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "The volume of the referenced dangerous goods.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Volume", - "type" : "object" - }, - "NetWeight" : { - "description" : "Total weight of the goods carried, excluding packaging.\n", - "properties" : { - "unit" : { - "description" : "Unit of measure used to describe the `netWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "Total weight of the goods carried, excluding packaging.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Weight", - "type" : "object" - }, - "NotifyParty" : { - "description" : "The person to be notified when a shipment arrives at its destination.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "reference" : { - "description" : "A reference linked to the `NotifyParty`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Notify Party", - "type" : "object" - }, - "NotifyPartyHBL" : { - "description" : "The person to be notified when a shipment arrives at its destination.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Notify Party", - "type" : "object" - }, - "OnwardInlandRouting" : { - "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).\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Onward Inland Routing", - "type" : "object" - }, - "OriginChargesPaymentTerm" : { - "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).\n", - "properties" : { - "haulageChargesPaymentTermCode" : { - "description" : "An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "otherChargesPaymentTermCode" : { - "description" : "An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "portChargesPaymentTermCode" : { - "description" : "An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - } - }, - "title" : "Origin Charges Payment Term", - "type" : "object" - }, - "OtherDocumentParty" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n", - "properties" : { - "party" : { - "$ref" : "#/components/schemas/Party" - }, - "partyFunction" : { - "description" : "Specifies the role of the party in a given context. Possible values are:\n\n- `SCO` (Service Contract Owner)\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `COW` (Invoice payer on behalf of the consignor (shipper))\n- `COX` (Invoice payer on behalf of the consignee)\n- `CSR` (Consolidator)\n- `MFR` (Manufacturer)\n- `WHK` (Warehouse Keeper)\n", - "example" : "DDS", - "maxLength" : 3, - "type" : "string" - } - }, - "required" : [ - "party", - "partyFunction" - ], - "title" : "Other Document Party", - "type" : "object" - }, - "OtherDocumentPartyHBL" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n", - "properties" : { - "party" : { - "$ref" : "#/components/schemas/Party" - }, - "partyFunction" : { - "description" : "Specifies the role of the party in a given context. Possible values are:\n\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `CSR` (Consolidator)\n- `MFR` (Manufacturer)\n- `WHK` (Warehouse Keeper)\n", - "example" : "DDS", - "maxLength" : 3, - "type" : "string" - } - }, - "required" : [ - "party", - "partyFunction" - ], - "title" : "Other Document Party", - "type" : "object" - }, - "OuterPackaging" : { - "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.\n", - "properties" : { - "dangerousGoods" : { - "description" : "A list of `Dangerous Goods`\n", - "items" : { - "$ref" : "#/components/schemas/DangerousGoods" - }, - "type" : "array" - }, - "description" : { - "description" : "Description of the outer packaging/overpack.\n", - "example" : "Drum, steel", - "maxLength" : 100, - "type" : "string" - }, - "imoPackagingCode" : { - "description" : "The code of the packaging as per IMO.\n\n**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.\n", - "example" : "1A2", - "maxLength" : 5, - "minLength" : 1, - "pattern" : "^[A-Z0-9]{1,5}$", - "type" : "string" - }, - "numberOfPackages" : { - "description" : "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n", - "example" : 18, - "format" : "int32", - "maximum" : 99999999, - "minimum" : 1, - "type" : "integer" - }, - "packageCode" : { - "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example" : "5H", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z0-9]{2}$", - "type" : "string" - }, - "woodDeclaration" : { - "description" : "Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include:\n- `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped)\n- `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate)\n- `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)\n- `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate)\n", - "example" : "TREATED_AND_CERTIFIED", - "maxLength" : 30, - "type" : "string" - } - }, - "required" : [ - "description", - "numberOfPackages" - ], - "title" : "Outer Packaging", - "type" : "object" - }, - "OuterPackagingShipper" : { - "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.\n\n**Condition:** Mandatory for non-dangerous goods cargo.\n", - "properties" : { - "description" : { - "description" : "Description of the outer packaging/overpack.\n", - "example" : "Drum, steel", - "maxLength" : 100, - "type" : "string" - }, - "numberOfPackages" : { - "description" : "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n", - "example" : 18, - "format" : "int32", - "maximum" : 99999999, - "minimum" : 1, - "type" : "integer" - }, - "packageCode" : { - "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example" : "5H", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z0-9]{2}$", - "type" : "string" - }, - "woodDeclaration" : { - "description" : "Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include:\n- `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped)\n- `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate)\n- `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)\n- `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate)\n", - "example" : "TREATED_AND_CERTIFIED", - "maxLength" : 30, - "type" : "string" - } - }, - "required" : [ - "description", - "numberOfPackages" - ], - "title" : "Outer Packaging (Shipper)", - "type" : "object" - }, - "Party" : { - "description" : "Refers to a company or a legal entity.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Asseco Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "reference" : { - "description" : "A reference linked to the `Party`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "partyName" - ], - "title" : "Party", - "type" : "object" - }, - "PartyAddress" : { - "description" : "An object for storing address related information\n", - "properties" : { - "POBox" : { - "description" : "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example" : "123", - "maxLength" : 20, - "type" : "string" - }, - "UNLocationCode" : { - "description" : "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "description" : "The city name of the party’s address.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "floor" : { - "description" : "The floor of the party’s street number.\n", - "example" : "2nd", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "postCode" : { - "description" : "The post code of the party’s address.", - "example" : "1047 HM", - "maxLength" : 10, - "type" : "string" - }, - "stateRegion" : { - "description" : "The state/region of the party’s address.", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - }, - "street" : { - "description" : "The name of the street of the party’s address.", - "example" : "Ruijggoordweg", - "maxLength" : 70, - "type" : "string" - }, - "streetNumber" : { - "description" : "The number of the street of the party’s address.", - "example" : "100", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode", - "street" - ], - "title" : "Party Address", - "type" : "object" - }, - "PartyContactDetail" : { - "anyOf" : [ - { - "description" : "`Phone` is mandatory to provide\n", - "properties" : { - "phone" : { - "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).\n", - "example" : "+45 70262970", - "maxLength" : 30, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "phone" - ], - "title" : "Phone required", - "type" : "object" - }, - { - "description" : "`Email` is mandatory to provide\n", - "properties" : { - "email" : { - "description" : "`E-mail` address to be used\n", - "example" : "info@dcsa.org", - "maxLength" : 100, - "pattern" : "^.+@\\S+$", - "type" : "string" - } - }, - "required" : [ - "email" - ], - "title" : "Email required", - "type" : "object" - } - ], - "description" : "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`.\n", - "example" : { - "name" : "Henrik", - "phone" : "+45 51801234" - }, - "properties" : { - "name" : { - "description" : "Name of the contact\n", - "example" : "Henrik", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "name" - ], - "title" : "Party Contact Detail", - "type" : "object" - }, - "PlaceOfAcceptance" : { - "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`.\n\n**Condition:** Mandatory if different from `Place of Receipt` at the `Master Transport Document` level.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, an `Address` or a `GeoCoordinate`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Acceptance", - "type" : "object" - }, - "PlaceOfDelivery" : { - "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.\n\n**Condition:** Only when onward transport is done by the carrier\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Delivery", - "type" : "object" - }, - "PlaceOfFinalDelivery" : { - "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`.\n\n**Condition:** Mandatory if different from `Place of Delivery` at the `Master Transport Document` level. (**Note:** in case of carrier haulage this will be the same as the `Place of Delivery`)\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility`, an `Address` or a `GeoCoordinate`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Final Delivery", - "type" : "object" - }, - "PlaceOfIssue" : { - "description" : "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", - "oneOf" : [ - { - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - } - }, - "required" : [ - "UNLocationCode" - ], - "title" : "UN Location Code", - "type" : "object" - }, - { - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - } - }, - "required" : [ - "countryCode" - ], - "title" : "Country Code", - "type" : "object" - } - ], - "properties" : { - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Issue", - "type" : "object" - }, - "PlaceOfReceipt" : { - "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.\n\n**Condition:** Only when pre-carriage is done by the carrier.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Receipt", - "type" : "object" - }, - "PortOfDischarge" : { - "description" : "An object to capture `Port of Discharge` location specified as: the location where the cargo is discharged from the last sea-going vessel.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "$ref" : "#/components/schemas/City" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Port of Discharge", - "type" : "object" - }, - "PortOfLoading" : { - "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.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "$ref" : "#/components/schemas/City" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Port of Loading", - "type" : "object" - }, - "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.\n", - "properties" : { - "type" : { - "description" : "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n", - "example" : "CR", - "maxLength" : 3, - "type" : "string" - }, - "value" : { - "description" : "The value of the reference. \n", - "example" : "HHL00103004", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "type", - "value" - ], - "title" : "Reference", - "type" : "object" - }, - "ReferenceConsignmentItem" : { - "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.\n", - "properties" : { - "type" : { - "description" : "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n- `SPO` (Shipper's Purchase Order)\n- `CPO` (Consignee's Purchase Order)\n", - "example" : "CR", - "maxLength" : 3, - "type" : "string" - }, - "values" : { - "description" : "List of `referenceValues` for a given `referenceType`.\n", - "items" : { - "description" : "The value of the reference. \n", - "example" : "HHL00103004", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "type", - "values" - ], - "title" : "Reference (Consignment Item)", - "type" : "object" - }, - "RequiredEquipment" : { - "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.\n", - "properties" : { - "ISOEquipmentCode" : { - "description" : "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n", - "example" : "22G1", - "maxLength" : 4, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "tareWeight" : { - "$ref" : "#/components/schemas/TareWeight" - } - }, - "required" : [ - "ISOEquipmentCode", - "equipmentReference", - "tareWeight" - ], - "title" : "Equipment (Required Properties)", - "type" : "object" - }, - "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.\n", - "properties" : { - "number" : { - "description" : "Identifies a seal affixed to the container.", - "example" : "VET123", - "maxLength" : 15, - "type" : "string" - }, - "source" : { - "description" : "The source of the seal, namely who has affixed the seal.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n\n**Condition:** Seal source may be required depending on the type of commodity being shipped.\n", - "enum" : [ - "CAR", - "SHI", - "VET", - "CUS" - ], - "example" : "CUS", - "type" : "string" - } - }, - "required" : [ - "number" - ], - "title" : "Seal", - "type" : "object" - }, - "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.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Seller", - "type" : "object" - }, - "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.\n\n**Condition:** Either the `address` or the `displayedAddress` must be included in the `Transport Document`.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "purchaseOrderReferences" : { - "description" : "A list of `Purchase Order Reference`s linked to the `Shipper`.\n", - "items" : { - "description" : "A purchase order reference linked to the `Shipper`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "reference" : { - "description" : "A reference linked to the `Shipper`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Shipper", - "type" : "object" - }, - "ShipperHBL" : { - "description" : "The `Shipper` on the `House Bill of Lading`.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Shipper", - "type" : "object" - }, - "ShippingInstructions" : { - "description" : "The `Shipping Instructions` as provided by the Shipper.\n", - "properties" : { - "advanceManifestFilings" : { - "description" : "A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing\n", - "items" : { - "$ref" : "#/components/schemas/AdvanceManifestFiling" - }, - "type" : "array" - }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItemShipper" - }, - "minItems" : 1, - "type" : "array" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "destinationChargesPaymentTerm" : { - "$ref" : "#/components/schemas/DestinationChargesPaymentTerm" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "documentParties" : { - "$ref" : "#/components/schemas/DocumentPartiesShippingInstructions" - }, - "feedbacks" : { - "description" : "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items" : { - "$ref" : "#/components/schemas/Feedback" - }, - "type" : "array" - }, - "freightPaymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "houseBillOfLadings" : { - "description" : "A list of `House Bill of Ladings` specified by the Shipper.\n", - "items" : { - "$ref" : "#/components/schemas/HouseBillOfLading" - }, - "type" : "array" - }, - "invoicePayableAt" : { - "$ref" : "#/components/schemas/InvoicePayableAtShippingInstructions" - }, - "isCarriersAgentAtDestinationRequired" : { - "description" : "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example" : false, - "type" : "boolean" - }, - "isElectronic" : { - "description" : "An indicator whether the transport document is electronically transferred.\n", - "example" : true, - "type" : "boolean" - }, - "isHBLIssued" : { - "description" : "Indicates whether one or more `House Bill of Lading(s)` have been issued. This property is used by the carrier to identify which `ENS` filing type must be submitted (`F10` or `F11`, `F12` or `F13`) to comply with `ICS2` customs regulations\n", - "example" : true, - "type" : "boolean" - }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" - }, - "isToOrder" : { - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example" : false, - "type" : "boolean" - }, - "methodOfPayment" : { - "description" : "Method used for the payment of prepaid charges. It can be one of the following values: \n- `A` (Cash)\n- `B` (Credit Card)\n- `C` (Cheque)\n- `D` (Other)\n- `H` (Electronic funds transfer)\n- `Y` (Account holder with carrier)\n- `Z` (Not prepaid)\n", - "example" : "A", - "maxLength" : 1, - "type" : "string" - }, - "numberOfCopiesWithCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfCopiesWithoutCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithoutCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "originChargesPaymentTerm" : { - "$ref" : "#/components/schemas/OriginChargesPaymentTerm" - }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "minItems" : 1, - "type" : "array" - }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/PlaceOfIssue" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "requestedCarrierCertificates" : { - "description" : "Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack\n", - "items" : { - "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:\n- `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1)\n- `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2)\n- `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3)\n- `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4)\n- `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5)\n- `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6)\n- `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7)\n- `VESSEL_PARTICULARS_1` (Vessel Particulars 1)\n- `VESSEL_PARTICULARS_2` (Vessel Particulars 2)\n- `VESSEL_PARTICULARS_3` (Vessel Particulars 3)\n- `VESSEL_PARTICULARS_4` (Vessel Particulars 4)\n- `VESSEL_PARTICULARS_5` (Vessel Particulars 5)\n- `VESSEL_PARTICULARS_6` (Vessel Particulars 6)\n- `VESSEL_PARTICULARS_7` (Vessel Particulars 7)\n- `VESSEL_PARTICULARS_8` (Vessel Particulars 8)\n- `VESSEL_PARTICULARS_9` (Vessel Particulars 9)\n- `VESSEL_PARTICULARS_10` (Vessel Particulars 10)\n- `VESSEL_PARTICULARS_11` (Vessel Particulars 11)\n- `VESSEL_PARTICULARS_12` (Vessel Particulars 12)\n- `VESSEL_PARTICULARS_13` (Vessel Particulars 13)\n- `VESSEL_PARTICULARS_14` (Vessel Particulars 14)\n- `VESSEL_PARTICULARS_15` (Vessel Particulars 15)\n- `VESSEL_PARTICULARS_16` (Vessel Particulars 16)\n- `VESSEL_PARTICULARS_17` (Vessel Particulars 17)\n- `VESSEL_PARTICULARS_18` (Vessel Particulars 18)\n", - "example" : "VESSEL_PARTICULARS_1", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "requestedCarrierClauses" : { - "description" : "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items" : { - "description" : "A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa.org/wp-content/uploads/2023/12/202312-Standardised-Clauses-BL.pdf). Possible values are:\n- `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics)\n- `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific)\n- `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container)\n- `CARGO_CARGOVALUE` (Cargo/Cargo value)\n- `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature)\n- `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads)\n", - "example" : "CARGO_CARGOSPECIFICS", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "routingOfConsignmentCountries" : { - "description" : "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : "array" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "shippingInstructionsStatus" : { - "description" : "The status of the `Shipping Instructions`. Possible values are:\n- `RECEIVED` (Shipping Instructions has been received)\n- `PENDING_UPDATE` (An update is required to the Shipping Instructions)\n- `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery)\n", - "example" : "RECEIVED", - "maxLength" : 50, - "type" : "string" - }, - "transportDocumentReference" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "enum" : [ - "BOL", - "SWB" - ], - "example" : "SWB", - "type" : "string" - }, - "updatedShippingInstructionsStatus" : { - "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:\n- `UPDATE_RECEIVED` (An update to a Shipping Instructions is waiting to be processed)\n- `UPDATE_CONFIRMED` (An update to a Shipping Instructions has been confirmed)\n- `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer)\n- `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider)\n", - "example" : "UPDATE_RECEIVED", - "maxLength" : 50, - "type" : "string" - }, - "utilizedTransportEquipments" : { - "description" : "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items" : { - "$ref" : "#/components/schemas/UtilizedTransportEquipmentShipper" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsStatus", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "title" : "Shipping Instructions", - "type" : "object" - }, - "ShippingInstructionsData" : { - "description" : "`Shipping Instructions` specific properties for the `Notification`\n", - "properties" : { - "feedbacks" : { - "description" : "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items" : { - "$ref" : "#/components/schemas/Feedback" - }, - "type" : "array" - }, - "shippingInstructions" : { - "$ref" : "#/components/schemas/ShippingInstructionsFullNotification" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n\n**Condition:** `shippingInstructionsReference` and/or `transportDocumentReference` is required to provide\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "shippingInstructionsStatus" : { - "description" : "The status of the `Shipping Instructions`. Possible values are:\n\n- `RECEIVED` (Shipping Instructions has been received)\n- `PENDING_UPDATE` (An update is required to the Shipping Instructions)\n- `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery)\n", - "example" : "RECEIVED", - "maxLength" : 50, - "type" : "string" - }, - "transportDocumentReference" : { - "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.\n\n**Condition:** `shippingInstructionsReference` and/or `transportDocumentReference` is required to provide\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "updatedShippingInstructions" : { - "$ref" : "#/components/schemas/UpdatedShippingInstructionsFullNotification" - }, - "updatedShippingInstructionsStatus" : { - "description" : "The status of latest update to the `Shipping Instructions`. If no update has been requested - then this property is empty. Possible values are:\n\n- `UPDATE_RECEIVED` (An update to a Shipping Instructions has been received and is awaiting to be processed)\n- `UPDATE_CONFIRMED` (Update is confirmed)\n- `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer)\n- `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider)\n", - "example" : "UPDATE_RECEIVED", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "shippingInstructionsStatus" - ], - "title" : "Data", - "type" : "object" - }, - "ShippingInstructionsFullNotification" : { - "allOf" : [ - { - "$ref" : "#/components/schemas/ShippingInstructions" - } - ], - "description" : "This property contains the shippingInstructions in case the subscriber is subscribing to the `Full State Transfer` of the Shipping Instructions.\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the Shipping Instructions then the content in this property can be ignored.\n", - "title" : "Shipping Instructions", - "type" : "object" - }, - "ShippingInstructionsNotification" : { - "description" : "`CloudEvent` specific properties for the `Notification`.\n", - "properties" : { - "data" : { - "$ref" : "#/components/schemas/ShippingInstructionsData" - }, - "datacontenttype" : { - "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).\n\nFor 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.\n\nIn 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\"`.\n\nWhen 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.\n", - "enum" : [ - "application/json" - ], - "example" : "application/json", - "type" : "string" - }, - "id" : { - "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.\n", - "example" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "maxLength" : 100, - "type" : "string" - }, - "source" : { - "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.\n\nProducers MUST ensure that `source` + `id` is unique for each distinct event.\n\nAn 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.\n\nA 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.\n", - "example" : "https://member.com/", - "maxLength" : 4096, - "type" : "string" - }, - "specversion" : { - "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.\n\nCurrently, 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.\n", - "enum" : [ - "1.0" - ], - "example" : "1.0", - "type" : "string" - }, - "subscriptionReference" : { - "description" : "The reference of the subscription that has triggered this event\n", - "example" : "30675492-50ff-4e17-a7df-7a487a8ad343", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "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.\n", - "example" : "2018-04-05T17:31:00Z", - "format" : "date-time", - "type" : "string" - }, - "type" : { - "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.\n", - "enum" : [ - "org.dcsa.shipping-instructions.v3" - ], - "example" : "org.dcsa.shipping-instructions.v3", - "type" : "string" - } - }, - "required" : [ - "data", - "datacontenttype", - "id", - "source", - "specversion", - "subscriptionReference", - "time", - "type" - ], - "title" : "Shipping Instructions Notification", - "type" : "object" - }, - "TareWeight" : { - "description" : "The weight of an empty container (gross container weight).\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "The weight of an empty container (gross container weight).\n", - "example" : 4800, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Tare Weight", - "type" : "object" - }, - "TaxLegalReference" : { - "description" : "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "IN", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The reference type code as defined by the relevant tax and/or legal authority.\n", - "example" : "PAN", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "value" : { - "description" : "The value of the `taxLegalReference`\n", - "example" : "AAAAA0000A", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "countryCode", - "type", - "value" - ], - "title" : "Tax & Legal Reference", - "type" : "object" - }, - "TransportDocument" : { - "description" : "The document that governs the terms of carriage between shipper and carrier for maritime transportation. Two distinct types of transport documents exist:\n- Bill of Lading\n- Sea Waybill. \n", - "properties" : { - "cargoMovementTypeAtDestination" : { - "description" : "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example" : "FCL", - "maxLength" : 3, - "type" : "string" - }, - "cargoMovementTypeAtOrigin" : { - "description" : "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example" : "FCL", - "maxLength" : 3, - "type" : "string" - }, - "carrierClauses" : { - "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.\n", - "items" : { - "description" : "The content of the clause.\n", - "example" : "It is not allowed to...", - "maxLength" : 20000, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "carrierCode" : { - "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.\n", - "example" : "MMCU", - "maxLength" : 4, - "pattern" : "^\\S+$", - "type" : "string" - }, - "carrierCodeListProvider" : { - "description" : "The code list provider for the `carrierCode`. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "enum" : [ - "SMDG", - "NMFTA" - ], - "example" : "NMFTA", - "type" : "string" - }, - "charges" : { - "description" : "A list of `Charges`\n", - "items" : { - "$ref" : "#/components/schemas/Charge" - }, - "type" : "array" - }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItem" - }, - "minItems" : 1, - "type" : "array" - }, - "contractQuotationReference" : { - "description" : "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n", - "example" : "HHL1401", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "declaredValue" : { - "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.\n\n**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).\n", - "example" : 1231.1, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "declaredValueCurrency" : { - "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).\n", - "example" : "DKK", - "maxLength" : 3, - "minLength" : 3, - "pattern" : "^[A-Z]{3}$", - "type" : "string" - }, - "deliveryTypeAtDestination" : { - "description" : "Indicates the type of service offered at `Destination`. The options are:\n\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "enum" : [ - "CY", - "SD", - "CFS" - ], - "example" : "CY", - "maxLength" : 3, - "type" : "string" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "displayedShippedOnBoardReceivedForShipment" : { - "description" : "The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board.\n", - "example" : "Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier", - "maxLength" : 250, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "documentParties" : { - "$ref" : "#/components/schemas/DocumentParties" - }, - "freightPaymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "invoicePayableAt" : { - "$ref" : "#/components/schemas/InvoicePayableAt" - }, - "isElectronic" : { - "description" : "An indicator whether the transport document is electronically transferred.\n", - "example" : true, - "type" : "boolean" - }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" - }, - "isToOrder" : { - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example" : false, - "type" : "boolean" - }, - "issueDate" : { - "description" : "Local date when the transport document has been issued.\n\nCan be omitted on draft transport documents, but must be provided when the document has been issued.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "numberOfCopiesWithCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfCopiesWithoutCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithoutCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfRiderPages" : { - "description" : "The number of additional pages required to contain the goods description on a transport document. Only applicable for physical transport documents.\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "minItems" : 1, - "type" : "array" - }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/PlaceOfIssue" - }, - "receiptTypeAtOrigin" : { - "description" : "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "enum" : [ - "CY", - "SD", - "CFS" - ], - "example" : "CY", - "maxLength" : 3, - "type" : "string" - }, - "receivedForShipmentDate" : { - "description" : "Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel).\n\nWhen provided on a transport document, the transportDocument is a `Received For Shipment` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "routingOfConsignmentCountries" : { - "description" : "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : "array" - }, - "serviceContractReference" : { - "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.\n", - "example" : "HHL51800000", - "maxLength" : 30, - "type" : "string" - }, - "shippedOnBoardDate" : { - "description" : "Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document.\n\nWhen provided on a transport document, the transportDocument is a `Shipped On Board` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "termsAndConditions" : { - "description" : "Carrier terms and conditions of transport.\n", - "example" : "Any reference in...", - "maxLength" : 50000, - "type" : "string" - }, - "transportDocumentReference" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocumentStatus" : { - "description" : "The status of the `Transport Document`. Possible values are:\n- DRAFT\n- APPROVED\n- ISSUED\n- PENDING_SURRENDER_FOR_AMENDMENT\n- SURRENDERED_FOR_AMENDMENT\n- PENDING_SURRENDER_FOR_DELIVERY\n- SURRENDERED_FOR_DELIVERY\n- VOIDED\n", - "example" : "DRAFT", - "maxLength" : 50, - "type" : "string" - }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "enum" : [ - "BOL", - "SWB" - ], - "example" : "SWB", - "type" : "string" - }, - "transports" : { - "$ref" : "#/components/schemas/Transports" - }, - "utilizedTransportEquipments" : { - "description" : "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items" : { - "$ref" : "#/components/schemas/UtilizedTransportEquipment" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "carrierCode", - "carrierCodeListProvider", - "consignmentItems", - "deliveryTypeAtDestination", - "documentParties", - "invoicePayableAt", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "receiptTypeAtOrigin", - "termsAndConditions", - "transportDocumentReference", - "transportDocumentStatus", - "transportDocumentTypeCode", - "transports", - "utilizedTransportEquipments" - ], - "title" : "Transport Document", - "type" : "object" - }, - "TransportDocumentData" : { - "description" : "`Transport Document` specific properties for the `Notification`\n", - "properties" : { - "feedbacks" : { - "description" : "Feedback that can be provided includes, but is not limited to:\n- unsupported properties\n- changed values\n- removed properties\n- general information\n", - "items" : { - "$ref" : "#/components/schemas/Feedback" - }, - "type" : "array" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocument" : { - "$ref" : "#/components/schemas/TransportDocumentFullNotification" - }, - "transportDocumentReference" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocumentStatus" : { - "description" : "The status of the `Transport Document`. Possible values are:\n\n- `DRAFT` (Transport Document is Drafted)\n- `APPROVED` (Transport Document has been Approved by consumer)\n- `ISSUED` (Transport Document has been Issued by provider)\n- `PENDING_SURRENDER_FOR_AMENDMENT` (Transport Document is Pending for Surrender for an Amendment)\n- `SURRENDER_FOR_AMENDMENT` (Transport Document Surrendered for an Amendment)\n- `VOID` (the Transport Document has been Voided)\n- `PENDING_SURRENDER_FOR_DELIVERY` (Transport Document pending surrender for Delivery)\n- `SURRENDER_FOR_DELIVERY` (Transport Document surrendered for Delivery)\n", - "example" : "DRAFT", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "transportDocumentReference", - "transportDocumentStatus" - ], - "title" : "Data", - "type" : "object" - }, - "TransportDocumentFullNotification" : { - "allOf" : [ - { - "$ref" : "#/components/schemas/TransportDocument" - } - ], - "description" : "This property contains the `transportDocument` in case the subscriber is subscribing to the `Full State Transfer` of the `Transport Document`.\n\nIn case the subscriber does not subscribe to the `Full State Transfer` of the `Transport Document` then the content in this property can be ignored.\n\n**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\n\n GET /v3/transport-documents/{transportDocumentReference}\n\npayload implemented by the provider of the **Shipping Instructions and Transport Document** API.\n", - "title" : "Transport Document", - "type" : "object" - }, - "TransportDocumentNotification" : { - "description" : "`CloudEvent` specific properties for the `Notification`.\n", - "properties" : { - "data" : { - "$ref" : "#/components/schemas/TransportDocumentData" - }, - "datacontenttype" : { - "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).\n\nFor 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.\n\nIn 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\"`.\n\nWhen 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.\n", - "enum" : [ - "application/json" - ], - "example" : "application/json", - "type" : "string" - }, - "id" : { - "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.\n", - "example" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "maxLength" : 100, - "type" : "string" - }, - "source" : { - "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.\n\nProducers MUST ensure that `source` + `id` is unique for each distinct event.\n\nAn 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.\n\nA 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.\n", - "example" : "https://member.com/", - "maxLength" : 4096, - "type" : "string" - }, - "specversion" : { - "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.\n\nCurrently, 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.\n", - "enum" : [ - "1.0" - ], - "example" : "1.0", - "type" : "string" - }, - "subscriptionReference" : { - "description" : "The reference of the subscription that has triggered this event\n", - "example" : "30675492-50ff-4e17-a7df-7a487a8ad343", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "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.\n", - "example" : "2018-04-05T17:31:00Z", - "format" : "date-time", - "type" : "string" - }, - "type" : { - "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.\n", - "enum" : [ - "org.dcsa.transport-document.v3" - ], - "example" : "org.dcsa.transport-document.v3", - "type" : "string" - } - }, - "required" : [ - "data", - "datacontenttype", - "id", - "source", - "specversion", - "subscriptionReference", - "time", - "type" - ], - "title" : "Transport Document Notification", - "type" : "object" - }, - "Transports" : { - "properties" : { - "onCarriageBy" : { - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example" : "TRUCK", - "maxLength" : 50, - "type" : "string" - }, - "onwardInlandRouting" : { - "$ref" : "#/components/schemas/OnwardInlandRouting" - }, - "placeOfDelivery" : { - "$ref" : "#/components/schemas/PlaceOfDelivery" - }, - "placeOfReceipt" : { - "$ref" : "#/components/schemas/PlaceOfReceipt" - }, - "plannedArrivalDate" : { - "description" : "The planned date of arrival.\n", - "example" : "2024-06-07", - "format" : "date", - "type" : "string" - }, - "plannedDepartureDate" : { - "description" : "The planned date of departure.\n", - "example" : "2024-06-03", - "format" : "date", - "type" : "string" - }, - "portOfDischarge" : { - "$ref" : "#/components/schemas/PortOfDischarge" - }, - "portOfLoading" : { - "$ref" : "#/components/schemas/PortOfLoading" - }, - "preCarriageBy" : { - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example" : "RAIL", - "maxLength" : 50, - "type" : "string" - }, - "vesselVoyages" : { - "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.\n", - "items" : { - "$ref" : "#/components/schemas/VesselVoyage" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "plannedArrivalDate", - "plannedDepartureDate", - "portOfDischarge", - "portOfLoading", - "vesselVoyages" - ], - "title" : "Transports", - "type" : "object" - }, - "UTEquipment" : { - "description" : "To be used for SoC (Shipper owned Containers). If `isShipperOwned` is true then the equipment used needs to be specified\n", - "properties" : { - "equipment" : { - "$ref" : "#/components/schemas/RequiredEquipment" - }, - "isShipperOwned" : { - "description" : "Indicates whether the container is shipper owned (SOC).\n", - "example" : true, - "type" : "boolean" - } - }, - "required" : [ - "equipment", - "isShipperOwned" - ], - "title" : "Shipper Owned Equipment (SoC)", - "type" : "object" - }, - "UTEquipmentReference" : { - "description" : "To be used when referring to carrier owned containers (`isShipperOwned` is false). In this case it is only necessary to provide `equipmentReference`\n", - "properties" : { - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "isShipperOwned" : { - "description" : "Indicates whether the container is shipper owned (SOC).\n", - "example" : false, - "type" : "boolean" - } - }, - "required" : [ - "equipmentReference", - "isShipperOwned" - ], - "title" : "Carrier Owned Equipment", - "type" : "object" - }, - "UpdateShippingInstructions" : { - "description" : "The `Shipping Instructions` to update.\n", - "properties" : { - "advanceManifestFilings" : { - "description" : "A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing\n", - "items" : { - "$ref" : "#/components/schemas/AdvanceManifestFiling" - }, - "type" : "array" - }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItemShipper" - }, - "minItems" : 1, - "type" : "array" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "destinationChargesPaymentTerm" : { - "$ref" : "#/components/schemas/DestinationChargesPaymentTerm" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "documentParties" : { - "$ref" : "#/components/schemas/DocumentPartiesShippingInstructions" - }, - "freightPaymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "houseBillOfLadings" : { - "description" : "A list of `House Bill of Ladings` specified by the Shipper.\n", - "items" : { - "$ref" : "#/components/schemas/HouseBillOfLading" - }, - "type" : "array" - }, - "invoicePayableAt" : { - "$ref" : "#/components/schemas/InvoicePayableAtShippingInstructions" - }, - "isCarriersAgentAtDestinationRequired" : { - "description" : "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example" : false, - "type" : "boolean" - }, - "isElectronic" : { - "description" : "An indicator whether the transport document is electronically transferred.\n", - "example" : true, - "type" : "boolean" - }, - "isHBLIssued" : { - "description" : "Indicates whether one or more `House Bill of Lading(s)` have been issued. This property is used by the carrier to identify which `ENS` filing type must be submitted (`F10` or `F11`, `F12` or `F13`) to comply with `ICS2` customs regulations\n", - "example" : true, - "type" : "boolean" - }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" - }, - "isToOrder" : { - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example" : false, - "type" : "boolean" - }, - "methodOfPayment" : { - "description" : "Method used for the payment of prepaid charges. It can be one of the following values: \n- `A` (Cash)\n- `B` (Credit Card)\n- `C` (Cheque)\n- `D` (Other)\n- `H` (Electronic funds transfer)\n- `Y` (Account holder with carrier)\n- `Z` (Not prepaid)\n", - "example" : "A", - "maxLength" : 1, - "type" : "string" - }, - "numberOfCopiesWithCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfCopiesWithoutCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithoutCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "originChargesPaymentTerm" : { - "$ref" : "#/components/schemas/OriginChargesPaymentTerm" - }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "minItems" : 1, - "type" : "array" - }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/PlaceOfIssue" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "requestedCarrierCertificates" : { - "description" : "Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack\n", - "items" : { - "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:\n- `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1)\n- `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2)\n- `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3)\n- `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4)\n- `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5)\n- `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6)\n- `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7)\n- `VESSEL_PARTICULARS_1` (Vessel Particulars 1)\n- `VESSEL_PARTICULARS_2` (Vessel Particulars 2)\n- `VESSEL_PARTICULARS_3` (Vessel Particulars 3)\n- `VESSEL_PARTICULARS_4` (Vessel Particulars 4)\n- `VESSEL_PARTICULARS_5` (Vessel Particulars 5)\n- `VESSEL_PARTICULARS_6` (Vessel Particulars 6)\n- `VESSEL_PARTICULARS_7` (Vessel Particulars 7)\n- `VESSEL_PARTICULARS_8` (Vessel Particulars 8)\n- `VESSEL_PARTICULARS_9` (Vessel Particulars 9)\n- `VESSEL_PARTICULARS_10` (Vessel Particulars 10)\n- `VESSEL_PARTICULARS_11` (Vessel Particulars 11)\n- `VESSEL_PARTICULARS_12` (Vessel Particulars 12)\n- `VESSEL_PARTICULARS_13` (Vessel Particulars 13)\n- `VESSEL_PARTICULARS_14` (Vessel Particulars 14)\n- `VESSEL_PARTICULARS_15` (Vessel Particulars 15)\n- `VESSEL_PARTICULARS_16` (Vessel Particulars 16)\n- `VESSEL_PARTICULARS_17` (Vessel Particulars 17)\n- `VESSEL_PARTICULARS_18` (Vessel Particulars 18)\n", - "example" : "VESSEL_PARTICULARS_1", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "requestedCarrierClauses" : { - "description" : "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items" : { - "description" : "A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa.org/wp-content/uploads/2023/12/202312-Standardised-Clauses-BL.pdf). Possible values are:\n- `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics)\n- `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific)\n- `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container)\n- `CARGO_CARGOVALUE` (Cargo/Cargo value)\n- `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature)\n- `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads)\n", - "example" : "CARGO_CARGOSPECIFICS", - "maxLength" : 100, - "type" : "string" - }, - "type" : "array" - }, - "routingOfConsignmentCountries" : { - "description" : "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : "array" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "enum" : [ - "BOL", - "SWB" - ], - "example" : "SWB", - "type" : "string" - }, - "utilizedTransportEquipments" : { - "description" : "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items" : { - "$ref" : "#/components/schemas/UtilizedTransportEquipmentShipper" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsReference", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "title" : "Update Shipping Instructions", - "type" : "object" - }, - "UpdatedShippingInstructionsFullNotification" : { - "allOf" : [ - { - "$ref" : "#/components/schemas/ShippingInstructions" - } - ], - "description" : "This property contains the updated shipping instructions in case:\n - an update is currently active\n - the subscriber is subscribing to the `Full State Transfer` of the Shipping Instructions\n\nIn 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.\n", - "title" : "Updated Shipping Instructions", - "type" : "object" - }, - "UtilizedTransportEquipment" : { - "description" : "Specifies the container (`equipment`), the total `weight`, total `volume`, possible `ActiveReeferSettings`, `seals` and `references`\n", - "properties" : { - "activeReeferSettings" : { - "$ref" : "#/components/schemas/ActiveReeferSettings" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "equipment" : { - "$ref" : "#/components/schemas/Equipment" - }, - "isNonOperatingReefer" : { - "description" : "If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container.\n\n**Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type.\n", - "example" : false, - "type" : "boolean" - }, - "isShipperOwned" : { - "description" : "Indicates whether the container is shipper owned (SOC).\n", - "example" : true, - "type" : "boolean" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "seals" : { - "description" : "A list of `Seals`\n", - "items" : { - "$ref" : "#/components/schemas/Seal" - }, - "minItems" : 1, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "equipment", - "isShipperOwned", - "seals" - ], - "title" : "Utilized Transport Equipment", - "type" : "object" - }, - "UtilizedTransportEquipmentShipper" : { - "description" : "Specifies the container (`Equipment`), `Seals` and `References`\n", - "discriminator" : { - "mapping" : { - "false" : "#/components/schemas/UTEquipmentReference", - "true" : "#/components/schemas/UTEquipment" - }, - "propertyName" : "isShipperOwned" - }, - "oneOf" : [ - { - "$ref" : "#/components/schemas/UTEquipment" - }, - { - "$ref" : "#/components/schemas/UTEquipmentReference" - } - ], - "properties" : { - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "seals" : { - "description" : "A list of `Seals`\n", - "items" : { - "$ref" : "#/components/schemas/Seal" - }, - "minItems" : 1, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "seals" - ], - "title" : "Utilized Transport Equipment (Shipper)", - "type" : "object" - }, - "VesselVoyage" : { - "description" : "Vessel and export voyage", - "properties" : { - "carrierExportVoyageNumber" : { - "description" : "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.\n", - "example" : "2103S", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "universalExportVoyageReference" : { - "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]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example" : "2103N", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type" : "string" - }, - "vesselName" : { - "description" : "The name of the first sea going Vessel on board which the cargo is loaded or intended to be loaded\n", - "example" : "King of the Seas", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "carrierExportVoyageNumber", - "vesselName" - ], - "title" : "Vessel/Voyage", - "type" : "object" - } - } - }, - "info" : { - "contact" : { - "email" : "info@dcsa.org", - "name" : "Digital Container Shipping Association (DCSA)", - "url" : "https://dcsa.org" - }, - "description" : "

DCSA OpenAPI specification for the Shipping Instructions and Transport Document process

\n\nThis API is intended as an API between a carrier and anyone creating a `Shipping Instructions` and approving a `Transport Document`. The process includes:\n\n- Shipping Instructions submission\n- Shipping Instructions update\n- Draft Transport Document publication\n- Draft Transport Document update\n- Draft Transport Document approval\n\nFor 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)**.\n\nAll other documents related to the Electronic Bill of Lading publication can be found [here](https://dcsa.org/standards/ebill-of-lading/)\n\n### EBL (Implemented by provider)\n\nIt is possible to use the eBL API as a standalone API. In that case use one of the poll endPoints:\n\n GET /v3/shipping-instructions/{documentReference} # For Shipping Instructions status\n GET /v3/transport-documents/{transportDocumentReference} # For Transport Document status\n\nin order to poll information about status changes.\n\n**Note:** All `/v3/shipping-instructions` and `/v3/transport-documents` endPoints must be implemented by the provider.\n\n### Notifications (Implemented by consumer)\nIt 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).\n\n POST /v3/shipping-instructions-notifications\n POST /v3/transport-document-notifications\n\nThe 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.\n\nSigning up for notifications is defined outside the scope of this API specification.\n\n**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.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n\nAPI specification issued by [DCSA.org](https://dcsa.org/).\n", - "license" : { - "name" : "Apache 2.0", - "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "title" : "DCSA Shipping Instructions and Transport Document API", - "version" : "3.0.0" - }, - "openapi" : "3.0.3", - "paths" : { - "/v3/shipping-instructions" : { - "post" : { - "description" : "Creates a new `Shipping Instructions`. This endPoint corresponds with **UseCase 1 - Submit Shipping Instructions**.\n\n## Precondition\nThe consumer has information for a `Shipping Instructions`. The empty equipment has been released to the shipper. The `Booking` is in state `CONFIRMED`.\n\n## Postcondition\nThe provider has received the `Shipping Instructions`.\n\nThe consumer will receive a `202` (Accepted) if the payload schema validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives a `Shipping Instructions`:\n1. The payload (`Shipping Instructions`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided.\n - all values provided have correct data type.\n\n A `shippingInstructionsReference` (as a reference to the `Shipping Instructions`) is created and linked to the payload in the provider system.\n \n **For the rest of this description and in all examples the value `si-123` will be used as `shippingInstructionsReference`**\n\n3. A `202` (Accepted) response is returned with a payload containing **only** the `shippingInstructionsReference`:\n ```\n {\n shippingInstructionsReference: 'si-123'\n }\n ```\n\nFor `POST` `Shipping Instructions` the process ends here. The `Shipping Instructions`:\n - is now accepted by the provider system\n - 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)\n - a `202` (Accepted) response is sent to the consumer with a payload **only** containing the `shippingInstructionsReference`\n - awaits further processing by the provider\n\nThe 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\n\n GET /v3/shipping-instructions/{documentReference}\n \n endPoint to check if the `shippingInstructionsStatus` of the `Shipping Instructions` has changed.\n \n After the status has changed to `RECEIVED` further processing can continue by provider and will be communicated via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\n", - "operationId" : "create-shipping-instructions", - "parameters" : [ - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "examples" : { - "regularSTDExample" : { - "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`\n\nThe `Shipping Instructions` now awaits the provider to `DRAFT` a `Transport Document`.\n", - "summary" : "Create a Shipping Instructions\n", - "value" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "transportDocumentTypeCode" : "BOL", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/CreateShippingInstructions" - } - } - }, - "description" : "Parameters used to create the `Shipping Instructions`\n", - "required" : true - }, - "responses" : { - "202" : { - "content" : { - "application/json" : { - "examples" : { - "receExample" : { - "description" : "The `shippingInstructionsReference` has been accepted (no `shippingInstructionsStatus`) and schema validated by provider\n", - "summary" : "Shipping Instructions received\n", - "value" : { - "shippingInstructionsReference" : "si-123" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/CreateShippingInstructionsResponse" - } - } - }, - "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.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "description" : "`isElectronic` is a mandatory property in the `Shipping Instructions`. In case this property is missing an error objet is created.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Shipping Instructions missing isElectronic\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "isElectronic must be provided as part of a Shipping Instructions", - "errorCodeText" : "mandatory property missing", - "property" : "isElectronic" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions", - "statusCode" : 400, - "statusCodeMessage" : "isElectronic not found - it is a mandatory property in Shipping Instructions", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the `Shipping Instructions` does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while processing Shipping Instructions\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while processing Booking request", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n POST /v3/shipping-instructions\n \ntoo many times within a time period results in an error.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Making too many Shipping Instructions\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Shipping Instructions can be created per hour", - "errorCodeText" : "Max Shipping Instructions reached" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to create a Shipping Instructions has been requested. Please try again in 1 hour", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Creates a Shipping Instructions\n", - "tags" : [ - "Shipping Instructions" - ] - } - }, - "/v3/shipping-instructions-notifications" : { - "post" : { - "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.\n\n**This endPoint is to be implemented by a consumer of the EBL API in order to receive Notifications**\n", - "operationId" : "shipping-instructions-notifications", - "parameters" : [ - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "examples" : { - "declinedFullStateTransferExample" : { - "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'`)\n\nThe example shows an original `ShippingInstructions` with a wrong weight on `consignmentItem` and `cargoItem`. The updated weight is also wrong!\n", - "summary" : "Shipping Instructions update declined (Full State Transfer)\n", - "value" : { - "data" : { - "shippingInstructions" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "PENDING_UPDATE", - "transportDocumentTypeCode" : "BOL", - "updatedShippingInstructionsStatus" : "UPDATE_DECLINED", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - }, - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "PENDING_UPDATE", - "updatedShippingInstructions" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 120000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "PENDING_UPDATE", - "transportDocumentTypeCode" : "BOL", - "updatedShippingInstructionsStatus" : "UPDATE_DECLINED", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - }, - "updatedShippingInstructionsStatus" : "UPDATE_DECLINED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "SI001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.shipping-instructions.v3" - } - }, - "declinedLightweightExample" : { - "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'`)\n", - "summary" : "Shipping Instructions update declined (Lightweight)\n", - "value" : { - "data" : { - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "PENDING_UPDATE", - "updatedShippingInstructionsStatus" : "UPDATE_DECLINED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "SI001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.shipping-instructions.v3" - } - }, - "receivedFullStateTransferExample" : { - "description" : "A full state transfer notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`).\n", - "summary" : "Shipping Instructions request received (Full State Transfer)\n", - "value" : { - "data" : { - "shippingInstructions" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "RECEIVED", - "transportDocumentTypeCode" : "BOL", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - }, - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "RECEIVED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "SI001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.shipping-instructions.v3" - } - }, - "receivedLightweightExample" : { - "description" : "A lightweight notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`).\n", - "summary" : "Shipping Instructions request received (Lightweight)\n", - "value" : { - "data" : { - "shippingInstructionsReference" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "shippingInstructionsStatus" : "RECEIVED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "SI001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.shipping-instructions.v3" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ShippingInstructionsNotification" - } - } - }, - "description" : "The payload used to create a [`Shipping Instructions Notification`](#/ShippingInstructionsNotification)\n" - }, - "responses" : { - "204" : { - "description" : "No Content\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "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\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Shipping Instructions missing shippingInstructionsReference\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "shippingInstructionsReference must be provided as part of a Notification\n", - "errorCodeText" : "mandatory property missing", - "property" : "shippingInstructionsReference" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions-notifications", - "statusCode" : 400, - "statusCodeMessage" : "shippingInstructionsReference not found - mandatory to provide in a Notification\n", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the `Notification` does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Internal Server Error while processing Notification\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions-notifications", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while processing Shipping Instructions\n", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n POST /v3/shipping-instructions-notifications\n\ntoo many times within a timeperiod.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Making too many Notifications\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Notifications can be created per hour", - "errorCodeText" : "Max Notifications reached" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions-notifications", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to create a Notification has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Send a new Shipping Instructions Notification", - "tags" : [ - "Notifications" - ] - } - }, - "/v3/shipping-instructions/{documentReference}" : { - "get" : { - "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.\n\nThe 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`.\n\n GET /v3/shipping-instructions/{documentReference}?updatedContent=true\n\nThe `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:\n- the provider requests for a new update (**UseCase 2: Request to update Shipping Instructions**) in which case the \"old update\" is no longer accessible.\n- the consumer submits a new update (**UseCase 3: Submit updated Shipping Instructions**) in which case the \"new update\" provided **replaces** the \"old update\".\n\nIf `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.\n\nIf the provider is requesting changes to the `Shipping Instructions`, the `Feedback` object is used to inform the consumer what needs to change.\n\nIn 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.\n\nIn 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.\n", - "operationId" : "get-shipping-instructions", - "parameters" : [ - { - "description" : "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "explode" : false, - "in" : "path", - "name" : "documentReference", - "required" : true, - "schema" : { - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - { - "description" : "If set to `true`, the payload returned is the content of the `Updated Shipping Instructions`.\n\nDefault value is `false` in which case the content of the \"original\" `Shipping Instructions` is returned.\n\n**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\n", - "explode" : true, - "in" : "query", - "name" : "updatedContent", - "required" : false, - "schema" : { - "default" : false, - "example" : false, - "type" : "boolean" - }, - "style" : "form" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "responses" : { - "200" : { - "content" : { - "application/json" : { - "examples" : { - "dgExample" : { - "description" : "A `Shipping Instructions` with `Environmentally hazardous substance, liquid, N.O.S (Propiconazole)` which is transported in steel Jarricans.\n\nThe `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`.\n\n**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`.\n", - "summary" : "Updated Shipping Instructions with DG cargo\n", - "value" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "293499" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "HLXU1234567", - "outerPackaging" : { - "description" : "Jerrican, steel", - "numberOfPackages" : 400 - } - } - ], - "carrierBookingReference" : "RTM1234567", - "commoditySubreference" : "DGSubRef003", - "descriptionOfGoods" : [ - "Environmentally hazardous substance", - "liquid, N.O.S (Propiconazole)" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "b36484d0-1115-43c2-93e4-a378823a8386", - "shippingInstructionsStatus" : "RECEIVED", - "transportDocumentReference" : "4AD3FA470BB541B980CE", - "transportDocumentTypeCode" : "BOL", - "updatedShippingInstructionsStatus" : "UPDATE_CONFIRMED", - "utilizedTransportEquipments" : [ - { - "equipment" : { - "ISOEquipmentCode" : "22G1", - "equipmentReference" : "HLXU1234567", - "tareWeight" : { - "unit" : "KGM", - "value" : 2370 - } - }, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - }, - "reeferExample" : { - "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.\n\n**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`.\n", - "summary" : "Shipping Instructions with reefer cargo\n", - "value" : { - "advanceManifestFilings" : [ - { - "advanceManifestFilingsHouseBLPerformedBy" : "SELF", - "countryCode" : "US", - "manifestTypeCode" : "AFR", - "selfFilerCode" : "HHL007" - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "04052090" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "KKFU6671914", - "outerPackaging" : { - "description" : "Bottles", - "numberOfPackages" : 400, - "packageCode" : "BQ" - } - } - ], - "carrierBookingReference" : "CBR_123_REEFER", - "commoditySubreference" : "ReeferSubRef002", - "descriptionOfGoods" : [ - "Dairy products" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "feedbacks" : [ - { - "code" : "PROPERTY_VALUE_MUST_CHANGE", - "jsonPath" : "$.advanceManifestFilings[0]", - "message" : "Not a legal combination of \"manifestTypeCode\" (AFR) and \"countryCode\" (US)\n", - "property" : "advanceManifestFilings", - "severity" : "ERROR" - }, - { - "code" : "PROPERTY_VALUE_MUST_CHANGE", - "jsonPath" : "$.advanceManifestFilings", - "message" : "Missing \"ACI\" filing required for import to US\n", - "property" : "advanceManifestFilings", - "severity" : "ERROR" - } - ], - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "9051da7d-4099-4930-af35-7add4e68c635", - "shippingInstructionsStatus" : "PENDING_UPDATE", - "transportDocumentReference" : "D8931B95625E4B339F2A", - "transportDocumentTypeCode" : "BOL", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "KKFU6671914", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - }, - "regularSTDExample" : { - "description" : "A `RECEIVED` `Shipping Instructions` with standard Dry cargo waiting for the provider to `DRAFT` a `Transport Document`.\n", - "summary" : "Fetch Shipping Instructions with standard Dry cargo\n", - "value" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "shippingInstructionsStatus" : "RECEIVED", - "transportDocumentTypeCode" : "BOL", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ShippingInstructions" - } - } - }, - "description" : "Fetching the content of either the \"original\" `Shipping Instructions` or the `Updated Shipping Instructions`\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "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`.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "examples" : { - "notFoundExample" : { - "description" : "The `documentReference` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "documentReference not found\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions does not exist", - "errorCodeText" : "documentReference not found" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123?updatedContent=true", - "statusCode" : 404, - "statusCodeMessage" : "documentReference not found", - "statusCodeText" : "Not Found" - } - }, - "notFoundUpdateExample" : { - "description" : "The `Update Shipping Instructions` does not exist. No updates have been requested by the consumer.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Shipping Instructions update not found\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions has not yet been updated - no update exists", - "errorCodeText" : "Shipping Instructions does not contain an update" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123?updatedContent=true", - "statusCode" : 404, - "statusCodeMessage" : "No update accessible", - "statusCodeText" : "Not Found" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the consumer is requesting the content of the `UpdatedShipping Instructions`, and no update has yet been requested.\n\nA `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)\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "examples" : { - "conflictExample" : { - "description" : "The provider is already processing a request and needs to finish this process before any new requests are processed\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Conflicting request\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions cannot be updated/amended while it is being processed. Please try again later\n", - "errorCodeText" : "Conflicting request is being processed" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 409, - "statusCodeMessage" : "Previous request is being processed. Please try again\nlater\n", - "statusCodeText" : "Conflict" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "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)\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while fetching the Shipping Instructions\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while fetching the Shipping Instructions", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n GET /v3/shipping-instructions/si-123\n \ntoo many times within a time period.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Fetching too many `Transport Document` requests\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Shipping Instructions can be requested per hour", - "errorCodeText" : "Max Shipping Instructions requests reached" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to fetch a Shipping Instructions has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Gets the Shipping Instructions\n", - "tags" : [ - "Shipping Instructions" - ] - }, - "patch" : { - "description" : "A way for the consumer to Cancel an `Updated Shipping Instructions`. This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions**.\n\n## Precondition\nIn 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 either `RECEIVED` or `PENDING_UPDATE`.\n\n## Postcondition\nThe provider has received a cancellation from the consumer for an `Updated Shipping Instructions` that is in state `UPDATE_RECEIVED`.\n\nThe consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives a cancellation:\n1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided.\n - all values provided have correct data type.\n3. An empty response is returned and the consumer now awaits further processing by the provider.\n\nOnce 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\n\n GET /v3/shipping-instructions/{documentReference}\n \nendPoint to check if the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` of the `Shipping Instructions` has changed.\n", - "operationId" : "patch-shipping-instructions", - "parameters" : [ - { - "description" : "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "explode" : false, - "in" : "path", - "name" : "documentReference", - "required" : true, - "schema" : { - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "examples" : { - "cancelUpdateExample" : { - "description" : "Consumer wants to cancel an update provided to a `Shipping Instructions`. The `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED`\n", - "summary" : "Cancel a Shipping Instructions update\n", - "value" : { - "updatedShippingInstructionsStatus" : "UPDATE_CANCELLED" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/CancelShippingInstructionsUpdate" - } - } - }, - "description" : "Cancel the `Update Shipping Instructions`\n", - "required" : true - }, - "responses" : { - "202" : { - "content" : { - "application/json" : { - "examples" : { - "cancelUpdateExample" : { - "description" : "Consumer wants to cancel an update provided to a `Shipping Instructions`.\n", - "summary" : "Cancel a Shipping Instructions update\n" - } - } - } - }, - "description" : "The cancellation of the `Updated Shipping Instructions` is accepted and is now awaiting further processing by the provider.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "description" : "`APPROVE` is not a possible value when PATCHING an `Updated Shipping Instructions`.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Wrong Update Shipping Instructions status\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Only UPDATE_CANCELLED is an allowed value: APPROVE was inserted", - "errorCodeText" : "incorrect value", - "property" : "updatedShippingInstructionsStatus", - "value" : "APPROVE" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 400, - "statusCodeMessage" : "APPROVE is not a valid status to set", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the cancel payload does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "examples" : { - "notUpdateFoundExample" : { - "description" : "The `Update Shipping Instructions` does not exist. No updates have been requested by the consumer.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Shipping Instructions update not found\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions has no update request - nothing to cancel", - "errorCodeText" : "Shipping Instructions does not contain an update" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 404, - "statusCodeMessage" : "No update exists", - "statusCodeText" : "Not Found" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "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`.\n\nA `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)\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "examples" : { - "conflictExample" : { - "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.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Conflicting Shipping Instructions cancellation\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions cannot be cancelled while it is being processed", - "errorCodeText" : "Shipping Instructions is being processed" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 409, - "statusCodeMessage" : "Is being processed", - "statusCodeText" : "Conflict" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "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\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while cancelling the `Shipping Instructions`\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while cancelling the Shipping Instructions", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n PATCH /v3/shipping-instructions/si-123\n\ntoo many times within a time period.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Patching the `Shipping Instructions` too many times\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Shipping Instructions patches can be requested per hour", - "errorCodeText" : "Max Shipping Instructions requests reached" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to patch a Shipping Instructions has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Cancels an update to a Shipping Instructions\n", - "tags" : [ - "Shipping Instructions" - ] - }, - "put" : { - "description" : "Updates the `Shipping Instructions` with the `documentReference`. The path can contain either a `shippingInstructionsReference` or a `transportDocumentReference`. This endPoint corresponds with **UseCase 3 - Submit updated Shipping Instructions**\n\n### Precondition\nIn order to update a `Shipping Instructions`, the status of the `Shipping Instructions` needs to be in state:\n\n- `RECEIVED` in case the consumer has updated information for the `Shipping Instructions`\n- `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**)\n\n## Postcondition\nThe provider has received an update to the `Shipping Instructions` (**UseCase 3 - Submit updated Shipping Instructions**), from now on called the `Updated Shipping Instructions`.\n\nThe `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**) 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.\n\nThe consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives an **update** to a `Shipping Instructions`\n1. The payload (`Updated Shipping Instructions`) is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided\n - all values provided have correct data type.\n3. An empty response is returned and the consumer now awaits further processing by the provider.\n\nFor `PUT` `Shipping Instructions` the process ends here. The `Shipping Instructions`:\n - is now accepted by the provider system\n - the status of the `Shipping Instructions` is unchanged\n - a `202` (Accepted) response is sent with an empty payload\n - awaits further processing by the provider\n\nThe 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:\n - `shippingInstructionsStatus='RECEIVED'` and `updatedShippingInstructionsStatus='UPDATE_RECEIVED'` (if endPoint is used to make an update to a Submitted Shipping Instructions - **UseCase 1 - Submit Shipping Instructions**)\n - `shippingInstructionsStatus='PENDING_UPDATE'` and `updatedShippingInstructionsStatus='UPDATE_RECEIVED'` (if endPoint is used as a response to **UseCase 2 - Request to update Shipping Instructions**)\n\nThe 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\n\n GET /v3/shipping-instructions/{documentReference}\n \nendPoint to check if the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` of the `Shipping Instructions` has changed.\n \nIf 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:\n \n GET /v3/shipping-instructions/{documentReference}?updatedContent=true\n \nIt is possible to `GET` the content of the `Updated Shipping Instructions` via the example above until either:\n - the provider requests for a new update (**UseCase 2: Request to update Shipping Instructions**) in which case the \"old update\" is no longer accessible\n - the consumer submits a new update (**UseCase 3: Submit updated Shipping Instructions**) in which case the \"new update\" provided **replaces** the \"old update\".\n", - "operationId" : "update-shipping-instructions", - "parameters" : [ - { - "description" : "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "explode" : false, - "in" : "path", - "name" : "documentReference", - "required" : true, - "schema" : { - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "examples" : { - "regularSTDExample" : { - "description" : "An update for a `Shipping Instructions` with standard Dry cargo. The `Shipping Instructions` update now wait to be confirmed by the provider.\n", - "summary" : "Update Shipping Instructions\n", - "value" : { - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "commoditySubreference" : "RegSubRef001", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "documentParties" : { - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "shippingInstructionsReference" : "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "transportDocumentTypeCode" : "BOL", - "utilizedTransportEquipments" : [ - { - "equipmentReference" : "NARU3472484", - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/UpdateShippingInstructions" - } - } - }, - "description" : "Parameters used to update the `Shipping Instructions`\n", - "required" : true - }, - "responses" : { - "202" : { - "content" : { - "application/json" : { - "examples" : { - "receivedExample" : { - "description" : "An `Updated Shipping Instructions` received and accepted by provider, the `Updated Shipping Instructions` now awaits provider action, the `shippingInstructionStatus` does not change.\n", - "summary" : "Shipping Instructions updated by consumer\n" - } - } - } - }, - "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.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "description" : "`isElectronic` is a mandatory property in the `Shipping Instructions`. In case this property is missing an error object is created.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Shipping Instructions missing isElectronic\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "isElectronic must be provided as part of a Shipping Instructions", - "errorCodeText" : "mandatory property missing", - "property" : "isElectronic" - } - ], - "httpMethod" : "PUT", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 400, - "statusCodeMessage" : "isElectronic not found - it is a mandatory property in Shipping Instructions", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the updated `Shipping Instructions` does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "examples" : { - "conflictExample" : { - "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.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Not found request\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions does not exist", - "errorCodeText" : "shippingInstructionsReference not found" - } - ], - "httpMethod" : "PUT", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 404, - "statusCodeMessage" : "shippingInstructionsReference not found", - "statusCodeText" : "Not Found" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "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)\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "examples" : { - "conflictExample" : { - "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.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Conflicting Shipping Instructions update\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Shipping Instructions cannot be updated while it is being processed. Please try again later", - "errorCodeText" : "Shipping Instructions is being processed" - } - ], - "httpMethod" : "PUT", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 409, - "statusCodeMessage" : "Is being processed", - "statusCodeText" : "Conflict" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "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\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while processing `Shipping Instructions`\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "PUT", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while processing Shipping Instructions", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n PUT /v3/shipping-instructions/si-123\n \ntoo many times within a time period.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Updating too many Shipping Instructions\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Shipping Instructions can be updated per hour", - "errorCodeText" : "Max Shipping Instructions requests reached" - } - ], - "httpMethod" : "PUT", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/shipping-instructions/si-123", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to update a Shipping Instructions has been requested. Please try again in 1 hour", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Updates the Shipping Instructions\n", - "tags" : [ - "Shipping Instructions" - ] - } - }, - "/v3/transport-document-notifications" : { - "post" : { - "description" : "Creates a new [`Transport Document Notification`](#/TransportDocumentNotification). This endPoint is called whenever a `Transport Document` that a cosumer has subscribed to changes state or is updated.\n\n**This endPoint is to be implemented by a consumer of the EBL API in order to receive Notifications**\n", - "operationId" : "transport-document-notifications", - "parameters" : [ - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "examples" : { - "draftFullStateTransferExample" : { - "description" : "A full state transfer notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`).\n", - "summary" : "Transport Document Draft created (Full State Transfer)\n", - "value" : { - "data" : { - "transportDocument" : { - "cargoMovementTypeAtDestination" : "FCL", - "cargoMovementTypeAtOrigin" : "FCL", - "carrierCode" : "MSC", - "carrierCodeListProvider" : "SMDG", - "charges" : [ - { - "calculationBasis" : "Per transport document", - "chargeName" : "Fictive transport document fee", - "currencyAmount" : 1, - "currencyCode" : "EUR", - "paymentTermCode" : "COL", - "quantity" : 1, - "unitPrice" : 1 - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "deliveryTypeAtDestination" : "CY", - "documentParties" : { - "issuingParty" : { - "address" : { - "city" : "Geneva", - "countryCode" : "CH", - "street" : "Chemin Rieu", - "streetNumber" : "12-14" - }, - "identifyingCodes" : [ - { - "codeListName" : "LCL", - "codeListProvider" : "SMDG", - "partyCode" : "MSC" - } - ], - "partyName" : "Mediterranean Shipping Company" - }, - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "receiptTypeAtOrigin" : "CY", - "serviceContractReference" : "SCR-1234-REGULAR", - "shippedOnBoardDate" : "2023-12-20", - "shippingInstructionsReference" : "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "termsAndConditions" : "You agree that this transport document exist is name only for the sake of\ntesting your conformance with the DCSA EBL API. This transport document is NOT backed\nby a real shipment with ANY carrier and NONE of the requested services will be\ncarried out in real life.\n\nUnless required by applicable law or agreed to in writing, DCSA provides\nthis JSON data on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied, including, without limitation, any\nwarranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,\nor FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for\ndetermining the appropriateness of using or redistributing this JSON\ndata and assume any risks associated with Your usage of this data.\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall DCSA be liable to\nYou for damages, including any direct, indirect, special, incidental, or\nconsequential damages of any character arising as a result of this terms or conditions\nor out of the use or inability to use the provided JSON data (including but not limited\nto damages for loss of goodwill, work stoppage, computer failure or malfunction, or any\nand all other commercial damages or losses), even if DCSA has been advised of the\npossibility of such damages.\n", - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "DRAFT", - "transportDocumentTypeCode" : "BOL", - "transports" : { - "plannedArrivalDate" : "2023-12-22", - "plannedDepartureDate" : "2023-12-20", - "portOfDischarge" : { - "UNLocationCode" : "DEBRV" - }, - "portOfLoading" : { - "UNLocationCode" : "DKAAR" - }, - "vesselVoyages" : [ - { - "carrierExportVoyageNumber" : "402E", - "vesselName" : "MSC Gülsün" - } - ] - }, - "utilizedTransportEquipments" : [ - { - "equipment" : { - "ISOEquipmentCode" : "22G1", - "equipmentReference" : "NARU3472484" - }, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - }, - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "DRAFT" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "EBL001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.transport-document.v3" - } - }, - "draftLightweightExample" : { - "description" : "A lightweight notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`).\n", - "summary" : "Transport Document Draft created (Lightweight)\n", - "value" : { - "data" : { - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "DRAFT" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "EBL001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.transport-document.v3" - } - }, - "issuedFullStateTransferExample" : { - "description" : "A full state transfer notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`)\n", - "summary" : "Transport Document has been issued (Full State Transfer)\n", - "value" : { - "data" : { - "transportDocument" : { - "cargoMovementTypeAtDestination" : "FCL", - "cargoMovementTypeAtOrigin" : "FCL", - "carrierCode" : "MSC", - "carrierCodeListProvider" : "SMDG", - "charges" : [ - { - "calculationBasis" : "Per transport document", - "chargeName" : "Fictive transport document fee", - "currencyAmount" : 1, - "currencyCode" : "EUR", - "paymentTermCode" : "COL", - "quantity" : 1, - "unitPrice" : 1 - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "deliveryTypeAtDestination" : "CY", - "documentParties" : { - "issuingParty" : { - "address" : { - "city" : "Geneva", - "countryCode" : "CH", - "street" : "Chemin Rieu", - "streetNumber" : "12-14" - }, - "identifyingCodes" : [ - { - "codeListName" : "LCL", - "codeListProvider" : "SMDG", - "partyCode" : "MSC" - } - ], - "partyName" : "Mediterranean Shipping Company" - }, - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "receiptTypeAtOrigin" : "CY", - "serviceContractReference" : "SCR-1234-REGULAR", - "shippedOnBoardDate" : "2023-12-20", - "shippingInstructionsReference" : "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "termsAndConditions" : "You agree that this transport document exist is name only for the sake of\ntesting your conformance with the DCSA EBL API. This transport document is NOT backed\nby a real shipment with ANY carrier and NONE of the requested services will be\ncarried out in real life.\n\nUnless required by applicable law or agreed to in writing, DCSA provides\nthis JSON data on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied, including, without limitation, any\nwarranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,\nor FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for\ndetermining the appropriateness of using or redistributing this JSON\ndata and assume any risks associated with Your usage of this data.\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall DCSA be liable to\nYou for damages, including any direct, indirect, special, incidental, or\nconsequential damages of any character arising as a result of this terms or conditions\nor out of the use or inability to use the provided JSON data (including but not limited\nto damages for loss of goodwill, work stoppage, computer failure or malfunction, or any\nand all other commercial damages or losses), even if DCSA has been advised of the\npossibility of such damages.\n", - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "ISSUED", - "transportDocumentTypeCode" : "BOL", - "transports" : { - "plannedArrivalDate" : "2023-12-22", - "plannedDepartureDate" : "2023-12-20", - "portOfDischarge" : { - "UNLocationCode" : "DEBRV" - }, - "portOfLoading" : { - "UNLocationCode" : "DKAAR" - }, - "vesselVoyages" : [ - { - "carrierExportVoyageNumber" : "402E", - "vesselName" : "MSC Gülsün" - } - ] - }, - "utilizedTransportEquipments" : [ - { - "equipment" : { - "ISOEquipmentCode" : "22G1", - "equipmentReference" : "NARU3472484" - }, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - }, - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "ISSUED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "EBL001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.transport-document.v3" - } - }, - "issuedLightweightExample" : { - "description" : "A lightweight notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`)\n", - "summary" : "Transport Document has been issued (Lightweight)\n", - "value" : { - "data" : { - "transportDocumentReference" : "HHL71800000", - "transportDocumentStatus" : "ISSUED" - }, - "datacontenttype" : "application/json", - "id" : "3cecb101-7a1a-43a4-9d62-e88a131651e2", - "source" : "https://member.com/", - "specversion" : "1.0", - "subscriptionReference" : "EBL001", - "time" : "2018-04-05T17:31:00Z", - "type" : "org.dcsa.transport-document.v3" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/TransportDocumentNotification" - } - } - }, - "description" : "The payload used to create a [`Transport Document Notification`](#/TransportDocumentNotification)\n" - }, - "responses" : { - "204" : { - "description" : "No Content\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "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\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Transport Document missing transportDocumentReference\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "transportDocumentReference must be provided as part of a Notification\n", - "errorCodeText" : "mandatory property missing", - "property" : "transportDocumentReference" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-document-notifications", - "statusCode" : 400, - "statusCodeMessage" : "transportDocumentReference not found - mandatory to provide in a Notification\n", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the `Notification` does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Internal Server Error while processing Notification\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-document-notifications", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while processing Transport Document\n", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n POST /v3/transport-document-notifications\n\ntoo many times within a time period.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Making too many Notifications\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Notifications can be created per hour", - "errorCodeText" : "Max Notifications reached" - } - ], - "httpMethod" : "POST", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-document-notifications", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to create a Notification has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Send a new Transport Document Notification", - "tags" : [ - "Notifications" - ] - } - }, - "/v3/transport-documents/{transportDocumentReference}" : { - "get" : { - "description" : "Retrieves the `Transport Document` with the `transportDocumentReference` in the path.\n\n**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.\n", - "operationId" : "get-transport-document", - "parameters" : [ - { - "description" : "The `transportDocumentReference` of the `Transport Document`\n", - "explode" : false, - "in" : "path", - "name" : "transportDocumentReference", - "required" : true, - "schema" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "responses" : { - "200" : { - "content" : { - "application/json" : { - "examples" : { - "dgExample" : { - "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 Jarricans.\n", - "summary" : "Issued Transport Document with DG (Dangerous Goods) cargo\n", - "value" : { - "cargoMovementTypeAtDestination" : "FCL", - "cargoMovementTypeAtOrigin" : "FCL", - "carrierCode" : "HLC", - "carrierCodeListProvider" : "SMDG", - "charges" : [ - { - "calculationBasis" : "Per transport document", - "chargeName" : "Fictive transport document fee", - "currencyAmount" : 1, - "currencyCode" : "EUR", - "paymentTermCode" : "COL", - "quantity" : 1, - "unitPrice" : 1 - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "293499" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "HLXU1234567", - "outerPackaging" : { - "dangerousGoods" : [ - { - "EMSNumber" : "F-A S-F", - "imoClass" : "9", - "packingGroup" : 3, - "properShippingName" : "Environmentally hazardous substance, liquid, N.O.S", - "unNumber" : "3082" - } - ], - "description" : "Jerrican, steel", - "imoPackagingCode" : "3A1", - "numberOfPackages" : 400 - } - } - ], - "carrierBookingReference" : "RTM1234567", - "descriptionOfGoods" : [ - "Environmentally hazardous substance", - "liquid, N.O.S (Propiconazole)" - ] - } - ], - "deliveryTypeAtDestination" : "CY", - "documentParties" : { - "issuingParty" : { - "address" : { - "city" : "Hamburg", - "countryCode" : "DE", - "postCode" : "D-20095", - "street" : "Ballindamm", - "streetNumber" : "25" - }, - "identifyingCodes" : [ - { - "codeListName" : "LCL", - "codeListProvider" : "SMDG", - "partyCode" : "HLC" - } - ], - "partyName" : "Hapag Lloyd" - }, - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "receiptTypeAtOrigin" : "CY", - "serviceContractReference" : "SCR-1234-DG", - "shippedOnBoardDate" : "2023-12-20", - "shippingInstructionsReference" : "b36484d0-1115-43c2-93e4-a378823a8386", - "termsAndConditions" : "You agree that this transport document exist is name only for the sake of\ntesting your conformance with the DCSA EBL API. This transport document is NOT backed\nby a real shipment with ANY carrier and NONE of the requested services will be\ncarried out in real life.\n\nUnless required by applicable law or agreed to in writing, DCSA provides\nthis JSON data on an \\\"AS IS\\\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied, including, without limitation, any\nwarranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,\nor FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for\ndetermining the appropriateness of using or redistributing this JSON\ndata and assume any risks associated with Your usage of this data.\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall DCSA be liable to\nYou for damages, including any direct, indirect, special, incidental, or\nconsequential damages of any character arising as a result of this terms or conditions\nor out of the use or inability to use the provided JSON data (including but not limited\nto damages for loss of goodwill, work stoppage, computer failure or malfunction, or any\nand all other commercial damages or losses), even if DCSA has been advised of the\npossibility of such damages.\n", - "transportDocumentReference" : "4AD3FA470BB541B980CE", - "transportDocumentStatus" : "ISSUED", - "transportDocumentTypeCode" : "BOL", - "transports" : { - "plannedArrivalDate" : "2023-12-22", - "plannedDepartureDate" : "2023-12-20", - "portOfDischarge" : { - "UNLocationCode" : "DEBRV" - }, - "portOfLoading" : { - "UNLocationCode" : "DKAAR" - }, - "vesselVoyages" : [ - { - "carrierExportVoyageNumber" : "402E", - "vesselName" : "Berlin Express" - } - ] - }, - "utilizedTransportEquipments" : [ - { - "equipment" : { - "ISOEquipmentCode" : "22G1", - "equipmentReference" : "HLXU1234567" - }, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - }, - "reeferExample" : { - "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.\n", - "summary" : "Approved Transport Document with reefer cargo\n", - "value" : { - "cargoMovementTypeAtDestination" : "FCL", - "cargoMovementTypeAtOrigin" : "FCL", - "carrierCode" : "MSC", - "carrierCodeListProvider" : "SMDG", - "charges" : [ - { - "calculationBasis" : "Per transport document", - "chargeName" : "Fictive transport document fee", - "currencyAmount" : 1, - "currencyCode" : "EUR", - "paymentTermCode" : "COL", - "quantity" : 1, - "unitPrice" : 1 - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "04052090" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "KKFU6671914", - "outerPackaging" : { - "description" : "Bottles", - "numberOfPackages" : 400, - "packageCode" : "BQ" - } - } - ], - "carrierBookingReference" : "CBR_123_REEFER", - "descriptionOfGoods" : [ - "Dairy products" - ] - } - ], - "deliveryTypeAtDestination" : "CY", - "documentParties" : { - "issuingParty" : { - "address" : { - "city" : "Geneva", - "countryCode" : "CH", - "street" : "Chemin Rieu", - "streetNumber" : "12-14" - }, - "identifyingCodes" : [ - { - "codeListName" : "LCL", - "codeListProvider" : "SMDG", - "partyCode" : "MSC" - } - ], - "partyName" : "Mediterranean Shipping Company" - }, - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "receiptTypeAtOrigin" : "CY", - "serviceContractReference" : "SCR-1234-REEFER", - "shippedOnBoardDate" : "2023-12-20", - "shippingInstructionsReference" : "9051da7d-4099-4930-af35-7add4e68c635", - "termsAndConditions" : "You agree that this transport document exist is name only for the sake of\ntesting your conformance with the DCSA EBL API. This transport document is NOT backed\nby a real shipment with ANY carrier and NONE of the requested services will be\ncarried out in real life.\n\nUnless required by applicable law or agreed to in writing, DCSA provides\nthis JSON data on an \\\"AS IS\\\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied, including, without limitation, any\nwarranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,\nor FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for\ndetermining the appropriateness of using or redistributing this JSON\ndata and assume any risks associated with Your usage of this data.\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall DCSA be liable to\nYou for damages, including any direct, indirect, special, incidental, or\nconsequential damages of any character arising as a result of this terms or conditions\nor out of the use or inability to use the provided JSON data (including but not limited\nto damages for loss of goodwill, work stoppage, computer failure or malfunction, or any\nand all other commercial damages or losses), even if DCSA has been advised of the\npossibility of such damages.\n", - "transportDocumentReference" : "D8931B95625E4B339F2A", - "transportDocumentStatus" : "APPROVED", - "transportDocumentTypeCode" : "BOL", - "transports" : { - "plannedArrivalDate" : "2023-12-22", - "plannedDepartureDate" : "2023-12-20", - "portOfDischarge" : { - "UNLocationCode" : "DEBRV" - }, - "portOfLoading" : { - "UNLocationCode" : "DKAAR" - }, - "vesselVoyages" : [ - { - "carrierExportVoyageNumber" : "402E", - "vesselName" : "Ever Ace" - } - ] - }, - "utilizedTransportEquipments" : [ - { - "activeReeferSettings" : { - "temperatureSetpoint" : -18, - "temperatureUnit" : "CEL" - }, - "equipment" : { - "ISOEquipmentCode" : "45R1", - "equipmentReference" : "KKFU6671914" - }, - "isNonOperatingReefer" : false, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - }, - "regularSTDExample" : { - "description" : "A `DRAFT` Transport Document waiting for consumer approval.\n", - "summary" : "Draft Transport Document with regular Dry cargo\n", - "value" : { - "cargoMovementTypeAtDestination" : "FCL", - "cargoMovementTypeAtOrigin" : "FCL", - "carrierCode" : "MSC", - "carrierCodeListProvider" : "SMDG", - "charges" : [ - { - "calculationBasis" : "Per transport document", - "chargeName" : "Fictive transport document fee", - "currencyAmount" : 1, - "currencyCode" : "EUR", - "paymentTermCode" : "COL", - "quantity" : 1, - "unitPrice" : 1 - } - ], - "consignmentItems" : [ - { - "HSCodes" : [ - "640510" - ], - "cargoItems" : [ - { - "cargoGrossWeight" : { - "unit" : "KGM", - "value" : 12000 - }, - "equipmentReference" : "NARU3472484", - "outerPackaging" : { - "description" : "Fibreboard boxes", - "numberOfPackages" : 400, - "packageCode" : "4G" - } - } - ], - "carrierBookingReference" : "CBR_123_REGULAR", - "descriptionOfGoods" : [ - "Shoes - black" - ] - } - ], - "deliveryTypeAtDestination" : "CY", - "documentParties" : { - "issuingParty" : { - "address" : { - "city" : "Geneva", - "countryCode" : "CH", - "street" : "Chemin Rieu", - "streetNumber" : "12-14" - }, - "identifyingCodes" : [ - { - "codeListName" : "LCL", - "codeListProvider" : "SMDG", - "partyCode" : "MSC" - } - ], - "partyName" : "Mediterranean Shipping Company" - }, - "shipper" : { - "displayedAddress" : [ - "Strawinskylaan 4117" - ], - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "partyName" : "DCSA CTK" - } - }, - "freightPaymentTermCode" : "PRE", - "invoicePayableAt" : { - "UNLocationCode" : "DKAAR" - }, - "isElectronic" : true, - "isShippedOnBoardType" : true, - "isToOrder" : true, - "partyContactDetails" : [ - { - "email" : "no-reply@dcsa.example.org", - "name" : "DCSA test person" - } - ], - "receiptTypeAtOrigin" : "CY", - "serviceContractReference" : "SCR-1234-REGULAR", - "shippedOnBoardDate" : "2023-12-20", - "shippingInstructionsReference" : "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "termsAndConditions" : "You agree that this transport document exist is name only for the sake of\ntesting your conformance with the DCSA EBL API. This transport document is NOT backed\nby a real shipment with ANY carrier and NONE of the requested services will be\ncarried out in real life.\n\nUnless required by applicable law or agreed to in writing, DCSA provides\nthis JSON data on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied, including, without limitation, any\nwarranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,\nor FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for\ndetermining the appropriateness of using or redistributing this JSON\ndata and assume any risks associated with Your usage of this data.\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall DCSA be liable to\nYou for damages, including any direct, indirect, special, incidental, or\nconsequential damages of any character arising as a result of this terms or conditions\nor out of the use or inability to use the provided JSON data (including but not limited\nto damages for loss of goodwill, work stoppage, computer failure or malfunction, or any\nand all other commercial damages or losses), even if DCSA has been advised of the\npossibility of such damages.\n", - "transportDocumentReference" : "62CD536BA8D34C469AFD", - "transportDocumentStatus" : "DRAFT", - "transportDocumentTypeCode" : "BOL", - "transports" : { - "plannedArrivalDate" : "2023-12-22", - "plannedDepartureDate" : "2023-12-20", - "portOfDischarge" : { - "UNLocationCode" : "DEBRV" - }, - "portOfLoading" : { - "UNLocationCode" : "DKAAR" - }, - "vesselVoyages" : [ - { - "carrierExportVoyageNumber" : "402E", - "vesselName" : "MSC Gülsün" - } - ] - }, - "utilizedTransportEquipments" : [ - { - "equipment" : { - "ISOEquipmentCode" : "22G1", - "equipmentReference" : "NARU3472484" - }, - "isShipperOwned" : false, - "seals" : [ - { - "number" : "DCSA-CTK-1234" - } - ] - } - ] - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/TransportDocument" - } - } - }, - "description" : "The `Transport Document`\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "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`.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "examples" : { - "notFoundExample" : { - "description" : "The `transportDocumentReference` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "documentReference not found\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Transport Document does not exist", - "errorCodeText" : "documentReference not found" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 404, - "statusCodeMessage" : "documentReference not found", - "statusCodeText" : "Not Found" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the consumer is requesting a `transportDocumentReference` that does not exist.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while fetching the Transport Document\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while fetching the Transport Document", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n GET /v3/transport-documents/td-987\n \ntoo many times within a time period.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Fetching too many `Transport Document` requests\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Transport Document can be requested per hour", - "errorCodeText" : "Max Transport Document requests reached" - } - ], - "httpMethod" : "GET", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to fetch a Transport Document has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Gets the Transport Document\n", - "tags" : [ - "Transport Document" - ] - }, - "patch" : { - "description" : "A way for the consumer to Approve the `Draft Transport Document`. This endPoint corresponds with **UseCase 7 - Approve Draft Transport Document**.\n\n## Precondition\nIn order to approve a `Draft Transport Document`, the status of the `Transport Document` needs to be in status `DRAFT`\n\n## Postcondition\nThe provider has received an approval from the consumer for a `Transport Document` that is in state `DRAFT`.\n\nThe consumer will receive a `202` (Accepted) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow for the `202` (Accepted) response\nThe following occurs when a provider receives an approval:\n1. The payload is schema-validated. In case the payload **is invalid** a `400` (Bad Request) is returned.\n\n **The process stops here!**\n2. The payload is schema-valid which means:\n - all required properties are provided.\n - all values provided have correct data type.\n3. An empty response is returned and the consumer now awaits further processing by the provider.\n\nOnce 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\n\n GET /v3/transport-documents/{transportDocumentReference}\n \nendPoint to check if the `transportDocumentStatus` of the `Transport Document` has changed.\n", - "operationId" : "approve-transport-document", - "parameters" : [ - { - "in": "query", - "name": "NewParameter", - "description": "New parameter", - "required": "true", - "schema": { - "": "" - } - }, - { - "in": "query", - "name": "NewParameter", - "description": "New parameter", - "required": "true", - "schema": { - "": "" - } - }, - { - "in": "query", - "name": "NewParameter", - "description": "New parameter", - "required": "true", - "schema": { - "": "" - } - }, - { - "description" : "The `transportDocumentReference` of the `Transport Document`\n", - "explode" : false, - "in" : "path", - "name" : "transportDocumentReference", - "required" : true, - "schema" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ApproveTransportDocument" - } - } - } - }, - "responses" : { - "202" : { - "content" : { - "application/json" : { - "examples" : { - "approveExample" : { - "description" : "Consumer approves the drafted `Transport Document` and now awaits further processing by provider.\n", - "summary" : "Approve Draft Transport Document\n" - } - } - } - }, - "description" : "The approval of the `Transport Document` has been accepted and now awaits further processing\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "400" : { - "content" : { - "application/json" : { - "examples" : { - "badRequestExample" : { - "description" : "`ISSUE` is not a possible value when PATCHING a `Transport Document`.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Wrong Transport Document status\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Only APPROVED is an allowed value: ISSUE was inserted", - "errorCodeText" : "incorrect value", - "property" : "transportDocumentStatus", - "value" : "ISSUE" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 400, - "statusCodeMessage" : "ISSUE is not a valid status to set", - "statusCodeText" : "Bad Request" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the Approve payload does not schema validate a `400` (Bad Request) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "examples" : { - "notFoundExample" : { - "description" : "The `transportDocumentReference` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "documentReference not found\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Transport Document does not exist", - "errorCodeText" : "documentReference not found" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 404, - "statusCodeMessage" : "documentReference not found", - "statusCodeText" : "Not Found" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the consumer is requesting a `transportDocumentReference` that does not exist.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "examples" : { - "notFoundExample" : { - "description" : "The `transportDocumentReference` is currently being processed - try again later.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "documentReference is being processed\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "The Transport Document is currently being processed", - "errorCodeText" : "documentReference being processed" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 409, - "statusCodeMessage" : "documentReference being processed", - "statusCodeText" : "Conflict" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case the consumer is requesting a `transportDocumentReference` that is being processed it is possible to return a `409` (Conflict).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "500" : { - "content" : { - "application/json" : { - "examples" : { - "internalServerErrorExample" : { - "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`)\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "summary" : "Internal Server Error while approving the `Draft Transport Document`\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "Internal Error occurred", - "errorCodeText" : "Internal Error occurred" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 500, - "statusCodeMessage" : "Internal Server Error occurred while approving the Transport Document", - "statusCodeText" : "Internal Server Error" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "examples" : { - "tooManyRequestsExample" : { - "description" : "Calling the endPoint\n\n PATCH /v3/transport-documents/td-987\n \ntoo many times within a time period.\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", - "summary" : "Too many Patch `Transport Document` requests\n", - "value" : { - "errorDateTime" : "2024-09-04T09:41:00Z", - "errors" : [ - { - "errorCode" : 7003, - "errorCodeMessage" : "A maximum of 10 Transport Document can be patched per hour", - "errorCodeText" : "Max Transport Document requests reached" - } - ], - "httpMethod" : "PATCH", - "providerCorrelationReference" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "requestUri" : "/v3/transport-documents/td-987", - "statusCode" : 429, - "statusCodeMessage" : "Too many request to patch a Transport Document has been requested. Please try again in 1 hour\n", - "statusCodeText" : "Too Many Requests" - } - } - }, - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "For other errors the error object should be populated with relevant information\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Approve a Transport Document\n", - "tags" : [ - "Transport Document" - ] - } - } - }, - "servers" : [ - { - "description" : "SwaggerHub API Auto Mocking", - "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL/3.0.0" - } - ], - "tags" : [ - { - "description" : "The Shipping Instructions endPoints to be implemented by **providers** of the Bill of Lading API\n", - "name" : "Shipping Instructions" - }, - { - "description" : "The Transport Document endPoints to be implemented by **providers** of the Bill of Lading API\n", - "name" : "Transport Document" - }, - { - "description" : "The Notifications to be implemented by the **consumers** of the Bill of Lading API", - "name" : "Notifications" - } - ] -} diff --git a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/OvsComponentFactory.java b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/OvsComponentFactory.java index bc370ce3..3251d888 100644 --- a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/OvsComponentFactory.java +++ b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/OvsComponentFactory.java @@ -98,11 +98,7 @@ public Set getReportRoleNames( } public JsonSchemaValidator getMessageSchemaValidator(String apiProviderRole, boolean forRequest) { - String schemaFilePath = - "/standards/ovs/schemas/ovs-%s-%s.json" - .formatted( - standardVersion.toLowerCase().replaceAll("[.-]", ""), - apiProviderRole.toLowerCase()); + String schemaFilePath = "/standards/ovs/schemas/OVS_v%s.yaml".formatted(standardVersion); String schemaName = OvsRole.isPublisher(apiProviderRole) ? (forRequest ? null : "serviceSchedules") : null; return JsonSchemaValidator.getInstance(schemaFilePath, schemaName); diff --git a/ovs/src/main/resources/standards/ovs/schemas/OVS_v3.0.0.yaml b/ovs/src/main/resources/standards/ovs/schemas/OVS_v3.0.0.yaml new file mode 100644 index 00000000..d82950fd --- /dev/null +++ b/ovs/src/main/resources/standards/ovs/schemas/OVS_v3.0.0.yaml @@ -0,0 +1,560 @@ +openapi: 3.0.3 +x-stoplight: + id: iu1gf3vhqkz92 +info: + title: Operational Vessel Schedules + version: 3.0.0 + description: "API specification issued by DCSA.org\r\n\r\nThis API supports OVS (Operational Vessel Schedules)\r\n\r\nThe Interface Standards for OVS and other documentation can be found on the [DCSA Website](https://dcsa.org/standards/operational-vessel-schedules/).\r\n\r\nFor explanation to specific values or objects please refer to the [Information Model](https://dcsa.org/wp-content/uploads/2024/01/DCSA-Information-Model-2023.Q4.pdf).\r\n\r\n### Stats API\r\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Operational Vessel Schedules API. Further details can be found [here](https://developer.dcsa.org/#/http/guides/api-guides/stats-api)\r\n\r\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new)" + contact: + name: Digital Container Shipping Association (DCSA) + url: 'https://dcsa.org' + email: info@dcsa.org + license: + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + name: Apache 2.0 +servers: + - url: 'http://localhost:3000' +paths: + /v3/service-schedules: + get: + summary: Get a list of Schedules + tags: + - Operational Vessel Schedules + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + headers: + API-Version: + $ref: ../../models/CommonComponents.yaml#/components/headers/API-Version + '400': + description: Bad Request + headers: + API-Version: + $ref: ../../models/CommonComponents.yaml#/components/headers/API-Version + content: + application/json: + schema: + $ref: ../../models/ErrorResponse.yaml + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/ovs/v3/service-schedules' + statusCode: 400 + statusCodeText: Bad Request + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: + - errorCode: 7007 + property: UNLocationCode + value: NA + errorCodeText: invalidQuery + erorCodeMessage: UNLocationCode does not exist + '500': + description: Internal Server Error + headers: + API-Version: + $ref: ../../models/CommonComponents.yaml#/components/headers/API-Version + content: + application/json: + schema: + $ref: ../../models/ErrorResponse.yaml + examples: + Example 1: + value: + httpMethod: GET + requestUri: 'https://dcsa.org/ovs/v3/service-schedules' + statusCode: 500 + statusCodeText: Internal Server Error + statusCodeMessage: Cannot process request. + providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962 + errorDateTime: '2019-11-12T07:41:00+08:30' + errors: [] + operationId: get-v3-service-schedules + x-stoplight: + id: ksu2cdfhjnmcd + description: "Get a list of service schedules. The result is `Vessel-Centric` - this means that the `Vessel` is in the top of the hierarchy of the response structure. A service is a heirarchical structure with the following elements:\r\n- One or more `Services` which can contain one or more `Vessels`\r\n- A `Vessel` which can call multiple `Ports` (`TransportCalls`).\r\n- A `Port` (`TransportCall`) can contain one or more `TimeStamps`.\r\n\r\nThe number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included.\r\n\r\nAn example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.\r\n\r\nBe aware that it is possible to specify filters that are mutially exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time:\r\n\r\n&vesselIMONumber=9321483&vesselName=King of the Seas\r\n\r\nIf no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list\r\n\r\nIf no `startDate` filter is provided then **3 months** prior to the request data is used. If no `endDate` filters is provided then **6 months** after the request date is used." + parameters: + - schema: + type: string + example: Great Lion Service + maxLength: 50 + in: query + name: carrierServiceName + description: The carrier service name to filter by. The result will only return schedules including the service name. + - schema: + type: string + example: FE1 + maxLength: 11 + in: query + name: carrierServiceCode + description: The carrier specific service code to filter by. The result will only return schedules including the service code. + - schema: + type: string + maxLength: 8 + pattern: '^SR\d{5}[A-Z]$' + example: SR12345A + in: query + name: universalServiceReference + description: 'The **U**niversal **S**ervice **R**eference (`USR`) as defined by **DCSA** to filter by. The service code must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. The result will only return schedules including the service reference' + - schema: + type: string + maxLength: 7 + pattern: '^\d{7}$' + example: '9321483' + in: query + name: vesselIMONumber + description: The identifier of a vessel. The result will only return schedules including the vessel with the specified IMO number. It is not a requirement for dummy vessels to have an `IMO Number`. In this case filtering by `vesselName` should be used. + - schema: + type: string + maxLength: 35 + example: King of the Seas + in: query + name: vesselName + description: 'The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the `vesselName` is not unique and might match multiple vessels. If possible, filtering by `IMO Number` is preferred. In case of dummy vessels an `IMO Number` might not exist in which case this filter is to be used.' + - schema: + type: string + maxLength: 50 + example: 2103S + in: query + name: carrierVoyageNumber + description: The carrier specific identifier of a `Voyage` - can be both **importVoyageNumber** and **exportVoyageNumber**. The result will only return schedules including the `Ports` where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber` + - schema: + type: string + pattern: '^\d{2}[0-9A-Z]{2}[NEWSR]$' + maxLength: 5 + example: 2201N + in: query + name: universalVoyageReference + description: The Universal Reference of a `Voyage` - can be both **importUniversalVoyageReference** and **exportUniversalVoyageReference**. The result will only return schedules including the `Ports` where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference` + - schema: + type: string + pattern: '^[A-Z]{2}[A-Z2-9]{3}$' + minLength: 5 + maxLength: 5 + example: NLAMS + in: query + name: UNLocationCode + description: The `UN Location Code` specifying where a port is located. Specifying this filter will only return schedules including **entire Voyages** related to this particular `UN Location Code`. + - schema: + type: string + maxLength: 6 + example: APM + in: query + name: facilitySMDGCode + description: The `facilitySMDGCode` specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including **entire Voyages** related to this particular `facilitySMDGCode`. + - schema: + type: string + format: date + example: '2020-04-06' + in: query + name: startDate + description: 'The start date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or after (`≥`) the `startDate` the **entire Voyage** (import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **3 months** prior to request time. The value is populated in `ISO 8601` date format.' + - schema: + type: string + format: date + example: '2020-04-10' + in: query + name: endDate + description: 'The end date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or before (`≤`) the `endDate` the **entire Voyage**(import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **6 months** after request time. The value is populated in `ISO 8601` date format.' + - schema: + type: number + default: 100 + in: query + name: limit + description: Maximum number of items to return. + - schema: + type: string + example: '3' + in: header + name: API-Version + 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. +components: + schemas: + ServiceSchedule: + title: Service Schedule + x-stoplight: + id: gwfh63i8o7zml + type: object + properties: + carrierServiceName: + type: string + x-stoplight: + id: 9ieesyalua8h3 + description: The name of the service. + maxLength: 50 + example: Great Lion Service + carrierServiceCode: + type: string + x-stoplight: + id: efdlkjixvvojc + maxLength: 11 + example: FE1 + description: The carrier-specific code of the service for which the schedule details are published. + universalServiceReference: + type: string + x-stoplight: + id: 7s3lkvp2am9hl + maxLength: 8 + example: SR12345A + pattern: '^SR\d{5}[A-Z]$' + description: 'A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.' + vesselSchedules: + type: array + x-stoplight: + id: o4coblts5du99 + items: + $ref: '#/components/schemas/VesselSchedule' + required: + - carrierServiceName + - carrierServiceCode + serviceSchedules: + type: array + items: + $ref: '#/components/schemas/ServiceSchedule' + VesselSchedule: + title: Vessel Schedule + x-stoplight: + id: w5qfj5e9wgtrk + type: object + required: + - vesselOperatorSMDGLinerCode + - isDummyVessel + properties: + vesselOperatorSMDGLinerCode: + type: string + x-stoplight: + id: xzvmwjeak358j + description: 'The carrier who is in charge of the vessel operation based on the SMDG code. If not available at the moment of sharing the schedule, use `TBD` (To be defined). In the case an operator is still using a code not from SMDG, use the available code.' + maxLength: 10 + example: HLC + vesselIMONumber: + type: string + x-stoplight: + id: odkxm88rg0w78 + pattern: '^\d{7}$' + maxLength: 7 + example: '9321483' + description: "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel\r\n\r\nCondition: If the vessel is not dummy, there needs to be an IMO. If the vessel is dummy, the IMO is optional." + vesselName: + type: string + x-stoplight: + id: p159tgelmrqgz + maxLength: 35 + example: King of the Seas + description: The name of the Vessel given by the Vessel Operator and registered with IMO. + vesselCallSign: + type: string + x-stoplight: + id: oe7hvowe160y7 + maxLength: 10 + example: NCVV + description: 'A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a threeletter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.' + isDummyVessel: + type: boolean + x-stoplight: + id: paaye96dudeup + description: Is this a dummy vessel. In case no vessel has been asigned yet - this property can be set to `true` indicating that the vesselIMONumber does not exist. + transportCalls: + type: array + x-stoplight: + id: ys0fhklzx5jfu + items: + $ref: '#/components/schemas/TransportCall' + TransportCall: + title: Transport Call + x-stoplight: + id: 37pvn11as2qkc + type: object + description: "\t\nA transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall.\n\nThe order of the list is the sequence of the list" + required: + - transportCallReference + - carrierImportVoyageNumber + properties: + portVisitReference: + type: string + x-stoplight: + id: 2uxtcye93albp + maxLength: 50 + example: NLAMS1234589 + description: The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call + transportCallReference: + type: string + x-stoplight: + id: xdcm7n5yk7uxr + maxLength: 100 + example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 + description: 'The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.' + carrierImportVoyageNumber: + type: string + x-stoplight: + id: 3vgc3xok72ptz + description: The identifier of an import voyage. The carrier-specific identifier of the import Voyage. + example: 2103N + maxLength: 50 + carrierExportVoyageNumber: + type: string + x-stoplight: + id: 3ru40r2oosjv1 + description: The identifier of an export voyage. The carrier-specific identifier of the export Voyage. + example: 2103S + maxLength: 50 + universalImportVoyageReference: + type: string + x-stoplight: + id: yzyd2uo4ix13n + pattern: '^\d{2}[0-9A-Z]{2}[NEWSR]$' + example: 2103N + description: "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\r\n- `2 digits` for the year\r\n- `2 alphanumeric characters` for the sequence number of the voyage\r\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip)." + universalExportVoyageReference: + type: string + x-stoplight: + id: t3olh9zvlg5ll + pattern: '^\d{2}[0-9A-Z]{2}[NEWSR]$' + example: 2103N + 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]`\r\n- `2 digits` for the year\r\n- `2 alphanumeric characters` for the sequence number of the voyage\r\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip)." + location: + x-stoplight: + id: dt9xme8zmy3n2 + description: 'General purpose object to capture location-related data, the location can be specified in **one** of the following ways: `UN Location Code`, a `Facility` or an `Address`.' + oneOf: + - $ref: '#/components/schemas/UNLocationLocation' + - $ref: '#/components/schemas/FacilitySMDGLocation' + - $ref: '#/components/schemas/AddressLocation' + statusCode: + type: string + x-stoplight: + id: eiwe2tmgi6jm2 + description: "The set of codes in `Status Code` are ONLY meant to communicate any change / exception to the published schedule. This is not required in case of normal schedule. Possible values are:\r\n\r\n- OMIT (Omit)\r\n- BLNK (Blank)\r\n- ADHO (Ad Hoc)\r\n- PHOT (Phase Out)\r\n- PHIN (Phase In)\r\n- SLID (Sliding)\r\n- ROTC (Rotation Change)\r\n- CUTR (Cut and Run)\r\n\r\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3/reference-data/portcallstatuscodes-v300.csv)" + example: OMIT + timestamps: + type: array + x-stoplight: + id: vux2gn6fosbgq + items: + $ref: '#/components/schemas/Timestamp' + Timestamp: + title: Timestamp + x-stoplight: + id: hv1u5gl6379ey + type: object + description: "\t\nA timestamp for a port." + properties: + eventTypeCode: + x-stoplight: + id: rzon1w5937fng + enum: + - ARRI + - DEPA + description: "Identifier for type of `transportEvent`\r\n\r\n- ARRI (Arrived)\r\n- DEPA (Departed)\r\n\r\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3/reference-data/transporteventtypecodes-v300.csv)." + eventClassifierCode: + x-stoplight: + id: xvc15h9nwxtfx + enum: + - PLN + - EST + - ACT + description: | + Code for the event classifier. Values can vary depending on eventType. + + Possible values are: + - ACT (Actual) + - EST (Estimated) + - PLN (Planned) + eventDateTime: + type: string + x-stoplight: + id: gqp3o1bhy5mzw + format: date-time + description: Time in the timestamp + example: '2025-01-14T09:21:00+01:00' + delayReasonCode: + type: string + x-stoplight: + id: pimsgnrx71a8q + maxLength: 3 + example: WEA + description: 'Reason code for the delay. See SMDG [Code list DELAY](https://smdg.org/documents/smdg-code-lists/delay-reason-and-port-call-activity/) for a list of valid codes to be used for this attribute.' + changeRemark: + type: string + x-stoplight: + id: yk384n8fylkg7 + maxLength: 250 + example: Bad weather + description: Free text field to provide information as to why the `TransportEvent` was sent. + required: + - eventTypeCode + - eventClassifierCode + - eventDateTime + AddressLocation: + title: Address Location + x-stoplight: + id: 7lubypdxb6mmg + type: object + description: An interface used to express a location using an `Address` object. + required: + - locationType + - address + properties: + locationName: + type: string + x-stoplight: + id: n7fong1q8pjz6 + description: The name of the location. + example: Port of Amsterdam + maxLength: 100 + locationType: + type: string + x-stoplight: + id: 5rg7p8kwuibxt + description: Discriminator used to identify this as an `Address` location interface. + example: ADDR + maxLength: 4 + address: + type: object + x-stoplight: + id: hvd7bhamm4ddm + required: + - name + description: An object for storing address related information. + properties: + name: + type: string + x-stoplight: + id: gs66kwkbgjbnq + description: Name of the address. + example: John + maxLength: 100 + street: + type: string + x-stoplight: + id: ikr1qny61yngg + description: The name of the street of the party’s address. + example: Ruijggoordweg + maxLength: 100 + streetNumber: + type: string + x-stoplight: + id: kgviri7xjh6jk + description: The number of the street of the party’s address. + example: '100' + maxLength: 50 + floor: + type: string + x-stoplight: + id: 2b90ghfmdnuzb + description: The floor of the party’s street number. + example: N/A + maxLength: 50 + postCode: + type: string + x-stoplight: + id: qh477we17171v + description: The post code of the party’s address. + example: 1047 HM + maxLength: 50 + city: + type: string + x-stoplight: + id: mam9o3p1v1xf4 + description: The city name of the party’s address. + example: Amsterdam + maxLength: 65 + stateRegion: + type: string + x-stoplight: + id: 1cz0m003w024d + description: The state/region of the party’s address. + example: North Holland + maxLength: 65 + country: + type: string + x-stoplight: + id: 5bkxe09r2qlqt + description: The country of the party’s address. + example: The Netherlands + maxLength: 75 + UNLocationLocation: + title: UNLocation Location + x-stoplight: + id: x4suin19xkq6q + type: object + description: An interface used to express a location using a `Un Location Code`. + required: + - locationType + - UNLocationCode + properties: + locationName: + type: string + x-stoplight: + id: 4c18hs0i6ys6p + description: The name of the location. + example: Port of Amsterdam + maxLength: 100 + pattern: ^\S+(\s+\S+)*$ + locationType: + type: string + x-stoplight: + id: 2wthlqxorc4dy + description: Discriminator used to identify this as a `UNLocation` location interface. + example: UNLO + maxLength: 4 + UNLocationCode: + type: string + x-stoplight: + id: a1nomkthncy9h + description: "The UN Location code specifying where the place is located. The pattern used must be\r\n\r\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\r\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\r\n\r\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)" + example: NLAMS + pattern: '^[A-Z]{2}[A-Z2-9]{3}$' + minLength: 5 + maxLength: 5 + FacilitySMDGLocation: + title: Facility SMDG Location + x-stoplight: + id: y3cpqlgmgy2b9 + type: object + description: An interface used to express a location using a `Facility` by the `SMDG` code list. The `facilitySMDGCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute. + required: + - locationType + - UNLocationCode + - facilitySMDGCode + properties: + locationName: + type: string + x-stoplight: + id: sk9wmzuuysvll + description: The name of the location. + example: Port of Amsterdam + maxLength: 100 + locationType: + type: string + x-stoplight: + id: sddcjdatphg1o + description: Discriminator used to identify this as a `Facility Location` interface only using `SMDG` code list. + example: FACS + maxLength: 4 + UNLocationCode: + type: string + x-stoplight: + id: mxkse3a3ub9t1 + description: "The UN Location code specifying where the place is located. The pattern used must be\r\n\r\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\r\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\r\n\r\nMore info can be found here: [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE)" + example: NLAMS + pattern: '^[A-Z]{2}[A-Z2-9]{3}$' + minLength: 5 + maxLength: 5 + facilitySMDGCode: + type: string + x-stoplight: + id: jrksswrdxnvad + description: "The code used for identifying the specific facility. This code does not include the UN Location Code.\r\n\r\nThe codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)" + example: ACT + maxLength: 6 +tags: + - name: Operational Vessel Schedules + description: ' ' diff --git a/ovs/src/main/resources/standards/ovs/schemas/ovs-300-publisher.json b/ovs/src/main/resources/standards/ovs/schemas/ovs-300-publisher.json deleted file mode 100644 index f9a94593..00000000 --- a/ovs/src/main/resources/standards/ovs/schemas/ovs-300-publisher.json +++ /dev/null @@ -1,832 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "Operational Vessel Schedules", - "description": "API specification issued by DCSA.org\r\n\r\nThis API supports OVS (Operational Vessel Schedules)\r\n\r\nThe Interface Standards for OVS and other documentation can be found on the [DCSA Website](https://dcsa.org/standards/operational-vessel-schedules/).\r\n\r\nFor explanation to specific values or objects please refer to the [Information Model](https://dcsa.org/wp-content/uploads/2024/01/DCSA-Information-Model-2023.Q4.pdf).\r\n\r\n### Stats API\r\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Operational Vessel Schedules API. Further details can be found [here](https://developer.dcsa.org/#/http/guides/api-guides/stats-api)\r\n\r\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new)", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "3.0.0" - }, - "servers": [ - { - "url": "http://localhost:3000" - } - ], - "tags": [ - { - "name": "Operational Vessel Schedules", - "description": " " - } - ], - "paths": { - "/v3/service-schedules": { - "get": { - "tags": [ - "Operational Vessel Schedules" - ], - "summary": "Get a list of Schedules", - "description": "Get a list of service schedules. The result is `Vessel-Centric` - this means that the `Vessel` is in the top of the hierarchy of the response structure. A service is a heirarchical structure with the following elements:\r\n- One or more `Services` which can contain one or more `Vessels`\r\n- A `Vessel` which can call multiple `Ports` (`TransportCalls`).\r\n- A `Port` (`TransportCall`) can contain one or more `TimeStamps`.\r\n\r\nThe number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included.\r\n\r\nAn example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.\r\n\r\nBe aware that it is possible to specify filters that are mutially exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time:\r\n\r\n&vesselIMONumber=9321483&vesselName=King of the Seas\r\n\r\nIf no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list\r\n\r\nIf no `startDate` filter is provided then **3 months** prior to the request data is used. If no `endDate` filters is provided then **6 months** after the request date is used.", - "operationId": "get-v3-service-schedules", - "parameters": [ - { - "name": "carrierServiceName", - "in": "query", - "description": "The carrier service name to filter by. The result will only return schedules including the service name.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 50, - "type": "string", - "example": "Great Lion Service" - } - }, - { - "name": "carrierServiceCode", - "in": "query", - "description": "The carrier specific service code to filter by. The result will only return schedules including the service code.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 11, - "type": "string", - "example": "FE1" - } - }, - { - "name": "universalServiceReference", - "in": "query", - "description": "The **U**niversal **S**ervice **R**eference (`USR`) as defined by **DCSA** to filter by. The service code must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`. The result will only return schedules including the service reference", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "example": "SR12345A" - } - }, - { - "name": "vesselIMONumber", - "in": "query", - "description": "The identifier of a vessel. The result will only return schedules including the vessel with the specified IMO number. It is not a requirement for dummy vessels to have an `IMO Number`. In this case filtering by `vesselName` should be used.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 7, - "pattern": "^\\d{7}$", - "type": "string", - "example": "9321483" - } - }, - { - "name": "vesselName", - "in": "query", - "description": "The name of a vessel. The result will only return schedules including the vessel with the specified name. Be aware that the `vesselName` is not unique and might match multiple vessels. If possible, filtering by `IMO Number` is preferred. In case of dummy vessels an `IMO Number` might not exist in which case this filter is to be used.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 35, - "type": "string", - "example": "King of the Seas" - } - }, - { - "name": "carrierVoyageNumber", - "in": "query", - "description": "The carrier specific identifier of a `Voyage` - can be both **importVoyageNumber** and **exportVoyageNumber**. The result will only return schedules including the `Ports` where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 50, - "type": "string", - "example": "2103S" - } - }, - { - "name": "universalVoyageReference", - "in": "query", - "description": "The Universal Reference of a `Voyage` - can be both **importUniversalVoyageReference** and **exportUniversalVoyageReference**. The result will only return schedules including the `Ports` where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference`", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "example": "2201N" - } - }, - { - "name": "UNLocationCode", - "in": "query", - "description": "The `UN Location Code` specifying where a port is located. Specifying this filter will only return schedules including **entire Voyages** related to this particular `UN Location Code`.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "example": "NLAMS" - } - }, - { - "name": "facilitySMDGCode", - "in": "query", - "description": "The `facilitySMDGCode` specifying a specific facility (using SMDG Code). Be aware that the `facilitySMDGCode` does not contain a `UNLocationCode` - this must be specified in the `UNLocationCode` filter. Specifying this filter will only return schedules including **entire Voyages** related to this particular `facilitySMDGCode`.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "maxLength": 6, - "type": "string", - "example": "APM" - } - }, - { - "name": "startDate", - "in": "query", - "description": "The start date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or after (`≥`) the `startDate` the **entire Voyage** (import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **3 months** prior to request time. The value is populated in `ISO 8601` date format.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2020-04-06" - } - }, - { - "name": "endDate", - "in": "query", - "description": "The end date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or before (`≤`) the `endDate` the **entire Voyage**(import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **6 months** after request time. The value is populated in `ISO 8601` date format.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "string", - "format": "date", - "example": "2020-04-10" - } - }, - { - "name": "API-Version", - "in": "header", - "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.", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - }, - { - "name": "limit", - "in": "query", - "description": "Maximum number of items to return.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 0, - "type": "number", - "default": 100 - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServiceSchedule" - } - } - } - } - }, - "400": { - "description": "Bad Request", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/ovs/v3/service-schedules", - "statusCode": 400, - "statusCodeText": "Bad Request", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [ - { - "errorCode": 7007, - "property": "UNLocationCode", - "value": "NA", - "errorCodeText": "invalidQuery", - "erorCodeMessage": "UNLocationCode does not exist" - } - ] - } - } - } - } - } - }, - "500": { - "description": "Internal Server Error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "Example 1": { - "value": { - "httpMethod": "GET", - "requestUri": "https://dcsa.org/ovs/v3/service-schedules", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Cannot process request.", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2019-11-12T07:41:00+08:30", - "errors": [] - } - } - } - } - } - } - }, - "servers": [ - { - "url": "http://localhost:3000" - } - ] - } - } - }, - "components": { - "schemas": { - "serviceSchedules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServiceSchedule" - } - }, - "ServiceSchedule": { - "title": "ServiceSchedule", - "required": [ - "carrierServiceCode", - "carrierServiceName" - ], - "type": "object", - "properties": { - "carrierServiceName": { - "maxLength": 50, - "type": "string", - "description": "The name of the service.", - "example": "Great Lion Service" - }, - "carrierServiceCode": { - "maxLength": 11, - "type": "string", - "description": "The carrier-specific code of the service for which the schedule details are published.", - "example": "FE1" - }, - "universalServiceReference": { - "maxLength": 8, - "pattern": "^SR\\d{5}[A-Z]$", - "type": "string", - "description": "A global unique service reference, as per DCSA standard, agreed by VSA partners for the service. The service reference must match the regular expression pattern: `SR\\d{5}[A-Z]`. The letters `SR` followed by `5 digits`, followed by a checksum-character as a capital letter from `A to Z`.", - "example": "SR12345A" - }, - "vesselSchedules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/VesselSchedule" - } - } - } - }, - "VesselSchedule": { - "title": "VesselSchedule", - "required": [ - "isDummyVessel", - "vesselOperatorSMDGLinerCode" - ], - "type": "object", - "properties": { - "vesselOperatorSMDGLinerCode": { - "maxLength": 10, - "type": "string", - "description": "The carrier who is in charge of the vessel operation based on the SMDG code.\r\nIf not available at the moment of sharing the schedule, use `TBD` (To be defined).\r\nIn the case an operator is still using a code not from SMDG, use the available code.", - "example": "HLC" - }, - "vesselIMONumber": { - "maxLength": 7, - "pattern": "^\\d{7}$", - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel\r\n\r\nCondition: If the vessel is not dummy, there needs to be an IMO. If the vessel is dummy, the IMO is optional.", - "example": "9321483" - }, - "vesselName": { - "maxLength": 35, - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.", - "example": "King of the Seas" - }, - "vesselCallSign": { - "maxLength": 10, - "type": "string", - "description": "A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a threeletter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.", - "example": "NCVV" - }, - "isDummyVessel": { - "type": "boolean", - "description": "Is this a dummy vessel. In case no vessel has been asigned yet - this property can be set to `true` indicating that the vesselIMONumber does not exist." - }, - "transportCalls": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TransportCall" - } - } - } - }, - "TransportCall": { - "title": "TransportCall", - "required": [ - "carrierImportVoyageNumber", - "transportCallReference" - ], - "type": "object", - "properties": { - "portVisitReference": { - "maxLength": 50, - "type": "string", - "description": "The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call", - "example": "NLAMS1234589" - }, - "transportCallReference": { - "maxLength": 100, - "type": "string", - "description": "The unique reference for a transport call. It’s the vessel operator’s responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator.", - "example": "SR11111X-9321483-2107W-NLAMS-ACT-1-1" - }, - "carrierImportVoyageNumber": { - "maxLength": 50, - "type": "string", - "description": "The identifier of an import voyage. The carrier-specific identifier of the import Voyage.", - "example": "2103N" - }, - "carrierExportVoyageNumber": { - "maxLength": 50, - "type": "string", - "description": "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.", - "example": "2103S" - }, - "universalImportVoyageReference": { - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\r\n- `2 digits` for the year\r\n- `2 alphanumeric characters` for the sequence number of the voyage\r\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).", - "example": "2103N" - }, - "universalExportVoyageReference": { - "pattern": "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type": "string", - "description": "A global unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\\d{2}[0-9A-Z]{2}[NEWSR]`\r\n- `2 digits` for the year\r\n- `2 alphanumeric characters` for the sequence number of the voyage\r\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).", - "example": "2103N" - }, - "location": { - "description": "General purpose object to capture location-related data, the location can be specified in **one** of the following ways: `UN Location Code`, a `Facility` or an `Address`.", - "discriminator": { - "propertyName": "locationType", - "mapping": { - "UNLO": "#/components/schemas/UNLocationLocation", - "FACS": "#/components/schemas/FacilitySMDGLocation", - "ADDR": "#/components/schemas/AddressLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/UNLocationLocation" - }, - { - "$ref": "#/components/schemas/FacilitySMDGLocation" - }, - { - "$ref": "#/components/schemas/AddressLocation" - } - ] - }, - "statusCode": { - "type": "string", - "description": "The set of codes in `Status Code` are ONLY meant to communicate any change / exception to the published schedule. This is not required in case of normal schedule. Possible values are:\r\n\r\n- OMIT (Omit)\r\n- BLNK (Blank)\r\n- ADHO (Ad Hoc)\r\n- PHOT (Phase Out)\r\n- PHIN (Phase In)\r\n- SLID (Sliding)\r\n- ROTC (Rotation Change)\r\n- CUTR (Cut and Run)\r\n\r\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3/reference-data/portcallstatuscodes-v300.csv)", - "example": "OMIT" - }, - "timestamps": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Timestamp" - } - } - }, - "description": "\t\nA transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall.\n\nThe order of the list is the sequence of the list" - }, - "UNLocationLocation": { - "title": "UNLocationLocation", - "required": [ - "UNLocationCode", - "locationType" - ], - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S+(\\s+\\S+)*$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, - "type": "string", - "description": "Discriminator used to identify this as a `UNLocation` location interface.", - "example": "UNLO" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example": "NLAMS" - } - }, - "additionalProperties": false, - "description": "An interface used to express a location using a `Un Location Code`." - }, - "FacilitySMDGLocation": { - "title": "FacilitySMDGLocation", - "required": [ - "UNLocationCode", - "facilitySMDGCode", - "locationType" - ], - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, - "type": "string", - "description": "Discriminator used to identify this as a `Facility Location` interface only using `SMDG` code list.", - "example": "FACS" - }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", - "type": "string", - "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\n - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE)", - "example": "NLAMS" - }, - "facilitySMDGCode": { - "maxLength": 6, - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\n\nThe codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)", - "example": "ACT" - } - }, - "description": "An interface used to express a location using a `Facility` by the `SMDG` code list. The `facilitySMDGCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute." - }, - "AddressLocation": { - "title": "AddressLocation", - "required": [ - "address", - "locationType" - ], - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, - "type": "string", - "description": "Discriminator used to identify this as an `Address` location interface.", - "example": "ADDR" - }, - "address": { - "$ref": "#/components/schemas/AddressLocation_address" - } - }, - "description": "An interface used to express a location using an `Address` object." - }, - "Timestamp": { - "title": "Timestamp", - "required": [ - "eventClassifierCode", - "eventDateTime", - "eventTypeCode" - ], - "type": "object", - "properties": { - "eventTypeCode": { - "type": "string", - "description": "Identifier for type of `transportEvent`\r\n\r\n- ARRI (Arrived)\r\n- DEPA (Departed)\r\n\r\nMore details can be found on [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/ovs/v3/reference-data/transporteventtypecodes-v300.csv).", - "enum": [ - "ARRI", - "DEPA" - ] - }, - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier. Values can vary depending on eventType.\n\nPossible values are:\n- ACT (Actual)\n- EST (Estimated)\n- PLN (Planned)\n", - "enum": [ - "PLN", - "EST", - "ACT" - ] - }, - "eventDateTime": { - "type": "string", - "description": "Time in the timestamp", - "format": "date-time", - "example": "2025-01-14T09:21:00+01:00" - }, - "delayReasonCode": { - "maxLength": 3, - "type": "string", - "description": "Reason code for the delay. See SMDG [Code list DELAY](https://smdg.org/documents/smdg-code-lists/delay-reason-and-port-call-activity/) for a list of valid codes to be used for this attribute.", - "example": "WEA" - }, - "changeRemark": { - "maxLength": 250, - "type": "string", - "description": "Free text field to provide information as to why the `TransportEvent` was sent.", - "example": "Bad weather" - } - }, - "description": "\t\nA timestamp for a port." - }, - "ErrorResponse": { - "title": "ErrorResponse", - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "example": "POST", - "enum": [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ] - }, - "requestUri": { - "type": "string", - "description": "The URI that was requested.\n", - "example": "/v1/events" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code returned.\n", - "format": "int32", - "example": 400 - }, - "statusCodeText": { - "maxLength": 50, - "type": "string", - "description": "A standard short description corresponding to the HTTP status code.\n", - "example": "Bad Request" - }, - "statusCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the HTTP status code with additional information.\n", - "example": "The supplied data could not be accepted" - }, - "providerCorrelationReference": { - "maxLength": 100, - "type": "string", - "description": "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example": "4426d965-0dd8-4005-8c63-dc68b01c4962" - }, - "errorDateTime": { - "type": "string", - "description": "The DateTime corresponding to the error occuring. Must be formatted using [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n", - "format": "date-time", - "example": "2019-11-12T07:41:00+08:30" - }, - "errors": { - "type": "array", - "description": "An array of errors provding more detail about the root cause.\n", - "items": { - "$ref": "#/components/schemas/DetailedError" - } - } - }, - "description": "Unexpected error" - }, - "AddressLocation_address": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "maxLength": 100, - "type": "string", - "description": "Name of the address.", - "example": "John" - }, - "street": { - "maxLength": 100, - "type": "string", - "description": "The name of the street of the party’s address.", - "example": "Ruijggoordweg" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street of the party’s address.", - "example": "100" - }, - "floor": { - "maxLength": 50, - "type": "string", - "description": "The floor of the party’s street number.", - "example": "N/A" - }, - "postCode": { - "maxLength": 50, - "type": "string", - "description": "The post code of the party’s address.", - "example": "1047 HM" - }, - "city": { - "maxLength": 65, - "type": "string", - "description": "The city name of the party’s address.", - "example": "Amsterdam" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The state/region of the party’s address.", - "example": "North Holland" - }, - "country": { - "maxLength": 75, - "type": "string", - "description": "The country of the party’s address.", - "example": "The Netherlands" - } - }, - "description": "An object for storing address related information." - }, - "DetailedError": { - "title": "DetailedError", - "required": [ - "errorCodeText" - ], - "type": "object", - "properties": { - "errorCode": { - "maximum": 9999, - "minimum": 7000, - "type": "integer", - "description": "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://dcsa.atlassian.net/wiki/spaces/DTG/pages/197132308/Standard+Error+Codes).\n", - "format": "int32", - "example": 7003 - }, - "property": { - "maxLength": 100, - "type": "string", - "description": "The name of the property causing the error.\n", - "example": "facilityCode" - }, - "value": { - "maxLength": 500, - "type": "string", - "description": "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example": "SG SIN WHS" - }, - "jsonPath": { - "maxLength": 500, - "type": "string", - "description": "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example": "$.location.facilityCode" - }, - "errorCodeText": { - "maxLength": 100, - "type": "string", - "description": "A standard short description corresponding to the `errorCode`.\n", - "example": "invalidData" - }, - "erorCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.\n", - "example": "Spaces not allowed in facility code" - } - } - } - }, - "parameters": { - "Limit": { - "name": "limit", - "in": "query", - "description": "Maximum number of items to return.", - "required": false, - "style": "form", - "explode": true, - "schema": { - "minimum": 0, - "type": "number", - "default": 100 - } - }, - "APIVersionMajor": { - "name": "API-Version", - "in": "header", - "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.", - "required": false, - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3" - } - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "style": "simple", - "explode": false, - "schema": { - "type": "string", - "example": "3.0.0" - } - } - } - } -} diff --git a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/PintScenarioListBuilder.java b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/PintScenarioListBuilder.java index ee58ccdc..6d4ebacf 100644 --- a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/PintScenarioListBuilder.java +++ b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/PintScenarioListBuilder.java @@ -340,7 +340,7 @@ private static PintScenarioListBuilder closeTransferAction(PintResponseCode sign private static JsonSchemaValidator resolveMessageSchemaValidator(String schemaName) { var standardVersion = STANDARD_VERSION.get(); - String schemaFilePath = "/standards/pint/schemas/pint-%s.json".formatted(standardVersion); + String schemaFilePath = "/standards/pint/schemas/EBL_PINT_v%s.yaml".formatted(standardVersion); return JsonSchemaValidator.getInstance(schemaFilePath, schemaName); } } diff --git a/pint/src/main/resources/standards/pint/schemas/EBL_PINT_v3.0.0.yaml b/pint/src/main/resources/standards/pint/schemas/EBL_PINT_v3.0.0.yaml new file mode 100644 index 00000000..0143efd5 --- /dev/null +++ b/pint/src/main/resources/standards/pint/schemas/EBL_PINT_v3.0.0.yaml @@ -0,0 +1,3960 @@ +openapi: 3.0.3 +servers: + - description: SwaggerHub API Auto Mocking + url: 'https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_PINT/3.0.0' +info: + version: 3.0.0 + title: DCSA eBL Platform Interoperability API + description: | +

DCSA OpenAPI specification for electronic Bill of Lading (eBL) Platform Interoperability (PINT)

+ +

The Envelope Transfer

+ + The PINT API is designed to support transfer of eBL documents with non-repudiation and any number of additional documents between two eBL platforms. + + In the most common scenario, the sending eBL platform executes the envelope transfer by: + 0. Optionally, using the [**'Receiver Validation'**](#/Receiver%20validation/post-receiver-validation) endpoint to allow the sending user to validate the identity of the receiver, before they transfer the eBL. + 1. Initiating the envelope transfer using [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint + 2. Transferring the additional documents (one at the time) using [**'Transfer additional document'**](#/Transfer%20additional%20document) endpoint + 3. Completing the envelope transfer using [**'Finish envelope transfer'**](#/Finish%20envelope%20transfer) endpoint + +

The eBL document

+ + The envelope transfer from the sending eBL Platform to the receiving eBL Platform always contains the **eBL document** (transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request body [`EblEnvelope.transportDocument`](#/EblEnvelope) schema object). The eBL document must be unchanged between different envelope transfers for the lifetime of the eBL document. + + The PINT API is designed to support transfer of the following types of eBL documents: + 1. Straight eBL documents. This type of eBL document is defined by [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `false` + 2. Blank-endorsed eBL documents. This type of eBL document is created by setting [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentparties[]`](#/EblEnvelope) list does not contain document party where `DocumentParty.partyFunction` has value `END` (Endorsee) + 3. To-order/Negotiable eBL documents. This type of eBL document is created by setting the [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentparties[]`](#/EblEnvelope) list contains document party where `DocumentParty.partyFunction` has value `END` (Endorsee). If the current endorsee party is also in possession of the eBL (possessor), this party can endorse some other party on the same eBL Platform (and make that other party new endorsee) by executing transaction with [`Transaction.action`](#/Transaction) type `ENDO` (Endorsement). The DCSA PINT API support To-order/Negotiable documents, however, given that not all of the eBL solution providers support the split between possession and endorsements, this doesn't apply yet to interoperable eBL + +

The Additional Documents

+ + The envelope transfer can optionally contain one or more **additional documents** which can be transferred via [**'Transfer additional document'**](#/Transfer%20additional%20document) endpoint: + - **'Digital copy of the original physical B/L document' document** (described via [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) schema object that has been previously transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint as JWS-signed payload of [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) schema object) a.k.a. **eBLVisualisationByCarrier document**. If transferred with the initial eBL envelope transfer, eBLVisualisationByCarrier document must be transferred with every subsequent envelope transfer for the lifetime of the eBL document. Also, eBLVisualisationByCarrier document must be unchanged between different envelope transfers for the lifetime of the eBL document. + - **Supporting document** (described via entry in the [`EnvelopeManifest.supportingDocuments[]`](#/EnvelopeManifest) list object that has been previously transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint as JWS-signed payload of [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) schema object). For every envelope transfer, the sending platform can choose which supporting documents it wants to send to the receiving platform irrespective of the contents of the previously received envelope transfer. All details of the supporting documents transferred from sending to receiving platform as a part of the envelope transfer are only privy to these 2 platforms. + +

Non-repudiation

+ + When receiving [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request, the receiving platform should confirm the integrity of the received [`EblEnvelope`](#/EblEnvelope) schema object for non-repudiation purposes. Since it has been decided not to use JWS for signing of [`EblEnvelope`](#/EblEnvelope) (for network traffic optimization purposes) itself, the receiving platform can confirm the integrity of the envelope data by confirming integrity of the [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) JWS-signed payload [`EnvelopeManifest`](#/EnvelopeManifest), and then use contents of [`EnvelopeManifest`](#/EnvelopeManifest) schema object to confirm the integrity of the other [`EblEnvelope`](#/EblEnvelope) schema object attributes (further details can be found in the description of [`EblEnvelope`](#/EblEnvelope) schema attributes). + + At various stages during the envelope transfer process, the receiving platform can inform the sending platform whether envelope transfer has been accepted or rejected by sending the final response using the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) schema object which has been wrapped in JWS-signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) schema object for non-repudiation purposes. All other response schema types are unsigned, and therefore they can not be used by the sending platform for the non-repudiation purposes. + + ### API Design & Implementation Principles + This API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design) + + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/pint/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + + API specification issued by [DCSA.org](https://dcsa.org/). + license: + name: Apache 2.0 + url: 'http://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: Receiver validation + description: Receiver validation + - name: Start envelope transfer + description: Start envelope transfer + - name: Transfer additional document + description: Transfer additional document + - name: Finish envelope transfer + description: Finish envelope transfer +paths: + /v3/envelopes: + post: + tags: + - Start envelope transfer + operationId: post-envelopes + summary: Start the eBL envelope transfer + description: | + Start the eBL envelope transfer. + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EblEnvelope' + responses: + '200': + description: | + The Receiving platform either accepts the envelope transfer immediately (if there are no additional documents to be transferred, or if it concludes that it is already in the possession of all the additional documents mentioned in the [`EnvelopeManifest`](#/EnvelopeManifest)), or concludes that in has previously accepted the envelope transfer with the same contents. + + The signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) that signals the accepted envelope transfer (`RECE` or `DUPE`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + '201': + description: | + The Receiving platform acknowledges that the envelope transfer is now active for this envelope transfer request. + + The sending platform should transfer all supporting documents listed in the [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) JWS-signed payload [`EnvelopeManifest.supportingDocuments`](#/EnvelopeManifest) list, as well as eBLVisualisationByCarrier document if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined, prior to sending request to finish the envelope transfer. + + If the sending platform attempts to start a new envelope transfer for an eBL that already has the active envelope transfer that is not yet completed, the receiving platform should assume that the sending platform is retrying the envelope transfer. The receiving platform should assume that the sending platform is aware that the previous envelope transfer failed or that the sending platform is not aware that the previous envelope transfer started. + + The [`EnvelopeTransferStartedResponse`](#/EnvelopeTransferStartedResponse) response is unsigned. The sending platform is required to finish the envelope transfer via [**'Finish envelope transfer'**](#/Finish%20envelope%20transfer) endpoint in order to get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload `EnvelopeTransferFinishedResponse` carrying the information whether the receiving platform has accepted or rejected the envelope transfer. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferStartedResponse' + '422': + description: | + Receiving platform rejects the envelope transfer. + + The signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + default: + description: | + Request failed for the unexpected reason. The unsigned response contains all the error details. + + The sending platform is required to retry the envelope transfer until they get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. + + In the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '/v3/envelopes/{envelopeReference}/additional-documents/{documentChecksum}': + put: + tags: + - Transfer additional document + operationId: put-additional-documents + summary: Transfer additional document associated with the eBL envelope transfer + description: | + Transfer **additional document** associated with an eBL envelope transfer. The transferred document should be either one of the **supporting documents** from the [`EnvelopeManifest.supportingDocuments`](#/EnvelopeManifest) list, or **eBLVisualisationByCarrier document** if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined. + + The `requestBody` should contain the document being transferred. It is recommended to use the `application/json` media type for the `requestBody`. The media type provided in the initial `ISSU` (Issuance) transaction is the one that will be associated with the transferred additional document in the end. + + The receiving platform should check that the transferred document has been declared at the start of the eBL envelope transfer. + This should be done by verifying that the `documentChecksum` URL path parameter matches either [`EnvelopeManifest.eBLVisualisationByCarrier.documentChecksum`](#/EnvelopeManifest) attribute value (in which case the receiving platform can conclude that the sending platform has transferred the **eBLVisualisationByCarrier document**), or one of the [`DocumentMetadata.documentChecksum`](#/DocumentMetadata) values from the [`EnvelopeManifest.supportingDocuments[]`](#/EnvelopeManifest) list (in which case the receiving platform can conclude that the sending platform has transferred the **supporting document**) + + Furthermore, the receiving platform should compute the SHA-256 checksum of the transferred additional document, and verify that it matches the value of `documentChecksum` URL path parameter. The SHA-256 checksum MUST be calculated based on the deserialized payload. + + If all the above mentioned verifications have been successfully, the receiving platform can conclude that the additional document was transferred successfully. + parameters: + - $ref: '#/components/parameters/envelopeReference' + - $ref: '#/components/parameters/documentChecksum' + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + type: string + format: byte + description: | + A Base64 encoded payload containing the file to transfer. + example: UmF3IGNvbnRlbnQgb2YgdGhlIGZpbGUgYmVpbmcgdHJhbnNmZXJyZWQ= + responses: + '204': + description: | + The receiving platform acknowledges that the additional document was transferred successfully. + + If the envelope transfer eventually gets accepted,the receiving platform will acknowledge the additional document transfer with a JWS-signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) containing JWS-signed payload [`EnvelopeTransferFinishedResponse.receivedAdditionalDocumentChecksums[]`](#/EnvelopeTransferFinishedResponse) list containing the additional document checksum. Therefore, this is unsigned response. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + '409': + description: | + The Receiving platform has discovered conflict between the request and the current state of the envelope transfer. + E.g. the checksum or the size of the transferred additional document does not match the data provided in the URL path or in the request at the start of the envelope transfer. + + The signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the issue with the envelope transfer that does *not* reject the envelope transfer (`INCD`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + '422': + description: | + The Receiving platform rejects the envelope transfer. + + The signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + default: + description: | + Request failed for the unexpected reason. The unsigned response contains all the error details. + + The sending platform is required to retry the additional document transfer until they get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. + + In the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '/v3/envelopes/{envelopeReference}/finish-transfer': + put: + tags: + - Finish envelope transfer + operationId: put-finish-transfer + summary: Finish the eBL envelope transfer + description: | + Finish the eBL envelope transfer. + + The sending platform believes all additional documents have been transferred and the envelope transfer can now be completed. + + Prior to accepting envelope transfer, the receiving platform should ensure that all supporting documents listed in the [`EnvelopeManifest.supportingDocument`](#/EnvelopeManifest) list have been successfully transferred, as well as eBLVisualisationByCarrier document if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined. Otherwise, The receiving platform should reject the envelope transfer. + parameters: + - $ref: '#/components/parameters/envelopeReference' + - $ref: '#/components/parameters/Api-Version-Major' + responses: + '200': + description: | + The Receiving platform accepts the envelope transfer. + + The signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the accepted envelope transfer (`RECE` or `DUPE`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + '409': + description: | + The Receiving platform has discovered conflict between the request and the current state of the envelope transfer. + + The signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the issue with the envelope transfer that does *not* reject the envelope transfer (`DISE` or `MDOC`). + + In the case of `MDOC` [`responseCode`](#/EnvelopeTransferFinishedResponse), the receiving platform cannot accept the envelope transfer due to one or more missing additional documents. In this case, the sending platform should (re)send the missing documents (provided in [`EnvelopeTransferFinishedResponse.missingAdditionalDocumentChecksums[]`](#/EnvelopeTransferFinishedResponse) list) and then retry to finish the envelope transfer. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + '422': + description: | + The Receiving platform rejects the envelope transfer. + + The signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`). + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/EnvelopeTransferFinishedResponseSignedContent' + default: + description: | + Request failed for the unexpected reason. The unsigned response contains all the error details. + + The sending platform should retry to finish the envelope transfer until it gets the signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. + + In the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + /v3/receiver-validation: + post: + tags: + - Receiver validation + operationId: post-receiver-validation + summary: Enable a user to validate the receiver + description: | + Request the name of a party given a party code. This enables the sending user to validate + the receiver information (similar how bank transfers enable users to conform the receiver + before confirming the transfer). + + A successful response to this query asserts that the platform will accept an eBL for the + account or user denoted by the provided identifying code and that said account or user + is "active and able to accept interoperable eBLs" as defined by the platform hosting + the account or user. + + The transfer can still be rejected due to an unknown user if the transfer has + multiple conflicting identifying codes. Platforms that supports using multiple identifying + codes when transferring an eBL will need to consider how they ensure they do not by accident + include conflicting codes. + parameters: + - $ref: '#/components/parameters/Api-Version-Major' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/IdentifyingCode' + responses: + '200': + description: | + On a successful match, this response includes the relevant information that should be displayed to the user + to help them assert they have the correct party. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ReceiverValidationResponse' + '404': + description: | + If the server cannot identify an account or user via the given party code, then it should use this + response code. This response is also applicable if the query matches multiple distinct accounts or + when the platform would reject a transfer request to said account or user. + + Note this code is also used, if the client is using a code list provider that the server cannot + (or will not) support. As an example, platforms are not required to support codes issued by + other eBL platforms and can unconditionally reject lookup requests for them with this response. + + The response is deliberately vague on negative results to limit data exposure by default. The + server may at its discretion include more details about the underlying issue in the response + body. + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + default: + description: | + Request failed for the unexpected reason. The unsigned response contains all the error details. + 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.0 + description: | + SemVer used to indicate the version of the contract (API version) returned. + schemas: + ############## + # Simple types + ############## + DocumentChecksum: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + description: | + The checksum of the document 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 + ############## + # Objects + ############## + 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 + EblEnvelope: + type: object + title: Ebl Envelope + properties: + transportDocument: + $ref: '#/components/schemas/TransportDocument' + envelopeManifestSignedContent: + $ref: '#/components/schemas/EnvelopeManifestSignedContent' + envelopeTransferChain: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/EnvelopeTransferChainEntrySignedContent' + description: | + The ordered list of [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entries associated with the eBL document. + + The receiving platform is required to validate that all the list entries are present, valid, and they are correctly ordered by: + 1. Computing the SHA-256 checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the `envelopeTransferChain[]` list, and confirming it's equal to received `EblEnvelope.envelopeManifestSignedContent` JWS-signed payload [`EnvelopeManifest.lastEnvelopeTransferChainEntrySignedContentChecksum`](#/EnvelopeManifest) attribute value. + 2. Walking back through the `envelopeTransferChain[]` list from the last entry, for each previous [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the list, computing the SHA-256 checksum and confirming it's equal to the current [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry JWT-signed payload [`EnvelopeTransferChainEntry.previousEnvelopeTransferChainEntrySignedContentChecksum`](#/EnvelopeTransferChainEntry) attribute value. + + The receiving platform can reject the envelope with `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse) if it concludes that the list entries are not correctly ordered by the sending platform, or discovers any other validity-related issue in the list. + + The first [`EnvelopeTransferChainEntry`](#/EnvelopeTransferChainEntry) in the `envelopeTransferChain[]` list should contain the ISSU (issuance) transaction as the first transaction in the [`EnvelopeTransferChainEntry.transactions[]`](#/EnvelopeTransferChainEntry) list. + required: + - transportDocument + - envelopeManifestSignedContent + - envelopeTransferChain + ReceiverValidationResponse: + type: object + title: Receiver Validation Response + description: | + Response to a receiver validation response, where the party code could successfully identified. + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + required: + - partyName + EnvelopeManifest: + type: object + title: Envelope Manifest + properties: + transportDocumentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + description: | + The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + + In order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value. + + The checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/). + example: 583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006 + lastEnvelopeTransferChainEntrySignedContentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + # TODO: Verify and if necessary update the example, or remove it altogether + example: 20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9 + description: | + This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + eBLVisualisationByCarrier: + allOf: + - $ref: '#/components/schemas/DocumentMetadata' + description: | + actual type: [`DocumentMetadata`](#\DocumentMetadata) + + This attribute is used to simplify validation of the document metadata of the **'Digital copy of the original physical B/L document' document** a.k.a. **eBLVisualisationByCarrier document**. If this attribute is defined, for each [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list, JWS-signed payload [`EnvelopeTransferChainEntry.eBLVisualisationByCarrier`](#/EnvelopeTransferChainEntry) attribute value should be identical to the value of this attribute. + supportingDocuments: + type: array + items: + $ref: '#/components/schemas/DocumentMetadata' + required: + - transportDocumentChecksum + - lastEnvelopeTransferChainEntrySignedContentChecksum + EnvelopeManifestSignedContent: + 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 [EnvelopeManifest](#/EnvelopeManifest). + # TODO: Verify and if necessary update the example, or remove it altogether + example: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJ0cmFuc3BvcnREb2N1bWVudENoZWNrc3VtIjogIjU4M2MyOWFiM2U0N2YyZDgwODk5OTkzMjAwZDNmYmFkYjlmOGEzNjdmM2EzOWY3MTU5MzVjNDZkN2EyODMwMDYiLCJsYXN0RW52ZWxvcGVUcmFuc2ZlckNoYWluRW50cnlTaWduZWRDb250ZW50Q2hlY2tzdW0iOiAiMjBhMDI1N2IzMTNhZTA4NDE3ZTA3ZjY1NTVjNGVjODI5YTUxMmMwODNmM2VhZDE2YjQxMTU4MDE4YTIyYWJlOSJ9.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA + IssuanceManifest: + type: object + title: Issuance Manifest + properties: + documentChecksum: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + description: | + The checksum of the transport document 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 document 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 + description: | + Checksums of the carrier provided documents from the issuance time. + required: + - documentChecksum + - issueToChecksum + EnvelopeTransferChainEntry: + type: object + title: Envelope Transfer Chain Entry + 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 + transportDocumentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + description: | + The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + + In order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value. + + The checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/). + example: 583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006 + previousEnvelopeTransferChainEntrySignedContentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + nullable: true + # TODO: Verify and if necessary update the example, or remove it altogether + example: 20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9 + description: | + This attribute should *not* be defined for the first entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. For all other entries after the first entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list, this attribute **MUST** be defined and contain the checksum of the previous [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. This attribute can be used to track signed envelope transfers between platforms (for details check description of [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope)). + + The checksum is computed over the entire [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry (JWS-signed payload is described in the `EnvelopeTransferChainEntry` schema). The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + 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). + The field is conditional and must be provided in the first EnvelopeTransferChainEntry. The value must be 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 + transactions: + type: array + minItems: 1 + description: | + The eBL platform is required to record certain internal transactions as issuance, endorsements and surrender. Internal possession transfers are not required but may be done + items: + $ref: '#/components/schemas/Transaction' + required: + - eblPlatform + - transportDocumentChecksum + - transactions + EnvelopeTransferChainEntrySignedContent: + 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 [EnvelopeTransferChainEntry](#/EnvelopeTransferChainEntry). + # TODO: Verify and if necessary update the example, or remove it altogether + example: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJlYmxQbGF0Zm9ybSI6IkJPTEUiLCJ0cmFuc3BvcnREb2N1bWVudENoZWNrc3VtIjoiNTgzYzI5YWIzZTQ3ZjJkODA4OTk5OTMyMDBkM2ZiYWRiOWY4YTM2N2YzYTM5ZjcxNTkzNWM0NmQ3YTI4MzAwNiIsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiVFJOUyIsImFjdG9yIjp7InBhcnR5TmFtZSI6IklLRUEgRGVubWFyayIsImVibFBsYXRmb3JtIjoiQk9MRSIsImlkZW50aWZ5aW5nQ29kZXMiOlt7ImNvZGVMaXN0UHJvdmlkZXIiOiJHTEVJRiIsInBhcnR5Q29kZSI6IjIxMzgwMEhYNklaTTFRTkJBSjMzIiwiY29kZUxpc3ROYW1lIjoiTEVJIn1dfSwicmVjaXBpZW50Ijp7InBhcnR5TmFtZSI6IkhlbnJpayBMYXJzZW4iLCJlYmxQbGF0Zm9ybSI6IldBVkUiLCJ0YXhMZWdhbFJlZmVyZW5jZXMiOlt7InR5cGUiOiJDVlIiLCJjb3VudHJ5Q29kZSI6IkRLIiwidmFsdWUiOiIzMzk5MTI4MiJ9XX0sInRpbWVzdGFtcCI6MTcxMzM0MjY3OTUzMX1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA + EnvelopeTransferStartedResponse: + type: object + title: Envelope Transfer Started Response + properties: + envelopeReference: + type: string + maxLength: 100 + description: | + Opaque receiving platform-provided identifier for a given eBL envelope. + example: 4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU + transportDocumentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + description: | + The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + + In order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value. + + The checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/). + example: 583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006 + lastEnvelopeTransferChainEntrySignedContentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + # TODO: Verify and if necessary update the example, or remove it altogether + example: 20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9 + description: | + This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + missingAdditionalDocumentChecksums: + type: array + minItems: 1 + description: | + The list of the checksums of the additional documents that the receiving platform expect to receive in good order before it can accept the envelope transfer. + items: + $ref: '#/components/schemas/DocumentChecksum' + required: + - envelopeReference + - transportDocumentChecksum + - lastEnvelopeTransferChainEntrySignedContentChecksum + - missingAdditionalDocumentChecksums + EnvelopeTransferFinishedResponse: + type: object + title: Envelope Transfer Finished Response + required: + - lastEnvelopeTransferChainEntrySignedContentChecksum + - responseCode + # TODO: Verify and if necessary update the example, or remove it altogether + example: + lastEnvelopeTransferChainEntrySignedContentChecksum: d56a93a7e9f86a2d895df818e0440bdca6ffe03246e2fee14131f2e66c84c75a + responseCode: RECE + properties: + lastEnvelopeTransferChainEntrySignedContentChecksum: + type: string + minLength: 64 + maxLength: 64 + pattern: ^[0-9a-f]+$ + description: | + This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). + # TODO: Verify and if necessary update the example, or remove it altogether + example: 20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9 + responseCode: + type: string + description: | + The response code can have one of the following values: + - `RECE` (Received) + - `DUPE` (Duplicated Envelope) + - `BSIG` (Bad Signature) + - `BENV` (Bad Envelope) + - `INCD` (Inconclusive Document) + - `MDOC` (Missing Document) + - `DISE` (Disputed Envelope) + + The `RECE` `responseCode` is used when the receiving platform acknowledges that the envelope transfer is accepted. + This response code can also be used when replying to [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request if and only if the receiving platform is already in possession of all the additional documents listed in the `EnvelopeManifest`, and is ready to commit to accepting the envelope transfer. This should only happen in special cases (e.g. Platform A which has performed the initial envelope transfer with additional documents to platform B later during the lifetime of the same eBL receives [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request from some other Platform C with `EnvelopeManifest` listing additional documents, for which it concludes (based on checksum comparison) that they are identical to the addition documents from the initial envelope transfer). The `RECE` `responseCode` should be used together with the HTTP `200 Ok` response status code. + + The `DUPE` `responseCode` is used in place of `RECE` `responseCode` when the receiving platform has already previously acknowledged and accepted the transfer of this envelope. In this case, the receiving platform asserts that this envelope transfer request is invalid but the prior envelope transfer was successful. The receiving platform should include accepted version of last `EnvelopeTransferChainEntrySignedContent` entry in `EblEnvelope.envelopeTransferChain` list in the `duplicateOfAcceptedEnvelopeTransferChainEntrySignedContent` field. The receiving platform is only required to detect DUPE `responseCode` if the EnvelopeTransferChainEntrySignedContentChecksum is the same between the two transfer attempt and the sending platform is expected to reuse the same envelope. The `DUPE` `responseCode` should be used together with the HTTP `200 Ok` response status code. + + The `BSIG` `responseCode` is used when the receiving platform could not process the envelope related to a signature and rejects the concrete transfer request. This response code should be used when the receiving platform decides to reject envelope transfer due to the issues with the signature used to create JWS content when starting envelope transfer (`EblEnvelope.envelopeManifestSignedContent`, and/or one or more `EnvelopeTransferChainEntrySignedContentChecksum` entries in the `EblEnvelope.envelopeTransferChain` list). Example use cases: the signature was made by an unknown key, the key or signature expired, the signed content does not match the EnvelopeTransferChainEntrySignedContentChecksum, etc. In this case, the receiving platform makes no assertions about the validity of the envelope contents. The sending platform may attempt to resolve the signature issue and retry with the same EnvelopeTransferChainEntrySignedContentChecksum. The `BSIG` `responseCode` should be used together with a HTTP `422 Unprocessable Content` response status code. + + The `BENV` `responseCode` is used when the receiving platform can not process the envelope and rejects the concrete envelope transfer request. This response code can be used when the receiving platform knows the transfer cannot succeed in the future and the sending platform should retain the eBL. Example use cases could be that the envelope does not list the receiving platform as the intended recipient, the transferee ID is unknown, an invalid action code was used in the transactions for this envelope transfer, etc. In this case, the receiving platform is asserting that the envelope itself is not acceptable. Basically any use case where the receiving platform decides to reject the envelope transfer for technical reasons that are not covered by `BSIG` `responseCode`. The `BENV` `responseCode` should be used together with a HTTP `422 Unprocessable Content` response status code. + + The `INCD` `responseCode` is used when the receiving platform concludes that the transferred additional document's checksum or size does not match the document checksum or size provided either directly in URL path or in `EnvelopeManifest` sent in the start envelope transfer request. The `INCD` `responseCode` does *not* reject the envelope transfer. The sending platform should try to either resend the correct document, or attempt to start new envelope transfer request with changed `EnvelopeManifest` that will contain correct document checksum and/or size for the inconclusive document. The `INCD` `responseCode` is not valid as a response to the start of a envelope transfer. The `INCD` `responseCode` should be used together with a HTTP `409 Conflict` response status code. + + The `MDOC` `responseCode` is used when the receiving platform cannot accept the envelope transfer due to a missing additional document. The `MDOC` `responseCode` does *not* reject the envelope transfer. The sending platform should resend relevant documents (provided in `missingAdditionalDocumentChecksums`) and then retry finishing the envelope transfer. The `MDOC` `responseCode` is not valid as a response to the start of a envelope transfer. The `MDOC` `responseCode` should be used together with a HTTP `409 Conflict` response status code. + + The `DISE` `responseCode` is used when the receiving platform has successfully parsed the envelope and validated the signatures. However, the receiving platform believes the envelope contradicts its current knowledge of the envelope transfer chain for the eBL document and there is a risk of double spending. The concrete detection method is implementation-specific. However, a method would be for the receiving platform to confirm whether it has `EnvelopeTransferChainEntrySignedContentChecksum` for the document, which are not listed in the transferred eBL envelope. Dispute resolution is not covered in the API and must be handled in via out of band process. The `DISE` `responseCode` should be used together with the HTTP `409 Conflict` response status code. + + Unless otherwise stated for a given response code, receiving platform will reject the active envelope transfer (if any). Some failures that result in receiving platform rejecting the envelope transfer may be retriable, in which case the sending platform can attempt a new envelope transfer for the same envelope. + + The sending platform must not rely on the HTTP response status code alone as it is not covered by the signature. When there is a mismatch between the HTTP response status code and the signed response `EnvelopeTransferFinishedResponseSignedResponse` JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse), [`responseCode`](#/EnvelopeTransferFinishedResponse) decides the outcome. + enum: + - RECE + - DUPE + - BSIG + - BENV + - MDOC + - DISE + example: RECE + duplicateOfAcceptedEnvelopeTransferChainEntrySignedContent: + type: string + pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ + description: | + actual type: [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) + + This attribute should be defined only in the case that [`responseCode`](#/EnvelopeTransferFinishedResponse) attribute has `DUPE` value, indicating that receiving platform has already received and accepted envelope transfer for the eBL document that is the sending platform trying to resend in the duplicate envelope transfer. + This attribute should contain the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received at the start of already received and accepted envelope transfer. + + The provided entry might differ in the retry (e.g. due to signing with the private key that differs from the private key used to sign already received and accepted envelope transfer). + example: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJlYmxQbGF0Zm9ybSI6IkJPTEUiLCJ0cmFuc3BvcnREb2N1bWVudENoZWNrc3VtIjoiNTgzYzI5YWIzZTQ3ZjJkODA4OTk5OTMyMDBkM2ZiYWRiOWY4YTM2N2YzYTM5ZjcxNTkzNWM0NmQ3YTI4MzAwNiIsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiVFJOUyIsImFjdG9yIjp7InBhcnR5TmFtZSI6IklLRUEgRGVubWFyayIsImVibFBsYXRmb3JtIjoiQk9MRSIsImlkZW50aWZ5aW5nQ29kZXMiOlt7ImNvZGVMaXN0UHJvdmlkZXIiOiJHTEVJRiIsInBhcnR5Q29kZSI6IjIxMzgwMEhYNklaTTFRTkJBSjMzIiwiY29kZUxpc3ROYW1lIjoiTEVJIn1dfSwicmVjaXBpZW50Ijp7InBhcnR5TmFtZSI6IkhlbnJpayBMYXJzZW4iLCJlYmxQbGF0Zm9ybSI6IldBVkUiLCJ0YXhMZWdhbFJlZmVyZW5jZXMiOlt7InR5cGUiOiJDVlIiLCJjb3VudHJ5Q29kZSI6IkRLIiwidmFsdWUiOiIzMzk5MTI4MiJ9XX0sInRpbWVzdGFtcCI6MTcxMzM0MjY3OTUzMX1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA + reason: + type: string + nullable: true + description: | + Free text comment for clarifying the result or suggesting follow up actions. Should be null or omitted when [`responseCode`](#/EnvelopeTransferFinishedResponse) is `RECE`, where there is no additional information to be given. + maxLength: 255 + example: null + missingAdditionalDocumentChecksums: + type: array + description: | + Used with the `MDOC` [`responseCode`](#/EnvelopeTransferFinishedResponse) to signal which additional documents the receiving platform believes have not been transferred. + + For other response codes, this attribute should be omitted. + items: + $ref: '#/components/schemas/DocumentChecksum' + receivedAdditionalDocumentChecksums: + type: array + description: | + The receiving platform includes this attribute with the `RECE` or `DUPE` [`responseCode`](#/EnvelopeTransferFinishedResponse) to confirm all additional documents it received during the envelope transfer. This attribute must include all the additional documents included in the envelope transfer request (including the ones the receiving platform already had). This attribute provides the sending platform with a signed receipt of the documents. + + For other response codes, this attribute should be omitted. + items: + $ref: '#/components/schemas/DocumentChecksum' + EnvelopeTransferFinishedResponseSignedContent: + 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 [EnvelopeTransferFinishedResponse](#/EnvelopeTransferFinishedResponse). + # TODO: Verify and if necessary update the example, or remove it altogether + example: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJsYXN0RW52ZWxvcGVUcmFuc2ZlckNoYWluRW50cnlTaWduZWRDb250ZW50Q2hlY2tzdW0iOiJkNTZhOTNhN2U5Zjg2YTJkODk1ZGY4MThlMDQ0MGJkY2E2ZmZlMDMyNDZlMmZlZTE0MTMxZjJlNjZjODRjNzVhIiwicmVzcG9uc2VDb2RlIjoiUkVDRSJ9.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA + DocumentMetadata: + type: object + title: Document Metadata + properties: + name: + type: string + pattern: ^\S(?:.*\S)?$ + example: Carrier rendered copy of the original B/L document.pdf + size: + type: number + minimum: 1 + description: the Size of the document in bytes + example: 4194304 + mediaType: + type: string + maxLength: 100 + description: The Media Type (MIME type) of the document + example: application/pdf + documentChecksum: + $ref: '#/components/schemas/DocumentChecksum' + required: + - name + - size + - mediaType + - documentChecksum + description: | + The document metadata that describes the document. + Transaction: + type: object + title: Transaction + properties: + action: + type: string + description: | + Action denotes the transaction type, which can have one of the following values: + - `ISSU` (Issuance) + - `TRNS` (Transfer of possession) + - `ENDO` (Endorsement a.k.a. Transfer of title) + - `RESD` (Request to surrender for delivery) + - `RESA` (Request to surrender for amendment) + - `SACC` (Surrender accepted) + - `SREJ` (Surrender rejected) + + The `ISSU` `action` is used for the eBL issuance transaction from the carrier party to the shipper party, and must appear exactly once in the first transaction of the first [`EnvelopeTransferChainEntry`](#/EnvelopeTransferChainEntry) entry (as JWS payload of [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry) in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list. If the eBL document is issued to the shipper party that resides on the different eBL Platform from the carrier's platform, initial envelope transfer should contain envelope transfer chain where first entry's first transaction has `ISSU` `action` type. + + The `TRNS` `action` is used for the transfer of possession of the eBL from the current possessor party to the new possessor party. + + The `ENDO` `action` is used for the endorsement (a.k.a. transfer of title, or the right to take the delivery of the goods) of To-order eBL documents, where the new endorsee party is not named in the eBL document. The endorsement should always happen on the platform of the user that is not only the current endorsee, but also the current possessor of the eBL document. If the new endorsee party resides on the different eBL Platform from the current endorsee's platform, the envelope transfer process is used to notify the new endorsee of the `ENDO` `action` transaction for non-repudiation purposes, and will NOT result in the transfer of possession of the eBL document contained in the envelope. + + If the party is the current possessor, and the party is the current consignee/endorsee/shipper (or eBL document is blank-endorsed), the party may request to surrender the eBL to the carrier. This is done by using one of the Request to surrender action types (`RESD` `action` or `RESA` `action`) and with the issuing carrier or the relevant carrier agent as the `recipient` of the action. + + The `RESD` `action` is used when the party wants to request the delivery of the goods. If the request is accepted (for details see `SACC` `action`), the carrier and the party submitting the surrender request will negotiate how the goods will be delivered (e.g. via DCSA shipment release API). + + The `RESA` `action` is used when the party wants to surrender the eBL document, so that the carrier can issue an amended eBL document. If the request is accepted (for details see `SACC` `action` response), the alignment on the exact change(s) that need to be made to the eBL document is done outside of the PINT API (e.g. via the DCSA EBL API). If the request is accepted, the existing eBL document is voided along with its envelope transfer chain, and the amended eBL document must be reissued with a new envelope transfer chain (for details see the `ISSU` `action` type description paragraph above). The `RESA` `action` is also used for switch to paper as the DCSA process flow for switching to paper is part of the amendment process (e.g. to note how many originals and copies with and without charges should be issued). + + If a surrender request (`RESD` `action` or `RESA` `action`) is not addressed to the carrier that issued the eBL document or to their legal representative, then the receiving platform should reject the envelope transfer with the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) containing `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse). + + The `SACC` `action` is used by the carrier to asynchronously accept the surrender request initiated via `RESD` `action` or `RESA` `action`. If the party that submitted the surrender request is on the different platform, the envelope transfer process is used to notify the (surrender request submitter) party of the `SACC` `action` transaction for non-repudiation purposes, and will NOT result in the transfer of possession of the eBL document contained in the envelope. No transactions may occur after a `SACC` `action` transaction. Any envelope transfer chain changes with new transactions after a `SACC` `action` transaction are invalid and should be answered with the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) containing `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse). + + The `SREJ` `action` is used by the carrier to asynchronously reject the surrender request initiated via `RESD` `action` or `RESA` `action`, and return the eBL document possession to the party that submitted the surrender request. + + When the transaction recipient is residing on the different platform from the transaction actor's platform, the transaction should be followed by the envelope transfer from the actor's (sending) platform to the recipient's (receiving) platform. If the envelope transfer is caused by either `ENDO` `action` or `SACC` `action` transaction (where the recipient is on the different platform), the envelope transfer process is NOT causing transfer of possession of the eBL document, but is merely used as notification for the non-repudiation purposes. + enum: + - ISSU + - ENDO + - TRNS + - RESD + - RESA + - SACC + - SREJ + example: ISSU + actor: + $ref: '#/components/schemas/TransactionParty' + recipient: + $ref: '#/components/schemas/TransactionParty' + timestamp: + type: integer + format: int64 + description: Unix epoch with millisecond precision of when the transaction was created. + example: 1713342679531 + reason: + type: string + maxLength: 4 + description: | + A code defined by DCSA indicating the reason for `RESA` (Request to surrender for amendment). Possible values are: + - `SWTP` (Switch to paper) + + **Condition:** on `action` being `RESA` + example: SWTP + comments: + type: string + pattern: ^\S(?:.*\S)?$ + description: Free text comment for the party receiving the transaction. + maxLength: 255 + example: The B/L has been issued. + required: + - action + - actor + - timestamp + - recipient + TransactionParty: + description: Refers to a company or a legal entity. + title: Transaction Party + type: object + properties: + partyName: + type: string + pattern: ^\S(?:.*\S)?$ + maxLength: 70 + description: | + Name of the party. + example: Globeteam + eblPlatform: + type: string + pattern: ^\S+$ + maxLength: 4 + description: | + The EBL platform of the 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 + - eblPlatform + - 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 receiving platform is required to validate the eBL document (a.k.a. transport document) by computing the SHA-256 checksum of the `transportDocument` attribute value, and confirming it's equal to received 'EblEnvelope.envelopeManifestSignedContent' JWS-signed payload [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute value. + 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 + 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: 22GP + 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 to provide if `temperatureSetpoint` is provided + enum: + - CEL + - FAH + example: CEL + o2Setpoint: + type: number + format: float + minimum: 0 + maximum: 100 + description: | + The percentage of the controlled atmosphere CO2 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 to provide if `airExchange` is provided + 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` 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 + 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` 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 + 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 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 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 + 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 + + 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 + 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 + + 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 + + PlaceOfIssue: + type: object + title: Place of Issue + description: | + An object to capture where the original Transport Document (`Bill of Lading`) will be issued. + + The location can be specified as one of `UN Location Code` or `CountryCode`. + 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 athorizes 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' + parameters: + ############## + # 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. + envelopeReference: + in: path + name: envelopeReference + schema: + type: string + maxLength: 100 + example: 4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU + required: true + description: | + The receiving platform-provided unique identifier for the given eBL envelope. + documentChecksum: + in: path + name: documentChecksum + schema: + type: string + pattern: ^[0-9a-f]+$ + maxLength: 64 + minLength: 64 + example: 7d00064ed0b90467ff7aff6032d8e2d94845745b6590895cd95708d2ee4243d8 + required: true + description: | + The checksum of the document computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234). diff --git a/pint/src/main/resources/standards/pint/schemas/pint-3.0.0.json b/pint/src/main/resources/standards/pint/schemas/pint-3.0.0.json deleted file mode 100644 index 1d88a9fd..00000000 --- a/pint/src/main/resources/standards/pint/schemas/pint-3.0.0.json +++ /dev/null @@ -1,3677 +0,0 @@ -{ - "components" : { - "headers" : { - "API-Version" : { - "description" : "SemVer used to indicate the version of the contract (API version) returned.\n", - "explode" : false, - "schema" : { - "example" : "3.0.0", - "type" : "string" - }, - "style" : "simple" - } - }, - "parameters" : { - "Api-Version-Major" : { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - }, - "documentChecksum" : { - "description" : "The checksum of the document computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).", - "explode" : false, - "in" : "path", - "name" : "documentChecksum", - "required" : true, - "schema" : { - "example" : "7d00064ed0b90467ff7aff6032d8e2d94845745b6590895cd95708d2ee4243d8", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "style" : "simple" - }, - "envelopeReference" : { - "description" : "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "explode" : false, - "in" : "path", - "name" : "envelopeReference", - "required" : true, - "schema" : { - "example" : "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU", - "maxLength" : 100, - "type" : "string" - }, - "style" : "simple" - } - }, - "schemas" : { - "ActiveReeferSettings" : { - "description" : "The specifications for a Reefer equipment.\n\n**Condition:** Only applicable when `isNonOperatingReefer` is set to `false`\n", - "properties" : { - "airExchangeSetpoint" : { - "description" : "Target value for the air exchange rate which is the rate at which outdoor air replaces indoor air within a Reefer container\n", - "example" : 15.4, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "airExchangeUnit" : { - "description" : "The unit for `airExchange` in metrics- or imperial- units per hour\n- `MQH` (Cubic metre per hour)\n- `FQH` (Cubic foot per hour)\n\n**Condition:** Mandatory to provide if `airExchange` is provided\n", - "enum" : [ - "MQH", - "FQH" - ], - "example" : "MQH", - "type" : "string" - }, - "co2Setpoint" : { - "description" : "The percentage of the controlled atmosphere CO2 target value\n", - "example" : 25, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "humiditySetpoint" : { - "description" : "The percentage of the controlled atmosphere humidity target value\n", - "example" : 95.6, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "isBulbMode" : { - "description" : "Is special container setting for handling flower bulbs active\n", - "example" : true, - "type" : "boolean" - }, - "isColdTreatmentRequired" : { - "description" : "Indicator whether cargo requires cold treatment prior to loading at origin or during transit, but prior arrival at POD\n", - "example" : true, - "type" : "boolean" - }, - "isControlledAtmosphereRequired" : { - "description" : "Indicator of whether cargo requires Controlled Atmosphere.\n", - "example" : true, - "type" : "boolean" - }, - "isDrainholesOpen" : { - "description" : "Is drain holes open on the container\n", - "example" : true, - "type" : "boolean" - }, - "isVentilationOpen" : { - "description" : "If `true` the ventilation orifice is `Open` - if `false` the ventilation orifice is `closed`\n", - "example" : true, - "type" : "boolean" - }, - "o2Setpoint" : { - "description" : "The percentage of the controlled atmosphere CO2 target value\n", - "example" : 25, - "format" : "float", - "maximum" : 100, - "minimum" : 0, - "type" : "number" - }, - "temperatureSetpoint" : { - "description" : "Target value of the temperature for the Reefer based on the cargo requirement.\n", - "example" : -15, - "format" : "float", - "type" : "number" - }, - "temperatureUnit" : { - "description" : "The unit for temperature in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n\n**Condition:** Mandatory to provide if `temperatureSetpoint` is provided\n", - "enum" : [ - "CEL", - "FAH" - ], - "example" : "CEL", - "type" : "string" - } - }, - "title" : "Active Reefer Settings", - "type" : "object" - }, - "Address" : { - "description" : "An object for storing address related information\n", - "properties" : { - "POBox" : { - "description" : "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example" : "123", - "maxLength" : 20, - "type" : "string" - }, - "city" : { - "description" : "The name of the city.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "floor" : { - "description" : "The floor of the street number.\n", - "example" : "N/A", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "postCode" : { - "description" : "The post code.", - "example" : "1047 HM", - "maxLength" : 10, - "type" : "string" - }, - "stateRegion" : { - "description" : "The name of the state/region.", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - }, - "street" : { - "description" : "The name of the street.", - "example" : "Ruijggoordweg", - "maxLength" : 70, - "type" : "string" - }, - "streetNumber" : { - "description" : "The number of the street.", - "example" : "100", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode", - "street" - ], - "title" : "Address", - "type" : "object" - }, - "CargoGrossVolume" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "enum" : [ - "MTQ", - "FTQ" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Gross Volume", - "type" : "object" - }, - "CargoGrossWeight" : { - "description" : "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 2400, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Gross Weight", - "type" : "object" - }, - "CargoItem" : { - "description" : "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", - "properties" : { - "cargoGrossVolume" : { - "$ref" : "#/components/schemas/CargoGrossVolume" - }, - "cargoGrossWeight" : { - "$ref" : "#/components/schemas/CargoGrossWeight" - }, - "cargoNetVolume" : { - "$ref" : "#/components/schemas/CargoNetVolume" - }, - "cargoNetWeight" : { - "$ref" : "#/components/schemas/CargoNetWeight" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `cargoItem`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "outerPackaging" : { - "$ref" : "#/components/schemas/OuterPackaging" - } - }, - "required" : [ - "cargoGrossWeight", - "equipmentReference", - "outerPackaging" - ], - "title" : "Cargo Item", - "type" : "object" - }, - "CargoNetVolume" : { - "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", - "enum" : [ - "MTQ", - "FTQ" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Net Volume", - "type" : "object" - }, - "CargoNetWeight" : { - "description" : "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 2400, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Cargo Net Weight", - "type" : "object" - }, - "CarriersAgentAtDestination" : { - "description" : "The party on the import side assigned by the carrier to whom the customer need to reach out to for cargo release.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "address", - "partyContactDetails", - "partyName" - ], - "title" : "Carrier's Agent At Destination", - "type" : "object" - }, - "Charge" : { - "description" : "Addresses the monetary value of freight and other service charges for a `Booking`.\n", - "properties" : { - "calculationBasis" : { - "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.\n", - "example" : "Per day", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "chargeName" : { - "description" : "Free text field describing the charge to apply\n", - "example" : "Documentation fee - Destination", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "currencyAmount" : { - "description" : "The monetary value of all freight and other service charges for a transport document, with a maximum of 2-digit decimals.\n", - "example" : 1012.12, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "currencyCode" : { - "description" : "The currency for the charge, using a 3-character code ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)).\n", - "example" : "DKK", - "maxLength" : 3, - "minLength" : 3, - "pattern" : "^[A-Z]{3}$", - "type" : "string" - }, - "paymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "quantity" : { - "description" : "The amount of unit for this charge item.\n", - "example" : 34.4, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "unitPrice" : { - "description" : "The unit price of this charge item in the currency of the charge.\n", - "example" : 3456.6, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "calculationBasis", - "chargeName", - "currencyAmount", - "currencyCode", - "paymentTermCode", - "quantity", - "unitPrice" - ], - "title" : "Charge", - "type" : "object" - }, - "City" : { - "description" : "An object for storing city, state/region and country related information\n", - "properties" : { - "city" : { - "description" : "The name of the city.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "stateRegion" : { - "description" : "The name of the state/region.\n", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode" - ], - "title" : "City", - "type" : "object" - }, - "Consignee" : { - "description" : "The party to which goods are consigned in the `Master Bill of Lading`.\n\n**Condition:** Mandatory for non-negotiable BL (`isToOrder=false`)\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "purchaseOrderReferences" : { - "description" : "A list of `Purchase Order Reference`s linked to the `Consignee`.\n", - "items" : { - "description" : "A purchase order reference linked to the `Consignee`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "reference" : { - "description" : "A reference linked to the `Consignee`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Consignee", - "type" : "object" - }, - "ConsignmentItem" : { - "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`\n", - "properties" : { - "HSCodes" : { - "description" : "A list of `HS Codes` that apply to this `consignmentItem`\n", - "items" : { - "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.\n\nMore information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools).\n", - "example" : "851713", - "maxLength" : 10, - "minLength" : 6, - "pattern" : "^\\d{6,10}$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - }, - "cargoItems" : { - "description" : "A list of all `cargoItems`\n", - "items" : { - "$ref" : "#/components/schemas/CargoItem" - }, - "minItems" : 1, - "type" : "array" - }, - "carrierBookingReference" : { - "description" : "The associated booking number provided by the carrier for this `Consignment Item`.\n\nWhen multiple `carrierBookingReferences` are used then the bookings referred to must all contain the same:\n- transportPlan\n- shipmentLocations\n- receiptTypeAtOrigin\n- deliveryTypeAtDestination\n- cargoMovementTypeAtOrigin\n- cargoMovementTypeAtDestination\n- serviceContractReference\n- termsAndConditions\n- Place of B/L Issue (if provided)\n", - "example" : "ABC709951", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "descriptionOfGoods" : { - "description" : "An array of lines accurately and properly describing the cargo being shipped in the container(s) as provided by the shipper.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line describing the cargo", - "example" : "blue shoes size 47", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "maxItems" : 150, - "type" : "array" - }, - "nationalCommodityCodes" : { - "description" : "A list of `National Commodity Codes` that apply to this `commodity`\n", - "items" : { - "$ref" : "#/components/schemas/NationalCommodityCode" - }, - "type" : "array" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/ReferenceConsignmentItem" - }, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "HSCodes", - "cargoItems", - "carrierBookingReference", - "descriptionOfGoods" - ], - "title" : "Consignment Item", - "type" : "object" - }, - "CustomsReference" : { - "description" : "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "EG", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The reference type code as defined in the relevant customs jurisdiction.\n", - "example" : "ACID", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "values" : { - "items" : { - "description" : "The value of the `customsReference`\n", - "example" : "4988470982020120017", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "countryCode", - "type", - "values" - ], - "title" : "Customs Reference", - "type" : "object" - }, - "DangerousGoods" : { - "description" : "Specification for `Dangerous Goods`. It is mandatory to either provide the `unNumber` or the `naNumber`. Dangerous Goods is based on **IMDG Amendment Version 41-22**.\n", - "oneOf" : [ - { - "properties" : { - "unNumber" : { - "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.\n", - "example" : "1463", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^\\d{4}$", - "type" : "string" - } - }, - "required" : [ - "unNumber" - ], - "title" : "UN Number", - "type" : "object" - }, - { - "properties" : { - "naNumber" : { - "description" : "Four-digit number that is assigned to dangerous, hazardous, and harmful substances by the United States Department of Transportation.\n", - "example" : "9037", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^\\d{4}$", - "type" : "string" - } - }, - "required" : [ - "naNumber" - ], - "title" : "NA Number", - "type" : "object" - } - ], - "properties" : { - "EMSNumber" : { - "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.\n", - "example" : "F-A S-Q", - "maxLength" : 7, - "type" : "string" - }, - "codedVariantList" : { - "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.\n\nCharacter | Valid Characters | Description\n:--------:|------------------|------------\n1| 0, 1, 2, 3|The packing group. Code 0 indicates there is no packing group\n2|0 to 9 and A to Z|A sequence letter for the PSN, or 0 if there were no alternative PSNs\n3 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.\n", - "example" : "2200", - "maxLength" : 4, - "minLength" : 4, - "pattern" : "^[0-3][0-9A-Z]{3}$", - "type" : "string" - }, - "competentAuthorityApproval" : { - "description" : "Name and reference number of the competent authority providing the approval.\n", - "example" : "{Name and reference...}", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "emergencyContactDetails" : { - "$ref" : "#/components/schemas/EmergencyContactDetails" - }, - "endOfHoldingTime" : { - "description" : "Date by when the refrigerated liquid needs to be delivered.\n", - "example" : "2021-09-03", - "format" : "date", - "type" : "string" - }, - "fumigationDateTime" : { - "description" : "Date & time when the container was fumigated\n", - "example" : "2024-09-04T09:41:00Z", - "format" : "date-time", - "type" : "string" - }, - "grossWeight" : { - "$ref" : "#/components/schemas/GrossWeight" - }, - "imoClass" : { - "description" : "The hazard class code of the referenced dangerous goods according to the specified regulation. Examples of possible values are:\n\n- `1.1A` (Substances and articles which have a mass explosion hazard)\n- `1.6N` (Extremely insensitive articles which do not have a mass explosion hazard)\n- `2.1` (Flammable gases)\n- `8` (Corrosive substances)\n", - "example" : "1.4S", - "maxLength" : 4, - "type" : "string" - }, - "inhalationZone" : { - "description" : "The zone classification of the toxicity of the inhalant. Possible values are:\n\n- `A` (Hazard Zone A) can be assigned to specific gases and liquids\n- `B` (Hazard Zone B) can be assigned to specific gases and liquids\n- `C` (Hazard Zone C) can **only** be assigned to specific gases\n- `D` (Hazard Zone D) can **only** be assigned to specific gases\n", - "example" : "A", - "maxLength" : 1, - "minLength" : 1, - "type" : "string" - }, - "innerPackagings" : { - "description" : "A list of `Inner Packings` contained inside this `outer packaging/overpack`.\n", - "items" : { - "$ref" : "#/components/schemas/InnerPackaging" - }, - "type" : "array" - }, - "isCompetentAuthorityApprovalRequired" : { - "description" : "Indicates if the cargo require approval from authorities\n", - "example" : false, - "type" : "boolean" - }, - "isEmptyUncleanedResidue" : { - "description" : "Indicates if the cargo is residue.\n", - "example" : false, - "type" : "boolean" - }, - "isExceptedQuantity" : { - "description" : "Indicates if the dangerous goods can be transported as excepted quantity in accordance with Chapter 3.5 of the IMO IMDG Code.\n", - "example" : false, - "type" : "boolean" - }, - "isHot" : { - "description" : "Indicates if high temperature cargo is shipped.\n", - "example" : false, - "type" : "boolean" - }, - "isLimitedQuantity" : { - "description" : "Indicates if the dangerous goods can be transported as limited quantity in accordance with Chapter 3.4 of the IMO IMDG Code.\n", - "example" : false, - "type" : "boolean" - }, - "isMarinePollutant" : { - "description" : "Indicates if the goods belong to the classification of Marine Pollutant.\n", - "example" : false, - "type" : "boolean" - }, - "isReportableQuantity" : { - "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.\n", - "example" : false, - "type" : "boolean" - }, - "isSalvagePackings" : { - "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.\n", - "example" : false, - "type" : "boolean" - }, - "isWaste" : { - "description" : "Indicates if waste is being shipped\n", - "example" : false, - "type" : "boolean" - }, - "limits" : { - "$ref" : "#/components/schemas/Limits" - }, - "netExplosiveContent" : { - "$ref" : "#/components/schemas/NetExplosiveContent" - }, - "netVolume" : { - "$ref" : "#/components/schemas/NetVolume" - }, - "netWeight" : { - "$ref" : "#/components/schemas/NetWeight" - }, - "packingGroup" : { - "description" : "The packing group according to the UN Recommendations on the Transport of Dangerous Goods and IMO IMDG Code.\n", - "example" : 3, - "format" : "int32", - "maximum" : 3, - "minimum" : 1, - "type" : "integer" - }, - "properShippingName" : { - "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.\n", - "example" : "Chromium Trioxide, anhydrous", - "maxLength" : 250, - "type" : "string" - }, - "segregationGroups" : { - "description" : "List of the segregation groups applicable to specific hazardous goods according to the IMO IMDG Code.\n\n**Condition:** only applicable to specific hazardous goods.\n", - "items" : { - "description" : "Grouping of Dangerous Goods having certain similar chemical properties. Possible values are:\n\n- `1` (Acids)\n- `2` (Ammonium Compounds)\n- `3` (Bromates)\n- `4` (Chlorates)\n- `5` (Chlorites)\n- `6` (Cyanides)\n- `7` (Heavy metals and their salts)\n- `8` (Hypochlorites)\n- `9` (Lead and its compounds)\n- `10` (Liquid halogenated hydrocarbons)\n- `11` (Mercury and mercury compounds)\n- `12` (Nitrites and their mixtures)\n- `13` (Perchlorates)\n- `14` (Permanganates)\n- `15` (Powdered metals)\n- `16` (Peroxides),\n- `17` (Azides)\n- `18` (Alkalis)\n", - "example" : "12", - "maxLength" : 2, - "type" : "string" - }, - "type" : "array" - }, - "subsidiaryRisk1" : { - "description" : "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example" : "1.2", - "maxLength" : 3, - "minLength" : 1, - "pattern" : "^[0-9](\\.[0-9])?$", - "type" : "string" - }, - "subsidiaryRisk2" : { - "description" : "Any risk in addition to the class of the referenced dangerous goods according to the IMO IMDG Code.\n", - "example" : "1.2", - "maxLength" : 3, - "minLength" : 1, - "pattern" : "^[0-9](\\.[0-9])?$", - "type" : "string" - }, - "technicalName" : { - "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.\n", - "example" : "xylene and benzene", - "maxLength" : 250, - "type" : "string" - } - }, - "required" : [ - "imoClass", - "properShippingName" - ], - "title" : "Dangerous Goods", - "type" : "object" - }, - "DetailedError" : { - "description" : "A detailed description of what has caused the error.\n", - "properties" : { - "errorCode" : { - "description" : "The detailed error code returned.\n\n - `7000-7999` Technical error codes\n - `8000-8999` Functional error codes\n - `9000-9999` API provider-specific error codes \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n", - "example" : 7003, - "format" : "int32", - "maximum" : 9999, - "minimum" : 7000, - "type" : "integer" - }, - "errorCodeMessage" : { - "description" : "A long description corresponding to the `errorCode` with additional information.\n", - "example" : "Spaces not allowed in facility code", - "maxLength" : 5000, - "type" : "string" - }, - "errorCodeText" : { - "description" : "A standard short description corresponding to the `errorCode`.\n", - "example" : "invalidData", - "maxLength" : 100, - "type" : "string" - }, - "jsonPath" : { - "description" : "A path to the property causing the error, formatted according to [JSONpath](https://github.com/json-path/JsonPath).\n", - "example" : "$.location.facilityCode", - "maxLength" : 500, - "type" : "string" - }, - "property" : { - "description" : "The name of the property causing the error.\n", - "example" : "facilityCode", - "maxLength" : 100, - "type" : "string" - }, - "value" : { - "description" : "The value of the property causing the error serialised as a string exactly as in the original request.\n", - "example" : "SG SIN WHS", - "maxLength" : 500, - "type" : "string" - } - }, - "required" : [ - "errorCodeMessage", - "errorCodeText" - ], - "title" : "Detailed Error", - "type" : "object" - }, - "DocumentChecksum" : { - "description" : "The checksum of the document 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.\n", - "example" : "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "DocumentMetadata" : { - "description" : "The document metadata that describes the document.\n", - "properties" : { - "documentChecksum" : { - "$ref" : "#/components/schemas/DocumentChecksum" - }, - "mediaType" : { - "description" : "The Media Type (MIME type) of the document", - "example" : "application/pdf", - "maxLength" : 100, - "type" : "string" - }, - "name" : { - "example" : "Carrier rendered copy of the original B/L document.pdf", - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "size" : { - "description" : "the Size of the document in bytes", - "example" : 4194304, - "minimum" : 1, - "type" : "number" - } - }, - "required" : [ - "documentChecksum", - "mediaType", - "name", - "size" - ], - "title" : "Document Metadata", - "type" : "object" - }, - "DocumentParties" : { - "description" : "All `Parties` with associated roles.\n", - "properties" : { - "carriersAgentAtDestination" : { - "$ref" : "#/components/schemas/CarriersAgentAtDestination" - }, - "consignee" : { - "$ref" : "#/components/schemas/Consignee" - }, - "endorsee" : { - "$ref" : "#/components/schemas/Endorsee" - }, - "issuingParty" : { - "$ref" : "#/components/schemas/IssuingParty" - }, - "notifyParties" : { - "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`).\n\n**Conditions:** If provided:\n - mandatory for To Order BLs, `isToOrder=true`\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "$ref" : "#/components/schemas/NotifyParty" - }, - "maxItems" : 3, - "type" : "array" - }, - "other" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", - "items" : { - "$ref" : "#/components/schemas/OtherDocumentParty" - }, - "type" : "array" - }, - "shipper" : { - "$ref" : "#/components/schemas/Shipper" - } - }, - "required" : [ - "issuingParty", - "shipper" - ], - "title" : "Document Parties", - "type" : "object" - }, - "EblEnvelope" : { - "properties" : { - "envelopeManifestSignedContent" : { - "$ref" : "#/components/schemas/EnvelopeManifestSignedContent" - }, - "envelopeTransferChain" : { - "description" : "The ordered list of [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entries associated with the eBL document.\n\nThe receiving platform is required to validate that all the list entries are present, valid, and they are correctly ordered by:\n1. Computing the SHA-256 checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the `envelopeTransferChain[]` list, and confirming it's equal to received `EblEnvelope.envelopeManifestSignedContent` JWS-signed payload [`EnvelopeManifest.lastEnvelopeTransferChainEntrySignedContentChecksum`](#/EnvelopeManifest) attribute value. \n2. Walking back through the `envelopeTransferChain[]` list from the last entry, for each previous [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the list, computing the SHA-256 checksum and confirming it's equal to the current [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry JWT-signed payload [`EnvelopeTransferChainEntry.previousEnvelopeTransferChainEntrySignedContentChecksum`](#/EnvelopeTransferChainEntry) attribute value.\n\nThe receiving platform can reject the envelope with `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse) if it concludes that the list entries are not correctly ordered by the sending platform, or discovers any other validity-related issue in the list.\n\nThe first [`EnvelopeTransferChainEntry`](#/EnvelopeTransferChainEntry) in the `envelopeTransferChain[]` list should contain the ISSU (issuance) transaction as the first transaction in the [`EnvelopeTransferChainEntry.transactions[]`](#/EnvelopeTransferChainEntry) list. \n", - "items" : { - "$ref" : "#/components/schemas/EnvelopeTransferChainEntrySignedContent" - }, - "type" : "array" - }, - "transportDocument" : { - "$ref" : "#/components/schemas/TransportDocument" - } - }, - "required" : [ - "envelopeManifestSignedContent", - "envelopeTransferChain", - "transportDocument" - ], - "title" : "Ebl Envelope", - "type" : "object" - }, - "EmergencyContactDetails" : { - "description" : "24 hr emergency contact details\n", - "properties" : { - "contact" : { - "description" : "Name of the Contact person during an emergency.\n", - "example" : "Henrik Larsen", - "maxLength" : 255, - "type" : "string" - }, - "phone" : { - "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).\n", - "example" : "+45 70262970", - "maxLength" : 30, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "provider" : { - "description" : "Name of the third party vendor providing emergency support\n", - "example" : "GlobeTeam", - "maxLength" : 255, - "type" : "string" - }, - "referenceNumber" : { - "description" : "Contract reference for the emergency support provided by an external third party vendor.\n", - "example" : "12234", - "maxLength" : 255, - "type" : "string" - } - }, - "required" : [ - "contact", - "phone" - ], - "title" : "Emergency Contact Details", - "type" : "object" - }, - "Endorsee" : { - "description" : "The party to whom the title to the goods is transferred by means of endorsement.\n\n**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.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "partyName" - ], - "title" : "Endorsee", - "type" : "object" - }, - "EnvelopeManifest" : { - "properties" : { - "eBLVisualisationByCarrier" : { - "allOf" : [ - { - "$ref" : "#/components/schemas/DocumentMetadata" - } - ], - "description" : "actual type: [`DocumentMetadata`](#\\DocumentMetadata)\n\nThis attribute is used to simplify validation of the document metadata of the **'Digital copy of the original physical B/L document' document** a.k.a. **eBLVisualisationByCarrier document**. If this attribute is defined, for each [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list, JWS-signed payload [`EnvelopeTransferChainEntry.eBLVisualisationByCarrier`](#/EnvelopeTransferChainEntry) attribute value should be identical to the value of this attribute.\n" - }, - "lastEnvelopeTransferChainEntrySignedContentChecksum" : { - "description" : "This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n", - "example" : "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "supportingDocuments" : { - "items" : { - "$ref" : "#/components/schemas/DocumentMetadata" - }, - "type" : "array" - }, - "transportDocumentChecksum" : { - "description" : "The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n\nIn order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value.\n\nThe checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/).\n", - "example" : "583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - } - }, - "required" : [ - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "supportingDocuments", - "transportDocumentChecksum" - ], - "title" : "Envelope Manifest", - "type" : "object" - }, - "EnvelopeManifestSignedContent" : { - "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 [EnvelopeManifest](#/EnvelopeManifest).\n", - "example" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA", - "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type" : "string" - }, - "EnvelopeTransferChainEntry" : { - "properties" : { - "eblPlatform" : { - "description" : "The EBL platform of the transaction party. \nThe value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n", - "example" : "BOLE", - "maxLength" : 4, - "pattern" : "^\\S+$", - "type" : "string" - }, - "issuanceManifestSignedContent" : { - "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).\nThe field is conditional and must be provided in the first EnvelopeTransferChainEntry. The value must be signed by the carrier.\n", - "example" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA", - "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type" : "string" - }, - "previousEnvelopeTransferChainEntrySignedContentChecksum" : { - "description" : "This attribute should *not* be defined for the first entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. For all other entries after the first entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list, this attribute **MUST** be defined and contain the checksum of the previous [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list. This attribute can be used to track signed envelope transfers between platforms (for details check description of [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope)).\n\nThe checksum is computed over the entire [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry (JWS-signed payload is described in the `EnvelopeTransferChainEntry` schema). The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n", - "example" : "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9", - "maxLength" : 64, - "minLength" : 64, - "nullable" : true, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "transactions" : { - "items" : { - "$ref" : "#/components/schemas/Transaction" - }, - "type" : "array" - }, - "transportDocumentChecksum" : { - "description" : "The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n\nIn order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value.\n\nThe checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/).\n", - "example" : "583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - } - }, - "required" : [ - "eblPlatform", - "transactions", - "transportDocumentChecksum" - ], - "title" : "Envelope Transfer Chain Entry", - "type" : "object" - }, - "EnvelopeTransferChainEntrySignedContent" : { - "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 [EnvelopeTransferChainEntry](#/EnvelopeTransferChainEntry).\n", - "example" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA", - "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type" : "string" - }, - "EnvelopeTransferFinishedResponse" : { - "example" : { - "lastEnvelopeTransferChainEntrySignedContentChecksum" : "d56a93a7e9f86a2d895df818e0440bdca6ffe03246e2fee14131f2e66c84c75a", - "responseCode" : "RECE" - }, - "properties" : { - "duplicateOfAcceptedEnvelopeTransferChainEntrySignedContent" : { - "description" : "actual type: [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) \n\nThis attribute should be defined only in the case that [`responseCode`](#/EnvelopeTransferFinishedResponse) attribute has `DUPE` value, indicating that receiving platform has already received and accepted envelope transfer for the eBL document that is the sending platform trying to resend in the duplicate envelope transfer.\nThis attribute should contain the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received at the start of already received and accepted envelope transfer. \n\nThe provided entry might differ in the retry (e.g. due to signing with the private key that differs from the private key used to sign already received and accepted envelope transfer). \n", - "example" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA", - "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type" : "string" - }, - "lastEnvelopeTransferChainEntrySignedContentChecksum" : { - "description" : "This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n", - "example" : "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "missingAdditionalDocumentChecksums" : { - "description" : "Used with the `MDOC` [`responseCode`](#/EnvelopeTransferFinishedResponse) to signal which additional documents the receiving platform believes have not been transferred.\n\nFor other response codes, this attribute should be omitted.\n", - "items" : { - "$ref" : "#/components/schemas/DocumentChecksum" - }, - "type" : "array" - }, - "reason" : { - "description" : "Free text comment for clarifying the result or suggesting follow up actions. Should be null or omitted when [`responseCode`](#/EnvelopeTransferFinishedResponse) is `RECE`, where there is no additional information to be given.\n", - "maxLength" : 255, - "nullable" : true, - "type" : "string" - }, - "receivedAdditionalDocumentChecksums" : { - "description" : "The receiving platform includes this attribute with the `RECE` or `DUPE` [`responseCode`](#/EnvelopeTransferFinishedResponse) to confirm all additional documents it received during the envelope transfer. This attribute must include all the additional documents included in the envelope transfer request (including the ones the receiving platform already had). This attribute provides the sending platform with a signed receipt of the documents.\n\nFor other response codes, this attribute should be omitted.\n", - "items" : { - "$ref" : "#/components/schemas/DocumentChecksum" - }, - "type" : "array" - }, - "responseCode" : { - "description" : "The response code can have one of the following values:\n- `RECE` (Received)\n- `DUPE` (Duplicated Envelope)\n- `BSIG` (Bad Signature)\n- `BENV` (Bad Envelope)\n- `INCD` (Inconclusive Document)\n- `MDOC` (Missing Document)\n- `DISE` (Disputed Envelope)\n\nThe `RECE` `responseCode` is used when the receiving platform acknowledges that the envelope transfer is accepted. \nThis response code can also be used when replying to [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request if and only if the receiving platform is already in possession of all the additional documents listed in the `EnvelopeManifest`, and is ready to commit to accepting the envelope transfer. This should only happen in special cases (e.g. Platform A which has performed the initial envelope transfer with additional documents to platform B later during the lifetime of the same eBL receives [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request from some other Platform C with `EnvelopeManifest` listing additional documents, for which it concludes (based on checksum comparison) that they are identical to the addition documents from the initial envelope transfer). The `RECE` `responseCode` should be used together with the HTTP `200 Ok` response status code.\n\nThe `DUPE` `responseCode` is used in place of `RECE` `responseCode` when the receiving platform has already previously acknowledged and accepted the transfer of this envelope. In this case, the receiving platform asserts that this envelope transfer request is invalid but the prior envelope transfer was successful. The receiving platform should include accepted version of last `EnvelopeTransferChainEntrySignedContent` entry in `EblEnvelope.envelopeTransferChain` list in the `duplicateOfAcceptedEnvelopeTransferChainEntrySignedContent` field. The receiving platform is only required to detect DUPE `responseCode` if the EnvelopeTransferChainEntrySignedContentChecksum is the same between the two transfer attempt and the sending platform is expected to reuse the same envelope. The `DUPE` `responseCode` should be used together with the HTTP `200 Ok` response status code.\n\nThe `BSIG` `responseCode` is used when the receiving platform could not process the envelope related to a signature and rejects the concrete transfer request. This response code should be used when the receiving platform decides to reject envelope transfer due to the issues with the signature used to create JWS content when starting envelope transfer (`EblEnvelope.envelopeManifestSignedContent`, and/or one or more `EnvelopeTransferChainEntrySignedContentChecksum` entries in the `EblEnvelope.envelopeTransferChain` list). Example use cases: the signature was made by an unknown key, the key or signature expired, the signed content does not match the EnvelopeTransferChainEntrySignedContentChecksum, etc. In this case, the receiving platform makes no assertions about the validity of the envelope contents. The sending platform may attempt to resolve the signature issue and retry with the same EnvelopeTransferChainEntrySignedContentChecksum. The `BSIG` `responseCode` should be used together with a HTTP `422 Unprocessable Content` response status code.\n\nThe `BENV` `responseCode` is used when the receiving platform can not process the envelope and rejects the concrete envelope transfer request. This response code can be used when the receiving platform knows the transfer cannot succeed in the future and the sending platform should retain the eBL. Example use cases could be that the envelope does not list the receiving platform as the intended recipient, the transferee ID is unknown, an invalid action code was used in the transactions for this envelope transfer, etc. In this case, the receiving platform is asserting that the envelope itself is not acceptable. Basically any use case where the receiving platform decides to reject the envelope transfer for technical reasons that are not covered by `BSIG` `responseCode`. The `BENV` `responseCode` should be used together with a HTTP `422 Unprocessable Content` response status code.\n\nThe `INCD` `responseCode` is used when the receiving platform concludes that the transferred additional document's checksum or size does not match the document checksum or size provided either directly in URL path or in `EnvelopeManifest` sent in the start envelope transfer request. The `INCD` `responseCode` does *not* reject the envelope transfer. The sending platform should try to either resend the correct document, or attempt to start new envelope transfer request with changed `EnvelopeManifest` that will contain correct document checksum and/or size for the inconclusive document. The `INCD` `responseCode` is not valid as a response to the start of a envelope transfer. The `INCD` `responseCode` should be used together with a HTTP `409 Conflict` response status code.\n\nThe `MDOC` `responseCode` is used when the receiving platform cannot accept the envelope transfer due to a missing additional document. The `MDOC` `responseCode` does *not* reject the envelope transfer. The sending platform should resend relevant documents (provided in `missingAdditionalDocumentChecksums`) and then retry finishing the envelope transfer. The `MDOC` `responseCode` is not valid as a response to the start of a envelope transfer. The `MDOC` `responseCode` should be used together with a HTTP `409 Conflict` response status code.\n\nThe `DISE` `responseCode` is used when the receiving platform has successfully parsed the envelope and validated the signatures. However, the receiving platform believes the envelope contradicts its current knowledge of the envelope transfer chain for the eBL document and there is a risk of double spending. The concrete detection method is implementation-specific. However, a method would be for the receiving platform to confirm whether it has `EnvelopeTransferChainEntrySignedContentChecksum` for the document, which are not listed in the transferred eBL envelope. Dispute resolution is not covered in the API and must be handled in via out of band process. The `DISE` `responseCode` should be used together with the HTTP `409 Conflict` response status code.\n\nUnless otherwise stated for a given response code, receiving platform will reject the active envelope transfer (if any). Some failures that result in receiving platform rejecting the envelope transfer may be retriable, in which case the sending platform can attempt a new envelope transfer for the same envelope.\n\nThe sending platform must not rely on the HTTP response status code alone as it is not covered by the signature. When there is a mismatch between the HTTP response status code and the signed response `EnvelopeTransferFinishedResponseSignedResponse` JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse), [`responseCode`](#/EnvelopeTransferFinishedResponse) decides the outcome.\n", - "enum" : [ - "RECE", - "DUPE", - "BSIG", - "BENV", - "MDOC", - "DISE" - ], - "example" : "RECE", - "type" : "string" - } - }, - "required" : [ - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "responseCode" - ], - "title" : "Envelope Transfer Finished Response", - "type" : "object" - }, - "EnvelopeTransferFinishedResponseSignedContent" : { - "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 [EnvelopeTransferFinishedResponse](#/EnvelopeTransferFinishedResponse).\n", - "example" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJyZXNwb25zZVRvRW52ZWxvcGVIYXNoIjoiZDU2YTkzYTdlOWY4NmEyZDg5NWRmODE4ZTA0NDBiZGNhNmZmZTAzMjQ2ZTJmZWUxNDEzMWYyZTY2Yzg0Yzc1YSIsInJlc3BvbnNlQ29kZSI6IlJFQ1YifQ.P2_evKyvHH25BrvW4eIxp7xo9S73oK90QomKEjZDrn3AX8drv7aeVrNYYPPh4vqK78fTVair-0Ww9G7czX9Q3xlATTPlTQrNPuThh_-nPOvNDqHBwZuq_nop6lQwIS210OQa__C4z-oGvO8m56pfXvpgfTIC9nesnIuNFtrdr1lU81q4ZQnnZI0GvWaB_4Q320PoAXmKN4EwjY5gTqdKMAvz9a5PNnWfGPkIrM-CBm_MNLpl9NAcpJONRdwI9i9zTi42NZCUnbowHuHnYNuz3WfWzVA43U4IdEBDU6XeIem0Zm331KlBAukOhZiyN8Bp7ZK7XGx50a6XcY3190lX5Q", - "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", - "type" : "string" - }, - "EnvelopeTransferStartedResponse" : { - "properties" : { - "envelopeReference" : { - "description" : "Opaque receiving platform-provided identifier for a given eBL envelope.\n", - "example" : "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU", - "maxLength" : 100, - "type" : "string" - }, - "lastEnvelopeTransferChainEntrySignedContentChecksum" : { - "description" : "This attribute should contain the checksum of the last [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list received. The checksum is computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n", - "example" : "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "missingAdditionalDocumentChecksums" : { - "description" : "The list of the checksums of the additional documents that the receiving platform expect to receive in good order before it can accept the envelope transfer.\n", - "items" : { - "$ref" : "#/components/schemas/DocumentChecksum" - }, - "type" : "array" - }, - "transportDocumentChecksum" : { - "description" : "The checksum of the eBL document (a.k.a. transport document) computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).\n\nIn order to guard itself against different types of MITM attacks (e.g. 'replay attack' where last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list is replaced with the similar entry extracted from the another envelope transfer previously sent by the same sending platform), upon start of the envelope transfer the receiving platform should validate that the [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute and the [`EnvelopeTransferChainEntry.transportDocumentChecksum`](#/EnvelopeTransferChainEntry) attribute of the last entry in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list have the same value.\n\nThe checksum is computed on the [canonical form of the JSON object](https://gibson042.github.io/canonicaljson-spec/).\n", - "example" : "583c29ab3e47f2d80899993200d3fbadb9f8a367f3a39f715935c46d7a283006", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - } - }, - "required" : [ - "envelopeReference", - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "missingAdditionalDocumentChecksums", - "transportDocumentChecksum" - ], - "title" : "Envelope Transfer Started Response", - "type" : "object" - }, - "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.\n", - "properties" : { - "ISOEquipmentCode" : { - "description" : "Unique code for the different equipment size and type used to transport commodities. The code can refer to either the ISO size type (e.g. 22G1) or the ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n", - "example" : "22GP", - "maxLength" : 4, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "equipmentReference" : { - "description" : "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording 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).\n\nIf 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.\n", - "example" : "APZU4812090", - "maxLength" : 11, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "tareWeight" : { - "$ref" : "#/components/schemas/TareWeight" - } - }, - "required" : [ - "equipmentReference" - ], - "title" : "Equipment", - "type" : "object" - }, - "ErrorResponse" : { - "description" : "Unexpected error", - "properties" : { - "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.\n", - "example" : "2024-09-04T09:41:00Z", - "format" : "date-time", - "type" : "string" - }, - "errors" : { - "description" : "An array of errors providing more detail about the root cause.\n", - "items" : { - "$ref" : "#/components/schemas/DetailedError" - }, - "minItems" : 1, - "type" : "array" - }, - "httpMethod" : { - "description" : "The HTTP method used to make the request e.g. `GET`, `POST`, etc\n", - "enum" : [ - "GET", - "HEAD", - "POST", - "PUT", - "DELETE", - "OPTION", - "PATCH" - ], - "example" : "POST", - "type" : "string" - }, - "providerCorrelationReference" : { - "description" : "A unique identifier to the HTTP request within the scope of the API provider.\n", - "example" : "4426d965-0dd8-4005-8c63-dc68b01c4962", - "maxLength" : 100, - "type" : "string" - }, - "requestUri" : { - "description" : "The URI that was requested.\n", - "example" : "/v1/events", - "type" : "string" - }, - "statusCode" : { - "description" : "The HTTP status code returned.\n", - "example" : 400, - "format" : "int32", - "type" : "integer" - }, - "statusCodeMessage" : { - "description" : "A long description corresponding to the HTTP status code with additional information.\n", - "example" : "The supplied data could not be accepted", - "maxLength" : 200, - "type" : "string" - }, - "statusCodeText" : { - "description" : "A standard short description corresponding to the HTTP status code.\n", - "example" : "Bad Request", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "title" : "Error Response", - "type" : "object" - }, - "Facility" : { - "description" : "An object used to express a location using a `Facility`. The facility can either be expressed using a `BIC` code or a `SMDG` code. The `facilityCode` does not contain the `UNLocationCode` - this should be provided in the `UnLocationCode` attribute.\n", - "properties" : { - "facilityCode" : { - "description" : "The code used for identifying the specific facility. This code does not include the UN Location Code.\nThe definition of the code depends on the `facilityCodeListProvider`. As code list providers maintain multiple codeLists the following codeList is used:\n- `SMDG` (the codeList used is the [SMDG Terminal Code List](https://smdg.org/documents/smdg-code-lists/))\n- `BIC` (the codeList used is the [BIC Facility Codes](https://www.bic-code.org/facility-codes/))", - "example" : "ADT", - "maxLength" : 6, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "facilityCodeListProvider" : { - "description" : "The provider used for identifying the facility Code. Some facility codes are only defined in combination with an `UN Location Code`\n- `BIC` (Requires a UN Location Code)\n- `SMDG` (Requires a UN Location Code)\n", - "enum" : [ - "BIC", - "SMDG" - ], - "example" : "SMDG", - "type" : "string" - } - }, - "required" : [ - "facilityCode", - "facilityCodeListProvider" - ], - "title" : "Facility", - "type" : "object" - }, - "GeoCoordinate" : { - "description" : "An object used to express a location using `latitude` and `longitude`.\n", - "properties" : { - "latitude" : { - "description" : "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", - "example" : "48.8585500", - "maxLength" : 10, - "type" : "string" - }, - "longitude" : { - "description" : "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", - "example" : "2.294492036", - "maxLength" : 11, - "type" : "string" - } - }, - "required" : [ - "latitude", - "longitude" - ], - "title" : "Geo Coordinate", - "type" : "object" - }, - "GrossWeight" : { - "description" : "Total weight of the goods carried, including packaging.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "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.\n", - "example" : 12000.3, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Gross Weight", - "type" : "object" - }, - "IdentifyingCode" : { - "properties" : { - "codeListName" : { - "description" : "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n- `EORI` (Economic Operators Registration and Identification) for codeListProvider `EU`\n", - "example" : "DID", - "maxLength" : 100, - "type" : "string" - }, - "codeListProvider" : { - "description" : "A list of codes identifying a party. Possible values are:\n\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `EU` (European Union Member State Customs Authority)\n- `ZZZ` (Mutually defined)\n", - "example" : "W3C", - "maxLength" : 100, - "type" : "string" - }, - "partyCode" : { - "description" : "Code to identify the party as provided by the code list provider\n", - "example" : "MSK", - "maxLength" : 150, - "type" : "string" - } - }, - "required" : [ - "codeListProvider", - "partyCode" - ], - "title" : "Identifying Code", - "type" : "object" - }, - "InnerPackaging" : { - "description" : "Object for inner packaging specification\n", - "properties" : { - "description" : { - "description" : "Description of the packaging.\n", - "example" : "Woven plastic water resistant Bag", - "maxLength" : 100, - "type" : "string" - }, - "material" : { - "description" : "The `material` used for the `Inner Packaging` of the referenced `Dangerous Goods`.\n", - "example" : "Plastic", - "maxLength" : 100, - "type" : "string" - }, - "quantity" : { - "description" : "Count of `Inner Packagings` of the referenced `Dangerous Goods`.\n", - "example" : 20, - "format" : "int32", - "type" : "integer" - } - }, - "required" : [ - "description", - "material", - "quantity" - ], - "title" : "Inner Packaging", - "type" : "object" - }, - "InvoicePayableAt" : { - "description" : "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location can be provided as a `UN Location Code` or as a fallback - a `freeText` field\n", - "oneOf" : [ - { - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - } - }, - "required" : [ - "UNLocationCode" - ], - "title" : "UN Location Code", - "type" : "object" - }, - { - "properties" : { - "freeText" : { - "description" : "The name of the location where payment will be rendered by the customer.\n", - "example" : "DCSA Headquarters", - "maxLength" : 35, - "type" : "string" - } - }, - "required" : [ - "freeText" - ], - "title" : "Free text", - "type" : "object" - } - ], - "title" : "Invoice Payable At", - "type" : "object" - }, - "IssuanceManifest" : { - "description" : "Checksums of the carrier provided documents from the issuance time.\n", - "properties" : { - "documentChecksum" : { - "description" : "The checksum of the transport document 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.\n", - "example" : "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "eBLVisualisationByCarrierChecksum" : { - "description" : "The checksum of the document 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.\n", - "example" : "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "issueToChecksum" : { - "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.\n", - "example" : "76a7d14c83d7268d643ae7345c448de60701f955d264a743e6928a0b8268b24f", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - } - }, - "required" : [ - "documentChecksum", - "issueToChecksum" - ], - "title" : "Issuance Manifest", - "type" : "object" - }, - "IssuingParty" : { - "description" : "Refers to a company or a legal entity.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Asseco Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "address", - "partyName" - ], - "title" : "Issuing Party", - "type" : "object" - }, - "Limits" : { - "description" : "Limits for the `Dangerous Goods`. The same `Temperature Unit` needs to apply to all attributes in this structure.\n", - "properties" : { - "SADT" : { - "description" : "Lowest temperature in which self-accelerating decomposition may occur in a substance\n", - "example" : 54.1, - "format" : "float", - "type" : "number" - }, - "SAPT" : { - "description" : "Lowest temperature in which self-accelerating polymerization may occur in a substance\n", - "example" : 70, - "format" : "float", - "type" : "number" - }, - "flashPoint" : { - "description" : "Lowest temperature at which a chemical can vaporize to form an ignitable mixture in air.\n\n**Condition:** only applicable to specific hazardous goods according to the IMO IMDG Code.\n", - "example" : 42, - "format" : "float", - "type" : "number" - }, - "temperatureUnit" : { - "description" : "The unit for **all attributes in the limits structure** in Celsius or Fahrenheit\n\n- `CEL` (Celsius)\n- `FAH` (Fahrenheit)\n", - "enum" : [ - "CEL", - "FAH" - ], - "example" : "CEL", - "type" : "string" - }, - "transportControlTemperature" : { - "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.\n", - "example" : 24.1, - "format" : "float", - "type" : "number" - }, - "transportEmergencyTemperature" : { - "description" : "Temperature at which emergency procedures shall be implemented\n", - "example" : 74.1, - "format" : "float", - "type" : "number" - } - }, - "required" : [ - "temperatureUnit" - ], - "title" : "Limits", - "type" : "object" - }, - "NationalCommodityCode" : { - "description" : "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "BR", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n", - "example" : "NCM", - "maxLength" : 10, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "values" : { - "description" : "A list of `national commodity codes` values.\n", - "example" : [ - "1515", - "2106", - "2507", - "2512" - ], - "items" : { - "description" : "The value of the `National Commodity Code`\n", - "example" : "1515", - "maxLength" : 10, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "countryCode", - "type", - "values" - ], - "title" : "National Commodity Code", - "type" : "object" - }, - "NetExplosiveContent" : { - "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", - "properties" : { - "unit" : { - "description" : "Unit of measure used to describe the `netExplosiveWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "enum" : [ - "KGM", - "LBR", - "GRM", - "ONZ" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Explosive Content", - "type" : "object" - }, - "NetVolume" : { - "description" : "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in either imperial or metric terms\n\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "enum" : [ - "MTQ", - "FTQ", - "LTR" - ], - "example" : "MTQ", - "type" : "string" - }, - "value" : { - "description" : "The volume of the referenced dangerous goods.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Volume", - "type" : "object" - }, - "NetWeight" : { - "description" : "Total weight of the goods carried, excluding packaging.\n", - "properties" : { - "unit" : { - "description" : "Unit of measure used to describe the `netWeight`. Possible values are\n\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "Total weight of the goods carried, excluding packaging.\n", - "example" : 2.4, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Net Weight", - "type" : "object" - }, - "NotifyParty" : { - "description" : "The person to be notified when a shipment arrives at its destination.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "reference" : { - "description" : "A reference linked to the `NotifyParty`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Notify Party", - "type" : "object" - }, - "OnwardInlandRouting" : { - "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).\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Onward Inland Routing", - "type" : "object" - }, - "OtherDocumentParty" : { - "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n", - "properties" : { - "party" : { - "$ref" : "#/components/schemas/Party" - }, - "partyFunction" : { - "description" : "Specifies the role of the party in a given context. Possible values are:\n\n- `SCO` (Service Contract Owner)\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `COW` (Invoice payer on behalf of the consignor (shipper))\n- `COX` (Invoice payer on behalf of the consignee)\n", - "example" : "DDS", - "maxLength" : 3, - "type" : "string" - } - }, - "required" : [ - "party", - "partyFunction" - ], - "title" : "Other Document Party", - "type" : "object" - }, - "OuterPackaging" : { - "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.\n", - "properties" : { - "dangerousGoods" : { - "description" : "A list of `Dangerous Goods`\n", - "items" : { - "$ref" : "#/components/schemas/DangerousGoods" - }, - "type" : "array" - }, - "description" : { - "description" : "Description of the outer packaging/overpack.\n", - "example" : "Drum, steel", - "maxLength" : 100, - "type" : "string" - }, - "imoPackagingCode" : { - "description" : "The code of the packaging as per IMO.\n\n**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.\n", - "example" : "1A2", - "maxLength" : 5, - "minLength" : 1, - "pattern" : "^[A-Z0-9]{1,5}$", - "type" : "string" - }, - "numberOfPackages" : { - "description" : "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n", - "example" : 18, - "format" : "int32", - "maximum" : 99999999, - "minimum" : 1, - "type" : "integer" - }, - "packageCode" : { - "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)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n", - "example" : "5H", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z0-9]{2}$", - "type" : "string" - }, - "woodDeclaration" : { - "description" : "Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include:\n- `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped)\n- `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate)\n- `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)\n- `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate)\n", - "example" : "TREATED_AND_CERTIFIED", - "maxLength" : 30, - "type" : "string" - } - }, - "required" : [ - "description", - "numberOfPackages" - ], - "title" : "Outer Packaging", - "type" : "object" - }, - "Party" : { - "description" : "Refers to a company or a legal entity.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Asseco Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "reference" : { - "description" : "A reference linked to the `Party`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "partyName" - ], - "title" : "Party", - "type" : "object" - }, - "PartyAddress" : { - "description" : "An object for storing address related information\n", - "properties" : { - "POBox" : { - "description" : "A numbered box at a post office where a person or business can have mail or parcels delivered.", - "example" : "123", - "maxLength" : 20, - "type" : "string" - }, - "UNLocationCode" : { - "description" : "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "description" : "The city name of the party’s address.\n", - "example" : "Amsterdam", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "floor" : { - "description" : "The floor of the party’s street number.\n", - "example" : "2nd", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "postCode" : { - "description" : "The post code of the party’s address.", - "example" : "1047 HM", - "maxLength" : 10, - "type" : "string" - }, - "stateRegion" : { - "description" : "The state/region of the party’s address.", - "example" : "North Holland", - "maxLength" : 65, - "type" : "string" - }, - "street" : { - "description" : "The name of the street of the party’s address.", - "example" : "Ruijggoordweg", - "maxLength" : 70, - "type" : "string" - }, - "streetNumber" : { - "description" : "The number of the street of the party’s address.", - "example" : "100", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "city", - "countryCode", - "street" - ], - "title" : "Party Address", - "type" : "object" - }, - "PartyContactDetail" : { - "anyOf" : [ - { - "description" : "`Phone` is mandatory to provide\n", - "properties" : { - "phone" : { - "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).\n", - "example" : "+45 70262970", - "maxLength" : 30, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "phone" - ], - "title" : "Phone required", - "type" : "object" - }, - { - "description" : "`Email` is mandatory to provide\n", - "properties" : { - "email" : { - "description" : "`E-mail` address to be used\n", - "example" : "info@dcsa.org", - "maxLength" : 100, - "pattern" : "^.+@\\S+$", - "type" : "string" - } - }, - "required" : [ - "email" - ], - "title" : "Email required", - "type" : "object" - } - ], - "description" : "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`.\n", - "example" : { - "name" : "Henrik", - "phone" : "+45 51801234" - }, - "properties" : { - "name" : { - "description" : "Name of the contact\n", - "example" : "Henrik", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "name" - ], - "title" : "Party Contact Detail", - "type" : "object" - }, - "PlaceOfDelivery" : { - "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.\n\n**Condition:** Only when onward transport is done by the carrier\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Delivery", - "type" : "object" - }, - "PlaceOfIssue" : { - "description" : "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\nThe location can be specified either as a `UN Location Code` or as a `CountryCode`.\n", - "oneOf" : [ - { - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - } - }, - "required" : [ - "UNLocationCode" - ], - "title" : "UN Location Code", - "type" : "object" - }, - { - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - } - }, - "required" : [ - "countryCode" - ], - "title" : "Country Code", - "type" : "object" - } - ], - "properties" : { - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Issue", - "type" : "object" - }, - "PlaceOfReceipt" : { - "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.\n\n**Condition:** Only when pre-carriage is done by the carrier.\n\nThe location can be specified in **any** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "address" : { - "$ref" : "#/components/schemas/Address" - }, - "facility" : { - "$ref" : "#/components/schemas/Facility" - }, - "geoCoordinate" : { - "$ref" : "#/components/schemas/GeoCoordinate" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Place of Receipt", - "type" : "object" - }, - "PortOfDischarge" : { - "description" : "An object to capture `Port of Discharge` location specified as: the location where the cargo is discharged from the last sea-going vessel.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "$ref" : "#/components/schemas/City" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Port of Discharge", - "type" : "object" - }, - "PortOfLoading" : { - "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.\n\nThe location can be specified in **any** of the following ways: `UN Location Code` or `City and Country`.\n\n**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.\n", - "example" : { - "UNLocationCode" : "DEHAM", - "locationName" : "Hamburg" - }, - "properties" : { - "UNLocationCode" : { - "description" : "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", - "example" : "NLAMS", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^[A-Z]{2}[A-Z2-9]{3}$", - "type" : "string" - }, - "city" : { - "$ref" : "#/components/schemas/City" - }, - "locationName" : { - "description" : "The name of the location.", - "example" : "Port of Amsterdam", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "title" : "Port of Loading", - "type" : "object" - }, - "ReceiverValidationResponse" : { - "description" : "Response to a receiver validation response, where the party code could successfully identified.\n", - "properties" : { - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Globeteam", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Receiver Validation Response", - "type" : "object" - }, - "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.\n", - "properties" : { - "type" : { - "description" : "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n", - "example" : "CR", - "maxLength" : 3, - "type" : "string" - }, - "value" : { - "description" : "The value of the reference. \n", - "example" : "HHL00103004", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "type", - "value" - ], - "title" : "Reference", - "type" : "object" - }, - "ReferenceConsignmentItem" : { - "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.\n", - "properties" : { - "type" : { - "description" : "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n- `SPO` (Shipper's Purchase Order)\n- `CPO` (Consignee's Purchase Order)\n", - "example" : "CR", - "maxLength" : 3, - "type" : "string" - }, - "values" : { - "description" : "List of `referenceValues` for a given `referenceType`.\n", - "items" : { - "description" : "The value of the reference. \n", - "example" : "HHL00103004", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "type", - "values" - ], - "title" : "Reference (Consignment Item)", - "type" : "object" - }, - "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.\n", - "properties" : { - "number" : { - "description" : "Identifies a seal affixed to the container.", - "example" : "VET123", - "maxLength" : 15, - "type" : "string" - }, - "source" : { - "description" : "The source of the seal, namely who has affixed the seal.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n\n**Condition:** Seal source may be required depending on the type of commodity being shipped.\n", - "enum" : [ - "CAR", - "SHI", - "VET", - "CUS" - ], - "example" : "CUS", - "type" : "string" - } - }, - "required" : [ - "number" - ], - "title" : "Seal", - "type" : "object" - }, - "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.\n\n**Condition:** Either the `address` or the `displayedAddress` must be included in the `Transport Document`.\n", - "properties" : { - "address" : { - "$ref" : "#/components/schemas/PartyAddress" - }, - "displayedAddress" : { - "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`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A single address line\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 6, - "type" : "array" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyContactDetails" : { - "description" : "A list of contact details\n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "IKEA Denmark", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "purchaseOrderReferences" : { - "description" : "A list of `Purchase Order Reference`s linked to the `Shipper`.\n", - "items" : { - "description" : "A purchase order reference linked to the `Shipper`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "reference" : { - "description" : "A reference linked to the `Shipper`.\n", - "example" : "HHL007", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - }, - "typeOfPerson" : { - "description" : "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `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)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n", - "example" : "NATURAL_PERSON", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "partyName" - ], - "title" : "Shipper", - "type" : "object" - }, - "TareWeight" : { - "description" : "The weight of an empty container (gross container weight).\n", - "properties" : { - "unit" : { - "description" : "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "enum" : [ - "KGM", - "LBR" - ], - "example" : "KGM", - "type" : "string" - }, - "value" : { - "description" : "The weight of an empty container (gross container weight).\n", - "example" : 4800, - "exclusiveMinimum" : true, - "format" : "float", - "minimum" : 0, - "type" : "number" - } - }, - "required" : [ - "unit", - "value" - ], - "title" : "Tare Weight", - "type" : "object" - }, - "TaxLegalReference" : { - "description" : "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n", - "properties" : { - "countryCode" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "IN", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : { - "description" : "The reference type code as defined by the relevant tax and/or legal authority.\n", - "example" : "PAN", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "value" : { - "description" : "The value of the `taxLegalReference`\n", - "example" : "AAAAA0000A", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "countryCode", - "type", - "value" - ], - "title" : "Tax & Legal Reference", - "type" : "object" - }, - "Transaction" : { - "properties" : { - "action" : { - "description" : "Action denotes the transaction type, which can have one of the following values:\n- `ISSU` (Issuance)\n- `TRNS` (Transfer of possession)\n- `ENDO` (Endorsement a.k.a. Transfer of title)\n- `RESD` (Request to surrender for delivery)\n- `RESA` (Request to surrender for amendment)\n- `SACC` (Surrender accepted)\n- `SREJ` (Surrender rejected)\n\nThe `ISSU` `action` is used for the eBL issuance transaction from the carrier party to the shipper party, and must appear exactly once in the first transaction of the first [`EnvelopeTransferChainEntry`](#/EnvelopeTransferChainEntry) entry (as JWS payload of [`EnvelopeTransferChainEntrySignedContent`](#/EnvelopeTransferChainEntrySignedContent) entry) in the [`EblEnvelope.envelopeTransferChain`](#/EblEnvelope) list. If the eBL document is issued to the shipper party that resides on the different eBL Platform from the carrier's platform, initial envelope transfer should contain envelope transfer chain where first entry's first transaction has `ISSU` `action` type. \n\nThe `TRNS` `action` is used for the transfer of possession of the eBL from the current possessor party to the new possessor party.\n\nThe `ENDO` `action` is used for the endorsement (a.k.a. transfer of title, or the right to take the delivery of the goods) of To-order eBL documents, where the new endorsee party is not named in the eBL document. The endorsement should always happen on the platform of the user that is not only the current endorsee, but also the current possessor of the eBL document. If the new endorsee party resides on the different eBL Platform from the current endorsee's platform, the envelope transfer process is used to notify the new endorsee of the `ENDO` `action` transaction for non-repudiation purposes, and will NOT result in the transfer of possession of the eBL document contained in the envelope. \n\nIf the party is the current possessor, and the party is the current consignee/endorsee/shipper (or eBL document is blank-endorsed), the party may request to surrender the eBL to the carrier. This is done by using one of the Request to surrender action types (`RESD` `action` or `RESA` `action`) and with the issuing carrier or the relevant carrier agent as the `recipient` of the action. \n \n The `RESD` `action` is used when the party wants to request the delivery of the goods. If the request is accepted (for details see `SACC` `action`), the carrier and the party submitting the surrender request will negotiate how the goods will be delivered (e.g. via DCSA shipment release API).\n \n The `RESA` `action` is used when the party wants to surrender the eBL document, so that the carrier can issue an amended eBL document. If the request is accepted (for details see `SACC` `action` response), the alignment on the exact change(s) that need to be made to the eBL document is done outside of the PINT API (e.g. via the DCSA EBL API). If the request is accepted, the existing eBL document is voided along with its envelope transfer chain, and the amended eBL document must be reissued with a new envelope transfer chain (for details see the `ISSU` `action` type description paragraph above). The `RESA` `action` is also used for switch to paper as the DCSA process flow for switching to paper is part of the amendment process (e.g. to note how many originals and copies with and without charges should be issued).\n\nIf a surrender request (`RESD` `action` or `RESA` `action`) is not addressed to the carrier that issued the eBL document or to their legal representative, then the receiving platform should reject the envelope transfer with the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) containing `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse).\n\nThe `SACC` `action` is used by the carrier to asynchronously accept the surrender request initiated via `RESD` `action` or `RESA` `action`. If the party that submitted the surrender request is on the different platform, the envelope transfer process is used to notify the (surrender request submitter) party of the `SACC` `action` transaction for non-repudiation purposes, and will NOT result in the transfer of possession of the eBL document contained in the envelope. No transactions may occur after a `SACC` `action` transaction. Any envelope transfer chain changes with new transactions after a `SACC` `action` transaction are invalid and should be answered with the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) containing `BENV` [`responseCode`](#/EnvelopeTransferFinishedResponse). \n\nThe `SREJ` `action` is used by the carrier to asynchronously reject the surrender request initiated via `RESD` `action` or `RESA` `action`, and return the eBL document possession to the party that submitted the surrender request.\n\nWhen the transaction recipient is residing on the different platform from the transaction actor's platform, the transaction should be followed by the envelope transfer from the actor's (sending) platform to the recipient's (receiving) platform. If the envelope transfer is caused by either `ENDO` `action` or `SACC` `action` transaction (where the recipient is on the different platform), the envelope transfer process is NOT causing transfer of possession of the eBL document, but is merely used as notification for the non-repudiation purposes.\n", - "enum" : [ - "ISSU", - "ENDO", - "TRNS", - "RESD", - "RESA", - "SACC", - "SREJ" - ], - "example" : "ISSU", - "type" : "string" - }, - "actor" : { - "$ref" : "#/components/schemas/TransactionParty" - }, - "comments" : { - "description" : "Free text comment for the party receiving the transaction.", - "example" : "The B/L has been issued.", - "maxLength" : 255, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "reason" : { - "description" : "A code defined by DCSA indicating the reason for `RESA` (Request to surrender for amendment). Possible values are: \n-\t`SWTP` (Switch to paper)\n\n**Condition:** on `action` being `RESA`\n", - "example" : "SWTP", - "maxLength" : 4, - "type" : "string" - }, - "recipient" : { - "$ref" : "#/components/schemas/TransactionParty" - }, - "timestamp" : { - "description" : "Unix epoch with millisecond precision of when the transaction was created.", - "example" : 1713342679531, - "format" : "int64", - "type" : "integer" - } - }, - "required" : [ - "action", - "actor", - "recipient", - "timestamp" - ], - "title" : "Transaction", - "type" : "object" - }, - "TransactionParty" : { - "description" : "Refers to a company or a legal entity.", - "properties" : { - "eblPlatform" : { - "description" : "The EBL platform of the transaction party. \nThe value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (TRACE Original)\n- `BRIT` (BRITC eBL)\n", - "example" : "BOLE", - "maxLength" : 4, - "pattern" : "^\\S+$", - "type" : "string" - }, - "identifyingCodes" : { - "items" : { - "$ref" : "#/components/schemas/IdentifyingCode" - }, - "type" : "array" - }, - "partyName" : { - "description" : "Name of the party.\n", - "example" : "Globeteam", - "maxLength" : 70, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "taxLegalReferences" : { - "description" : "A list of `Tax References` for a `Party`\n", - "items" : { - "$ref" : "#/components/schemas/TaxLegalReference" - }, - "type" : "array" - } - }, - "required" : [ - "eblPlatform", - "partyName" - ], - "title" : "Transaction Party", - "type" : "object" - }, - "TransportDocument" : { - "description" : "The receiving platform is required to validate the eBL document (a.k.a. transport document) by computing the SHA-256 checksum of the `transportDocument` attribute value, and confirming it's equal to received 'EblEnvelope.envelopeManifestSignedContent' JWS-signed payload [`EnvelopeManifest.transportDocumentChecksum`](#/EnvelopeManifest) attribute value.\n", - "properties" : { - "cargoMovementTypeAtDestination" : { - "description" : "Refers to the shipment term at the **unloading** of the cargo out of the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example" : "FCL", - "maxLength" : 3, - "type" : "string" - }, - "cargoMovementTypeAtOrigin" : { - "description" : "Refers to the shipment term at the **loading** of the cargo into the container. Possible values are:\n\n- `FCL` (Full Container Load)\n- `LCL` (Less than Container Load)\n", - "example" : "FCL", - "maxLength" : 3, - "type" : "string" - }, - "carrierClauses" : { - "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.\n", - "items" : { - "description" : "The content of the clause.\n", - "example" : "It is not allowed to...", - "maxLength" : 20000, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "type" : "array" - }, - "carrierCode" : { - "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.\n", - "example" : "MMCU", - "maxLength" : 4, - "pattern" : "^\\S+$", - "type" : "string" - }, - "carrierCodeListProvider" : { - "description" : "The code list provider for the `carrierCode`. Possible values are:\n- `SMDG` (Ship Message Design Group)\n- `NMFTA` (National Motor Freight Traffic Association)\n", - "enum" : [ - "SMDG", - "NMFTA" - ], - "example" : "NMFTA", - "type" : "string" - }, - "charges" : { - "description" : "A list of `Charges`\n", - "items" : { - "$ref" : "#/components/schemas/Charge" - }, - "type" : "array" - }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItem" - }, - "minItems" : 1, - "type" : "array" - }, - "contractQuotationReference" : { - "description" : "Information provided by the shipper to identify whether pricing for the shipment has been agreed via a contract or a quotation reference.\n", - "example" : "HHL1401", - "maxLength" : 35, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "declaredValue" : { - "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.\n\n**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).\n", - "example" : 1231.1, - "format" : "float", - "minimum" : 0, - "type" : "number" - }, - "declaredValueCurrency" : { - "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).\n", - "example" : "DKK", - "maxLength" : 3, - "minLength" : 3, - "pattern" : "^[A-Z]{3}$", - "type" : "string" - }, - "deliveryTypeAtDestination" : { - "description" : "Indicates the type of service offered at `Destination`. The options are:\n\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "enum" : [ - "CY", - "SD", - "CFS" - ], - "example" : "CY", - "maxLength" : 3, - "type" : "string" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "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`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "A line of the address to be displayed on the transport document.\n", - "example" : "Strawinskylaan 4117", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 5, - "type" : "array" - }, - "displayedShippedOnBoardReceivedForShipment" : { - "description" : "The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board.\n", - "example" : "Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier", - "maxLength" : 250, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "documentParties" : { - "$ref" : "#/components/schemas/DocumentParties" - }, - "freightPaymentTermCode" : { - "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).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", - "enum" : [ - "PRE", - "COL" - ], - "example" : "PRE", - "type" : "string" - }, - "invoicePayableAt" : { - "$ref" : "#/components/schemas/InvoicePayableAt" - }, - "isElectronic" : { - "description" : "An indicator whether the transport document is electronically transferred.\n", - "example" : true, - "type" : "boolean" - }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" - }, - "isToOrder" : { - "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`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n", - "example" : false, - "type" : "boolean" - }, - "issueDate" : { - "description" : "Local date when the transport document has been issued.\n\nCan be omitted on draft transport documents, but must be provided when the document has been issued.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "numberOfCopiesWithCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfCopiesWithoutCharges" : { - "description" : "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfOriginalsWithoutCharges" : { - "description" : "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n", - "example" : 1, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "numberOfRiderPages" : { - "description" : "The number of additional pages required to contain the goods description on a transport document. Only applicable for physical transport documents.\n", - "example" : 2, - "format" : "int32", - "minimum" : 0, - "type" : "integer" - }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", - "items" : { - "$ref" : "#/components/schemas/PartyContactDetail" - }, - "minItems" : 1, - "type" : "array" - }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/PlaceOfIssue" - }, - "receiptTypeAtOrigin" : { - "description" : "Indicates the type of service offered at `Origin`. The options are:\n- `CY` (Container yard (incl. rail ramp))\n- `SD` (Store Door)\n- `CFS` (Container Freight Station)\n", - "enum" : [ - "CY", - "SD", - "CFS" - ], - "example" : "CY", - "maxLength" : 3, - "type" : "string" - }, - "receivedForShipmentDate" : { - "description" : "Date when the last container linked to the transport document is physically in the terminal (customers cleared against the intended vessel).\n\nWhen provided on a transport document, the transportDocument is a `Received For Shipment` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "routingOfConsignmentCountries" : { - "description" : "A list of countries the goods will be routed through from origin to destination defined by the 2 characters country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", - "example" : "NL", - "maxLength" : 2, - "minLength" : 2, - "pattern" : "^[A-Z]{2}$", - "type" : "string" - }, - "type" : "array" - }, - "serviceContractReference" : { - "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.\n", - "example" : "HHL51800000", - "maxLength" : 30, - "type" : "string" - }, - "shippedOnBoardDate" : { - "description" : "Date when the last container that is linked to the transport document is physically loaded onboard the vessel indicated on the transport document.\n\nWhen provided on a transport document, the transportDocument is a `Shipped On Board` B/L.\n\nExactly one of `shippedOnBoard` and `receiveForShipmentDate` must be provided on an issued B/L.\n", - "example" : "2020-12-12", - "format" : "date", - "type" : "string" - }, - "shippingInstructionsReference" : { - "description" : "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n", - "example" : "e0559d83-00e2-438e-afd9-fdd610c1a008", - "maxLength" : 100, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "termsAndConditions" : { - "description" : "Carrier terms and conditions of transport.\n", - "example" : "Any reference in...", - "maxLength" : 50000, - "type" : "string" - }, - "transportDocumentReference" : { - "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.\n", - "example" : "HHL71800000", - "maxLength" : 20, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "transportDocumentStatus" : { - "description" : "The status of the `Transport Document`. Possible values are:\n- DRAFT\n- APPROVED\n- ISSUED\n- PENDING_SURRENDER_FOR_AMENDMENT\n- SURRENDERED_FOR_AMENDMENT\n- PENDING_SURRENDER_FOR_DELIVERY\n- SURRENDERED_FOR_DELIVERY\n- VOIDED\n", - "example" : "DRAFT", - "maxLength" : 50, - "type" : "string" - }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", - "enum" : [ - "BOL", - "SWB" - ], - "example" : "SWB", - "type" : "string" - }, - "transports" : { - "$ref" : "#/components/schemas/Transports" - }, - "utilizedTransportEquipments" : { - "description" : "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items" : { - "$ref" : "#/components/schemas/UtilizedTransportEquipment" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "cargoMovementTypeAtDestination", - "cargoMovementTypeAtOrigin", - "carrierCode", - "carrierCodeListProvider", - "consignmentItems", - "deliveryTypeAtDestination", - "documentParties", - "invoicePayableAt", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "receiptTypeAtOrigin", - "termsAndConditions", - "transportDocumentReference", - "transportDocumentStatus", - "transportDocumentTypeCode", - "transports", - "utilizedTransportEquipments" - ], - "title" : "Transport Document", - "type" : "object" - }, - "Transports" : { - "properties" : { - "onCarriageBy" : { - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example" : "TRUCK", - "maxLength" : 50, - "type" : "string" - }, - "onwardInlandRouting" : { - "$ref" : "#/components/schemas/OnwardInlandRouting" - }, - "placeOfDelivery" : { - "$ref" : "#/components/schemas/PlaceOfDelivery" - }, - "placeOfReceipt" : { - "$ref" : "#/components/schemas/PlaceOfReceipt" - }, - "plannedArrivalDate" : { - "description" : "The planned date of arrival.\n", - "example" : "2024-06-07", - "format" : "date", - "type" : "string" - }, - "plannedDepartureDate" : { - "description" : "The planned date of departure.\n", - "example" : "2024-06-03", - "format" : "date", - "type" : "string" - }, - "portOfDischarge" : { - "$ref" : "#/components/schemas/PortOfDischarge" - }, - "portOfLoading" : { - "$ref" : "#/components/schemas/PortOfLoading" - }, - "preCarriageBy" : { - "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:\n- `VESSEL` (Vessel)\n- `RAIL` (Rail)\n- `TRUCK` (Truck)\n- `BARGE` (Barge)\n- `MULTIMODAL` (if multiple modes are used)\n", - "example" : "RAIL", - "maxLength" : 50, - "type" : "string" - }, - "vesselVoyages" : { - "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.\n", - "items" : { - "$ref" : "#/components/schemas/VesselVoyage" - }, - "minItems" : 1, - "type" : "array" - } - }, - "required" : [ - "plannedArrivalDate", - "plannedDepartureDate", - "portOfDischarge", - "portOfLoading", - "vesselVoyages" - ], - "title" : "Transports", - "type" : "object" - }, - "UtilizedTransportEquipment" : { - "description" : "Specifies the container (`equipment`), the total `weight`, total `volume`, possible `ActiveReeferSettings`, `seals` and `references`\n", - "properties" : { - "activeReeferSettings" : { - "$ref" : "#/components/schemas/ActiveReeferSettings" - }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" - }, - "equipment" : { - "$ref" : "#/components/schemas/Equipment" - }, - "isNonOperatingReefer" : { - "description" : "If the equipment is a Reefer Container then setting this attribute will indicate that the container should be treated as a `DRY` container.\n\n**Condition:** Only applicable if `ISOEquipmentCode` shows a Reefer type.\n", - "example" : false, - "type" : "boolean" - }, - "isShipperOwned" : { - "description" : "Indicates whether the container is shipper owned (SOC).\n", - "example" : true, - "type" : "boolean" - }, - "references" : { - "description" : "A list of `References`\n", - "items" : { - "$ref" : "#/components/schemas/Reference" - }, - "type" : "array" - }, - "seals" : { - "description" : "A list of `Seals`\n", - "items" : { - "$ref" : "#/components/schemas/Seal" - }, - "minItems" : 1, - "type" : "array" - }, - "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", - "items" : { - "description" : "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n", - "example" : "Made in China", - "maxLength" : 35, - "type" : "string" - }, - "maxItems" : 50, - "type" : "array" - } - }, - "required" : [ - "equipment", - "isShipperOwned", - "seals" - ], - "title" : "Utilized Transport Equipment", - "type" : "object" - }, - "VesselVoyage" : { - "description" : "Vessel and export voyage", - "properties" : { - "carrierExportVoyageNumber" : { - "description" : "The identifier of an export voyage. The carrier-specific identifier of the export Voyage.\n", - "example" : "2103S", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - }, - "universalExportVoyageReference" : { - "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]`\n- `2 digits` for the year\n- `2 alphanumeric characters` for the sequence number of the voyage\n- `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).\n", - "example" : "2103N", - "maxLength" : 5, - "minLength" : 5, - "pattern" : "^\\d{2}[0-9A-Z]{2}[NEWSR]$", - "type" : "string" - }, - "vesselName" : { - "description" : "The name of the first sea going Vessel on board which the cargo is loaded or intended to be loaded\n", - "example" : "King of the Seas", - "maxLength" : 50, - "pattern" : "^\\S(?:.*\\S)?$", - "type" : "string" - } - }, - "required" : [ - "carrierExportVoyageNumber", - "vesselName" - ], - "title" : "Vessel/Voyage", - "type" : "object" - } - } - }, - "info" : { - "contact" : { - "email" : "info@dcsa.org", - "name" : "Digital Container Shipping Association (DCSA)", - "url" : "https://dcsa.org" - }, - "description" : "

DCSA OpenAPI specification for electronic Bill of Lading (eBL) Platform Interoperability (PINT)

\n\n

The Envelope Transfer

\n\nThe PINT API is designed to support transfer of eBL documents with non-repudiation and any number of additional documents between two eBL platforms. \n\nIn the most common scenario, the sending eBL platform executes the envelope transfer by:\n0. Optionally, using the [**'Receiver Validation'**](#/Receiver%20validation/post-receiver-validation) endpoint to allow the sending user to validate the identity of the receiver, before they transfer the eBL.\n1. Initiating the envelope transfer using [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint\n2. Transferring the additional documents (one at the time) using [**'Transfer additional document'**](#/Transfer%20additional%20document) endpoint\n3. Completing the envelope transfer using [**'Finish envelope transfer'**](#/Finish%20envelope%20transfer) endpoint\n\n

The eBL document

\n\nThe envelope transfer from the sending eBL Platform to the receiving eBL Platform always contains the **eBL document** (transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request body [`EblEnvelope.transportDocument`](#/EblEnvelope) schema object). The eBL document must be unchanged between different envelope transfers for the lifetime of the eBL document. \n\nThe PINT API is designed to support transfer of the following types of eBL documents:\n1. Straight eBL documents. This type of eBL document is defined by [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `false`\n2. Blank-endorsed eBL documents. This type of eBL document is created by setting [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentparties[]`](#/EblEnvelope) list does not contain document party where `DocumentParty.partyFunction` has value `END` (Endorsee)\n3. To-order/Negotiable eBL documents. This type of eBL document is created by setting the [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentparties[]`](#/EblEnvelope) list contains document party where `DocumentParty.partyFunction` has value `END` (Endorsee). If the current endorsee party is also in possession of the eBL (possessor), this party can endorse some other party on the same eBL Platform (and make that other party new endorsee) by executing transaction with [`Transaction.action`](#/Transaction) type `ENDO` (Endorsement). The DCSA PINT API support To-order/Negotiable documents, however, given that not all of the eBL solution providers support the split between possession and endorsements, this doesn't apply yet to interoperable eBL\n\n

The Additional Documents

\n\nThe envelope transfer can optionally contain one or more **additional documents** which can be transferred via [**'Transfer additional document'**](#/Transfer%20additional%20document) endpoint:\n- **'Digital copy of the original physical B/L document' document** (described via [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) schema object that has been previously transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint as JWS-signed payload of [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) schema object) a.k.a. **eBLVisualisationByCarrier document**. If transferred with the initial eBL envelope transfer, eBLVisualisationByCarrier document must be transferred with every subsequent envelope transfer for the lifetime of the eBL document. Also, eBLVisualisationByCarrier document must be unchanged between different envelope transfers for the lifetime of the eBL document.\n- **Supporting document** (described via entry in the [`EnvelopeManifest.supportingDocuments[]`](#/EnvelopeManifest) list object that has been previously transferred via [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint as JWS-signed payload of [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) schema object). For every envelope transfer, the sending platform can choose which supporting documents it wants to send to the receiving platform irrespective of the contents of the previously received envelope transfer. All details of the supporting documents transferred from sending to receiving platform as a part of the envelope transfer are only privy to these 2 platforms.\n\n

Non-repudiation

\n\nWhen receiving [**'Start envelope transfer'**](#/Start%20envelope%20transfer) endpoint request, the receiving platform should confirm the integrity of the received [`EblEnvelope`](#/EblEnvelope) schema object for non-repudiation purposes. Since it has been decided not to use JWS for signing of [`EblEnvelope`](#/EblEnvelope) (for network traffic optimization purposes) itself, the receiving platform can confirm the integrity of the envelope data by confirming integrity of the [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) JWS-signed payload [`EnvelopeManifest`](#/EnvelopeManifest), and then use contents of [`EnvelopeManifest`](#/EnvelopeManifest) schema object to confirm the integrity of the other [`EblEnvelope`](#/EblEnvelope) schema object attributes (further details can be found in the description of [`EblEnvelope`](#/EblEnvelope) schema attributes).\n\nAt various stages during the envelope transfer process, the receiving platform can inform the sending platform whether envelope transfer has been accepted or rejected by sending the final response using the [`EnvelopeTransferFinishedResponse`](#/EnvelopeTransferFinishedResponse) schema object which has been wrapped in JWS-signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) schema object for non-repudiation purposes. All other response schema types are unsigned, and therefore they can not be used by the sending platform for the non-repudiation purposes.\n\n### API Design & Implementation Principles\nThis API follows the guidelines defined in version 2.1 of the API Design & Implementation Principles which can be found on the [DCSA Developer page](https://developer.dcsa.org/api_design)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/pint/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n\nAPI specification issued by [DCSA.org](https://dcsa.org/).\n", - "license" : { - "name" : "Apache 2.0", - "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "title" : "DCSA eBL Platform Interoperability API", - "version" : "3.0.0" - }, - "openapi" : "3.0.3", - "paths" : { - "/v3/envelopes" : { - "post" : { - "description" : "Start the eBL envelope transfer.\n", - "operationId" : "post-envelopes", - "parameters" : [ - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EblEnvelope" - } - } - }, - "required" : true - }, - "responses" : { - "200" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform either accepts the envelope transfer immediately (if there are no additional documents to be transferred, or if it concludes that it is already in the possession of all the additional documents mentioned in the [`EnvelopeManifest`](#/EnvelopeManifest)), or concludes that in has previously accepted the envelope transfer with the same contents.\n\nThe signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) that signals the accepted envelope transfer (`RECE` or `DUPE`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "201" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferStartedResponse" - } - } - }, - "description" : "The Receiving platform acknowledges that the envelope transfer is now active for this envelope transfer request.\n\nThe sending platform should transfer all supporting documents listed in the [`EblEnvelope.envelopeManifestSignedContent`](#/EblEnvelope) JWS-signed payload [`EnvelopeManifest.supportingDocuments`](#/EnvelopeManifest) list, as well as eBLVisualisationByCarrier document if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined, prior to sending request to finish the envelope transfer.\n\nIf the sending platform attempts to start a new envelope transfer for an eBL that already has the active envelope transfer that is not yet completed, the receiving platform should assume that the sending platform is retrying the envelope transfer. The receiving platform should assume that the sending platform is aware that the previous envelope transfer failed or that the sending platform is not aware that the previous envelope transfer started.\n\nThe [`EnvelopeTransferStartedResponse`](#/EnvelopeTransferStartedResponse) response is unsigned. The sending platform is required to finish the envelope transfer via [**'Finish envelope transfer'**](#/Finish%20envelope%20transfer) endpoint in order to get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload `EnvelopeTransferFinishedResponse` carrying the information whether the receiving platform has accepted or rejected the envelope transfer.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "422" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "Receiving platform rejects the envelope transfer.\n\nThe signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "Request failed for the unexpected reason. The unsigned response contains all the error details.\n\nThe sending platform is required to retry the envelope transfer until they get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. \n\nIn the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Start the eBL envelope transfer", - "tags" : [ - "Start envelope transfer" - ] - } - }, - "/v3/envelopes/{envelopeReference}/additional-documents/{documentChecksum}" : { - "put" : { - "description" : "Transfer **additional document** associated with an eBL envelope transfer. The transferred document should be either one of the **supporting documents** from the [`EnvelopeManifest.supportingDocuments`](#/EnvelopeManifest) list, or **eBLVisualisationByCarrier document** if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined.\n\nThe `requestBody` should contain the document being transferred. It is recommended to use the `application/json` media type for the `requestBody`. The media type provided in the initial `ISSU` (Issuance) transaction is the one that will be associated with the transferred additional document in the end.\n\nThe receiving platform should check that the transferred document has been declared at the start of the eBL envelope transfer.\nThis should be done by verifying that the `documentChecksum` URL path parameter matches either [`EnvelopeManifest.eBLVisualisationByCarrier.documentChecksum`](#/EnvelopeManifest) attribute value (in which case the receiving platform can conclude that the sending platform has transferred the **eBLVisualisationByCarrier document**), or one of the [`DocumentMetadata.documentChecksum`](#/DocumentMetadata) values from the [`EnvelopeManifest.supportingDocuments[]`](#/EnvelopeManifest) list (in which case the receiving platform can conclude that the sending platform has transferred the **supporting document**)\n \nFurthermore, the receiving platform should compute the SHA-256 checksum of the transferred additional document, and verify that it matches the value of `documentChecksum` URL path parameter. The SHA-256 checksum MUST be calculated based on the deserialized payload.\n\nIf all the above mentioned verifications have been successfully, the receiving platform can conclude that the additional document was transferred successfully.\n", - "operationId" : "put-additional-documents", - "parameters" : [ - { - "description" : "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "explode" : false, - "in" : "path", - "name" : "envelopeReference", - "required" : true, - "schema" : { - "example" : "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU", - "maxLength" : 100, - "type" : "string" - }, - "style" : "simple" - }, - { - "description" : "The checksum of the document computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).", - "explode" : false, - "in" : "path", - "name" : "documentChecksum", - "required" : true, - "schema" : { - "example" : "7d00064ed0b90467ff7aff6032d8e2d94845745b6590895cd95708d2ee4243d8", - "maxLength" : 64, - "minLength" : 64, - "pattern" : "^[0-9a-f]+$", - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "description" : "A Base64 encoded payload containing the file to transfer.\n", - "example" : "UmF3IGNvbnRlbnQgb2YgdGhlIGZpbGUgYmVpbmcgdHJhbnNmZXJyZWQ=", - "format" : "byte", - "type" : "string" - } - } - }, - "required" : true - }, - "responses" : { - "204" : { - "description" : "The receiving platform acknowledges that the additional document was transferred successfully.\n\nIf the envelope transfer eventually gets accepted,the receiving platform will acknowledge the additional document transfer with a JWS-signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) containing JWS-signed payload [`EnvelopeTransferFinishedResponse.receivedAdditionalDocumentChecksums[]`](#/EnvelopeTransferFinishedResponse) list containing the additional document checksum. Therefore, this is unsigned response.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform has discovered conflict between the request and the current state of the envelope transfer.\nE.g. the checksum or the size of the transferred additional document does not match the data provided in the URL path or in the request at the start of the envelope transfer.\n\nThe signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the issue with the envelope transfer that does *not* reject the envelope transfer (`INCD`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "422" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform rejects the envelope transfer.\n\nThe signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "Request failed for the unexpected reason. The unsigned response contains all the error details.\n\nThe sending platform is required to retry the additional document transfer until they get a signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. \n\nIn the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Transfer additional document associated with the eBL envelope transfer", - "tags" : [ - "Transfer additional document" - ] - } - }, - "/v3/envelopes/{envelopeReference}/finish-transfer" : { - "put" : { - "description" : "Finish the eBL envelope transfer.\n\nThe sending platform believes all additional documents have been transferred and the envelope transfer can now be completed. \n\nPrior to accepting envelope transfer, the receiving platform should ensure that all supporting documents listed in the [`EnvelopeManifest.supportingDocument`](#/EnvelopeManifest) list have been successfully transferred, as well as eBLVisualisationByCarrier document if attribute [`EnvelopeManifest.eBLVisualisationByCarrier`](#/EnvelopeManifest) was defined. Otherwise, The receiving platform should reject the envelope transfer.\n", - "operationId" : "put-finish-transfer", - "parameters" : [ - { - "description" : "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "explode" : false, - "in" : "path", - "name" : "envelopeReference", - "required" : true, - "schema" : { - "example" : "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU", - "maxLength" : 100, - "type" : "string" - }, - "style" : "simple" - }, - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "responses" : { - "200" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform accepts the envelope transfer.\n\nThe signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the accepted envelope transfer (`RECE` or `DUPE`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "409" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform has discovered conflict between the request and the current state of the envelope transfer.\n\nThe signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the issue with the envelope transfer that does *not* reject the envelope transfer (`DISE` or `MDOC`).\n\nIn the case of `MDOC` [`responseCode`](#/EnvelopeTransferFinishedResponse), the receiving platform cannot accept the envelope transfer due to one or more missing additional documents. In this case, the sending platform should (re)send the missing documents (provided in [`EnvelopeTransferFinishedResponse.missingAdditionalDocumentChecksums[]`](#/EnvelopeTransferFinishedResponse) list) and then retry to finish the envelope transfer.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "422" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - }, - "description" : "The Receiving platform rejects the envelope transfer.\n\nThe signed response `EnvelopeTransferFinishedResponseSignedContent` JWS-signed payload must contain [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value that signals the rejected envelope transfer (`BENV` or `BSIG`).\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "Request failed for the unexpected reason. The unsigned response contains all the error details.\n\nThe sending platform should retry to finish the envelope transfer until it gets the signed response [`EnvelopeTransferFinishedResponseSignedContent`](#/EnvelopeTransferFinishedResponseSignedContent) with the JWS-signed payload [`EnvelopeTransferFinishedResponse.responseCode`](#/EnvelopeTransferFinishedResponse) attribute value providing the information whether the receiving platform has accepted or rejected the envelope transfer. \n\nIn the rare corner cases, the unsigned `error` response could come from middleware and hide a true envelope transfer acceptance/rejection message. The sending platform will be liable if they act on an unsigned response that does *not* match the actions of the receiving platform.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Finish the eBL envelope transfer", - "tags" : [ - "Finish envelope transfer" - ] - } - }, - "/v3/receiver-validation" : { - "post" : { - "description" : "Request the name of a party given a party code. This enables the sending user to validate\nthe receiver information (similar how bank transfers enable users to conform the receiver\nbefore confirming the transfer).\n\nA successful response to this query asserts that the platform will accept an eBL for the\naccount or user denoted by the provided identifying code and that said account or user\nis \"active and able to accept interoperable eBLs\" as defined by the platform hosting\nthe account or user.\n\nThe transfer can still be rejected due to an unknown user if the transfer has\nmultiple conflicting identifying codes. Platforms that supports using multiple identifying\ncodes when transferring an eBL will need to consider how they ensure they do not by accident\ninclude conflicting codes.\n", - "operationId" : "post-receiver-validation", - "parameters" : [ - { - "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.\n", - "explode" : false, - "in" : "header", - "name" : "API-Version", - "required" : false, - "schema" : { - "example" : "3", - "type" : "string" - }, - "style" : "simple" - } - ], - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/IdentifyingCode" - } - } - }, - "required" : true - }, - "responses" : { - "200" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ReceiverValidationResponse" - } - } - }, - "description" : "On a successful match, this response includes the relevant information that should be displayed to the user\nto help them assert they have the correct party.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "404" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "If the server cannot identify an account or user via the given party code, then it should use this\nresponse code. This response is also applicable if the query matches multiple distinct accounts or\nwhen the platform would reject a transfer request to said account or user.\n\nNote this code is also used, if the client is using a code list provider that the server cannot\n(or will not) support. As an example, platforms are not required to support codes issued by\nother eBL platforms and can unconditionally reject lookup requests for them with this response.\n\nThe response is deliberately vague on negative results to limit data exposure by default. The\nserver may at its discretion include more details about the underlying issue in the response\nbody.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - }, - "default" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ErrorResponse" - } - } - }, - "description" : "Request failed for the unexpected reason. The unsigned response contains all the error details.\n", - "headers" : { - "API-Version" : { - "$ref" : "#/components/headers/API-Version" - } - } - } - }, - "summary" : "Enable a user to validate the receiver", - "tags" : [ - "Receiver validation" - ] - } - } - }, - "servers" : [ - { - "description" : "SwaggerHub API Auto Mocking", - "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_PINT/3.0.0" - } - ], - "tags" : [ - { - "description" : "Receiver validation", - "name" : "Receiver validation" - }, - { - "description" : "Start envelope transfer", - "name" : "Start envelope transfer" - }, - { - "description" : "Transfer additional document", - "name" : "Transfer additional document" - }, - { - "description" : "Finish envelope transfer", - "name" : "Finish envelope transfer" - } - ] -} diff --git a/spring-boot/src/test/java/org/dcsa/conformance/frontend/SeleniumTest.java b/spring-boot/src/test/java/org/dcsa/conformance/frontend/SeleniumTest.java index 21f9741e..55323042 100644 --- a/spring-boot/src/test/java/org/dcsa/conformance/frontend/SeleniumTest.java +++ b/spring-boot/src/test/java/org/dcsa/conformance/frontend/SeleniumTest.java @@ -13,7 +13,6 @@ import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.ValueSource; import org.openqa.selenium.By; -import org.openqa.selenium.WebElement; import org.springframework.boot.test.context.SpringBootTest; @Slf4j @@ -25,9 +24,9 @@ class SeleniumTest extends SeleniumTestBase { void testLoginAndCreateSandboxStart() { loginUser(); driver.get(baseUrl); + wait.until(webDriver -> webDriver.findElement(By.id("create_sandbox_button"))); assertEquals(baseUrl + "/environment", driver.getCurrentUrl()); - WebElement createSandbox = driver.findElement(By.id("create_sandbox_button")); - createSandbox.click(); + driver.findElement(By.id("create_sandbox_button")).click(); waitForUIReadiness(); assertEquals("Create sandbox", driver.findElement(By.className("pageTitle")).getText()); diff --git a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/TntComponentFactory.java b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/TntComponentFactory.java index e42e313e..2f58b134 100644 --- a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/TntComponentFactory.java +++ b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/TntComponentFactory.java @@ -99,7 +99,7 @@ public Set getReportRoleNames( } public Map getEventSchemaValidators() { - String schemaFilePath = "/standards/tnt/schemas/tnt-220-publisher.json"; + String schemaFilePath = "/standards/tnt/schemas/TNT_v2.2.0-resolved.yaml"; return Map.ofEntries( Map.entry( TntEventType.EQUIPMENT, diff --git a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/AttributeMapping.java b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/AttributeMapping.java index b81c6b5b..38a20037 100644 --- a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/AttributeMapping.java +++ b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/AttributeMapping.java @@ -134,7 +134,7 @@ private static void addCarrierBookingReferenceMappings(Map !node.isMissingNode() - && node.path("documentTypeCode").asText().equals("BKG") && node.path("documentID").asText().equals(value), + && node.path(DOCUMENT_TYPE_CODE).asText().equals("BKG") && node.path("documentID").asText().equals(value), Set.of()))); } diff --git a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/QueryParameterSpecificRule.java b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/QueryParameterSpecificRule.java index b00051f8..9898c71e 100644 --- a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/QueryParameterSpecificRule.java +++ b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/QueryParameterSpecificRule.java @@ -1,18 +1,17 @@ package org.dcsa.conformance.standards.tnt.party; +import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_DOCUMENT_TYPE_CODES; +import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_EQUIPMENT_EVENT_TYPES; +import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_EVENT_TYPES; +import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_SHIPMENT_EVENT_TYPES; + import java.util.Arrays; import java.util.Collection; -import java.util.HashSet; import java.util.Map; import java.util.Set; import java.util.function.Predicate; import java.util.stream.Collectors; -import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_DOCUMENT_TYPE_CODES; -import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_EQUIPMENT_EVENT_TYPES; -import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_EVENT_TYPES; -import static org.dcsa.conformance.standards.tnt.checks.TntDataSets.VALID_SHIPMENT_EVENT_TYPES; - public class QueryParameterSpecificRule implements QueryParamRule{ private static final String EVENT_TYPE = "eventType"; @@ -25,7 +24,7 @@ public class QueryParameterSpecificRule implements QueryParamRule{ "EQUIPMENT", Set.of("carrierBookingReference", "transportDocumentReference", "transportCallID", "vesselIMONumber", "exportVoyageNumber", "carrierServiceCode", "UNLocationCode", "equipmentEventTypeCode", "equipmentReference", "eventCreatedDateTime") ); - private static final Set excludedQueryParams = Set.of("eventType", "cursor", "limit", "eventCreatedDateTime:gte", + private static final Set excludedQueryParams = Set.of(EVENT_TYPE, "cursor", "limit", "eventCreatedDateTime:gte", "eventCreatedDateTime:gt", "eventCreatedDateTime:lt", "eventCreatedDateTime:lte", "eventCreatedDateTime:eq", "eventCreatedDateTime"); @Override diff --git a/tnt/src/main/resources/standards/tnt/schemas/TNT_v2.2.0-resolved.yaml b/tnt/src/main/resources/standards/tnt/schemas/TNT_v2.2.0-resolved.yaml new file mode 100644 index 00000000..2aa8e465 --- /dev/null +++ b/tnt/src/main/resources/standards/tnt/schemas/TNT_v2.2.0-resolved.yaml @@ -0,0 +1,2613 @@ +openapi: 3.0.3 +info: + title: DCSA OpenAPI specification for Track & Trace + description: | + Managing and sending Shipment-, Transport- and Equipment-events and subscriptions for Track & Trace (T&T). API specification issued by DCSA.org. + + For explanation to specific values or objects please refer to the Information Model v3.3 + + Polling can be done on the GET /v2/events endPoint. It is also possible to setup a subscription on the /v2/event-subscriptions endPoints in order to use the push model. Here events are pushed as they occur. + + For a changelog please click here + contact: + name: Digital Container Shipping Association (DCSA) + url: https://dcsa.org + email: info@dcsa.org + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + version: 2.2.0 +servers: +- url: / +tags: +- name: Events + description: Event operations +- name: Subscriptions + description: Subscription operations +- name: Secret + description: Update secret +paths: + /v2/events: + get: + tags: + - Events + summary: Find events. + description: | + Returns all events filtered by the queryParameters. + + NB: It is possible to combine queryParameters. When combining queryParameters be aware that it is also possible to make combinations that are mutual contradicting. + + Example: shipmentEventTypeCode=DRFT and equipmentEventTypeCode=GTIN + + Since there is no event that can be a ShipmentEvent and an EquipmentEvent at the same time this will return an empty list! + parameters: + - name: eventType + in: query + description: | + The type of event(s) to filter by. Possible values are + + - SHIPMENT (Shipment events) + - TRANSPORT (Transport events) + - EQUIPMENT (Equipment events) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example eventType=SHIPMENT,EQUIPMENT matches both Shipment- and Equipment-events. + + Default value is all event types. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - SHIPMENT + - TRANSPORT + - EQUIPMENT + - name: shipmentEventTypeCode + in: query + description: | + The status of the document in the process to filter by. Possible values are + - RECE (Received) + - DRFT (Drafted) + - PENA (Pending Approval) + - PENU (Pending Update) + - REJE (Rejected) + - APPR (Approved) + - ISSU (Issued) + - SURR (Surrendered) + - SUBM (Submitted) + - VOID (Void) + - CONF (Confirmed) + - REQS (Requested) + - CMPL (Completed) + - HOLD (On Hold) + - RELS (Released) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example shipmentEventTypeCode=RECE,DRFT Matches both Received (RECE) and Drafted (DRFT) shipment events. + + Default is all shipmentEventTypeCodes. + + This filter is only relevant when filtering on ShipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/shipmentEventTypeCode' + default: "RECE,DRFT,PENA,PENU,REJE,APPR,ISSU,SURR,SUBM,VOID,CONF,REQS,CMPL,HOLD,RELS" + example: "RECE,DRFT" + - name: documentTypeCode + in: query + description: | + The documentTypeCode to filter by. Possible values are + - CBR (Carrier Booking Request Reference) + - BKG (Booking) + - SHI (Shipping Instruction) + - SRM (Shipment Release Message) + - TRD (Transport Document) + - ARN (Arrival Notice) + - VGM (Verified Gross Mass) + - CAS (Cargo Survey) + - CUS (Customs Inspection) + - DGD (Dangerous Goods Declaration) + - OOG (Out of Gauge) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example documentTypeCode=SHI,TRD Matches both ShippingInstruction (SHI) and TransportDocument (TRD) shipment events. + + Default is all documentTypeCodes. + + This filter is only relevant when filtering on ShipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/documentTypeCode' + default: "CBR,BKG,SHI,SRM,TRD,ARN,VGM,CAS,CUS,DGD,OOG" + example: "SHI,TRD" + - name: carrierBookingReference + in: query + description: | + A set of unique characters provided by carrier to identify a booking. + + Specifying this filter will only return events related to this particular carrierBookingReference. + schema: + $ref: '#/components/schemas/carrierBookingReference' + - name: bookingReference + in: query + description: Deprecated - use carrierBookingReference instead. + required: false + deprecated: true + schema: + type: string + - name: transportDocumentID + in: query + description: | + A unique id to identify a transport document. + + Deprecated - use transportDocumentReference instead transportDocumentReference + deprecated: true + schema: + type: string + format: uuid + - name: transportDocumentReference + in: query + description: | + A unique number reference allocated by the shipping line to the transport document and the main number used for the tracking of the status of the shipment. + + Specifying this filter will only return events related to this particular transportDocumentReference + required: false + schema: + $ref: '#/components/schemas/transportDocumentReference' + - name: transportEventTypeCode + in: query + description: | + Identifier for type of Transport event to filter by + - ARRI (Arrived) + - DEPA (Departed) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example transportEventTypeCode=ARRI,DEPA matches both Arrived (ARRI) and Departed (DEPA) transport events. + + Default is all transportEventTypeCodes. + + This filter is only relevant when filtering on TransportEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/transportEventTypeCode' + default: "ARRI,DEPA" + example: "ARRI,DEPA" + - name: scheduleID + in: query + description: | + ID uniquely identifying a schedule, to filter events by. + + This filter was added by mistake and is thus deprecated. + required: false + deprecated: true + schema: + $ref: '#/components/schemas/scheduleID' + - name: transportCallID + in: query + description: | + ID uniquely identifying a transport call, to filter events by. + + Specifying this filter will only return events related to this particular transportCallID + required: false + schema: + $ref: '#/components/schemas/transportCallID' + - name: vesselIMONumber + in: query + description: | + The identifier of vessel for which schedule details are published. Depending on schedule type, this may not be available yet. + + Specifying this filter will only return events related to this particular vesselIMONumber. + required: false + schema: + $ref: '#/components/schemas/vesselIMONumber' + - name: carrierVoyageNumber + in: query + description: | + Filter on the vessel operator-specific identifier of the Voyage. + + Specifying this filter will only return events related to this particular carrierVoyageNumber. + + Deprecated: Use exportVoyageNumber instead + required: false + deprecated: true + schema: + $ref: '#/components/schemas/carrierVoyageNumber' + - name: exportVoyageNumber + in: query + description: | + Filter on the vessel operator-specific identifier of the export Voyage. + + Specifying this filter will only return events related to this particular exportVoyageNumber. + required: false + schema: + $ref: '#/components/schemas/exportVoyageNumber' + - name: carrierServiceCode + in: query + description: | + Filter on the carrier specific identifier of the service. + + Specifying this filter will only return events related to this particular carrierServiceCode. + required: false + schema: + $ref: '#/components/schemas/carrierServiceCode' + - name: UNLocationCode + in: query + description: | + The UN Location code specifying where the place is located. + + Specifying this filter will only return events related to this particular UN Location code. + required: false + schema: + $ref: '#/components/schemas/UNLocationCode' + - name: equipmentEventTypeCode + in: query + description: | + Unique identifier for equipmentEventTypeCode. + - LOAD (Loaded) + - DISC (Discharged) + - GTIN (Gated in) + - GTOT (Gated out) + - STUF (Stuffed) + - STRP (Stripped) + - PICK (Pick-up) + - DROP (Drop-off) + - INSP (Inspected) + - RSEA (Resealed) + - RMVD (Removed) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example equipmentEventTypeCode=GTIN,GTOT matches both Gated in (GTIN) and Gated out (GTOT) equipment events. + + Default is all equipmentEventTypeCodes. + + This filter is only relevant when filtering on EquipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/equipmentEventTypeCode' + default: "LOAD,DISC,GTIN,GTOT,STUF,STRP,PICK,DROP,INSP,RSEA,RMVD" + example: "GTIN,GTOT" + - name: equipmentReference + in: query + description: | + Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + Specifying this filter will only return events related to this particular equipmentReference + required: false + schema: + $ref: '#/components/schemas/equipmentReference' + - name: eventCreatedDateTime + in: query + description: | + Limit the result based on the creating date of the event. It is possible to use operators on this query parameter. This is done by adding a colon followed by an operator at the end of the queryParameterName (before the =) + + eventCreatedDateTime:gte=2021-04-01T14:12:56+01:00 + + would result in all events created ≥ 2021-04-01T14:12:56+01:00 + + The following operators are supported + - :gte (≥ Greater than or equal) + - :gt (> Greater than) + - :lte (≤ Less than or equal) + - :lt (< Less than) + - :eq (= Equal to) + + If no operator is provided, a strictly equal is used (this is equivalent to :eq operator). + required: false + schema: + $ref: '#/components/schemas/eventCreatedDateTime' + example: 2021-04-01T14:12:56+01:00 + - name: limit + in: query + description: Maximum number of items to return. + required: false + schema: + minimum: 1 + type: integer + format: int32 + default: 100 + example: 100 + - name: cursor + in: query + description: "A server generated value to specify a specific point in a collection result, used for pagination." + required: false + schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA= + - name: sort + in: query + description: | + A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used. + required: false + schema: + type: string + example: carrierBookingReference:DESC + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + responses: + "200": + description: Successful operation + headers: + API-Version: + $ref: '#/components/headers/API-Version' + Current-Page: + $ref: '#/components/headers/Current-Page' + Next-Page: + $ref: '#/components/headers/Next-Page' + Prev-Page: + $ref: '#/components/headers/Prev-Page' + Last-Page: + $ref: '#/components/headers/Last-Page' + First-Page: + $ref: '#/components/headers/First-Page' + content: + application/json: + schema: + type: array + items: + anyOf: + - $ref: '#/components/schemas/transportEvent' + - $ref: '#/components/schemas/shipmentEvent' + - $ref: '#/components/schemas/equipmentEvent' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default' + /v2/events/{eventID}: + get: + tags: + - Events + summary: Find events by eventID. + description: Returns event with the specified eventID. + parameters: + - name: eventID + in: path + description: The ID of the event to receive + required: true + deprecated: true + schema: + $ref: '#/components/schemas/eventID' + example: 123e4567-e89b-12d3-a456-426614174000 + responses: + "200": + description: Successful operation + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_200' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_1' + deprecated: true + /v2/event-subscriptions: + get: + tags: + - Subscriptions + summary: Receive a list of your active subscriptions + parameters: + - name: limit + in: query + description: Maximum number of items to return. + required: false + schema: + minimum: 1 + type: integer + format: int32 + default: 100 + example: 100 + - name: cursor + in: query + description: "A server generated value to specify a specific point in a collection result, used for pagination." + required: false + schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA= + - name: sort + in: query + description: | + A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used. + required: false + schema: + type: string + example: carrierBookingReference:DESC + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + responses: + "200": + description: Returns a list of subscriptions + headers: + API-Version: + $ref: '#/components/headers/API-Version' + Current-Page: + $ref: '#/components/headers/Current-Page' + Next-Page: + $ref: '#/components/headers/Next-Page' + Prev-Page: + $ref: '#/components/headers/Prev-Page' + Last-Page: + $ref: '#/components/headers/Last-Page' + First-Page: + $ref: '#/components/headers/First-Page' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/subscription' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_2' + post: + tags: + - Subscriptions + summary: Create a subscription + parameters: + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + requestBody: + description: | + Parameters used to configure the subscription. It is possible to only receive cirtain types of events by adding filter values to the subscription. + + All values in the subscription body except: callback, secret and subscriptionID will be used as filters. All filters specified must be filfilled in order to match an Event. A logical AND is used between filters. So + + shipmentEventTypeCode=DRFT&carrierBookingReference=ABC123123 + + means that the events matched must both be Draft (shipmentEventTypeCode=DRFT) and be connected to carrierBookingReference ABC123123 (carrierBookingReference=ABC123123) + + Filters that are specified as (comma separated) lists use logical OR between list values. So + + eventType=SHIPMENT,TRANSPORT + + means that both Shipment- and Transport-events will be matched by this subscription. + content: + application/json: + schema: + $ref: '#/components/schemas/subscriptionBodyWithSecret' + required: true + responses: + "201": + description: Subscription created + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/subscription' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_3' + callbacks: + event: + '{$request.body.callbackUrl}': + post: + parameters: + - name: Signature + in: header + description: | + The signature certifying the request originates from the carrier. + required: true + deprecated: true + schema: + type: object + properties: + keyId: + type: string + format: uuid + example: 4fb682bc-3cd1-43a9-a23a-618a61bd87ca + created: + type: integer + example: 1591960384 + headers: + type: string + example: (request-target) (created) date host + signature: + type: string + example: aGkgZnJvbSBkZW5tYXJr + - name: Subscription-ID + in: header + description: The ID of the subscription triggering the event being sent. + required: true + schema: + type: string + format: uuid + example: b80d923d-e8ac-4c34-9506-55d3de347034 + - name: Notification-Signature + in: header + description: "the Notification-Signature is used to sign the notification. The header has the following format: \n\nNotification-Signature: <signature-type>=<signature>\n\nThe <signature-type> part is a keyword that determines which algorithm was used to compute the signature.\n\nThe signature MUST cover the entire request body of the request including whitespace and newlines. The content MUST decoded into bytes using the UTF-8 encoding before computing the signature. None of the HTTP headers nor the request URL is covered by the signature.\n\nSupported signature typies are:\n- sha256\n\nExample: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de\n" + required: true + schema: + pattern: "\\s*([a-zA-Z0-9-_+]+=[0-9a-fA-F]+)\\s*" + type: string + example: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de + - name: API-Version + in: header + description: | + SemVer used to indicate the version of the contract (API version) returned. + required: true + schema: + type: string + example: 1.0.0 + requestBody: + content: + application/json: + schema: + type: array + items: + anyOf: + - $ref: '#/components/schemas/transportEvent' + - $ref: '#/components/schemas/shipmentEvent' + - $ref: '#/components/schemas/equipmentEvent' + required: true + responses: + "204": + description: Your server returns this code if it accepts the callback + /v2/event-subscriptions/{subscriptionID}: + get: + tags: + - Subscriptions + summary: Find a subscription by subscription ID + parameters: + - name: subscriptionID + in: path + description: The universal unique ID of the subscription. + required: true + schema: + $ref: '#/components/schemas/subscriptionID' + example: 123e4567-e89b-12d3-a456-426614174000 + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + responses: + "200": + description: Subscription returned + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/subscription' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_4' + put: + tags: + - Subscriptions + summary: Alter a subscription + parameters: + - name: subscriptionID + in: path + description: The universal unique ID of the subscription. + required: true + schema: + $ref: '#/components/schemas/subscriptionID' + example: 123e4567-e89b-12d3-a456-426614174000 + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + requestBody: + description: Parameters used to configure the subscription + content: + application/json: + schema: + $ref: '#/components/schemas/subscription' + required: true + responses: + "200": + description: Subscription updated + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/subscription' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_5' + delete: + tags: + - Subscriptions + summary: "Stop a subscription, using the subscription ID" + parameters: + - name: subscriptionID + in: path + description: The universal unique ID of the subscription. + required: true + schema: + $ref: '#/components/schemas/subscriptionID' + example: 123e4567-e89b-12d3-a456-426614174000 + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + responses: + "204": + description: Subscription stopped + headers: + API-Version: + $ref: '#/components/headers/API-Version' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_6' + /v2/event-subscriptions/{subscriptionID}/secret: + put: + tags: + - Secret + summary: Resets the Secret on an existing subscription. + parameters: + - name: subscriptionID + in: path + description: The universal unique ID of the subscription. + required: true + schema: + $ref: '#/components/schemas/subscriptionID' + example: 123e4567-e89b-12d3-a456-426614174000 + - name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + requestBody: + description: Parameters used to configure the subscription + content: + application/json: + schema: + $ref: '#/components/schemas/subscriptionID_secret_body' + required: true + responses: + "204": + description: Secret updated + headers: + API-Version: + $ref: '#/components/headers/API-Version' + default: + description: Unexpected error + headers: + API-Version: + $ref: '#/components/headers/API-Version' + content: + application/json: + schema: + $ref: '#/components/schemas/inline_response_default_7' +components: + schemas: + eventTypes: + type: array + description: | + List of eventType to filter by. If multiple values are selected - the OR-operator will be used. + + Possible values are + - SHIPMENT (Shipment events) + - TRANSPORT (Transport events) + - EQUIPMENT (Equipment events) + + Default is none as it will not filter on eventType if not specified. + example: + - TRANSPORT + - EQUIPMENT + items: + type: string + enum: + - SHIPMENT + - TRANSPORT + - EQUIPMENT + subscriptionBody: + required: + - callbackUrl + type: object + allOf: + - type: object + properties: + callbackUrl: + $ref: '#/components/schemas/callbackUrl' + - type: object + properties: + eventType: + $ref: '#/components/schemas/eventTypes' + - $ref: '#/components/schemas/shipmentSubscriptionBody' + - $ref: '#/components/schemas/transportSubscriptionBody' + - $ref: '#/components/schemas/equipmentSubscriptionBody' + subscriptionBodyWithSecret: + required: + - secret + type: object + allOf: + - $ref: '#/components/schemas/subscriptionBody' + - type: object + properties: + secret: + allOf: + - $ref: '#/components/schemas/secret' + - description: A shared secret shared between the Publisher and the Subscriber. It is used to compute the contents of the Notification-Signature header. Only valid in POST calls - anywhere else must be omitted! + subscription: + type: object + allOf: + - type: object + properties: + subscriptionID: + $ref: '#/components/schemas/subscriptionID' + - $ref: '#/components/schemas/subscriptionBody' + shipmentEventTypeCode: + type: string + description: | + The status of the document in the process. Possible values are + - RECE (Received) + - DRFT (Drafted) + - PENA (Pending Approval) + - PENU (Pending Update) + - REJE (Rejected) + - APPR (Approved) + - ISSU (Issued) + - SURR (Surrendered) + - SUBM (Submitted) + - VOID (Void) + - CONF (Confirmed) + - REQS (Requested) + - CMPL (Completed) + - HOLD (On Hold) + - RELS (Released) + + More details can be found on GitHub + example: DRFT + enum: + - RECE + - DRFT + - PENA + - PENU + - REJE + - APPR + - ISSU + - SURR + - SUBM + - VOID + - CONF + - REQS + - CMPL + - HOLD + - RELS + documentTypeCode: + maxLength: 3 + type: string + description: | + The code to identify the type of information documentID points to. Can be one of the following values + - CBR (Carrier Booking Request Reference) + - BKG (Booking) + - SHI (Shipping Instruction) + - SRM (Shipment Release Message) + - TRD (Transport Document) + - ARN (Arrival Notice) + - VGM (Verified Gross Mass) + - CAS (Cargo Survey) + - CUS (Customs Inspection) + - DGD (Dangerous Goods Declaration) + - OOG (Out of Gauge) + + More details can be found on GitHub + example: SHI + enum: + - CBR + - BKG + - SHI + - SRM + - TRD + - ARN + - VGM + - CAS + - CUS + - DGD + - OOG + carrierBookingReference: + maxLength: 35 + type: string + description: A set of unique characters provided by carrier to identify a booking. + example: ABC709951 + transportDocumentReference: + maxLength: 20 + type: string + 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. + transportEventTypeCode: + type: string + description: | + Identifier for type of Transport event + - ARRI (Arrived) + - DEPA (Departed) + + More details can be found on GitHub + example: ARRI + enum: + - ARRI + - DEPA + scheduleID: + type: string + description: ID uniquely identifying a schedule + format: uuid + example: 9679a405-3316-42a5-8533-aba000f5689c + transportCallID: + maxLength: 100 + type: string + description: The unique identifier for a transport call + example: 123e4567-e89b-12d3-a456-426614174000 + vesselIMONumber: + maxLength: 7 + type: string + description: | + The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel + example: "9321483" + carrierVoyageNumber: + maxLength: 50 + type: string + description: The vessel operator-specific identifier of the Voyage. + example: 2103S + exportVoyageNumber: + maxLength: 50 + type: string + description: The vessel operator-specific identifier of the export Voyage. + example: 2103S + carrierServiceCode: + maxLength: 5 + type: string + description: | + The code of the service for which the schedule details are published. + example: FE1 + UNLocationCode: + maxLength: 5 + type: string + description: The UN Location code specifying where the place is located. + example: FRPAR + equipmentEventTypeCode: + type: string + description: | + Unique identifier for equipmentEventTypeCode. + - LOAD (Loaded) + - DISC (Discharged) + - GTIN (Gated in) + - GTOT (Gated out) + - STUF (Stuffed) + - STRP (Stripped) + - PICK (Pick-up) + - DROP (Drop-off) + - INSP (Inspected) + - RSEA (Resealed) + - RMVD (Removed) + + More details can be found on GitHub + example: LOAD + enum: + - LOAD + - DISC + - GTIN + - GTOT + - STUF + - STRP + - PICK + - DROP + - INSP + - RSEA + - RMVD + equipmentReference: + maxLength: 15 + type: string + description: | + The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + According to ISO 6346, 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, it is suggested to follow Recommendation #2 “Container with non-ISO identification” from SMDG. + example: APZU4812090 + eventCreatedDateTime: + type: string + description: | + The timestamp of when the event was created. + + NB: This field should be considered Metadata + format: date-time + example: 2021-01-09T14:12:56+01:00 + transportEvent: + type: object + allOf: + - $ref: '#/components/schemas/operationsTransportEvent' + - type: object + properties: + documentReferences: + $ref: '#/components/schemas/documentReferences' + - $ref: '#/components/schemas/references' + operationsTransportEvent: + type: object + allOf: + - $ref: '#/components/schemas/baseEvent' + - $ref: '#/components/schemas/baseTransportEvent' + baseEvent: + required: + - eventCreatedDateTime + type: object + allOf: + - type: object + properties: + eventID: + $ref: '#/components/schemas/eventID' + - type: object + properties: + eventCreatedDateTime: + $ref: '#/components/schemas/eventCreatedDateTime' + - $ref: '#/components/schemas/baseEventBody' + eventID: + type: string + description: | + The unique identifier for the event (the message - not the source). + + NB: This field should be considered Metadata + format: uuid + example: 3cecb101-7a1a-43a4-9d62-e88a131651e2 + baseEventBody: + required: + - eventClassifierCode + - eventDateTime + - eventType + type: object + description: | + The Event entity is described as a generalization of all the specific event categories. An event always takes place in relation to a shipment and can additionally be linked to a transport or an equipment + allOf: + - type: object + properties: + eventType: + $ref: '#/components/schemas/eventType' + - type: object + properties: + eventClassifierCode: + $ref: '#/components/schemas/eventClassifierCode' + - type: object + properties: + eventDateTime: + $ref: '#/components/schemas/eventDateTime' + eventType: + type: string + description: | + The Event Type of the object - to be used as a discriminator. + + NB: This field should be considered Metadata + eventClassifierCode: + type: string + description: | + Code for the event classifier. Values can vary depending on eventType + eventDateTime: + type: string + description: "The local date and time, where the event took place or when the event will take place, in ISO 8601 format." + format: date-time + example: 2019-11-12T07:41:00+08:30 + baseTransportEvent: + required: + - transportCall + - transportEventTypeCode + type: object + description: | + The transport event entity is a specialization of the event entity to support specification of data that only applies to a transport event. + allOf: + - type: object + properties: + eventType: + type: string + example: TRANSPORT + enum: + - TRANSPORT + - type: object + properties: + eventClassifierCode: + type: string + description: | + Code for the event classifier can be + - ACT (Actual) + - PLN (Planned) + - EST (Estimated) + example: ACT + enum: + - ACT + - PLN + - EST + - type: object + properties: + transportEventTypeCode: + $ref: '#/components/schemas/transportEventTypeCode' + - type: object + properties: + delayReasonCode: + $ref: '#/components/schemas/delayReasonCode' + - type: object + properties: + vesselScheduleChangeRemark: + $ref: '#/components/schemas/vesselScheduleChangeRemark' + - type: object + properties: + changeRemark: + $ref: '#/components/schemas/changeRemark' + - type: object + properties: + transportCallID: + allOf: + - $ref: '#/components/schemas/transportCallID' + - deprecated: true + - description: The unique identifier for a transport call

Deprecated - not needed as the TransportCall object is included + - type: object + properties: + transportCall: + $ref: '#/components/schemas/transportCall' + - type: object + properties: + eventTypeCode: + $ref: '#/components/schemas/eventTypeCode' + - type: object + properties: + eventTypeCode: + type: string + description: | + Unique identifier for Event Type Code, for transport events this is either + - ARRI (Arrival) + - DEPA (Departure) + + Deprecated - use transportEventTypeCode instead + deprecated: true + enum: + - ARRI + - DEPA + delayReasonCode: + maxLength: 3 + type: string + description: Reason code for the delay. The SMDG-Delay-Reason-Codes are used for this attribute. The code list can be found at http://www.smdg.org/smdg-code-lists/ + example: WEA + vesselScheduleChangeRemark: + maxLength: 250 + type: string + description: | + Free text information provided by the vessel operator regarding the reasons for the change in schedule and/or plans to mitigate schedule slippage. + + Deprecated - use changeRemark instead + example: Bad weather + deprecated: true + changeRemark: + maxLength: 250 + type: string + description: Free text information provided by the vessel operator regarding the reasons for the change in schedule and/or plans to mitigate schedule slippage. + example: Bad weather + transportCall: + required: + - modeOfTransport + - transportCallID + type: object + allOf: + - type: object + properties: + transportCallID: + $ref: '#/components/schemas/transportCallID' + - type: object + properties: + carrierServiceCode: + $ref: '#/components/schemas/carrierServiceCode' + - type: object + properties: + carrierVoyageNumber: + $ref: '#/components/schemas/carrierVoyageNumber' + - type: object + properties: + carrierVoyageNumber: + description: | + The vessel operator-specific identifier of the Voyage. + + In case there are multiple voyages the export voyage is chosen. + deprecated: true + - type: object + properties: + exportVoyageNumber: + $ref: '#/components/schemas/exportVoyageNumber' + - type: object + properties: + importVoyageNumber: + $ref: '#/components/schemas/importVoyageNumber' + - type: object + properties: + transportCallSequenceNumber: + $ref: '#/components/schemas/transportCallSequenceNumber' + - type: object + properties: + UNLocationCode: + $ref: '#/components/schemas/UNLocationCode' + - type: object + properties: + facilityCode: + $ref: '#/components/schemas/facilityCode' + - type: object + properties: + facilityCodeListProvider: + $ref: '#/components/schemas/facilityCodeListProvider' + - type: object + properties: + facilityTypeCode: + $ref: '#/components/schemas/facilityTypeCodeTRN' + - type: object + properties: + otherFacility: + $ref: '#/components/schemas/otherFacility' + - type: object + properties: + modeOfTransport: + $ref: '#/components/schemas/modeOfTransport' + - type: object + properties: + location: + allOf: + - $ref: '#/components/schemas/location' + - type: object + description: Location of the facility. Can often be omitted when it is just repeating the contents of the UNLocationCode field. + example: null + - type: object + properties: + vessel: + $ref: '#/components/schemas/vessel' + importVoyageNumber: + maxLength: 50 + type: string + description: The vessel operator-specific identifier of the import Voyage. + example: 2103N + transportCallSequenceNumber: + type: integer + description: Transport operator's key that uniquely identifies each individual call. This key is essential to distinguish between two separate calls at the same location within one voyage. + example: 2 + facilityCode: + maxLength: 6 + type: string + description: | + The code used for identifying the specific facility. This code does not include the UN Location Code. + nullable: false + example: ADT + facilityCodeListProvider: + type: string + description: | + The provider used for identifying the facility Code + example: SMDG + enum: + - BIC + - SMDG + facilityTypeCodeTRN: + type: string + description: | + A specialized version of the facilityCode to be used in TransportCalls. The code to identify the specific type of facility. + - BOCR (Border crossing) + - CLOC (Customer location) + - COFS (Container freight station) + - COYA (Deprecated - use OFFD intead) + - OFFD (Off dock storage) + - DEPO (Depot) + - INTE (Inland terminal) + - POTE (Port terminal) + - RAMP (Ramp) + example: POTE + enum: + - BOCR + - CLOC + - COFS + - COYA + - OFFD + - DEPO + - INTE + - POTE + - RAMP + otherFacility: + maxLength: 50 + type: string + description: An alternative way to capture the facility when no standardized DCSA facility code can be found. + example: Depot location or address + modeOfTransport: + type: string + description: | + The mode of transport as defined by DCSA. + enum: + - VESSEL + - RAIL + - TRUCK + - BARGE + location: + type: object + description: | + generally used to capture location-related data, also for locations without UN Location Codes. + allOf: + - type: object + properties: + locationName: + $ref: '#/components/schemas/locationName' + - type: object + properties: + latitude: + $ref: '#/components/schemas/latitude' + - type: object + properties: + longitude: + $ref: '#/components/schemas/longitude' + - type: object + properties: + UNLocationCode: + $ref: '#/components/schemas/UNLocationCode' + - type: object + properties: + facilityCode: + $ref: '#/components/schemas/facilityCode' + - type: object + properties: + facilityCodeListProvider: + $ref: '#/components/schemas/facilityCodeListProvider' + - type: object + properties: + address: + description: Address related information + allOf: + - $ref: '#/components/schemas/address' + locationName: + maxLength: 100 + type: string + description: The name of the location. + example: Eiffel Tower + latitude: + maxLength: 10 + type: string + description: Geographic coordinate that specifies the north–south position of a point on the Earth's surface. + example: "48.8585500" + longitude: + maxLength: 11 + type: string + description: Geographic coordinate that specifies the east–west position of a point on the Earth's surface. + example: "2.294492036" + address: + type: object + description: An object for storing address related information + allOf: + - type: object + properties: + name: + $ref: '#/components/schemas/addressName' + - type: object + properties: + street: + $ref: '#/components/schemas/streetName' + - type: object + properties: + streetNumber: + $ref: '#/components/schemas/streetNumber' + - type: object + properties: + floor: + $ref: '#/components/schemas/floor' + - type: object + properties: + postCode: + $ref: '#/components/schemas/postCode' + - type: object + properties: + city: + $ref: '#/components/schemas/cityName' + - type: object + properties: + stateRegion: + $ref: '#/components/schemas/stateRegion' + - type: object + properties: + country: + $ref: '#/components/schemas/country' + addressName: + maxLength: 100 + type: string + description: Name of the address + example: Henrik + streetName: + maxLength: 100 + type: string + description: The name of the street of the party’s address. + example: Kronprincessegade + streetNumber: + maxLength: 50 + type: string + description: The number of the street of the party’s address. + example: "54" + floor: + maxLength: 50 + type: string + description: The floor of the party’s street number. + example: 5. sal + postCode: + maxLength: 10 + type: string + description: The post code of the party’s address. + example: "1306" + cityName: + maxLength: 65 + type: string + description: The city name of the party’s address. + example: København + stateRegion: + maxLength: 65 + type: string + description: The state/region of the party’s address. + example: N/A + country: + maxLength: 75 + type: string + description: The country of the party’s address. + example: Denmark + vessel: + required: + - vesselIMONumber + type: object + description: "describes a floating, sea going structure (mother vessels and feeder vessels) with either an internal or external mode of propulsion designed for the transport of cargo and/or passengers. Ocean vessels are uniquely identified by an IMO number consisting of 7 digits, or alternatively by their AIS signal with an MMSI number. \n" + allOf: + - type: object + properties: + vesselIMONumber: + $ref: '#/components/schemas/vesselIMONumber' + - type: object + properties: + vesselName: + $ref: '#/components/schemas/vesselName' + - type: object + properties: + vesselFlag: + $ref: '#/components/schemas/vesselFlag' + - type: object + properties: + vesselCallSignNumber: + $ref: '#/components/schemas/vesselCallSignNumber' + - type: object + properties: + vesselOperatorCarrierCode: + $ref: '#/components/schemas/vesselOperatorCarrierCode' + - type: object + properties: + vesselOperatorCarrierCodeListProvider: + $ref: '#/components/schemas/vesselOperatorCarrierCodeListProvider' + vesselName: + maxLength: 35 + type: string + description: | + The name of the Vessel given by the Vessel Operator and registered with IMO. + example: King of the Seas + vesselFlag: + maxLength: 2 + type: string + description: | + The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code + example: DE + vesselCallSignNumber: + maxLength: 10 + type: string + description: | + A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a threeletter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag. + example: NCVV + vesselOperatorCarrierCode: + maxLength: 10 + type: string + description: | + The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists + nullable: false + example: MAEU + vesselOperatorCarrierCodeListProvider: + type: string + description: Identifies the code list provider used for the operator and partner carriercodes. + nullable: false + example: NMFTA + enum: + - SMDG + - NMFTA + eventTypeCode: + maxLength: 4 + type: string + description: | + Deprecated - Unique identifier for Event Type Code. This has been replaced by Specialized eventTypeCodes: shipmentEventTypeCode, transportEventTypeCode, equipmentEventTypeCode and opertaionsEventType + example: ARRI + deprecated: true + documentReferences: + type: array + description: An optional list of key-value (documentReferenceType-documentReferenceValue) pairs representing links to objects relevant to the event. The documentReferenceType-field is used to describe where the documentReferenceValue-field is pointing to. + example: + - documentReferenceType: BKG + documentReferenceValue: ABC123123123 + - documentReferenceType: TRD + documentReferenceValue: 85943567-eedb-98d3-f4ed-aed697474ed4 + items: + $ref: '#/components/schemas/documentReferences_inner' + references: + type: object + properties: + references: + type: array + items: + $ref: '#/components/schemas/reference' + reference: + required: + - referenceType + - referenceValue + type: object + description: | + references provided by the shipper or freight forwarder at the time of booking or at the time of providing shipping instruction. Carriers share it back when providing track and trace event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems. + allOf: + - type: object + properties: + referenceType: + $ref: '#/components/schemas/referenceType' + - type: object + properties: + referenceValue: + $ref: '#/components/schemas/referenceValue' + referenceType: + type: string + description: | + The reference type codes defined by DCSA. + - FF (Freight Forwarder’s Reference) + - SI (Shipper’s Reference) + - PO (Purchase Order Reference) + - CR (Customer’s Reference) + - AAO (Consignee’s Reference) + - EQ (Equipment Reference) + example: FF + enum: + - FF + - SI + - PO + - CR + - AAO + - EQ + referenceValue: + maxLength: 100 + type: string + description: The actual value of the reference. + shipmentEvent: + type: object + allOf: + - $ref: '#/components/schemas/baseEvent' + - $ref: '#/components/schemas/baseShipmentEvent' + baseShipmentEvent: + required: + - documentID + - documentTypeCode + - shipmentEventTypeCode + type: object + description: | + The shipment event entity is a specialization of the event entity to support specification of data that only applies to a shipment event. + allOf: + - type: object + properties: + eventType: + type: string + example: SHIPMENT + enum: + - SHIPMENT + - type: object + properties: + eventDateTime: + description: | + Value for eventDateTime must be the same value as eventCreatedDateTime + - type: object + properties: + eventClassifierCode: + type: string + description: | + Code for the event classifier can be + - ACT (Actual) + - PLN (Planned) + - EST (Estimated) + example: ACT + enum: + - ACT + - PLN + - EST + - type: object + properties: + shipmentEventTypeCode: + $ref: '#/components/schemas/shipmentEventTypeCode' + - type: object + properties: + documentID: + $ref: '#/components/schemas/documentID' + - type: object + properties: + documentTypeCode: + $ref: '#/components/schemas/documentTypeCode' + - type: object + properties: + shipmentInformationTypeCode: + $ref: '#/components/schemas/shipmentInformationType' + - type: object + properties: + reason: + $ref: '#/components/schemas/reason' + - type: object + properties: + eventTypeCode: + $ref: '#/components/schemas/eventTypeCode' + - type: object + properties: + eventTypeCode: + type: string + description: | + Unique identifier for Event Type Code. For shipment events this can be + - RECE (Received) + - CONF (Confirmed) + - ISSU (Issued) + - APPR (Approved) + - SUBM (Submitted) + - SURR (Surrendered) + - REJE (Rejected) + - PENA (Pending approval) + + Deprecated - use shipmentEventTypeCode instead + example: RECE + deprecated: true + enum: + - RECE + - CONF + - ISSU + - APPR + - SUBM + - SURR + - REJE + - PENA + - type: object + properties: + shipmentID: + $ref: '#/components/schemas/shipmentID' + - type: object + properties: + shipmentID: + description: | + ID uniquely identifying a shipment. + + Deprecated - this is replaced by documentID which can contain different values depending on the value of the documentTypeCode field + deprecated: true + - $ref: '#/components/schemas/references' + documentID: + type: string + description: | + The id of the object defined by the documentTypeCode. + example: the-id-of-the-documentTypeCode + shipmentInformationType: + maxLength: 3 + type: string + description: | + The code to identify the type of information documentID points to. Can be one of the following values + - BOK (Booking - deprecated use BKG instead) + - BKG (Booking) + - SHI (Shipping Instruction) + - VGM (Verified Gross Mass) + - SRM (Shipment Release Message) + - TRD (Transport Document) + - ARN (Arrival Notice) + + Deprecated - use documentTypeCode instead + example: SHI + deprecated: true + enum: + - BOK + - BKG + - SHI + - VGM + - SRM + - TRD + - ARN + reason: + type: string + description: Reason field in a Shipment event. This field can be used to explain why a specific event has been sent. + example: The following attributes are missing... + shipmentID: + type: string + description: The identifier for a shipment + format: uuid + example: c32d56f3-a4a5-4964-bb49-abd168b06160 + equipmentEvent: + type: object + allOf: + - $ref: '#/components/schemas/baseEvent' + - $ref: '#/components/schemas/baseEquipmentEvent' + baseEquipmentEvent: + required: + - emptyIndicatorCode + - equipmentEventTypeCode + type: object + description: | + The equipment event entity is a specialization of the event entity to support specification of data that only applies to an equipment event. + allOf: + - type: object + properties: + eventType: + type: string + example: EQUIPMENT + enum: + - EQUIPMENT + - type: object + properties: + eventClassifierCode: + type: string + description: | + Code for the event classifier can be + - PLN (Planned) + - ACT (Actual) + - EST (Estimated) + example: EST + enum: + - PLN + - ACT + - EST + - type: object + properties: + equipmentEventTypeCode: + $ref: '#/components/schemas/equipmentEventTypeCode' + - type: object + properties: + equipmentReference: + $ref: '#/components/schemas/equipmentReference' + - type: object + properties: + ISOEquipmentCode: + $ref: '#/components/schemas/ISOEquipmentCode' + - type: object + properties: + emptyIndicatorCode: + $ref: '#/components/schemas/emptyIndicatorCode' + - type: object + properties: + eventLocation: + $ref: '#/components/schemas/location' + - type: object + properties: + transportCallID: + allOf: + - $ref: '#/components/schemas/transportCallID' + - deprecated: true + - description: The unique identifier for a transport call

Deprecated - not needed as the TransportCall object is included + - type: object + properties: + transportCall: + $ref: '#/components/schemas/transportCall' + - type: object + properties: + documentReferences: + $ref: '#/components/schemas/documentReferences' + - $ref: '#/components/schemas/references' + - $ref: '#/components/schemas/seals' + - type: object + properties: + eventTypeCode: + $ref: '#/components/schemas/eventTypeCode' + - type: object + properties: + eventTypeCode: + type: string + description: | + Unique identifier for Event Type Code, for transport events this is either + - LOAD (Loaded) + - DISC (Discharged) + - GTIN (Gated in) + - GTOT (Gated out) + - STUF (Stuffed) + - STRP (Stripped) + + Deprecated - use equipmentEventTypeCode instead + deprecated: true + enum: + - LOAD + - DISC + - GTIN + - GTOT + - STUF + - STRP + ISOEquipmentCode: + maxLength: 4 + type: string + description: Unique code for the different equipment size/type used for transporting commodities. The code is a concatenation of ISO Equipment Size Code and ISO Equipment Type Code A and follows the ISO 6346 standard. + example: 22GP + emptyIndicatorCode: + type: string + description: Code to denote whether the equipment is empty or laden. + example: EMPTY + enum: + - EMPTY + - LADEN + seals: + type: object + properties: + seals: + type: array + items: + $ref: '#/components/schemas/seal' + seal: + required: + - sealNumber + - sealType + type: object + 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. + allOf: + - type: object + properties: + sealNumber: + $ref: '#/components/schemas/sealNumber' + - type: object + properties: + sealSource: + $ref: '#/components/schemas/sealSource' + - type: object + properties: + sealType: + $ref: '#/components/schemas/sealType' + sealNumber: + maxLength: 15 + type: string + description: Identifies a seal affixed to the container. + sealSource: + type: string + description: | + The source of the seal, namely who has affixed the seal. This attribute links to the Seal Source ID defined in the Seal Source reference data entity. + - CAR (Carrier) + - SHI (Shipper) + - PHY (Phytosanitary) + - VET (Veterinary) + - CUS (Customs) + example: CUS + enum: + - CAR + - SHI + - PHY + - VET + - CUS + sealType: + type: string + description: | + The type of seal. This attribute links to the Seal Type ID defined in the Seal Type reference data entity. + - KLP (Keyless padlock) + - BLT (Bolt) + - WIR (Wire) + example: WIR + enum: + - KLP + - BLT + - WIR + error: + required: + - errorDateTime + - errors + - httpMethod + - requestUri + - statusCode + - statusCodeText + type: object + properties: + httpMethod: + type: string + description: The HTTP request method type + example: POST + requestUri: + type: string + description: The request URI. + example: https://dcsa.org/dcsa/tnt/v1/events + errors: + $ref: '#/components/schemas/subErrors' + statusCode: + type: integer + description: The HTTP status code + example: 400 + statusCodeText: + type: string + description: The textual representation of the response status. + example: Bad Request + errorDateTime: + type: string + description: The date and time (in ISO 8601 format) the error occurred. + format: $date-time + example: 2019-11-12T07:41:00+08:30 + subErrors: + type: array + items: + $ref: '#/components/schemas/subErrors_inner' + subscriptionID: + type: string + description: The carrier issues a unique ID to the shipper or consignee for that subscription + format: uuid + example: 8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809 + secret: + type: string + description: | + A Base64 encoded secret shared between the Publisher and the Subscriber. + It is used to compute the contents of the Notification-Signature header. + format: byte + example: MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDM2NTc4NjIzODk3NDY5MDgyNzM0OTg3MTIzNzg2NA== + callbackUrl: + type: string + description: | + The endPoint where a Carrier whould send back events to the Shipper. The callback can contain query parameters uniquely identifying the originator of the events. + format: uri + example: https://myserver.com/send/callback/here?shipperRef= + shipmentSubscriptionBody: + type: object + allOf: + - type: object + properties: + shipmentEventTypeCode: + $ref: '#/components/schemas/shipmentEventTypeCodes' + - type: object + properties: + documentTypeCode: + $ref: '#/components/schemas/documentTypeCodes' + - type: object + properties: + carrierBookingReference: + $ref: '#/components/schemas/carrierBookingReference' + - type: object + properties: + bookingReference: + maxLength: 35 + type: string + description: | + The identifier for a shipment, which is issued by and unique within each of the carriers. + + Deprecated - use carrierBookingReference instead + example: ABC709951 + deprecated: true + - type: object + properties: + transportDocumentID: + type: string + description: | + Uniquely identify a transport document. + + Deprecated - use transportDocumentReference instead + format: uuid + deprecated: true + - type: object + properties: + transportDocumentReference: + $ref: '#/components/schemas/transportDocumentReference' + - type: object + properties: + transportDocumentTypeCode: + allOf: + - $ref: '#/components/schemas/transportDocumentTypeCodes' + - deprecated: true + - description: | + List of transportDocumentType to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on transportDocumentType if not specified. + + Deprecated: Not to be used any more + shipmentEventTypeCodes: + type: array + description: | + List of shipmentEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on shipmentEventTypeCode if not specified. + example: + - RECE + - DRFT + items: + $ref: '#/components/schemas/shipmentEventTypeCode' + documentTypeCodes: + type: array + description: | + List of documentTypeCode to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on documentTypeCode if not specified. + example: + - SHI + - TRD + items: + $ref: '#/components/schemas/documentTypeCode' + transportDocumentTypeCodes: + type: array + description: | + List of transportDocumentType to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on transportDocumentType if not specified. + example: + - BOL + items: + $ref: '#/components/schemas/transportDocumentType' + transportDocumentType: + type: string + description: Specifies the type of the transport document (a Bill of Lading (BOL) or a Sea Waybill (SWB)). + example: SWB + enum: + - BOL + - SWB + transportSubscriptionBody: + type: object + allOf: + - type: object + properties: + transportEventTypeCode: + $ref: '#/components/schemas/transportEventTypeCodes' + - type: object + properties: + scheduleID: + allOf: + - $ref: '#/components/schemas/scheduleID' + - deprecated: true + - description: ID uniquely identifying a schedul.
Deprecated as this was added by mistake + - type: object + properties: + transportCallID: + $ref: '#/components/schemas/transportCallID' + - type: object + properties: + vesselIMONumber: + $ref: '#/components/schemas/vesselIMONumber' + - type: object + properties: + carrierVoyageNumber: + allOf: + - $ref: '#/components/schemas/carrierVoyageNumber' + - deprecated: true + - type: object + properties: + exportVoyageNumber: + $ref: '#/components/schemas/exportVoyageNumber' + - type: object + properties: + carrierServiceCode: + $ref: '#/components/schemas/carrierServiceCode' + - type: object + properties: + UNLocationCode: + $ref: '#/components/schemas/UNLocationCode' + transportEventTypeCodes: + type: array + description: | + List of transportEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on transportEventTypeCode if not specified. + example: + - ARRI + - DEPA + items: + $ref: '#/components/schemas/transportEventTypeCode' + equipmentSubscriptionBody: + type: object + allOf: + - type: object + properties: + equipmentEventTypeCode: + $ref: '#/components/schemas/equipmentEventTypeCodes' + - type: object + properties: + equipmentReference: + $ref: '#/components/schemas/equipmentReference' + - type: object + properties: + UNLocationCode: + $ref: '#/components/schemas/UNLocationCode' + equipmentEventTypeCodes: + type: array + description: | + List of equipmentEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used. + + Default is none as it will not filter on equipmentEventTypeCode if not specified. + example: + - GTIN + - GTOT + items: + $ref: '#/components/schemas/equipmentEventTypeCode' + inline_response_default: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: GET + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/events + inline_response_200: + example: + eventID: 84db923d-2a19-4eb0-beb5-446c1ec57d34 + eventType: SHIPMENT + eventCreatedDateTime: 2019-11-12T07:41:00+08:30 + eventSubtype: ISSU + documentID: 84db923d-2a19-4eb0-beb5-446c1ec57d34 + documentTypeCode: TRD + reason: All good + discriminator: + propertyName: eventType + oneOf: + - $ref: '#/components/schemas/shipmentEvent' + - $ref: '#/components/schemas/transportEvent' + - $ref: '#/components/schemas/equipmentEvent' + inline_response_default_1: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: GET + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/events/123e4567-e89b-12d3-a456-426614174000 + inline_response_default_2: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: GET + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions + inline_response_default_3: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: POST + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions + inline_response_default_4: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: GET + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809 + inline_response_default_5: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: PUT + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809 + inline_response_default_6: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: DELETE + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809 + subscriptionID_secret_body: + allOf: + - type: object + properties: + secret: + $ref: '#/components/schemas/secret' + inline_response_default_7: + allOf: + - $ref: '#/components/schemas/error' + - type: object + properties: + httpMethod: + example: PUT + - type: object + properties: + requestUri: + example: https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809/secret + documentReferences_inner: + type: object + properties: + documentReferenceType: + type: string + description: Describes where the documentReferenceValue is pointing to + example: BKG + enum: + - BKG + - TRD + documentReferenceValue: + type: string + description: The value of the identifier the documentReferenceType is describing + example: 123e4567-e89b-12d3-a456-426614174000 + subErrors_inner: + required: + - message + - reason + type: object + properties: + reason: + type: string + description: High level error message. + example: invalidQuery + message: + type: string + description: Detailed error message. + example: The request did not contain one of the three required query parameters. + parameters: + shipmentEventTypeCode: + name: shipmentEventTypeCode + in: query + description: | + The status of the document in the process to filter by. Possible values are + - RECE (Received) + - DRFT (Drafted) + - PENA (Pending Approval) + - PENU (Pending Update) + - REJE (Rejected) + - APPR (Approved) + - ISSU (Issued) + - SURR (Surrendered) + - SUBM (Submitted) + - VOID (Void) + - CONF (Confirmed) + - REQS (Requested) + - CMPL (Completed) + - HOLD (On Hold) + - RELS (Released) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example shipmentEventTypeCode=RECE,DRFT Matches both Received (RECE) and Drafted (DRFT) shipment events. + + Default is all shipmentEventTypeCodes. + + This filter is only relevant when filtering on ShipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/shipmentEventTypeCode' + default: "RECE,DRFT,PENA,PENU,REJE,APPR,ISSU,SURR,SUBM,VOID,CONF,REQS,CMPL,HOLD,RELS" + example: "RECE,DRFT" + documentTypeCode: + name: documentTypeCode + in: query + description: | + The documentTypeCode to filter by. Possible values are + - CBR (Carrier Booking Request Reference) + - BKG (Booking) + - SHI (Shipping Instruction) + - SRM (Shipment Release Message) + - TRD (Transport Document) + - ARN (Arrival Notice) + - VGM (Verified Gross Mass) + - CAS (Cargo Survey) + - CUS (Customs Inspection) + - DGD (Dangerous Goods Declaration) + - OOG (Out of Gauge) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example documentTypeCode=SHI,TRD Matches both ShippingInstruction (SHI) and TransportDocument (TRD) shipment events. + + Default is all documentTypeCodes. + + This filter is only relevant when filtering on ShipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/documentTypeCode' + default: "CBR,BKG,SHI,SRM,TRD,ARN,VGM,CAS,CUS,DGD,OOG" + example: "SHI,TRD" + carrierBookingReference: + name: carrierBookingReference + in: query + description: | + A set of unique characters provided by carrier to identify a booking. + + Specifying this filter will only return events related to this particular carrierBookingReference. + schema: + $ref: '#/components/schemas/carrierBookingReference' + bookingReference: + name: bookingReference + in: query + description: Deprecated - use carrierBookingReference instead. + required: false + deprecated: true + schema: + type: string + transportDocumentID: + name: transportDocumentID + in: query + description: | + A unique id to identify a transport document. + + Deprecated - use transportDocumentReference instead transportDocumentReference + deprecated: true + schema: + type: string + format: uuid + transportDocumentReference: + name: transportDocumentReference + in: query + description: | + A unique number reference allocated by the shipping line to the transport document and the main number used for the tracking of the status of the shipment. + + Specifying this filter will only return events related to this particular transportDocumentReference + required: false + schema: + $ref: '#/components/schemas/transportDocumentReference' + transportEventTypeCode: + name: transportEventTypeCode + in: query + description: | + Identifier for type of Transport event to filter by + - ARRI (Arrived) + - DEPA (Departed) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example transportEventTypeCode=ARRI,DEPA matches both Arrived (ARRI) and Departed (DEPA) transport events. + + Default is all transportEventTypeCodes. + + This filter is only relevant when filtering on TransportEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/transportEventTypeCode' + default: "ARRI,DEPA" + example: "ARRI,DEPA" + scheduleID: + name: scheduleID + in: query + description: | + ID uniquely identifying a schedule, to filter events by. + + This filter was added by mistake and is thus deprecated. + required: false + deprecated: true + schema: + $ref: '#/components/schemas/scheduleID' + transportCallID: + name: transportCallID + in: query + description: | + ID uniquely identifying a transport call, to filter events by. + + Specifying this filter will only return events related to this particular transportCallID + required: false + schema: + $ref: '#/components/schemas/transportCallID' + vesselIMONumber: + name: vesselIMONumber + in: query + description: | + The identifier of vessel for which schedule details are published. Depending on schedule type, this may not be available yet. + + Specifying this filter will only return events related to this particular vesselIMONumber. + required: false + schema: + $ref: '#/components/schemas/vesselIMONumber' + carrierVoyageNumber: + name: carrierVoyageNumber + in: query + description: | + Filter on the vessel operator-specific identifier of the Voyage. + + Specifying this filter will only return events related to this particular carrierVoyageNumber. + + Deprecated: Use exportVoyageNumber instead + required: false + deprecated: true + schema: + $ref: '#/components/schemas/carrierVoyageNumber' + exportVoyageNumber: + name: exportVoyageNumber + in: query + description: | + Filter on the vessel operator-specific identifier of the export Voyage. + + Specifying this filter will only return events related to this particular exportVoyageNumber. + required: false + schema: + $ref: '#/components/schemas/exportVoyageNumber' + carrierServiceCode: + name: carrierServiceCode + in: query + description: | + Filter on the carrier specific identifier of the service. + + Specifying this filter will only return events related to this particular carrierServiceCode. + required: false + schema: + $ref: '#/components/schemas/carrierServiceCode' + UNLocationCode: + name: UNLocationCode + in: query + description: | + The UN Location code specifying where the place is located. + + Specifying this filter will only return events related to this particular UN Location code. + required: false + schema: + $ref: '#/components/schemas/UNLocationCode' + equipmentEventTypeCode: + name: equipmentEventTypeCode + in: query + description: | + Unique identifier for equipmentEventTypeCode. + - LOAD (Loaded) + - DISC (Discharged) + - GTIN (Gated in) + - GTOT (Gated out) + - STUF (Stuffed) + - STRP (Stripped) + - PICK (Pick-up) + - DROP (Drop-off) + - INSP (Inspected) + - RSEA (Resealed) + - RMVD (Removed) + + It is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example equipmentEventTypeCode=GTIN,GTOT matches both Gated in (GTIN) and Gated out (GTOT) equipment events. + + Default is all equipmentEventTypeCodes. + + This filter is only relevant when filtering on EquipmentEvents + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/equipmentEventTypeCode' + default: "LOAD,DISC,GTIN,GTOT,STUF,STRP,PICK,DROP,INSP,RSEA,RMVD" + example: "GTIN,GTOT" + equipmentReference: + name: equipmentReference + in: query + description: | + Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible. + + Specifying this filter will only return events related to this particular equipmentReference + required: false + schema: + $ref: '#/components/schemas/equipmentReference' + eventCreatedDateTime: + name: eventCreatedDateTime + in: query + description: | + Limit the result based on the creating date of the event. It is possible to use operators on this query parameter. This is done by adding a colon followed by an operator at the end of the queryParameterName (before the =) + + eventCreatedDateTime:gte=2021-04-01T14:12:56+01:00 + + would result in all events created ≥ 2021-04-01T14:12:56+01:00 + + The following operators are supported + - :gte (≥ Greater than or equal) + - :gt (> Greater than) + - :lte (≤ Less than or equal) + - :lt (< Less than) + - :eq (= Equal to) + + If no operator is provided, a strictly equal is used (this is equivalent to :eq operator). + required: false + schema: + $ref: '#/components/schemas/eventCreatedDateTime' + example: 2021-04-01T14:12:56+01:00 + limit: + name: limit + in: query + description: Maximum number of items to return. + required: false + schema: + minimum: 1 + type: integer + format: int32 + default: 100 + example: 100 + cursor: + name: cursor + in: query + description: "A server generated value to specify a specific point in a collection result, used for pagination." + required: false + schema: + type: string + example: fE9mZnNldHw9MTAmbGltaXQ9MTA= + sort: + name: sort + in: query + description: | + A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used. + required: false + schema: + type: string + example: carrierBookingReference:DESC + Api-Version-Major: + name: API-Version + in: header + 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. + required: false + schema: + type: string + example: "1" + eventID: + name: eventID + in: path + description: The ID of the event to receive + required: true + deprecated: true + schema: + $ref: '#/components/schemas/eventID' + example: 123e4567-e89b-12d3-a456-426614174000 + signatureHeader: + name: Signature + in: header + description: | + The signature certifying the request originates from the carrier. + required: true + deprecated: true + schema: + type: object + properties: + keyId: + type: string + format: uuid + example: 4fb682bc-3cd1-43a9-a23a-618a61bd87ca + created: + type: integer + example: 1591960384 + headers: + type: string + example: (request-target) (created) date host + signature: + type: string + example: aGkgZnJvbSBkZW5tYXJr + subscriptionIDHeader: + name: Subscription-ID + in: header + description: The ID of the subscription triggering the event being sent. + required: true + schema: + type: string + format: uuid + example: b80d923d-e8ac-4c34-9506-55d3de347034 + notificationSignature: + name: Notification-Signature + in: header + description: "the Notification-Signature is used to sign the notification. The header has the following format: \n\nNotification-Signature: <signature-type>=<signature>\n\nThe <signature-type> part is a keyword that determines which algorithm was used to compute the signature.\n\nThe signature MUST cover the entire request body of the request including whitespace and newlines. The content MUST decoded into bytes using the UTF-8 encoding before computing the signature. None of the HTTP headers nor the request URL is covered by the signature.\n\nSupported signature typies are:\n- sha256\n\nExample: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de\n" + required: true + schema: + pattern: "\\s*([a-zA-Z0-9-_+]+=[0-9a-fA-F]+)\\s*" + type: string + example: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de + apiVersion: + name: API-Version + in: header + description: | + SemVer used to indicate the version of the contract (API version) returned. + required: true + schema: + type: string + example: 1.0.0 + subscriptionID: + name: subscriptionID + in: path + description: The universal unique ID of the subscription. + required: true + schema: + $ref: '#/components/schemas/subscriptionID' + example: 123e4567-e89b-12d3-a456-426614174000 + headers: + API-Version: + description: SemVer used to indicate the version of the contract (API version) returned. + schema: + type: string + example: 1.0.0 + Current-Page: + description: A link to the current page. + required: true + schema: + type: string + example: fE9mZnNldHw9MCZsaW1pdD01 + Next-Page: + description: A link to the next page. Next-Page header link MAY be omitted if the current page is the last page. + required: false + schema: + type: string + example: fE9mZnNldHw9NSZsaW1pdD01 + Prev-Page: + description: A link to the previous page. Previous-Page header link MAY be omitted if the current page is the first page. + required: false + schema: + type: string + example: fE9mZnNldHw9MCZsaW1pdD01 + Last-Page: + description: A link to the last page. Last-Page header link MAY be omitted if the current page is the last page. + required: false + schema: + type: string + example: fE9mZnNldHw9NTkmbGltaXQ9NQ== + First-Page: + description: A link to thefirst page. First-Page header link MAY be omitted if current page is the first page. + required: false + schema: + type: string + example: fE9mZnNldHw9NjAmbGltaXQ9NQ== diff --git a/tnt/src/main/resources/standards/tnt/schemas/tnt-220-publisher.json b/tnt/src/main/resources/standards/tnt/schemas/tnt-220-publisher.json deleted file mode 100644 index d7e62c99..00000000 --- a/tnt/src/main/resources/standards/tnt/schemas/tnt-220-publisher.json +++ /dev/null @@ -1,3344 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "DCSA OpenAPI specification for Track & Trace", - "description": "Managing and sending Shipment-, Transport- and Equipment-events and subscriptions for Track & Trace (T&T). API specification issued by DCSA.org.\n\nFor explanation to specific values or objects please refer to the Information Model v3.3\n\nPolling can be done on the GET /v2/events endPoint. It is also possible to setup a subscription on the /v2/event-subscriptions endPoints in order to use the push model. Here events are pushed as they occur.\n\nFor a changelog please click here\n", - "contact": { - "name": "Digital Container Shipping Association (DCSA)", - "url": "https://dcsa.org", - "email": "info@dcsa.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "2.2.0" - }, - "servers": [ - { - "url": "/" - } - ], - "tags": [ - { - "name": "Events", - "description": "Event operations" - }, - { - "name": "Subscriptions", - "description": "Subscription operations" - }, - { - "name": "Secret", - "description": "Update secret" - } - ], - "paths": { - "/v2/events": { - "get": { - "tags": [ - "Events" - ], - "summary": "Find events.", - "description": "Returns all events filtered by the queryParameters.\n\nNB: It is possible to combine queryParameters. When combining queryParameters be aware that it is also possible to make combinations that are mutual contradicting.\n\nExample: shipmentEventTypeCode=DRFT and equipmentEventTypeCode=GTIN\n\nSince there is no event that can be a ShipmentEvent and an EquipmentEvent at the same time this will return an empty list!\n", - "parameters": [ - { - "name": "eventType", - "in": "query", - "description": "The type of event(s) to filter by. Possible values are\n\n- SHIPMENT (Shipment events)\n- TRANSPORT (Transport events)\n- EQUIPMENT (Equipment events)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example eventType=SHIPMENT,EQUIPMENT matches both Shipment- and Equipment-events.\n\nDefault value is all event types.\n", - "required": false, - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "SHIPMENT", - "TRANSPORT", - "EQUIPMENT" - ] - } - } - }, - { - "name": "shipmentEventTypeCode", - "in": "query", - "description": "The status of the document in the process to filter by. Possible values are\n- RECE (Received)\n- DRFT (Drafted)\n- PENA (Pending Approval)\n- PENU (Pending Update)\n- REJE (Rejected)\n- APPR (Approved)\n- ISSU (Issued)\n- SURR (Surrendered)\n- SUBM (Submitted)\n- VOID (Void)\n- CONF (Confirmed)\n- REQS (Requested)\n- CMPL (Completed)\n- HOLD (On Hold)\n- RELS (Released)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example shipmentEventTypeCode=RECE,DRFT Matches both Received (RECE) and Drafted (DRFT) shipment events.\n\nDefault is all shipmentEventTypeCodes.\n\nThis filter is only relevant when filtering on ShipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/shipmentEventTypeCode" - }, - "default": "RECE,DRFT,PENA,PENU,REJE,APPR,ISSU,SURR,SUBM,VOID,CONF,REQS,CMPL,HOLD,RELS" - }, - "example": "RECE,DRFT" - }, - { - "name": "documentTypeCode", - "in": "query", - "description": "The documentTypeCode to filter by. Possible values are\n- CBR (Carrier Booking Request Reference)\n- BKG (Booking)\n- SHI (Shipping Instruction)\n- SRM (Shipment Release Message)\n- TRD (Transport Document)\n- ARN (Arrival Notice)\n- VGM (Verified Gross Mass)\n- CAS (Cargo Survey)\n- CUS (Customs Inspection)\n- DGD (Dangerous Goods Declaration)\n- OOG (Out of Gauge)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example documentTypeCode=SHI,TRD Matches both ShippingInstruction (SHI) and TransportDocument (TRD) shipment events.\n\nDefault is all documentTypeCodes.\n\nThis filter is only relevant when filtering on ShipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/documentTypeCode" - }, - "default": "CBR,BKG,SHI,SRM,TRD,ARN,VGM,CAS,CUS,DGD,OOG" - }, - "example": "SHI,TRD" - }, - { - "name": "carrierBookingReference", - "in": "query", - "description": "A set of unique characters provided by carrier to identify a booking.\n\nSpecifying this filter will only return events related to this particular carrierBookingReference.\n", - "schema": { - "$ref": "#/components/schemas/carrierBookingReference" - } - }, - { - "name": "bookingReference", - "in": "query", - "description": "Deprecated - use carrierBookingReference instead.", - "required": false, - "deprecated": true, - "schema": { - "type": "string" - } - }, - { - "name": "transportDocumentID", - "in": "query", - "description": "A unique id to identify a transport document.\n\nDeprecated - use transportDocumentReference instead transportDocumentReference\n", - "deprecated": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "transportDocumentReference", - "in": "query", - "description": "A unique number reference allocated by the shipping line to the transport document and the main number used for the tracking of the status of the shipment.\n\nSpecifying this filter will only return events related to this particular transportDocumentReference\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/transportDocumentReference" - } - }, - { - "name": "transportEventTypeCode", - "in": "query", - "description": "Identifier for type of Transport event to filter by\n- ARRI (Arrived)\n- DEPA (Departed)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example transportEventTypeCode=ARRI,DEPA matches both Arrived (ARRI) and Departed (DEPA) transport events.\n\nDefault is all transportEventTypeCodes.\n\nThis filter is only relevant when filtering on TransportEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/transportEventTypeCode" - }, - "default": "ARRI,DEPA" - }, - "example": "ARRI,DEPA" - }, - { - "name": "scheduleID", - "in": "query", - "description": "ID uniquely identifying a schedule, to filter events by.\n\nThis filter was added by mistake and is thus deprecated.\n", - "required": false, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/scheduleID" - } - }, - { - "name": "transportCallID", - "in": "query", - "description": "ID uniquely identifying a transport call, to filter events by.\n\nSpecifying this filter will only return events related to this particular transportCallID\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/transportCallID" - } - }, - { - "name": "vesselIMONumber", - "in": "query", - "description": "The identifier of vessel for which schedule details are published. Depending on schedule type, this may not be available yet.\n\nSpecifying this filter will only return events related to this particular vesselIMONumber.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/vesselIMONumber" - } - }, - { - "name": "carrierVoyageNumber", - "in": "query", - "description": "Filter on the vessel operator-specific identifier of the Voyage.\n\nSpecifying this filter will only return events related to this particular carrierVoyageNumber.\n\nDeprecated: Use exportVoyageNumber instead\n", - "required": false, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/carrierVoyageNumber" - } - }, - { - "name": "exportVoyageNumber", - "in": "query", - "description": "Filter on the vessel operator-specific identifier of the export Voyage.\n\nSpecifying this filter will only return events related to this particular exportVoyageNumber.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/exportVoyageNumber" - } - }, - { - "name": "carrierServiceCode", - "in": "query", - "description": "Filter on the carrier specific identifier of the service.\n\nSpecifying this filter will only return events related to this particular carrierServiceCode.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/carrierServiceCode" - } - }, - { - "name": "UNLocationCode", - "in": "query", - "description": "The UN Location code specifying where the place is located.\n\nSpecifying this filter will only return events related to this particular UN Location code.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/UNLocationCode" - } - }, - { - "name": "equipmentEventTypeCode", - "in": "query", - "description": "Unique identifier for equipmentEventTypeCode.\n- LOAD (Loaded)\n- DISC (Discharged)\n- GTIN (Gated in)\n- GTOT (Gated out)\n- STUF (Stuffed)\n- STRP (Stripped)\n- PICK (Pick-up)\n- DROP (Drop-off)\n- INSP (Inspected)\n- RSEA (Resealed)\n- RMVD (Removed)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example equipmentEventTypeCode=GTIN,GTOT matches both Gated in (GTIN) and Gated out (GTOT) equipment events.\n\nDefault is all equipmentEventTypeCodes.\n\nThis filter is only relevant when filtering on EquipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/equipmentEventTypeCode" - }, - "default": "LOAD,DISC,GTIN,GTOT,STUF,STRP,PICK,DROP,INSP,RSEA,RMVD" - }, - "example": "GTIN,GTOT" - }, - { - "name": "equipmentReference", - "in": "query", - "description": "Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\n\nSpecifying this filter will only return events related to this particular equipmentReference\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/equipmentReference" - } - }, - { - "name": "eventCreatedDateTime", - "in": "query", - "description": "Limit the result based on the creating date of the event. It is possible to use operators on this query parameter. This is done by adding a colon followed by an operator at the end of the queryParameterName (before the =)\n\neventCreatedDateTime:gte=2021-04-01T14:12:56+01:00\n\nwould result in all events created ≥ 2021-04-01T14:12:56+01:00\n\nThe following operators are supported\n- :gte (≥ Greater than or equal)\n- :gt (> Greater than)\n- :lte (≤ Less than or equal)\n- :lt (< Less than)\n- :eq (= Equal to)\n\nIf no operator is provided, a strictly equal is used (this is equivalent to :eq operator).\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/eventCreatedDateTime" - }, - "example": "2021-04-01T14:12:56+01:00" - }, - { - "name": "limit", - "in": "query", - "description": "Maximum number of items to return.", - "required": false, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "default": 100 - }, - "example": 100 - }, - { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "schema": { - "type": "string" - }, - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA=" - }, - { - "name": "sort", - "in": "query", - "description": "A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used.\n", - "required": false, - "schema": { - "type": "string" - }, - "example": "carrierBookingReference:DESC" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "Successful operation", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - }, - "Current-Page": { - "$ref": "#/components/headers/Current-Page" - }, - "Next-Page": { - "$ref": "#/components/headers/Next-Page" - }, - "Prev-Page": { - "$ref": "#/components/headers/Prev-Page" - }, - "Last-Page": { - "$ref": "#/components/headers/Last-Page" - }, - "First-Page": { - "$ref": "#/components/headers/First-Page" - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/transportEvent" - }, - { - "$ref": "#/components/schemas/shipmentEvent" - }, - { - "$ref": "#/components/schemas/equipmentEvent" - } - ] - } - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default" - } - } - } - } - } - } - }, - "/v2/events/{eventID}": { - "get": { - "tags": [ - "Events" - ], - "summary": "Find events by eventID.", - "description": "Returns event with the specified eventID.", - "parameters": [ - { - "name": "eventID", - "in": "path", - "description": "The ID of the event to receive", - "required": true, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/eventID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - } - ], - "responses": { - "200": { - "description": "Successful operation", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_200" - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_1" - } - } - } - } - }, - "deprecated": true - } - }, - "/v2/event-subscriptions": { - "get": { - "tags": [ - "Subscriptions" - ], - "summary": "Receive a list of your active subscriptions", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Maximum number of items to return.", - "required": false, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "default": 100 - }, - "example": 100 - }, - { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "schema": { - "type": "string" - }, - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA=" - }, - { - "name": "sort", - "in": "query", - "description": "A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used.\n", - "required": false, - "schema": { - "type": "string" - }, - "example": "carrierBookingReference:DESC" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "Returns a list of subscriptions", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - }, - "Current-Page": { - "$ref": "#/components/headers/Current-Page" - }, - "Next-Page": { - "$ref": "#/components/headers/Next-Page" - }, - "Prev-Page": { - "$ref": "#/components/headers/Prev-Page" - }, - "Last-Page": { - "$ref": "#/components/headers/Last-Page" - }, - "First-Page": { - "$ref": "#/components/headers/First-Page" - } - }, - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/subscription" - } - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_2" - } - } - } - } - } - }, - "post": { - "tags": [ - "Subscriptions" - ], - "summary": "Create a subscription", - "parameters": [ - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "requestBody": { - "description": "Parameters used to configure the subscription. It is possible to only receive cirtain types of events by adding filter values to the subscription.\n\nAll values in the subscription body except: callback, secret and subscriptionID will be used as filters. All filters specified must be filfilled in order to match an Event. A logical AND is used between filters. So\n\nshipmentEventTypeCode=DRFT&carrierBookingReference=ABC123123\n\nmeans that the events matched must both be Draft (shipmentEventTypeCode=DRFT) and be connected to carrierBookingReference ABC123123 (carrierBookingReference=ABC123123)\n\nFilters that are specified as (comma separated) lists use logical OR between list values. So\n\neventType=SHIPMENT,TRANSPORT\n\nmeans that both Shipment- and Transport-events will be matched by this subscription.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscriptionBodyWithSecret" - } - } - }, - "required": true - }, - "responses": { - "201": { - "description": "Subscription created", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription" - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_3" - } - } - } - } - }, - "callbacks": { - "event": { - "{$request.body.callbackUrl}": { - "post": { - "parameters": [ - { - "name": "Signature", - "in": "header", - "description": "The signature certifying the request originates from the carrier.\n", - "required": true, - "deprecated": true, - "schema": { - "type": "object", - "properties": { - "keyId": { - "type": "string", - "format": "uuid", - "example": "4fb682bc-3cd1-43a9-a23a-618a61bd87ca" - }, - "created": { - "type": "integer", - "example": 1591960384 - }, - "headers": { - "type": "string", - "example": "(request-target) (created) date host" - }, - "signature": { - "type": "string", - "example": "aGkgZnJvbSBkZW5tYXJr" - } - } - } - }, - { - "name": "Subscription-ID", - "in": "header", - "description": "The ID of the subscription triggering the event being sent.", - "required": true, - "schema": { - "type": "string", - "format": "uuid", - "example": "b80d923d-e8ac-4c34-9506-55d3de347034" - } - }, - { - "name": "Notification-Signature", - "in": "header", - "description": "the Notification-Signature is used to sign the notification. The header has the following format: \n\nNotification-Signature: <signature-type>=<signature>\n\nThe <signature-type> part is a keyword that determines which algorithm was used to compute the signature.\n\nThe signature MUST cover the entire request body of the request including whitespace and newlines. The content MUST decoded into bytes using the UTF-8 encoding before computing the signature. None of the HTTP headers nor the request URL is covered by the signature.\n\nSupported signature typies are:\n- sha256\n\nExample: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de\n", - "required": true, - "schema": { - "pattern": "\\s*([a-zA-Z0-9-_+]+=[0-9a-fA-F]+)\\s*", - "type": "string", - "example": "sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de" - } - }, - { - "name": "API-Version", - "in": "header", - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "required": true, - "schema": { - "type": "string", - "example": "1.0.0" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/transportEvent" - }, - { - "$ref": "#/components/schemas/shipmentEvent" - }, - { - "$ref": "#/components/schemas/equipmentEvent" - } - ] - } - } - } - }, - "required": true - }, - "responses": { - "204": { - "description": "Your server returns this code if it accepts the callback" - } - } - } - } - } - } - } - }, - "/v2/event-subscriptions/{subscriptionID}": { - "get": { - "tags": [ - "Subscriptions" - ], - "summary": "Find a subscription by subscription ID", - "parameters": [ - { - "name": "subscriptionID", - "in": "path", - "description": "The universal unique ID of the subscription.", - "required": true, - "schema": { - "$ref": "#/components/schemas/subscriptionID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "200": { - "description": "Subscription returned", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription" - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_4" - } - } - } - } - } - }, - "put": { - "tags": [ - "Subscriptions" - ], - "summary": "Alter a subscription", - "parameters": [ - { - "name": "subscriptionID", - "in": "path", - "description": "The universal unique ID of the subscription.", - "required": true, - "schema": { - "$ref": "#/components/schemas/subscriptionID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "requestBody": { - "description": "Parameters used to configure the subscription", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "Subscription updated", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription" - } - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_5" - } - } - } - } - } - }, - "delete": { - "tags": [ - "Subscriptions" - ], - "summary": "Stop a subscription, using the subscription ID", - "parameters": [ - { - "name": "subscriptionID", - "in": "path", - "description": "The universal unique ID of the subscription.", - "required": true, - "schema": { - "$ref": "#/components/schemas/subscriptionID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "responses": { - "204": { - "description": "Subscription stopped", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_6" - } - } - } - } - } - } - }, - "/v2/event-subscriptions/{subscriptionID}/secret": { - "put": { - "tags": [ - "Secret" - ], - "summary": "Resets the Secret on an existing subscription.", - "parameters": [ - { - "name": "subscriptionID", - "in": "path", - "description": "The universal unique ID of the subscription.", - "required": true, - "schema": { - "$ref": "#/components/schemas/subscriptionID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - } - ], - "requestBody": { - "description": "Parameters used to configure the subscription", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscriptionID_secret_body" - } - } - }, - "required": true - }, - "responses": { - "204": { - "description": "Secret updated", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - } - }, - "default": { - "description": "Unexpected error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/inline_response_default_7" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "events": { - "type": "array", - "description": "List of events.\n", - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/transportEvent" - }, - { - "$ref": "#/components/schemas/shipmentEvent" - }, - { - "$ref": "#/components/schemas/equipmentEvent" - } - ] - } - }, - "eventTypes": { - "type": "array", - "description": "List of eventType to filter by. If multiple values are selected - the OR-operator will be used.\n\nPossible values are\n- SHIPMENT (Shipment events)\n- TRANSPORT (Transport events)\n- EQUIPMENT (Equipment events)\n\nDefault is none as it will not filter on eventType if not specified.\n", - "example": [ - "TRANSPORT", - "EQUIPMENT" - ], - "items": { - "type": "string", - "enum": [ - "SHIPMENT", - "TRANSPORT", - "EQUIPMENT" - ] - } - }, - "subscriptionBody": { - "required": [ - "callbackUrl" - ], - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "callbackUrl": { - "$ref": "#/components/schemas/callbackUrl" - } - } - }, - { - "type": "object", - "properties": { - "eventType": { - "$ref": "#/components/schemas/eventTypes" - } - } - }, - { - "$ref": "#/components/schemas/shipmentSubscriptionBody" - }, - { - "$ref": "#/components/schemas/transportSubscriptionBody" - }, - { - "$ref": "#/components/schemas/equipmentSubscriptionBody" - } - ] - }, - "subscriptionBodyWithSecret": { - "required": [ - "secret" - ], - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/subscriptionBody" - }, - { - "type": "object", - "properties": { - "secret": { - "allOf": [ - { - "$ref": "#/components/schemas/secret" - }, - { - "description": "A shared secret shared between the Publisher and the Subscriber. It is used to compute the contents of the Notification-Signature header. Only valid in POST calls - anywhere else must be omitted!" - } - ] - } - } - } - ] - }, - "subscription": { - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "subscriptionID": { - "$ref": "#/components/schemas/subscriptionID" - } - } - }, - { - "$ref": "#/components/schemas/subscriptionBody" - } - ] - }, - "shipmentEventTypeCode": { - "type": "string", - "description": "The status of the document in the process. Possible values are\n- RECE (Received)\n- DRFT (Drafted)\n- PENA (Pending Approval)\n- PENU (Pending Update)\n- REJE (Rejected)\n- APPR (Approved)\n- ISSU (Issued)\n- SURR (Surrendered)\n- SUBM (Submitted)\n- VOID (Void)\n- CONF (Confirmed)\n- REQS (Requested)\n- CMPL (Completed)\n- HOLD (On Hold)\n- RELS (Released)\n\nMore details can be found on GitHub\n", - "example": "DRFT", - "enum": [ - "RECE", - "DRFT", - "PENA", - "PENU", - "REJE", - "APPR", - "ISSU", - "SURR", - "SUBM", - "VOID", - "CONF", - "REQS", - "CMPL", - "HOLD", - "RELS" - ] - }, - "documentTypeCode": { - "maxLength": 3, - "type": "string", - "description": "The code to identify the type of information documentID points to. Can be one of the following values\n- CBR (Carrier Booking Request Reference)\n- BKG (Booking)\n- SHI (Shipping Instruction)\n- SRM (Shipment Release Message)\n- TRD (Transport Document)\n- ARN (Arrival Notice)\n- VGM (Verified Gross Mass)\n- CAS (Cargo Survey)\n- CUS (Customs Inspection)\n- DGD (Dangerous Goods Declaration)\n- OOG (Out of Gauge)\n\nMore details can be found on GitHub\n", - "example": "SHI", - "enum": [ - "CBR", - "BKG", - "SHI", - "SRM", - "TRD", - "ARN", - "VGM", - "CAS", - "CUS", - "DGD", - "OOG" - ] - }, - "carrierBookingReference": { - "maxLength": 35, - "type": "string", - "description": "A set of unique characters provided by carrier to identify a booking.", - "example": "ABC709951" - }, - "transportDocumentReference": { - "maxLength": 20, - "type": "string", - "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.\n" - }, - "transportEventTypeCode": { - "type": "string", - "description": "Identifier for type of Transport event\n- ARRI (Arrived)\n- DEPA (Departed)\n\nMore details can be found on GitHub\n", - "example": "ARRI", - "enum": [ - "ARRI", - "DEPA" - ] - }, - "scheduleID": { - "type": "string", - "description": "ID uniquely identifying a schedule", - "format": "uuid", - "example": "9679a405-3316-42a5-8533-aba000f5689c" - }, - "transportCallID": { - "maxLength": 100, - "type": "string", - "description": "The unique identifier for a transport call", - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - "vesselIMONumber": { - "maxLength": 7, - "type": "string", - "description": "The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel\n", - "example": "9321483" - }, - "carrierVoyageNumber": { - "maxLength": 50, - "type": "string", - "description": "The vessel operator-specific identifier of the Voyage.", - "example": "2103S" - }, - "exportVoyageNumber": { - "maxLength": 50, - "type": "string", - "description": "The vessel operator-specific identifier of the export Voyage.", - "example": "2103S" - }, - "carrierServiceCode": { - "maxLength": 5, - "type": "string", - "description": "The code of the service for which the schedule details are published.\n", - "example": "FE1" - }, - "UNLocationCode": { - "maxLength": 5, - "type": "string", - "description": "The UN Location code specifying where the place is located.", - "example": "FRPAR" - }, - "equipmentEventTypeCode": { - "type": "string", - "description": "Unique identifier for equipmentEventTypeCode.\n- LOAD (Loaded)\n- DISC (Discharged)\n- GTIN (Gated in)\n- GTOT (Gated out)\n- STUF (Stuffed)\n- STRP (Stripped)\n- PICK (Pick-up)\n- DROP (Drop-off)\n- INSP (Inspected)\n- RSEA (Resealed)\n- RMVD (Removed)\n\nMore details can be found on GitHub\n", - "example": "LOAD", - "enum": [ - "LOAD", - "DISC", - "GTIN", - "GTOT", - "STUF", - "STRP", - "PICK", - "DROP", - "INSP", - "RSEA", - "RMVD" - ] - }, - "equipmentReference": { - "maxLength": 15, - "type": "string", - "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to ISO 6346, 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, it is suggested to follow Recommendation #2 “Container with non-ISO identification” from SMDG.\n", - "example": "APZU4812090" - }, - "eventCreatedDateTime": { - "type": "string", - "description": "The timestamp of when the event was created.\n\nNB: This field should be considered Metadata\n", - "format": "date-time", - "example": "2021-01-09T14:12:56+01:00" - }, - "transportEvent": { - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/operationsTransportEvent" - }, - { - "type": "object", - "properties": { - "documentReferences": { - "$ref": "#/components/schemas/documentReferences" - } - } - }, - { - "$ref": "#/components/schemas/references" - } - ] - }, - "operationsTransportEvent": { - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/baseEvent" - }, - { - "$ref": "#/components/schemas/baseTransportEvent" - } - ] - }, - "baseEvent": { - "required": [ - "eventCreatedDateTime" - ], - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "eventID": { - "$ref": "#/components/schemas/eventID" - } - } - }, - { - "type": "object", - "properties": { - "eventCreatedDateTime": { - "$ref": "#/components/schemas/eventCreatedDateTime" - } - } - }, - { - "$ref": "#/components/schemas/baseEventBody" - } - ] - }, - "eventID": { - "type": "string", - "description": "The unique identifier for the event (the message - not the source).\n\nNB: This field should be considered Metadata\n", - "format": "uuid", - "example": "3cecb101-7a1a-43a4-9d62-e88a131651e2" - }, - "baseEventBody": { - "required": [ - "eventClassifierCode", - "eventDateTime", - "eventType" - ], - "type": "object", - "description": "The Event entity is described as a generalization of all the specific event categories. An event always takes place in relation to a shipment and can additionally be linked to a transport or an equipment\n", - "allOf": [ - { - "type": "object", - "properties": { - "eventType": { - "$ref": "#/components/schemas/eventType" - } - } - }, - { - "type": "object", - "properties": { - "eventClassifierCode": { - "$ref": "#/components/schemas/eventClassifierCode" - } - } - }, - { - "type": "object", - "properties": { - "eventDateTime": { - "$ref": "#/components/schemas/eventDateTime" - } - } - } - ] - }, - "eventType": { - "type": "string", - "description": "The Event Type of the object - to be used as a discriminator.\n\nNB: This field should be considered Metadata\n" - }, - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier. Values can vary depending on eventType\n" - }, - "eventDateTime": { - "type": "string", - "description": "The local date and time, where the event took place or when the event will take place, in ISO 8601 format.", - "format": "date-time", - "example": "2019-11-12T07:41:00+08:30" - }, - "baseTransportEvent": { - "required": [ - "transportCall", - "transportEventTypeCode" - ], - "type": "object", - "description": "The transport event entity is a specialization of the event entity to support specification of data that only applies to a transport event.\n", - "allOf": [ - { - "type": "object", - "properties": { - "eventType": { - "type": "string", - "example": "TRANSPORT", - "enum": [ - "TRANSPORT" - ] - } - } - }, - { - "type": "object", - "properties": { - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier can be\n- ACT (Actual)\n- PLN (Planned)\n- EST (Estimated)\n", - "example": "ACT", - "enum": [ - "ACT", - "PLN", - "EST" - ] - } - } - }, - { - "type": "object", - "properties": { - "transportEventTypeCode": { - "$ref": "#/components/schemas/transportEventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "delayReasonCode": { - "$ref": "#/components/schemas/delayReasonCode" - } - } - }, - { - "type": "object", - "properties": { - "vesselScheduleChangeRemark": { - "$ref": "#/components/schemas/vesselScheduleChangeRemark" - } - } - }, - { - "type": "object", - "properties": { - "changeRemark": { - "$ref": "#/components/schemas/changeRemark" - } - } - }, - { - "type": "object", - "properties": { - "transportCallID": { - "allOf": [ - { - "$ref": "#/components/schemas/transportCallID" - }, - { - "deprecated": true - }, - { - "description": "The unique identifier for a transport call

Deprecated - not needed as the TransportCall object is included" - } - ] - } - } - }, - { - "type": "object", - "properties": { - "transportCall": { - "$ref": "#/components/schemas/transportCall" - } - } - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "$ref": "#/components/schemas/eventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "type": "string", - "description": "Unique identifier for Event Type Code, for transport events this is either\n- ARRI (Arrival)\n- DEPA (Departure)\n\nDeprecated - use transportEventTypeCode instead\n", - "deprecated": true, - "enum": [ - "ARRI", - "DEPA" - ] - } - } - } - ] - }, - "delayReasonCode": { - "maxLength": 3, - "type": "string", - "description": "Reason code for the delay. The SMDG-Delay-Reason-Codes are used for this attribute. The code list can be found at http://www.smdg.org/smdg-code-lists/", - "example": "WEA" - }, - "vesselScheduleChangeRemark": { - "maxLength": 250, - "type": "string", - "description": "Free text information provided by the vessel operator regarding the reasons for the change in schedule and/or plans to mitigate schedule slippage.\n\nDeprecated - use changeRemark instead\n", - "example": "Bad weather", - "deprecated": true - }, - "changeRemark": { - "maxLength": 250, - "type": "string", - "description": "Free text information provided by the vessel operator regarding the reasons for the change in schedule and/or plans to mitigate schedule slippage.", - "example": "Bad weather" - }, - "transportCall": { - "required": [ - "modeOfTransport", - "transportCallID" - ], - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "transportCallID": { - "$ref": "#/components/schemas/transportCallID" - } - } - }, - { - "type": "object", - "properties": { - "carrierServiceCode": { - "$ref": "#/components/schemas/carrierServiceCode" - } - } - }, - { - "type": "object", - "properties": { - "carrierVoyageNumber": { - "$ref": "#/components/schemas/carrierVoyageNumber" - } - } - }, - { - "type": "object", - "properties": { - "carrierVoyageNumber": { - "description": "The vessel operator-specific identifier of the Voyage.\n\nIn case there are multiple voyages the export voyage is chosen.\n", - "deprecated": true - } - } - }, - { - "type": "object", - "properties": { - "exportVoyageNumber": { - "$ref": "#/components/schemas/exportVoyageNumber" - } - } - }, - { - "type": "object", - "properties": { - "importVoyageNumber": { - "$ref": "#/components/schemas/importVoyageNumber" - } - } - }, - { - "type": "object", - "properties": { - "transportCallSequenceNumber": { - "$ref": "#/components/schemas/transportCallSequenceNumber" - } - } - }, - { - "type": "object", - "properties": { - "UNLocationCode": { - "$ref": "#/components/schemas/UNLocationCode" - } - } - }, - { - "type": "object", - "properties": { - "facilityCode": { - "$ref": "#/components/schemas/facilityCode" - } - } - }, - { - "type": "object", - "properties": { - "facilityCodeListProvider": { - "$ref": "#/components/schemas/facilityCodeListProvider" - } - } - }, - { - "type": "object", - "properties": { - "facilityTypeCode": { - "$ref": "#/components/schemas/facilityTypeCodeTRN" - } - } - }, - { - "type": "object", - "properties": { - "otherFacility": { - "$ref": "#/components/schemas/otherFacility" - } - } - }, - { - "type": "object", - "properties": { - "modeOfTransport": { - "$ref": "#/components/schemas/modeOfTransport" - } - } - }, - { - "type": "object", - "properties": { - "location": { - "allOf": [ - { - "$ref": "#/components/schemas/location" - }, - { - "type": "object", - "description": "Location of the facility. Can often be omitted when it is just repeating the contents of the UNLocationCode field.", - "example": null - } - ] - } - } - }, - { - "type": "object", - "properties": { - "vessel": { - "$ref": "#/components/schemas/vessel" - } - } - } - ] - }, - "importVoyageNumber": { - "maxLength": 50, - "type": "string", - "description": "The vessel operator-specific identifier of the import Voyage.", - "example": "2103N" - }, - "transportCallSequenceNumber": { - "type": "integer", - "description": "Transport operator's key that uniquely identifies each individual call. This key is essential to distinguish between two separate calls at the same location within one voyage.", - "example": 2 - }, - "facilityCode": { - "maxLength": 6, - "type": "string", - "description": "The code used for identifying the specific facility. This code does not include the UN Location Code.\n", - "nullable": false, - "example": "ADT" - }, - "facilityCodeListProvider": { - "type": "string", - "description": "The provider used for identifying the facility Code\n", - "example": "SMDG", - "enum": [ - "BIC", - "SMDG" - ] - }, - "facilityTypeCodeTRN": { - "type": "string", - "description": "A specialized version of the facilityCode to be used in TransportCalls. The code to identify the specific type of facility.\n- BOCR (Border crossing)\n- CLOC (Customer location)\n- COFS (Container freight station)\n- COYA (Deprecated - use OFFD intead)\n- OFFD (Off dock storage)\n- DEPO (Depot)\n- INTE (Inland terminal)\n- POTE (Port terminal)\n- RAMP (Ramp)\n", - "example": "POTE", - "enum": [ - "BOCR", - "CLOC", - "COFS", - "COYA", - "OFFD", - "DEPO", - "INTE", - "POTE", - "RAMP" - ] - }, - "otherFacility": { - "maxLength": 50, - "type": "string", - "description": "An alternative way to capture the facility when no standardized DCSA facility code can be found.", - "example": "Depot location or address" - }, - "modeOfTransport": { - "type": "string", - "description": "The mode of transport as defined by DCSA.\n", - "enum": [ - "VESSEL", - "RAIL", - "TRUCK", - "BARGE" - ] - }, - "location": { - "type": "object", - "description": "generally used to capture location-related data, also for locations without UN Location Codes.\n", - "allOf": [ - { - "type": "object", - "properties": { - "locationName": { - "$ref": "#/components/schemas/locationName" - } - } - }, - { - "type": "object", - "properties": { - "latitude": { - "$ref": "#/components/schemas/latitude" - } - } - }, - { - "type": "object", - "properties": { - "longitude": { - "$ref": "#/components/schemas/longitude" - } - } - }, - { - "type": "object", - "properties": { - "UNLocationCode": { - "$ref": "#/components/schemas/UNLocationCode" - } - } - }, - { - "type": "object", - "properties": { - "facilityCode": { - "$ref": "#/components/schemas/facilityCode" - } - } - }, - { - "type": "object", - "properties": { - "facilityCodeListProvider": { - "$ref": "#/components/schemas/facilityCodeListProvider" - } - } - }, - { - "type": "object", - "properties": { - "address": { - "description": "Address related information", - "allOf": [ - { - "$ref": "#/components/schemas/address" - } - ] - } - } - } - ] - }, - "locationName": { - "maxLength": 100, - "type": "string", - "description": "The name of the location.", - "example": "Eiffel Tower" - }, - "latitude": { - "maxLength": 10, - "type": "string", - "description": "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", - "example": "48.8585500" - }, - "longitude": { - "maxLength": 11, - "type": "string", - "description": "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", - "example": "2.294492036" - }, - "address": { - "type": "object", - "description": "An object for storing address related information", - "allOf": [ - { - "type": "object", - "properties": { - "name": { - "$ref": "#/components/schemas/addressName" - } - } - }, - { - "type": "object", - "properties": { - "street": { - "$ref": "#/components/schemas/streetName" - } - } - }, - { - "type": "object", - "properties": { - "streetNumber": { - "$ref": "#/components/schemas/streetNumber" - } - } - }, - { - "type": "object", - "properties": { - "floor": { - "$ref": "#/components/schemas/floor" - } - } - }, - { - "type": "object", - "properties": { - "postCode": { - "$ref": "#/components/schemas/postCode" - } - } - }, - { - "type": "object", - "properties": { - "city": { - "$ref": "#/components/schemas/cityName" - } - } - }, - { - "type": "object", - "properties": { - "stateRegion": { - "$ref": "#/components/schemas/stateRegion" - } - } - }, - { - "type": "object", - "properties": { - "country": { - "$ref": "#/components/schemas/country" - } - } - } - ] - }, - "addressName": { - "maxLength": 100, - "type": "string", - "description": "Name of the address", - "example": "Henrik" - }, - "streetName": { - "maxLength": 100, - "type": "string", - "description": "The name of the street of the party’s address.", - "example": "Kronprincessegade" - }, - "streetNumber": { - "maxLength": 50, - "type": "string", - "description": "The number of the street of the party’s address.", - "example": "54" - }, - "floor": { - "maxLength": 50, - "type": "string", - "description": "The floor of the party’s street number.", - "example": "5. sal" - }, - "postCode": { - "maxLength": 10, - "type": "string", - "description": "The post code of the party’s address.", - "example": "1306" - }, - "cityName": { - "maxLength": 65, - "type": "string", - "description": "The city name of the party’s address.", - "example": "København" - }, - "stateRegion": { - "maxLength": 65, - "type": "string", - "description": "The state/region of the party’s address.", - "example": "N/A" - }, - "country": { - "maxLength": 75, - "type": "string", - "description": "The country of the party’s address.", - "example": "Denmark" - }, - "vessel": { - "required": [ - "vesselIMONumber" - ], - "type": "object", - "description": "describes a floating, sea going structure (mother vessels and feeder vessels) with either an internal or external mode of propulsion designed for the transport of cargo and/or passengers. Ocean vessels are uniquely identified by an IMO number consisting of 7 digits, or alternatively by their AIS signal with an MMSI number. \n", - "allOf": [ - { - "type": "object", - "properties": { - "vesselIMONumber": { - "$ref": "#/components/schemas/vesselIMONumber" - } - } - }, - { - "type": "object", - "properties": { - "vesselName": { - "$ref": "#/components/schemas/vesselName" - } - } - }, - { - "type": "object", - "properties": { - "vesselFlag": { - "$ref": "#/components/schemas/vesselFlag" - } - } - }, - { - "type": "object", - "properties": { - "vesselCallSignNumber": { - "$ref": "#/components/schemas/vesselCallSignNumber" - } - } - }, - { - "type": "object", - "properties": { - "vesselOperatorCarrierCode": { - "$ref": "#/components/schemas/vesselOperatorCarrierCode" - } - } - }, - { - "type": "object", - "properties": { - "vesselOperatorCarrierCodeListProvider": { - "$ref": "#/components/schemas/vesselOperatorCarrierCodeListProvider" - } - } - } - ] - }, - "vesselName": { - "maxLength": 35, - "type": "string", - "description": "The name of the Vessel given by the Vessel Operator and registered with IMO.\n", - "example": "King of the Seas" - }, - "vesselFlag": { - "maxLength": 2, - "type": "string", - "description": "The flag of the nation whose laws the vessel is registered under. This is the ISO 3166 two-letter country code\n", - "example": "DE" - }, - "vesselCallSignNumber": { - "maxLength": 10, - "type": "string", - "description": "A unique alphanumeric identity that belongs to the vessel and is assigned by the International Telecommunication Union (ITU). It consists of a threeletter alphanumeric prefix that indicates nationality, followed by one to four characters to identify the individual vessel. For instance, vessels registered under Denmark are assigned the prefix ranges 5PA-5QZ, OUAOZZ, and XPA-XPZ. The Call Sign changes whenever a vessel changes its flag.\n", - "example": "NCVV" - }, - "vesselOperatorCarrierCode": { - "maxLength": 10, - "type": "string", - "description": "The carrier who is in charge of the vessel operation based on either the SMDG or SCAC code lists\n", - "nullable": false, - "example": "MAEU" - }, - "vesselOperatorCarrierCodeListProvider": { - "type": "string", - "description": "Identifies the code list provider used for the operator and partner carriercodes.", - "nullable": false, - "example": "NMFTA", - "enum": [ - "SMDG", - "NMFTA" - ] - }, - "eventTypeCode": { - "maxLength": 4, - "type": "string", - "description": "Deprecated - Unique identifier for Event Type Code. This has been replaced by Specialized eventTypeCodes: shipmentEventTypeCode, transportEventTypeCode, equipmentEventTypeCode and opertaionsEventType\n", - "example": "ARRI", - "deprecated": true - }, - "documentReferences": { - "type": "array", - "description": "An optional list of key-value (documentReferenceType-documentReferenceValue) pairs representing links to objects relevant to the event. The documentReferenceType-field is used to describe where the documentReferenceValue-field is pointing to.", - "example": [ - { - "documentReferenceType": "BKG", - "documentReferenceValue": "ABC123123123" - }, - { - "documentReferenceType": "TRD", - "documentReferenceValue": "85943567-eedb-98d3-f4ed-aed697474ed4" - } - ], - "items": { - "$ref": "#/components/schemas/documentReferences_inner" - } - }, - "references": { - "type": "object", - "properties": { - "references": { - "type": "array", - "items": { - "$ref": "#/components/schemas/reference" - } - } - } - }, - "reference": { - "required": [ - "referenceType", - "referenceValue" - ], - "type": "object", - "description": "references provided by the shipper or freight forwarder at the time of booking or at the time of providing shipping instruction. Carriers share it back when providing track and trace event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems.\n", - "allOf": [ - { - "type": "object", - "properties": { - "referenceType": { - "$ref": "#/components/schemas/referenceType" - } - } - }, - { - "type": "object", - "properties": { - "referenceValue": { - "$ref": "#/components/schemas/referenceValue" - } - } - } - ] - }, - "referenceType": { - "type": "string", - "description": "The reference type codes defined by DCSA.\n- FF (Freight Forwarder’s Reference)\n- SI (Shipper’s Reference)\n- PO (Purchase Order Reference)\n- CR (Customer’s Reference)\n- AAO (Consignee’s Reference)\n- EQ (Equipment Reference)\n", - "example": "FF", - "enum": [ - "FF", - "SI", - "PO", - "CR", - "AAO", - "EQ" - ] - }, - "referenceValue": { - "maxLength": 100, - "type": "string", - "description": "The actual value of the reference." - }, - "shipmentEvent": { - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/baseEvent" - }, - { - "$ref": "#/components/schemas/baseShipmentEvent" - } - ] - }, - "baseShipmentEvent": { - "required": [ - "documentID", - "documentTypeCode", - "shipmentEventTypeCode" - ], - "type": "object", - "description": "The shipment event entity is a specialization of the event entity to support specification of data that only applies to a shipment event.\n", - "allOf": [ - { - "type": "object", - "properties": { - "eventType": { - "type": "string", - "example": "SHIPMENT", - "enum": [ - "SHIPMENT" - ] - } - } - }, - { - "type": "object", - "properties": { - "eventDateTime": { - "description": "Value for eventDateTime must be the same value as eventCreatedDateTime\n" - } - } - }, - { - "type": "object", - "properties": { - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier can be\n- ACT (Actual)\n- PLN (Planned)\n- EST (Estimated)\n", - "example": "ACT", - "enum": [ - "ACT", - "PLN", - "EST" - ] - } - } - }, - { - "type": "object", - "properties": { - "shipmentEventTypeCode": { - "$ref": "#/components/schemas/shipmentEventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "documentID": { - "$ref": "#/components/schemas/documentID" - } - } - }, - { - "type": "object", - "properties": { - "documentTypeCode": { - "$ref": "#/components/schemas/documentTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "shipmentInformationTypeCode": { - "$ref": "#/components/schemas/shipmentInformationType" - } - } - }, - { - "type": "object", - "properties": { - "reason": { - "$ref": "#/components/schemas/reason" - } - } - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "$ref": "#/components/schemas/eventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "type": "string", - "description": "Unique identifier for Event Type Code. For shipment events this can be\n- RECE (Received)\n- CONF (Confirmed)\n- ISSU (Issued)\n- APPR (Approved)\n- SUBM (Submitted)\n- SURR (Surrendered)\n- REJE (Rejected)\n- PENA (Pending approval)\n\nDeprecated - use shipmentEventTypeCode instead\n", - "example": "RECE", - "deprecated": true, - "enum": [ - "RECE", - "CONF", - "ISSU", - "APPR", - "SUBM", - "SURR", - "REJE", - "PENA" - ] - } - } - }, - { - "type": "object", - "properties": { - "shipmentID": { - "$ref": "#/components/schemas/shipmentID" - } - } - }, - { - "type": "object", - "properties": { - "shipmentID": { - "description": "ID uniquely identifying a shipment.\n\nDeprecated - this is replaced by documentID which can contain different values depending on the value of the documentTypeCode field\n", - "deprecated": true - } - } - }, - { - "$ref": "#/components/schemas/references" - } - ] - }, - "documentID": { - "type": "string", - "description": "The id of the object defined by the documentTypeCode.\n", - "example": "the-id-of-the-documentTypeCode" - }, - "shipmentInformationType": { - "maxLength": 3, - "type": "string", - "description": "The code to identify the type of information documentID points to. Can be one of the following values\n- BOK (Booking - deprecated use BKG instead)\n- BKG (Booking)\n- SHI (Shipping Instruction)\n- VGM (Verified Gross Mass)\n- SRM (Shipment Release Message)\n- TRD (Transport Document)\n- ARN (Arrival Notice)\n\nDeprecated - use documentTypeCode instead\n", - "example": "SHI", - "deprecated": true, - "enum": [ - "BOK", - "BKG", - "SHI", - "VGM", - "SRM", - "TRD", - "ARN" - ] - }, - "reason": { - "type": "string", - "description": "Reason field in a Shipment event. This field can be used to explain why a specific event has been sent.", - "example": "The following attributes are missing..." - }, - "shipmentID": { - "type": "string", - "description": "The identifier for a shipment", - "format": "uuid", - "example": "c32d56f3-a4a5-4964-bb49-abd168b06160" - }, - "equipmentEvent": { - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/baseEvent" - }, - { - "$ref": "#/components/schemas/baseEquipmentEvent" - } - ] - }, - "baseEquipmentEvent": { - "required": [ - "emptyIndicatorCode", - "equipmentEventTypeCode" - ], - "type": "object", - "description": "The equipment event entity is a specialization of the event entity to support specification of data that only applies to an equipment event.\n", - "allOf": [ - { - "type": "object", - "properties": { - "eventType": { - "type": "string", - "example": "EQUIPMENT", - "enum": [ - "EQUIPMENT" - ] - } - } - }, - { - "type": "object", - "properties": { - "eventClassifierCode": { - "type": "string", - "description": "Code for the event classifier can be\n- PLN (Planned)\n- ACT (Actual)\n- EST (Estimated)\n", - "example": "EST", - "enum": [ - "PLN", - "ACT", - "EST" - ] - } - } - }, - { - "type": "object", - "properties": { - "equipmentEventTypeCode": { - "$ref": "#/components/schemas/equipmentEventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "equipmentReference": { - "$ref": "#/components/schemas/equipmentReference" - } - } - }, - { - "type": "object", - "properties": { - "ISOEquipmentCode": { - "$ref": "#/components/schemas/ISOEquipmentCode" - } - } - }, - { - "type": "object", - "properties": { - "emptyIndicatorCode": { - "$ref": "#/components/schemas/emptyIndicatorCode" - } - } - }, - { - "type": "object", - "properties": { - "eventLocation": { - "$ref": "#/components/schemas/location" - } - } - }, - { - "type": "object", - "properties": { - "transportCallID": { - "allOf": [ - { - "$ref": "#/components/schemas/transportCallID" - }, - { - "deprecated": true - }, - { - "description": "The unique identifier for a transport call

Deprecated - not needed as the TransportCall object is included" - } - ] - } - } - }, - { - "type": "object", - "properties": { - "transportCall": { - "$ref": "#/components/schemas/transportCall" - } - } - }, - { - "type": "object", - "properties": { - "documentReferences": { - "$ref": "#/components/schemas/documentReferences" - } - } - }, - { - "$ref": "#/components/schemas/references" - }, - { - "$ref": "#/components/schemas/seals" - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "$ref": "#/components/schemas/eventTypeCode" - } - } - }, - { - "type": "object", - "properties": { - "eventTypeCode": { - "type": "string", - "description": "Unique identifier for Event Type Code, for transport events this is either\n- LOAD (Loaded)\n- DISC (Discharged)\n- GTIN (Gated in)\n- GTOT (Gated out)\n- STUF (Stuffed)\n- STRP (Stripped)\n\nDeprecated - use equipmentEventTypeCode instead\n", - "deprecated": true, - "enum": [ - "LOAD", - "DISC", - "GTIN", - "GTOT", - "STUF", - "STRP" - ] - } - } - } - ] - }, - "ISOEquipmentCode": { - "maxLength": 4, - "type": "string", - "description": "Unique code for the different equipment size/type used for transporting commodities. The code is a concatenation of ISO Equipment Size Code and ISO Equipment Type Code A and follows the ISO 6346 standard.", - "example": "22GP" - }, - "emptyIndicatorCode": { - "type": "string", - "description": "Code to denote whether the equipment is empty or laden.", - "example": "EMPTY", - "enum": [ - "EMPTY", - "LADEN" - ] - }, - "seals": { - "type": "object", - "properties": { - "seals": { - "type": "array", - "items": { - "$ref": "#/components/schemas/seal" - } - } - } - }, - "seal": { - "required": [ - "sealNumber", - "sealType" - ], - "type": "object", - "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.", - "allOf": [ - { - "type": "object", - "properties": { - "sealNumber": { - "$ref": "#/components/schemas/sealNumber" - } - } - }, - { - "type": "object", - "properties": { - "sealSource": { - "$ref": "#/components/schemas/sealSource" - } - } - }, - { - "type": "object", - "properties": { - "sealType": { - "$ref": "#/components/schemas/sealType" - } - } - } - ] - }, - "sealNumber": { - "maxLength": 15, - "type": "string", - "description": "Identifies a seal affixed to the container." - }, - "sealSource": { - "type": "string", - "description": "The source of the seal, namely who has affixed the seal. This attribute links to the Seal Source ID defined in the Seal Source reference data entity.\n- CAR (Carrier)\n- SHI (Shipper)\n- PHY (Phytosanitary)\n- VET (Veterinary)\n- CUS (Customs)\n", - "example": "CUS", - "enum": [ - "CAR", - "SHI", - "PHY", - "VET", - "CUS" - ] - }, - "sealType": { - "type": "string", - "description": "The type of seal. This attribute links to the Seal Type ID defined in the Seal Type reference data entity.\n- KLP (Keyless padlock)\n- BLT (Bolt)\n- WIR (Wire)\n", - "example": "WIR", - "enum": [ - "KLP", - "BLT", - "WIR" - ] - }, - "error": { - "required": [ - "errorDateTime", - "errors", - "httpMethod", - "requestUri", - "statusCode", - "statusCodeText" - ], - "type": "object", - "properties": { - "httpMethod": { - "type": "string", - "description": "The HTTP request method type", - "example": "POST" - }, - "requestUri": { - "type": "string", - "description": "The request URI.", - "example": "https://dcsa.org/dcsa/tnt/v1/events" - }, - "errors": { - "$ref": "#/components/schemas/subErrors" - }, - "statusCode": { - "type": "integer", - "description": "The HTTP status code", - "example": 400 - }, - "statusCodeText": { - "type": "string", - "description": "The textual representation of the response status.", - "example": "Bad Request" - }, - "errorDateTime": { - "type": "string", - "description": "The date and time (in ISO 8601 format) the error occurred.", - "format": "$date-time", - "example": "2019-11-12T07:41:00+08:30" - } - } - }, - "subErrors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/subErrors_inner" - } - }, - "subscriptionID": { - "type": "string", - "description": "The carrier issues a unique ID to the shipper or consignee for that subscription", - "format": "uuid", - "example": "8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809" - }, - "secret": { - "type": "string", - "description": "A Base64 encoded secret shared between the Publisher and the Subscriber.\nIt is used to compute the contents of the Notification-Signature header.\n", - "format": "byte", - "example": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDM2NTc4NjIzODk3NDY5MDgyNzM0OTg3MTIzNzg2NA==" - }, - "callbackUrl": { - "type": "string", - "description": "The endPoint where a Carrier whould send back events to the Shipper. The callback can contain query parameters uniquely identifying the originator of the events.\n", - "format": "uri", - "example": "https://myserver.com/send/callback/here?shipperRef=" - }, - "shipmentSubscriptionBody": { - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "shipmentEventTypeCode": { - "$ref": "#/components/schemas/shipmentEventTypeCodes" - } - } - }, - { - "type": "object", - "properties": { - "documentTypeCode": { - "$ref": "#/components/schemas/documentTypeCodes" - } - } - }, - { - "type": "object", - "properties": { - "carrierBookingReference": { - "$ref": "#/components/schemas/carrierBookingReference" - } - } - }, - { - "type": "object", - "properties": { - "bookingReference": { - "maxLength": 35, - "type": "string", - "description": "The identifier for a shipment, which is issued by and unique within each of the carriers.\n\nDeprecated - use carrierBookingReference instead\n", - "example": "ABC709951", - "deprecated": true - } - } - }, - { - "type": "object", - "properties": { - "transportDocumentID": { - "type": "string", - "description": "Uniquely identify a transport document.\n\nDeprecated - use transportDocumentReference instead\n", - "format": "uuid", - "deprecated": true - } - } - }, - { - "type": "object", - "properties": { - "transportDocumentReference": { - "$ref": "#/components/schemas/transportDocumentReference" - } - } - }, - { - "type": "object", - "properties": { - "transportDocumentTypeCode": { - "allOf": [ - { - "$ref": "#/components/schemas/transportDocumentTypeCodes" - }, - { - "deprecated": true - }, - { - "description": "List of transportDocumentType to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on transportDocumentType if not specified.\n\nDeprecated: Not to be used any more\n" - } - ] - } - } - } - ] - }, - "shipmentEventTypeCodes": { - "type": "array", - "description": "List of shipmentEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on shipmentEventTypeCode if not specified.\n", - "example": [ - "RECE", - "DRFT" - ], - "items": { - "$ref": "#/components/schemas/shipmentEventTypeCode" - } - }, - "documentTypeCodes": { - "type": "array", - "description": "List of documentTypeCode to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on documentTypeCode if not specified.\n", - "example": [ - "SHI", - "TRD" - ], - "items": { - "$ref": "#/components/schemas/documentTypeCode" - } - }, - "transportDocumentTypeCodes": { - "type": "array", - "description": "List of transportDocumentType to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on transportDocumentType if not specified.\n", - "example": [ - "BOL" - ], - "items": { - "$ref": "#/components/schemas/transportDocumentType" - } - }, - "transportDocumentType": { - "type": "string", - "description": "Specifies the type of the transport document (a Bill of Lading (BOL) or a Sea Waybill (SWB)).", - "example": "SWB", - "enum": [ - "BOL", - "SWB" - ] - }, - "transportSubscriptionBody": { - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "transportEventTypeCode": { - "$ref": "#/components/schemas/transportEventTypeCodes" - } - } - }, - { - "type": "object", - "properties": { - "scheduleID": { - "allOf": [ - { - "$ref": "#/components/schemas/scheduleID" - }, - { - "deprecated": true - }, - { - "description": "ID uniquely identifying a schedul.
Deprecated as this was added by mistake" - } - ] - } - } - }, - { - "type": "object", - "properties": { - "transportCallID": { - "$ref": "#/components/schemas/transportCallID" - } - } - }, - { - "type": "object", - "properties": { - "vesselIMONumber": { - "$ref": "#/components/schemas/vesselIMONumber" - } - } - }, - { - "type": "object", - "properties": { - "carrierVoyageNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/carrierVoyageNumber" - }, - { - "deprecated": true - } - ] - } - } - }, - { - "type": "object", - "properties": { - "exportVoyageNumber": { - "$ref": "#/components/schemas/exportVoyageNumber" - } - } - }, - { - "type": "object", - "properties": { - "carrierServiceCode": { - "$ref": "#/components/schemas/carrierServiceCode" - } - } - }, - { - "type": "object", - "properties": { - "UNLocationCode": { - "$ref": "#/components/schemas/UNLocationCode" - } - } - } - ] - }, - "transportEventTypeCodes": { - "type": "array", - "description": "List of transportEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on transportEventTypeCode if not specified.\n", - "example": [ - "ARRI", - "DEPA" - ], - "items": { - "$ref": "#/components/schemas/transportEventTypeCode" - } - }, - "equipmentSubscriptionBody": { - "type": "object", - "allOf": [ - { - "type": "object", - "properties": { - "equipmentEventTypeCode": { - "$ref": "#/components/schemas/equipmentEventTypeCodes" - } - } - }, - { - "type": "object", - "properties": { - "equipmentReference": { - "$ref": "#/components/schemas/equipmentReference" - } - } - }, - { - "type": "object", - "properties": { - "UNLocationCode": { - "$ref": "#/components/schemas/UNLocationCode" - } - } - } - ] - }, - "equipmentEventTypeCodes": { - "type": "array", - "description": "List of equipmentEventTypeCode to filter by. If multiple values are selected - the OR-operator will be used.\n\nDefault is none as it will not filter on equipmentEventTypeCode if not specified.\n", - "example": [ - "GTIN", - "GTOT" - ], - "items": { - "$ref": "#/components/schemas/equipmentEventTypeCode" - } - }, - "inline_response_default": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "GET" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/events" - } - } - } - ] - }, - "inline_response_200": { - "example": { - "eventID": "84db923d-2a19-4eb0-beb5-446c1ec57d34", - "eventType": "SHIPMENT", - "eventCreatedDateTime": "2019-11-12T07:41:00+08:30", - "eventSubtype": "ISSU", - "documentID": "84db923d-2a19-4eb0-beb5-446c1ec57d34", - "documentTypeCode": "TRD", - "reason": "All good" - }, - "discriminator": { - "propertyName": "eventType" - }, - "oneOf": [ - { - "$ref": "#/components/schemas/shipmentEvent" - }, - { - "$ref": "#/components/schemas/transportEvent" - }, - { - "$ref": "#/components/schemas/equipmentEvent" - } - ] - }, - "inline_response_default_1": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "GET" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/events/123e4567-e89b-12d3-a456-426614174000" - } - } - } - ] - }, - "inline_response_default_2": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "GET" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions" - } - } - } - ] - }, - "inline_response_default_3": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "POST" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions" - } - } - } - ] - }, - "inline_response_default_4": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "GET" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809" - } - } - } - ] - }, - "inline_response_default_5": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "PUT" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809" - } - } - } - ] - }, - "inline_response_default_6": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "DELETE" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809" - } - } - } - ] - }, - "subscriptionID_secret_body": { - "allOf": [ - { - "type": "object", - "properties": { - "secret": { - "$ref": "#/components/schemas/secret" - } - } - } - ] - }, - "inline_response_default_7": { - "allOf": [ - { - "$ref": "#/components/schemas/error" - }, - { - "type": "object", - "properties": { - "httpMethod": { - "example": "PUT" - } - } - }, - { - "type": "object", - "properties": { - "requestUri": { - "example": "https://dcsa.org/dcsa/tnt/v2/event-subscriptions/8fbdc2d8-57c8-48b9-a04b-18fd8ec1d809/secret" - } - } - } - ] - }, - "documentReferences_inner": { - "type": "object", - "properties": { - "documentReferenceType": { - "type": "string", - "description": "Describes where the documentReferenceValue is pointing to", - "example": "BKG", - "enum": [ - "BKG", - "TRD" - ] - }, - "documentReferenceValue": { - "type": "string", - "description": "The value of the identifier the documentReferenceType is describing", - "example": "123e4567-e89b-12d3-a456-426614174000" - } - } - }, - "subErrors_inner": { - "required": [ - "message", - "reason" - ], - "type": "object", - "properties": { - "reason": { - "type": "string", - "description": "High level error message.", - "example": "invalidQuery" - }, - "message": { - "type": "string", - "description": "Detailed error message.", - "example": "The request did not contain one of the three required query parameters." - } - } - } - }, - "parameters": { - "shipmentEventTypeCode": { - "name": "shipmentEventTypeCode", - "in": "query", - "description": "The status of the document in the process to filter by. Possible values are\n- RECE (Received)\n- DRFT (Drafted)\n- PENA (Pending Approval)\n- PENU (Pending Update)\n- REJE (Rejected)\n- APPR (Approved)\n- ISSU (Issued)\n- SURR (Surrendered)\n- SUBM (Submitted)\n- VOID (Void)\n- CONF (Confirmed)\n- REQS (Requested)\n- CMPL (Completed)\n- HOLD (On Hold)\n- RELS (Released)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example shipmentEventTypeCode=RECE,DRFT Matches both Received (RECE) and Drafted (DRFT) shipment events.\n\nDefault is all shipmentEventTypeCodes.\n\nThis filter is only relevant when filtering on ShipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/shipmentEventTypeCode" - }, - "default": "RECE,DRFT,PENA,PENU,REJE,APPR,ISSU,SURR,SUBM,VOID,CONF,REQS,CMPL,HOLD,RELS" - }, - "example": "RECE,DRFT" - }, - "documentTypeCode": { - "name": "documentTypeCode", - "in": "query", - "description": "The documentTypeCode to filter by. Possible values are\n- CBR (Carrier Booking Request Reference)\n- BKG (Booking)\n- SHI (Shipping Instruction)\n- SRM (Shipment Release Message)\n- TRD (Transport Document)\n- ARN (Arrival Notice)\n- VGM (Verified Gross Mass)\n- CAS (Cargo Survey)\n- CUS (Customs Inspection)\n- DGD (Dangerous Goods Declaration)\n- OOG (Out of Gauge)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example documentTypeCode=SHI,TRD Matches both ShippingInstruction (SHI) and TransportDocument (TRD) shipment events.\n\nDefault is all documentTypeCodes.\n\nThis filter is only relevant when filtering on ShipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/documentTypeCode" - }, - "default": "CBR,BKG,SHI,SRM,TRD,ARN,VGM,CAS,CUS,DGD,OOG" - }, - "example": "SHI,TRD" - }, - "carrierBookingReference": { - "name": "carrierBookingReference", - "in": "query", - "description": "A set of unique characters provided by carrier to identify a booking.\n\nSpecifying this filter will only return events related to this particular carrierBookingReference.\n", - "schema": { - "$ref": "#/components/schemas/carrierBookingReference" - } - }, - "bookingReference": { - "name": "bookingReference", - "in": "query", - "description": "Deprecated - use carrierBookingReference instead.", - "required": false, - "deprecated": true, - "schema": { - "type": "string" - } - }, - "transportDocumentID": { - "name": "transportDocumentID", - "in": "query", - "description": "A unique id to identify a transport document.\n\nDeprecated - use transportDocumentReference instead transportDocumentReference\n", - "deprecated": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - "transportDocumentReference": { - "name": "transportDocumentReference", - "in": "query", - "description": "A unique number reference allocated by the shipping line to the transport document and the main number used for the tracking of the status of the shipment.\n\nSpecifying this filter will only return events related to this particular transportDocumentReference\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/transportDocumentReference" - } - }, - "transportEventTypeCode": { - "name": "transportEventTypeCode", - "in": "query", - "description": "Identifier for type of Transport event to filter by\n- ARRI (Arrived)\n- DEPA (Departed)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example transportEventTypeCode=ARRI,DEPA matches both Arrived (ARRI) and Departed (DEPA) transport events.\n\nDefault is all transportEventTypeCodes.\n\nThis filter is only relevant when filtering on TransportEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/transportEventTypeCode" - }, - "default": "ARRI,DEPA" - }, - "example": "ARRI,DEPA" - }, - "scheduleID": { - "name": "scheduleID", - "in": "query", - "description": "ID uniquely identifying a schedule, to filter events by.\n\nThis filter was added by mistake and is thus deprecated.\n", - "required": false, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/scheduleID" - } - }, - "transportCallID": { - "name": "transportCallID", - "in": "query", - "description": "ID uniquely identifying a transport call, to filter events by.\n\nSpecifying this filter will only return events related to this particular transportCallID\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/transportCallID" - } - }, - "vesselIMONumber": { - "name": "vesselIMONumber", - "in": "query", - "description": "The identifier of vessel for which schedule details are published. Depending on schedule type, this may not be available yet.\n\nSpecifying this filter will only return events related to this particular vesselIMONumber.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/vesselIMONumber" - } - }, - "carrierVoyageNumber": { - "name": "carrierVoyageNumber", - "in": "query", - "description": "Filter on the vessel operator-specific identifier of the Voyage.\n\nSpecifying this filter will only return events related to this particular carrierVoyageNumber.\n\nDeprecated: Use exportVoyageNumber instead\n", - "required": false, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/carrierVoyageNumber" - } - }, - "exportVoyageNumber": { - "name": "exportVoyageNumber", - "in": "query", - "description": "Filter on the vessel operator-specific identifier of the export Voyage.\n\nSpecifying this filter will only return events related to this particular exportVoyageNumber.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/exportVoyageNumber" - } - }, - "carrierServiceCode": { - "name": "carrierServiceCode", - "in": "query", - "description": "Filter on the carrier specific identifier of the service.\n\nSpecifying this filter will only return events related to this particular carrierServiceCode.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/carrierServiceCode" - } - }, - "UNLocationCode": { - "name": "UNLocationCode", - "in": "query", - "description": "The UN Location code specifying where the place is located.\n\nSpecifying this filter will only return events related to this particular UN Location code.\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/UNLocationCode" - } - }, - "equipmentEventTypeCode": { - "name": "equipmentEventTypeCode", - "in": "query", - "description": "Unique identifier for equipmentEventTypeCode.\n- LOAD (Loaded)\n- DISC (Discharged)\n- GTIN (Gated in)\n- GTOT (Gated out)\n- STUF (Stuffed)\n- STRP (Stripped)\n- PICK (Pick-up)\n- DROP (Drop-off)\n- INSP (Inspected)\n- RSEA (Resealed)\n- RMVD (Removed)\n\nIt is possible to select multiple values by comma (,) separating them. For multiple values the OR-operator is used. For example equipmentEventTypeCode=GTIN,GTOT matches both Gated in (GTIN) and Gated out (GTOT) equipment events.\n\nDefault is all equipmentEventTypeCodes.\n\nThis filter is only relevant when filtering on EquipmentEvents\n", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/equipmentEventTypeCode" - }, - "default": "LOAD,DISC,GTIN,GTOT,STUF,STRP,PICK,DROP,INSP,RSEA,RMVD" - }, - "example": "GTIN,GTOT" - }, - "equipmentReference": { - "name": "equipmentReference", - "in": "query", - "description": "Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\n\nSpecifying this filter will only return events related to this particular equipmentReference\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/equipmentReference" - } - }, - "eventCreatedDateTime": { - "name": "eventCreatedDateTime", - "in": "query", - "description": "Limit the result based on the creating date of the event. It is possible to use operators on this query parameter. This is done by adding a colon followed by an operator at the end of the queryParameterName (before the =)\n\neventCreatedDateTime:gte=2021-04-01T14:12:56+01:00\n\nwould result in all events created ≥ 2021-04-01T14:12:56+01:00\n\nThe following operators are supported\n- :gte (≥ Greater than or equal)\n- :gt (> Greater than)\n- :lte (≤ Less than or equal)\n- :lt (< Less than)\n- :eq (= Equal to)\n\nIf no operator is provided, a strictly equal is used (this is equivalent to :eq operator).\n", - "required": false, - "schema": { - "$ref": "#/components/schemas/eventCreatedDateTime" - }, - "example": "2021-04-01T14:12:56+01:00" - }, - "limit": { - "name": "limit", - "in": "query", - "description": "Maximum number of items to return.", - "required": false, - "schema": { - "minimum": 1, - "type": "integer", - "format": "int32", - "default": 100 - }, - "example": 100 - }, - "cursor": { - "name": "cursor", - "in": "query", - "description": "A server generated value to specify a specific point in a collection result, used for pagination.", - "required": false, - "schema": { - "type": "string" - }, - "example": "fE9mZnNldHw9MTAmbGltaXQ9MTA=" - }, - "sort": { - "name": "sort", - "in": "query", - "description": "A comma-separated list of field names to define the sort order. Field names should be suffixed by a (:) followed by either the keyword ASC (for ascending order) or DESC (for descening order) to specify direction. :ASC may be omitted, in which case ascending order will be used.\n", - "required": false, - "schema": { - "type": "string" - }, - "example": "carrierBookingReference:DESC" - }, - "Api-Version-Major": { - "name": "API-Version", - "in": "header", - "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.\n", - "required": false, - "schema": { - "type": "string", - "example": "1" - } - }, - "eventID": { - "name": "eventID", - "in": "path", - "description": "The ID of the event to receive", - "required": true, - "deprecated": true, - "schema": { - "$ref": "#/components/schemas/eventID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - }, - "signatureHeader": { - "name": "Signature", - "in": "header", - "description": "The signature certifying the request originates from the carrier.\n", - "required": true, - "deprecated": true, - "schema": { - "type": "object", - "properties": { - "keyId": { - "type": "string", - "format": "uuid", - "example": "4fb682bc-3cd1-43a9-a23a-618a61bd87ca" - }, - "created": { - "type": "integer", - "example": 1591960384 - }, - "headers": { - "type": "string", - "example": "(request-target) (created) date host" - }, - "signature": { - "type": "string", - "example": "aGkgZnJvbSBkZW5tYXJr" - } - } - } - }, - "subscriptionIDHeader": { - "name": "Subscription-ID", - "in": "header", - "description": "The ID of the subscription triggering the event being sent.", - "required": true, - "schema": { - "type": "string", - "format": "uuid", - "example": "b80d923d-e8ac-4c34-9506-55d3de347034" - } - }, - "notificationSignature": { - "name": "Notification-Signature", - "in": "header", - "description": "the Notification-Signature is used to sign the notification. The header has the following format: \n\nNotification-Signature: <signature-type>=<signature>\n\nThe <signature-type> part is a keyword that determines which algorithm was used to compute the signature.\n\nThe signature MUST cover the entire request body of the request including whitespace and newlines. The content MUST decoded into bytes using the UTF-8 encoding before computing the signature. None of the HTTP headers nor the request URL is covered by the signature.\n\nSupported signature typies are:\n- sha256\n\nExample: sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de\n", - "required": true, - "schema": { - "pattern": "\\s*([a-zA-Z0-9-_+]+=[0-9a-fA-F]+)\\s*", - "type": "string", - "example": "sha256=ae688919f5e31f4c210ca6af362ce4d9ed87acfb51c1721a8507ee395de5e2de" - } - }, - "apiVersion": { - "name": "API-Version", - "in": "header", - "description": "SemVer used to indicate the version of the contract (API version) returned.\n", - "required": true, - "schema": { - "type": "string", - "example": "1.0.0" - } - }, - "subscriptionID": { - "name": "subscriptionID", - "in": "path", - "description": "The universal unique ID of the subscription.", - "required": true, - "schema": { - "$ref": "#/components/schemas/subscriptionID" - }, - "example": "123e4567-e89b-12d3-a456-426614174000" - } - }, - "headers": { - "API-Version": { - "description": "SemVer used to indicate the version of the contract (API version) returned.", - "schema": { - "type": "string", - "example": "1.0.0" - } - }, - "Current-Page": { - "description": "A link to the current page.", - "required": true, - "schema": { - "type": "string", - "example": "fE9mZnNldHw9MCZsaW1pdD01" - } - }, - "Next-Page": { - "description": "A link to the next page. Next-Page header link MAY be omitted if the current page is the last page.", - "required": false, - "schema": { - "type": "string", - "example": "fE9mZnNldHw9NSZsaW1pdD01" - } - }, - "Prev-Page": { - "description": "A link to the previous page. Previous-Page header link MAY be omitted if the current page is the first page.", - "required": false, - "schema": { - "type": "string", - "example": "fE9mZnNldHw9MCZsaW1pdD01" - } - }, - "Last-Page": { - "description": "A link to the last page. Last-Page header link MAY be omitted if the current page is the last page.", - "required": false, - "schema": { - "type": "string", - "example": "fE9mZnNldHw9NTkmbGltaXQ9NQ==" - } - }, - "First-Page": { - "description": "A link to thefirst page. First-Page header link MAY be omitted if current page is the first page.", - "required": false, - "schema": { - "type": "string", - "example": "fE9mZnNldHw9NjAmbGltaXQ9NQ==" - } - } - } - } -} \ No newline at end of file