From 4497f7a8759445b610dd15a4ff05feda314b5120 Mon Sep 17 00:00:00 2001 From: Niels Thykier Date: Thu, 26 Sep 2024 09:40:42 +0200 Subject: [PATCH 1/5] DT-1688: Schema update The schema change required some minor changes unrelated to this issue to keep tests green. --- .../messages/eblissuance-v3.0.0-request.json | 2 +- .../schemas/eblissuance-v3.0.0.json | 6143 +++--- .../schemas/eblsurrender-v3.0.0.json | 1044 +- .../standards/ebl/EblScenarioListBuilder.java | 33 +- ...mitUpdatedShippingInstructionsAction.java} | 4 +- ...r_ApproveDraftTransportDocumentAction.java | 10 - .../standards/ebl/party/EblShipper.java | 2 +- .../ebl/messages/ebl-api-3.0.0-2c2u1e.json | 4 +- .../ebl/messages/ebl-api-3.0.0-2c2u2e.json | 8 +- .../ebl/messages/ebl-api-3.0.0-amf.json | 2 +- .../ebl/messages/ebl-api-3.0.0-clad.json | 2 +- .../ebl/messages/ebl-api-3.0.0-dg.json | 2 +- .../messages/ebl-api-3.0.0-negotiable-bl.json | 2 +- ...l-api-3.0.0-no-commodity-subreference.json | 2 +- .../ebl/messages/ebl-api-3.0.0-request.json | 2 +- .../ebl-api-3.0.0-soc-references.json | 8 +- .../standards/ebl/schemas/ebl-api-3.0.0.json | 17639 ++++++++-------- .../pint-3.0.0-transport-document.json | 2 +- .../standards/pint/schemas/pint-3.0.0.json | 7201 +++---- 19 files changed, 16072 insertions(+), 16040 deletions(-) rename ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/{UC3_Shipper_SubmitUpdatedShippingInstructionsAction.java => UC3ShipperSubmitUpdatedShippingInstructionsAction.java} (96%) diff --git a/ebl-issuance/src/main/resources/standards/eblissuance/messages/eblissuance-v3.0.0-request.json b/ebl-issuance/src/main/resources/standards/eblissuance/messages/eblissuance-v3.0.0-request.json index ccbe4a74..fd5f96b1 100644 --- a/ebl-issuance/src/main/resources/standards/eblissuance/messages/eblissuance-v3.0.0-request.json +++ b/ebl-issuance/src/main/resources/standards/eblissuance/messages/eblissuance-v3.0.0-request.json @@ -87,7 +87,7 @@ "cargoItems": [ { "equipmentReference": "NARU3472484", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 index 06af131d..41f31271 100644 --- 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 @@ -1,3030 +1,3151 @@ { - "openapi": "3.0.3", - "info": { - "title": "DCSA OpenAPI specification for Issuance an EBL to an EBL platform.\n", - "description": "This API is intended as an API between a carrier and a EBL Solution Platform.\n\nThe EBL Solution Provider is to implement\n\n /v3/ebl-issuance-requests\n\nfor the carrier to call and the carrier is to implement\n\n /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\nAPI specification issued by DCSA.org.\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", - "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 successful", - "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://en.wikipedia.org/wiki/ISO_8601) 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://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" - }, - "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==" - } - } - }, - "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" + "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" + } }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "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 `NMFTA` or `SMDG` code of the issuing carrier of the `Transport Document`\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" - ] - }, - "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/Place of Issue" - }, - "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" - } - } - } - ] - }, - "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/Document Parties" - }, - "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", - "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" + "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" + } }, - "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" + "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" ], - "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" + "title" : "Address", + "type" : "object" + }, + "Cargo Gross Volume" : { + "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" ], - "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" - }, - "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", - "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", - "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/Reference" - } - }, - "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" + "title" : "Cargo Gross Volume", + "type" : "object" + }, + "Cargo Gross Weight" : { + "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" ], - "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": [ - "equipmentReference", - "grossWeight", - "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://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" - }, - "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" - }, - "grossVolume": { - "$ref": "#/components/schemas/Gross Volume" - }, - "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" - }, - "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": { - "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/Gross Weight_1" - }, - "netWeight": { - "$ref": "#/components/schemas/Net Weight" - }, - "netExplosiveContent": { - "$ref": "#/components/schemas/Net Explosive Content" - }, - "netVolume": { - "$ref": "#/components/schemas/Net Volume" - }, - "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" + "title" : "Cargo Gross Weight", + "type" : "object" + }, + "Cargo Net Volume" : { + "description" : "Calculated by multiplying the width, height, and length of the packed 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 packed cargo, excluding packaging.\n", + "example" : 2.4, + "exclusiveMinimum" : true, + "format" : "float", + "minimum" : 0, + "type" : "number" + } + }, + "required" : [ + "unit", + "value" ], - "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" + "title" : "Cargo Net Volume", + "type" : "object" + }, + "Cargo Net Weight" : { + "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" ], - "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": "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\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", - "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://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" - }, - "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": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "weightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n\n**Condition:** Mandatory to provide if `tareWeight` is provided\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "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" - }, - "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 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": "N/A" - }, - "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" - }, - "City": { - "title": "City", - "required": [ - "city", - "countryCode" - ], - "type": "object", - "properties": { - "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.\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- 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) - for `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", - "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" - }, - "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\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", - "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" - }, - "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\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", - "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", - "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" - } - } - } - }, - "Place of Issue": { - "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" + "title" : "Cargo Net 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/Cargo Gross Volume" + }, + "cargoGrossWeight" : { + "$ref" : "#/components/schemas/Cargo Gross Weight" + }, + "cargoNetVolume" : { + "$ref" : "#/components/schemas/Cargo Net Volume" + }, + "cargoNetWeight" : { + "$ref" : "#/components/schemas/Cargo Net Weight" + }, + "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" ], - "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" + "title" : "Cargo Item", + "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" ], - "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" - } - } - } - ] - }, - "Document Parties": { - "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**Condition:** Mandatory for To Order BLs, `isToOrder=true`\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" - }, - "Gross Weight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, including packaging. Excludes the tare weight of the container(s).\n", - "format": "float", - "example": 2.4 - }, - "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 total weight of the cargo including packaging items being carried in the container(s). Excludes the tare weight of the container(s).\n" - }, - "Gross Volume": { - "title": "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.\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" - }, - "Gross Weight_1": { - "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" + "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", + "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", + "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", + "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/Gross Weight" + }, + "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/Net Explosive Content" + }, + "netVolume" : { + "$ref" : "#/components/schemas/Net Volume" + }, + "netWeight" : { + "$ref" : "#/components/schemas/Net Weight" + }, + "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" + }, + "Document Parties" : { + "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:** Mandatory for To Order BLs, `isToOrder=true`\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" + }, + "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", + "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/Tare Weight" + } + }, + "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 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", + "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" + }, + "Gross Weight" : { + "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" + }, + "IssuanceError" : { + "properties" : { + "errorCode" : { + "description" : "A vendor provided error code.\n\nThe meaning of each code is agreed bilaterally between the vendor.\n", + "example" : "ERR-1234", + "maxLength" : 50, + "pattern" : "^\\S+$", + "type" : "string" + }, + "reason" : { + "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...", + "maxLength" : 255, + "pattern" : "^\\S(?:.*\\S)?$", + "type" : "string" + } + }, + "title" : "Issuance Error", + "type" : "object" + }, + "IssuanceManifest" : { + "description" : "Checksums of the carrier provided documents from the issuance time.\n", + "properties" : { + "documentChecksum" : { + "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", + "maxLength" : 64, + "minLength" : 64, + "pattern" : "^[0-9a-f]+$", + "type" : "string" + }, + "eBLVisualisationByCarrierChecksum" : { + "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", + "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" + }, + "IssuanceRequest" : { + "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", + "properties" : { + "document" : { + "$ref" : "#/components/schemas/TransportDocument" + }, + "eBLVisualisationByCarrier" : { + "$ref" : "#/components/schemas/SupportingDocument" + }, + "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).\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", + "pattern" : "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", + "type" : "string" + }, + "issueTo" : { + "$ref" : "#/components/schemas/IssueToParty" + } + }, + "required" : [ + "document", + "issuanceManifestSignedContent", + "issueTo" + ], + "title" : "Issuance Request", + "type" : "object" + }, + "IssuanceResponse" : { + "properties" : { + "errors" : { + "description" : "A list of errors if the issuance failed for some reason.\n", + "items" : { + "$ref" : "#/components/schemas/IssuanceError" + }, + "maxItems" : 255, + "type" : "array" + }, + "issuanceResponseCode" : { + "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", + "enum" : [ + "ISSU", + "BREQ", + "REFU" + ], + "example" : "ISSU", + "type" : "string" + }, + "reason" : { + "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...", + "maxLength" : 255, + "pattern" : "^\\S(?:.*\\S)?$", + "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" + } + }, + "required" : [ + "issuanceResponseCode", + "transportDocumentReference" + ], + "title" : "Issuance Response", + "type" : "object" + }, + "IssueToParty" : { + "description" : "The party to whom the electronic Bill of Lading (eBL) 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", + "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", + "sendToPlatform" + ], + "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" + }, + "Net Explosive Content" : { + "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" + }, + "Net Volume" : { + "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" + }, + "Net Weight" : { + "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", + "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" + }, + "Place of Issue" : { + "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" + }, + "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" + }, + "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" + }, + "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", + "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" + }, + "SupportingDocument" : { + "properties" : { + "content" : { + "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==", + "format" : "byte", + "type" : "string" + }, + "contentType" : { + "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).\n\n**Conditional:** This property is mandatory to provide if it differs from `application/pdf`\n", + "example" : "application/msword", + "maxLength" : 100, + "type" : "string" + }, + "name" : { + "example" : "Carrier rendered copy of the EBL.pdf", + "maxLength" : 100, + "type" : "string" + } + }, + "required" : [ + "content", + "name" + ], + "title" : "Supporting Document", + "type" : "object" + }, + "Tare Weight" : { + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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" : { + "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" + }, + "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/Place of Issue" + }, + "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", + "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", + "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" }, - "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\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "description": "Total weight of the goods carried, excluding packaging.\n" + "description" : "This API is intended as an API between a carrier and a EBL Solution Platform.\n\nThe EBL Solution Provider is to implement\n\n /v3/ebl-issuance-requests\n\nfor the carrier to call and the carrier is to implement\n\n /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\nAPI specification issued by DCSA.org.\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", + "license" : { + "name" : "Apache 2.0", + "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "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\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR", - "GRM", - "ONZ" + "title" : "DCSA OpenAPI specification for Issuance an EBL to an EBL platform.\n", + "version" : "3.0.0" + }, + "openapi" : "3.0.3", + "paths" : { + "/v3/ebl-issuance-requests" : { + "put" : { + "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" : [ + { + "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/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" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "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" + } + } + }, + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "description" : "Request failed for some reason.", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + } + }, + "summary" : "Request issuance of an EBL", + "tags" : [ + "Issuance EBL" ] - } - }, - "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\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ", - "LTR" + "/v3/ebl-issuance-responses" : { + "post" : { + "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" : [ + { + "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/IssuanceResponse" + } + } + }, + "required" : true + }, + "responses" : { + "204" : { + "description" : "Carrier's acknowledgement of the Issuance Response", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + }, + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "description" : "Request successful", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + } + }, + "summary" : "Respond to a transport document issuance request", + "tags" : [ + "Issuance Response" ] - } - }, - "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": "3" - } + }, + "servers" : [ + { + "description" : "SwaggerHub API Auto Mocking", + "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_ISS/3.0.0" } - }, - "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" - } + ], + "tags" : [ + { + "description" : "Issuance EBL **implemented** by EBL Solution Platform\n", + "name" : "Issuance EBL" + }, + { + "description" : "Issuance Response **implemented** by carrier\n", + "name" : "Issuance Response" } - } - } + ] } 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 index 81e0f910..8c447c6b 100644 --- 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 @@ -1,536 +1,536 @@ { - "openapi": "3.0.3", - "info": { - "title": "DCSA EBL Surrender API", - "description": "This 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 /v3/ebl-surrender-requests\n\nwhich will be processed asynchronously. Responses to the surrender requests will be submitted by the carrier via \n\n /v3/ebl-surrender-responses\n\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", - "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" - } + "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" }, - "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" - } + "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" + } + }, + "schemas" : { + "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" + }, + "EndorsementChainLink" : { + "description" : "Entry in the endorsement chain.\n", + "properties" : { + "actionCode" : { + "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", + "maxLength" : 50, + "type" : "string" + }, + "actionDateTime" : { + "description" : "Date time when the action occurred.", + "example" : "2024-09-04T09:41:00Z", + "format" : "date-time", + "type" : "string" + }, + "actor" : { + "$ref" : "#/components/schemas/TransactionParty" + }, + "recipient" : { + "$ref" : "#/components/schemas/TransactionParty" + } + }, + "required" : [ + "actionCode", + "actionDateTime", + "actor", + "recipient" + ], + "title" : "Endorsement Chain Link", + "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" + }, + "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 `codeListProvider`\n", + "example" : "MSK", + "maxLength" : 150, + "type" : "string" + } + }, + "required" : [ + "codeListProvider", + "partyCode" + ], + "title" : "Identifying Code", + "type" : "object" + }, + "SurrenderRequestAnswer" : { + "properties" : { + "action" : { + "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", + "enum" : [ + "SURR", + "SREJ" + ], + "example" : "SURR", + "type" : "string" + }, + "comments" : { + "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...", + "maxLength" : 255, + "pattern" : "^\\S(?:.*\\S)?$", + "type" : "string" + }, + "surrenderRequestReference" : { + "description" : "The surrender request provided by the EBL solution in the surrender request.\n", + "example" : "Z12345", + "maxLength" : 100, + "pattern" : "^\\S(?:.*\\S)?$", + "type" : "string" + } + }, + "required" : [ + "action", + "surrenderRequestReference" + ], + "title" : "Surrender Request Answer", + "type" : "object" + }, + "SurrenderRequestDetails" : { + "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", + "properties" : { + "comments" : { + "description" : "Optional free text comment associated with the surrender request transaction.", + "example" : "As requested...", + "maxLength" : 255, + "pattern" : "^\\S(?:.*\\S)?$", + "type" : "string" + }, + "endorsementChain" : { + "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" + }, + "type" : "array" + }, + "reasonCode" : { + "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", + "maxLength" : 4, + "type" : "string" + }, + "surrenderRequestCode" : { + "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", + "enum" : [ + "SREQ", + "AREQ" + ], + "example" : "SREQ", + "type" : "string" + }, + "surrenderRequestReference" : { + "description" : "A server defined reference for a concrete surrender request. Surrender request references MUST NOT be reused.\n", + "example" : "Z12345", + "maxLength" : 100, + "pattern" : "^\\S(?:.*\\S)?$", + "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" + } + }, + "required" : [ + "surrenderRequestCode", + "surrenderRequestReference", + "surrenderRequestedBy", + "transportDocumentReference" + ], + "title" : "Surrender Request Details", + "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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + "required" : [ + "countryCode", + "type", + "value" + ], + "title" : "Tax & Legal Reference", + "type" : "object" + }, + "TransactionParty" : { + "description" : "Refers to a company or a legal entity.", + "properties" : { + "eblPlatform" : { + "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` (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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } + "required" : [ + "eblPlatform", + "partyName" + ], + "title" : "Transaction Party", + "type" : "object" + } } - } - }, - "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` (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." + }, + "info" : { + "contact" : { + "email" : "info@dcsa.org", + "name" : "Digital Container Shipping Association (DCSA)", + "url" : "https://dcsa.org" }, - "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" + "description" : "This 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 /v3/ebl-surrender-requests\n\nwhich will be processed asynchronously. Responses to the surrender requests will be submitted by the carrier via \n\n /v3/ebl-surrender-responses\n\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", + "license" : { + "name" : "Apache 2.0", + "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "SurrenderRequestDetails": { - "title": "Surrender Request Details", - "required": [ - "surrenderRequestCode", - "surrenderRequestReference", - "surrenderRequestedBy", - "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` (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" + "title" : "DCSA EBL Surrender API", + "version" : "3.0.0" + }, + "openapi" : "3.0.3", + "paths" : { + "/v3/ebl-surrender-requests" : { + "post" : { + "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" : [ + { + "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/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" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "description" : "Error", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + } + }, + "summary" : "Creates a Surrender Request\n", + "tags" : [ + "Surrender Requests" ] - }, - "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": "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://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" + } }, - "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" + "/v3/ebl-surrender-responses" : { + "post" : { + "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" : [ + { + "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/SurrenderRequestAnswer" + } + } + }, + "required" : true + }, + "responses" : { + "204" : { + "description" : "Request successful", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + }, + "409" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "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" + } + } + }, + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" + } + } + }, + "description" : "Error", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } + } + } + }, + "tags" : [ + "Surrender Request responses" ] - }, - "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" - } + }, + "servers" : [ + { + "description" : "SwaggerHub API Auto Mocking", + "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_SUR/3.0.0" } - }, - "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" - } + ], + "tags" : [ + { + "description" : "The Surrender Requests implemented\n", + "name" : "Surrender Requests" + }, + { + "description" : "The Surrender Request responses\n", + "name" : "Surrender Request responses" } - } - } + ] } 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 4591d3ac..b11c1cd3 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 @@ -46,8 +46,7 @@ class EblScenarioListBuilder extends ScenarioListBuilder private static final String PUT_EBL_SCHEMA_NAME = "UpdateShippingInstructions"; private static final String PATCH_SI_SCHEMA_NAME = "shippinginstructions_documentReference_body"; private static final String PATCH_TD_SCHEMA_NAME = "transportdocuments_transportDocumentReference_body"; - private static final String RESPONSE_POST_SHIPPING_INSTRUCTIONS_SCHEMA_NAME = "Shipping Instructions Response_1"; - private static final String TD_REF_STATUS_SCHEMA_NAME = "TransportDocumentRefStatus"; + private static final String RESPONSE_POST_SHIPPING_INSTRUCTIONS_SCHEMA_NAME = "Shipping Instructions Response"; private static final String EBL_SI_NOTIFICATION_SCHEMA_NAME = "ShippingInstructionsNotification"; private static final String EBL_TD_NOTIFICATION_SCHEMA_NAME = "TransportDocumentNotification"; @@ -178,7 +177,7 @@ private static EblScenarioListBuilder _uc3_get( ShippingInstructionsStatus originalSiState, ShippingInstructionsStatus modifiedSiState, EblScenarioListBuilder... thenEither) { - return uc3_shipper_submitUpdatedShippingInstructions(originalSiState, false) + return uc3ShipperSubmitUpdatedShippingInstructions(originalSiState, false) .then( shipper_GetShippingInstructions(originalSiState, modifiedSiState, false) .thenEither(thenEither)); @@ -336,7 +335,7 @@ yield then( .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, useTDRef) .thenAllPathsFrom(SI_PENDING_UPDATE, transportDocumentStatus, useTDRef)), - uc3_shipper_submitUpdatedShippingInstructions(SI_RECEIVED, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_RECEIVED, useTDRef) .then( shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, useTDRef) .then(shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, true, useTDRef) @@ -398,7 +397,7 @@ yield thenEither( case SI_PENDING_UPDATE -> { if (transportDocumentStatus != TD_START) { yield thenEither( - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) .then(shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, true, useTDRef) @@ -419,7 +418,7 @@ yield thenEither( SI_PENDING_UPDATE, SI_UPDATE_CANCELLED, useTDRef) .thenEither( noAction().thenHappyPathFrom(SI_PENDING_UPDATE, transportDocumentStatus, useTDRef), - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions( SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) @@ -440,7 +439,7 @@ yield thenEither( ); } yield thenEither( - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) .then(shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, true, useTDRef) @@ -461,7 +460,7 @@ yield thenEither( SI_PENDING_UPDATE, SI_UPDATE_CANCELLED, useTDRef) .thenEither( noAction().thenHappyPathFrom(SI_PENDING_UPDATE, transportDocumentStatus, useTDRef), - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions( SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) @@ -483,7 +482,7 @@ yield thenEither( .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, useTDRef) .thenHappyPathFrom(SI_PENDING_UPDATE, transportDocumentStatus, useTDRef)), - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) .then(shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, true, useTDRef) @@ -530,7 +529,7 @@ private EblScenarioListBuilder thenHappyPathFrom( default -> throw new IllegalStateException("Unexpected transportDocumentStatus: " + transportDocumentStatus.name()); }); case SI_PENDING_UPDATE -> then( - uc3_shipper_submitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) + uc3ShipperSubmitUpdatedShippingInstructions(SI_PENDING_UPDATE, useTDRef) .then( shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, useTDRef) .then(shipper_GetShippingInstructions(SI_PENDING_UPDATE, SI_UPDATE_RECEIVED, true, useTDRef) @@ -560,7 +559,7 @@ private EblScenarioListBuilder thenAllPathsFrom(TransportDocumentStatus transpor // https://github.com/dcsaorg/Conformance-Gateway/pull/29#discussion_r1421732797 .thenHappyPathFrom(TD_ISSUED)), - uc3_shipper_submitUpdatedShippingInstructions(SI_RECEIVED, true).then( + uc3ShipperSubmitUpdatedShippingInstructions(SI_RECEIVED, true).then( shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, true).then( shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, true, true) .thenEither( @@ -583,7 +582,7 @@ private EblScenarioListBuilder thenAllPathsFrom(TransportDocumentStatus transpor .thenHappyPathFrom(transportDocumentStatus)) ) )), - uc3_shipper_submitUpdatedShippingInstructions(SI_RECEIVED, false).then( + uc3ShipperSubmitUpdatedShippingInstructions(SI_RECEIVED, false).then( shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, false).then( shipper_GetShippingInstructions(SI_RECEIVED, SI_UPDATE_RECEIVED, true, false) .thenEither( @@ -619,9 +618,9 @@ private EblScenarioListBuilder thenAllPathsFrom(TransportDocumentStatus transpor .thenAllPathsFrom(TD_ISSUED)) ); case TD_ISSUED -> thenEither( - uc3_shipper_submitUpdatedShippingInstructions(SI_RECEIVED, true) + uc3ShipperSubmitUpdatedShippingInstructions(SI_RECEIVED, true) .thenHappyPathFrom(SI_UPDATE_RECEIVED, TD_ISSUED, true), - uc3_shipper_submitUpdatedShippingInstructions(SI_RECEIVED, false) + uc3ShipperSubmitUpdatedShippingInstructions(SI_RECEIVED, false) .thenHappyPathFrom(SI_UPDATE_RECEIVED, TD_ISSUED, false), uc9_carrier_awaitSurrenderRequestForAmendment() .then(shipper_GetTransportDocument(TD_PENDING_SURRENDER_FOR_AMENDMENT) @@ -813,7 +812,7 @@ private static EblScenarioListBuilder uc1_shipper_submitShippingInstructions() { resolveMessageSchemaValidator(EBL_NOTIFICATIONS_API, EBL_SI_NOTIFICATION_SCHEMA_NAME))); } - private static EblScenarioListBuilder uc3_shipper_submitUpdatedShippingInstructions( + private static EblScenarioListBuilder uc3ShipperSubmitUpdatedShippingInstructions( ShippingInstructionsStatus expectedSiStatus, boolean useTDRef ) { @@ -821,7 +820,7 @@ private static EblScenarioListBuilder uc3_shipper_submitUpdatedShippingInstructi String shipperPartyName = threadLocalShipperPartyName.get(); return new EblScenarioListBuilder( previousAction -> - new UC3_Shipper_SubmitUpdatedShippingInstructionsAction( + new UC3ShipperSubmitUpdatedShippingInstructionsAction( carrierPartyName, shipperPartyName, (EblAction) previousAction, @@ -919,8 +918,6 @@ private static EblScenarioListBuilder uc7_shipper_approveDraftTransportDocument( (EblAction) previousAction, resolveMessageSchemaValidator( EBL_API, PATCH_TD_SCHEMA_NAME), - resolveMessageSchemaValidator( - EBL_API, TD_REF_STATUS_SCHEMA_NAME), resolveMessageSchemaValidator( EBL_NOTIFICATIONS_API, EBL_TD_NOTIFICATION_SCHEMA_NAME))); } diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3_Shipper_SubmitUpdatedShippingInstructionsAction.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3ShipperSubmitUpdatedShippingInstructionsAction.java similarity index 96% rename from ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3_Shipper_SubmitUpdatedShippingInstructionsAction.java rename to ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3ShipperSubmitUpdatedShippingInstructionsAction.java index 96d1b237..2accec06 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3_Shipper_SubmitUpdatedShippingInstructionsAction.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC3ShipperSubmitUpdatedShippingInstructionsAction.java @@ -14,13 +14,13 @@ @Getter @Slf4j -public class UC3_Shipper_SubmitUpdatedShippingInstructionsAction extends StateChangingSIAction { +public class UC3ShipperSubmitUpdatedShippingInstructionsAction extends StateChangingSIAction { private final ShippingInstructionsStatus expectedSiStatus; private final JsonSchemaValidator requestSchemaValidator; private final JsonSchemaValidator notificationSchemaValidator; private final boolean useTDRef; - public UC3_Shipper_SubmitUpdatedShippingInstructionsAction( + public UC3ShipperSubmitUpdatedShippingInstructionsAction( String carrierPartyName, String shipperPartyName, EblAction previousAction, diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC7_Shipper_ApproveDraftTransportDocumentAction.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC7_Shipper_ApproveDraftTransportDocumentAction.java index 5a479d40..b24c6269 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC7_Shipper_ApproveDraftTransportDocumentAction.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC7_Shipper_ApproveDraftTransportDocumentAction.java @@ -16,7 +16,6 @@ @Slf4j public class UC7_Shipper_ApproveDraftTransportDocumentAction extends StateChangingSIAction { private final JsonSchemaValidator requestSchemaValidator; - private final JsonSchemaValidator responseSchemaValidator; private final JsonSchemaValidator notificationSchemaValidator; public UC7_Shipper_ApproveDraftTransportDocumentAction( @@ -24,11 +23,9 @@ public UC7_Shipper_ApproveDraftTransportDocumentAction( String shipperPartyName, EblAction previousAction, JsonSchemaValidator requestSchemaValidator, - JsonSchemaValidator responseSchemaValidator, JsonSchemaValidator notificationSchemaValidator) { super(shipperPartyName, carrierPartyName, previousAction, "UC7", Set.of(200, 202)); this.requestSchemaValidator = requestSchemaValidator; - this.responseSchemaValidator = responseSchemaValidator; this.notificationSchemaValidator = notificationSchemaValidator; } @@ -82,18 +79,11 @@ protected Stream createSubChecks() { getMatchedExchangeUuid(), HttpMessageType.RESPONSE, expectedApiVersion), - // TODO: Add Carrier Ref Status Payload response check - // TODO: Add Shipper content conformance check new JsonSchemaCheck( EblRole::isShipper, getMatchedExchangeUuid(), HttpMessageType.REQUEST, requestSchemaValidator), - new JsonSchemaCheck( - EblRole::isCarrier, - getMatchedExchangeUuid(), - HttpMessageType.RESPONSE, - responseSchemaValidator), EBLChecks.tdRefStatusChecks(getMatchedExchangeUuid(), expectedApiVersion, getDspSupplier(), TransportDocumentStatus.TD_APPROVED)); return Stream.concat( primaryExchangeChecks, diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java index 083c1280..283090d2 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java @@ -62,7 +62,7 @@ protected Map, Consumer> getActionP Map.entry(Shipper_GetShippingInstructionsAction.class, this::getShippingInstructionsRequest), Map.entry(Shipper_GetTransportDocumentAction.class, this::getTransportDocument), Map.entry(AUC_Shipper_SendOutOfOrderSIMessageAction.class, this::sendOutOfOrderMessage), - Map.entry(UC3_Shipper_SubmitUpdatedShippingInstructionsAction.class, this::sendUpdatedShippingInstructionsRequest), + Map.entry(UC3ShipperSubmitUpdatedShippingInstructionsAction.class, this::sendUpdatedShippingInstructionsRequest), Map.entry(UC5_Shipper_CancelUpdateToShippingInstructionsAction.class, this::cancelUpdateToShippingInstructions), Map.entry(UC7_Shipper_ApproveDraftTransportDocumentAction.class, this::approveDraftTransportDocument) ); 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 23d95371..256aaffb 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 @@ -24,7 +24,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 15000, "unit": "KGM" }, @@ -45,7 +45,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_2_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 20000, "unit": "KGM" }, 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 8abfce9f..f7e1b75a 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 @@ -24,7 +24,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" }, @@ -35,7 +35,7 @@ }, { "equipmentReference": "EQUIPMENT_REFERENCE_2_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" }, @@ -56,7 +56,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" }, @@ -67,7 +67,7 @@ }, { "equipmentReference": "EQUIPMENT_REFERENCE_2_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" }, 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 44087faf..e3f854b2 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 @@ -24,7 +24,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 dba242ad..48f0c573 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 @@ -32,7 +32,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 6c1bb2b8..f25af9a5 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 @@ -24,7 +24,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" } 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 bdd05ceb..1ae3b50e 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 @@ -31,7 +31,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 5000, "unit": "KGM" }, 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 2ec8873c..55447e37 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 @@ -30,7 +30,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 099d1318..860b127a 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 @@ -31,7 +31,7 @@ "cargoItems": [ { "equipmentReference": "EQUIPMENT_REFERENCE_PLACEHOLDER", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 1338fff0..503f4185 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 @@ -24,7 +24,7 @@ "cargoItems": [ { "equipmentReference": "ABCU7341935", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, @@ -49,8 +49,10 @@ "equipment": { "equipmentReference": "ABCU7341935", "ISOEquipmentCode": "45G1", - "tareWeight": 4030, - "weightUnit": "KGM" + "tareWeight": { + "value": 4030, + "unit": "KGM" + } }, "seals": [ { 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 index 00a13bd3..f66ad736 100644 --- 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 @@ -1,9041 +1,8848 @@ { - "openapi": "3.0.3", - "info": { - "title": "DCSA specification for Shipping Instructions and Transport Document", - "description": "API specification issued by DCSA.org.\n\nFor explanation of specific values or objects please refer to the [Information Model v2024.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 Bill of Lading 3.0](https://dcsa.org/standards/bill-of-lading/documentation-bill-of-lading-3) to address this. **All use cases mentioned in this API specification refer to use cases defined in the eBL IFS**.\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", - "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": "/" - } - ], - "tags": [ - { - "name": "Shipping Instructions", - "description": "The Shipping Instructions endPoints to be implemented by **providers** of the Bill of Lading API\n" - }, - { - "name": "Transport Document", - "description": "The Transport Document endPoints to be implemented by **providers** of the Bill of Lading API\n" - }, - { - "name": "Notifications", - "description": "The Notifications to be implemented by the **consumers** of the Bill of Lading API" - } - ], - "paths": { - "/v3/shipping-instructions": { - "post": { - "tags": [ - "Shipping Instructions" - ], - "summary": "Creates a Shipping Instructions\n", - "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 `201` (Created) or a `202` (Accepted) if the 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 `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 `201` (Created) response is returned with a payload containing the `shippingInstructionsReference` and `shippingInstructionsStatus`:\n ```\n {\n shippingInstructionsReference: 'si-123',\n shippingInstructionsStatus: 'RECEIVED'\n }\n ```\n4. All '_relevant_' subscribers will be notified via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\n\nFor `POST` `Shipping Instructions` responding with `201` (Created) the process ends here. The `Shipping Instructions`:\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 `shippingInstructionsReference` and `shippingInstructionsStatus='RECEIVED'`\n - '_relevant_' subscribers have been notified.\n - awaits further processing by the provider\n\nThe provider will now start asynchronous processing. Once processed, the new status 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 \nendPoint to check if the `shippingInstructionsStatus` of the `Shipping Instructions` has changed.\n\n## Flow for a `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` responding with `202` (Accepted) 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 and will be communicated via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\n", - "operationId": "create-shipping-instructions", - "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": { - "description": "Parameters used to create the `Shipping Instructions`\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateShippingInstructions" - }, - "examples": { - "regularSTDExample": { - "summary": "Create a Shipping Instructions\n", - "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", - "value": { - "transportDocumentTypeCode": "BOL", - "isShippedOnBoardType": true, - "freightPaymentTermCode": "PRE", - "isElectronic": true, - "isToOrder": true, - "invoicePayableAt": { - "UNLocationCode": "DKAAR" - }, - "partyContactDetails": [ - { - "name": "DCSA test person", - "email": "no-reply@dcsa.example.org" - } - ], - "documentParties": { - "shipper": { - "partyName": "DCSA CTK", - "displayedAddress": [ - "Strawinskylaan 4117" + "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**Conditional:** 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" + }, + "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" + }, + "Cargo Gross Volume" : { + "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" + }, + "Cargo Gross Weight" : { + "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" + }, + "Cargo Net Volume" : { + "description" : "Calculated by multiplying the width, height, and length of the packed 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 packed cargo, excluding packaging.\n", + "example" : 2.4, + "exclusiveMinimum" : true, + "format" : "float", + "minimum" : 0, + "type" : "number" + } + }, + "required" : [ + "unit", + "value" + ], + "title" : "Cargo Net Volume", + "type" : "object" + }, + "Cargo Net Weight" : { + "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" + }, + "CargoItem" : { + "description" : "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", + "properties" : { + "cargoGrossVolume" : { + "$ref" : "#/components/schemas/Cargo Gross Volume" + }, + "cargoGrossWeight" : { + "$ref" : "#/components/schemas/Cargo Gross Weight" + }, + "cargoNetVolume" : { + "$ref" : "#/components/schemas/Cargo Net Volume" + }, + "cargoNetWeight" : { + "$ref" : "#/components/schemas/Cargo Net Weight" + }, + "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/Cargo Gross Volume" + }, + "cargoGrossWeight" : { + "$ref" : "#/components/schemas/Cargo Gross Weight" + }, + "cargoNetVolume" : { + "$ref" : "#/components/schemas/Cargo Net Volume" + }, + "cargoNetWeight" : { + "$ref" : "#/components/schemas/Cargo Net Weight" + }, + "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" + }, + "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", + "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", + "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", + "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", + "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", + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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/Invoice Payable At" + }, + "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/Place of Issue" + }, + "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", + "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" + }, + "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/Gross Weight" + }, + "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/Net Explosive Content" + }, + "netVolume" : { + "$ref" : "#/components/schemas/Net Volume" + }, + "netWeight" : { + "$ref" : "#/components/schemas/Net Weight" + }, + "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" + }, + "Data" : { + "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/Shipping Instructions" + }, + "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/Updated Shipping Instructions" + }, + "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" + }, + "Data_1" : { + "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/Transport Document" + }, + "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" + }, + "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" + }, + "Document Parties" : { + "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:** Mandatory for To Order BLs, `isToOrder=true`\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" + }, + "Document Parties_1" : { + "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:** Mandatory for To Order BLs, `isToOrder=true`\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" + }, + "Document Parties_2" : { + "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" + }, + "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", + "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/Tare Weight" + } + }, + "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" + }, + "Gross Weight" : { + "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/Document Parties_2" + }, + "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" + }, + "Invoice Payable At" : { + "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**Conditional:** 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" + }, + "Net Explosive Content" : { + "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" + }, + "Net Volume" : { + "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" + }, + "Net Weight" : { + "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", + "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" + }, + "Place of Issue" : { + "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" + }, + "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" + }, + "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/Tare Weight" + } + }, + "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", + "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" + }, + "Shipping Instructions" : { + "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", + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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/Invoice Payable At" + }, + "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/Place of Issue" + }, + "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", + "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" + }, + "Shipping Instructions Response" : { + "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" : "Shipping Instructions Response", + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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/Invoice Payable At" + }, + "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/Place of Issue" + }, + "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", + "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" + }, + "ShippingInstructionsNotification" : { + "description" : "`CloudEvent` specific properties for the `Notification`.\n", + "properties" : { + "data" : { + "$ref" : "#/components/schemas/Data" + }, + "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" + }, + "Tare Weight" : { + "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" + }, + "Transport Document" : { + "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", + "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", + "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", + "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", + "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", + "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/Document Parties_1" + }, + "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" : { + "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" ], - "partyContactDetails": [ - { - "name": "DCSA test person", - "email": "no-reply@dcsa.example.org" - } - ] - } - }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "descriptionOfGoods": [ - "Shoes - black" + "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" ], - "HSCodes": [ - "640510" + "title" : "Free text", + "type" : "object" + } + ], + "title" : "Invoice Payable At", + "type" : "object" + }, + "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/Place of Issue" + }, + "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", + "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" + }, + "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", + "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", + "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", + "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", + "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/Document Parties_1" + }, + "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" : { + "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" ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" - } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } + "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" ], - "equipmentReference": "NARU3472484" - } - ] - } - } - } - } - }, - "required": true - }, - "responses": { - "201": { - "description": "The `Shipping Instructions` has been successfully created in the provider system. The status of the `Shipping Instructions` is now `RECEIVED`. The consumer is now awaiting provider to process the `Shipping Instructions` asynchronously.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + "title" : "Free text", + "type" : "object" + } + ], + "title" : "Invoice Payable At", + "type" : "object" + }, + "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/Place of Issue" + }, + "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", + "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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Shipping Instructions Response" - }, - "examples": { - "receExample": { - "summary": "Shipping Instructions received\n", - "description": "A `Shipping Instructions` has been received (`shippingInstructionsStatus='RECEIVED'`), schema validated and stored in provider system\n", - "value": { - "shippingInstructionsReference": "si-123", - "shippingInstructionsStatus": "RECEIVED" - } - } - } - } - } - }, - "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.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + "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" + }, + "TransportDocumentNotification" : { + "description" : "`CloudEvent` specific properties for the `Notification`.\n", + "properties" : { + "data" : { + "$ref" : "#/components/schemas/Data_1" + }, + "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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Shipping Instructions Response_1" - }, - "examples": { - "receExample": { - "summary": "Shipping Instructions received\n", - "description": "The `shippingInstructionsReference` has been accepted (no `shippingInstructionsStatus`) and schema validated by provider\n", - "value": { - "shippingInstructionsReference": "si-123" - } - } - } - } - } - }, - "400": { - "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" - } + "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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Shipping Instructions missing isElectronic\n", - "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", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + "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" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while processing Shipping Instructions\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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/Invoice Payable At" + }, + "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/Place of Issue" + }, + "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", + "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" + }, + "Updated Shipping Instructions" : { + "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", + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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/Invoice Payable At" + }, + "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/Place of Issue" + }, + "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", + "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" : "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", + "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", + "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" + }, + "shippinginstructions_documentReference_body" : { + "properties" : { + "updatedShippingInstructionsStatus" : { + "description" : "The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED`\n", + "example" : "UPDATE_CANCELLED", + "maxLength" : 50, + "type" : "string" + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Making too many Shipping Instructions\n", - "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", - "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" + "required" : [ + "updatedShippingInstructionsStatus" + ], + "type" : "object" + }, + "transportdocuments_transportDocumentReference_body" : { + "properties" : { + "transportDocumentStatus" : { + "description" : "The status of the `Transport Document`. It can only be `APPROVED`\n", + "example" : "APPROVED", + "maxLength" : 50, + "type" : "string" + } + }, + "required" : [ + "transportDocumentStatus" + ], + "type" : "object" + } + } + }, + "info" : { + "contact" : { + "email" : "info@dcsa.org", + "name" : "Digital Container Shipping Association (DCSA)", + "url" : "https://dcsa.org" + }, + "description" : "API specification issued by DCSA.org.\n\nFor explanation of specific values or objects please refer to the [Information Model v2024.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 Bill of Lading 3.0](https://dcsa.org/standards/bill-of-lading/documentation-bill-of-lading-3) to address this. **All use cases mentioned in this API specification refer to use cases defined in the eBL IFS**.\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", + "license" : { + "name" : "Apache 2.0", + "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "title" : "DCSA specification for Shipping Instructions and Transport Document", + "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" + } } - } - } - } - } - } - } - }, - "/v3/shipping-instructions/{documentReference}": { - "get": { - "tags": [ - "Shipping Instructions" - ], - "summary": "Gets the Shipping Instructions\n", - "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 `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 `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": [ - { - "name": "documentReference", - "in": "path", - "description": "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "e0559d83-00e2-438e-afd9-fdd610c1a008" - } - }, - { - "name": "updatedContent", - "in": "query", - "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", - "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": "3" - } - } - ], - "responses": { - "200": { - "description": "Fetching the content of either the \"original\" `Shipping Instructions` or the `Updated Shipping Instructions`\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + }, + "description" : "Parameters used to create the `Shipping Instructions`\n", + "required" : true }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShippingInstructions" - }, - "examples": { - "regularSTDExample": { - "summary": "Fetch Shipping Instructions with standard Dry cargo\n", - "description": "A `RECEIVED` `Shipping Instructions` with standard Dry cargo waiting for the provider to `DRAFT` a `Transport Document`.\n", - "value": { - "shippingInstructionsReference": "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "shippingInstructionsStatus": "RECEIVED", - "transportDocumentTypeCode": "BOL", - "isShippedOnBoardType": true, - "freightPaymentTermCode": "PRE", - "isElectronic": true, - "isToOrder": true, - "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" - } - ] - } - }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "weight": 12000, - "weightUnit": "KGM", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" + "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" } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } - ], - "equipmentReference": "NARU3472484" - } - ] - } - }, - "reeferExample": { - "summary": "Shipping Instructions with reefer cargo\n", - "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", - "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" - }, - "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" - } - ] + } + }, + "schema" : { + "$ref" : "#/components/schemas/Shipping Instructions Response" } - }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REEFER", - "descriptionOfGoods": [ - "Dairy products" - ], - "HSCodes": [ - "04052090" - ], - "commoditySubreference": "ReeferSubRef002", - "cargoItems": [ - { - "equipmentReference": "KKFU6671914", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "BQ", - "description": "Bottles" + } + }, + "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" } - } - ] - } - ], - "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)\n", - "jsonPath": "$.advanceManifestFilings[0]", - "property": "advanceManifestFilings" + } }, - { - "severity": "ERROR", - "code": "PROPERTY_VALUE_MUST_CHANGE", - "message": "Missing \"ACI\" filing required for import to US\n", - "jsonPath": "$.advanceManifestFilings", - "property": "advanceManifestFilings" + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" } - ] - } - }, - "dgExample": { - "summary": "Updated Shipping Instructions with DG cargo\n", - "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", - "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" - }, - "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", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "description": "Jerrican, steel" + } + }, + "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" } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } - ], - "equipment": { - "ISOEquipmentCode": "22G1", - "equipmentReference": "HLXU1234567", - "tareWeight": 2370, - "weightUnit": "KGM" - } + } + }, + "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" + } } - } - } - } - }, - "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": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundUpdateExample": { - "summary": "Shipping Instructions update not found\n", - "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", - "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\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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)\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": "/v3/shipping-instructions/si-123", - "statusCode": 409, - "statusCodeText": "Conflict", - "statusCodeMessage": "Previous request is being processed. Please try again\nlater\n", - "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\n" + "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" + } } - } - } - } - }, - "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" - } + }, + "description" : "The payload used to create a [`Shipping Instructions Notification`](#/ShippingInstructionsNotification)\n" }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while fetching the Shipping Instructions\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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" - } - ] - } + "responses" : { + "204" : { + "description" : "No Content\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - } - } - } - }, - "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": "Fetching too many `Transport Document` requests\n", - "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", - "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\n", - "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" + }, + "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" } - ] - } - } - } - } - } - } - } - }, - "put": { - "tags": [ - "Shipping Instructions" - ], - "summary": "Updates the Shipping Instructions\n", - "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 `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** 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.\n \n The `Updated Shipping Instructions` is stored in the provider system alongside the \"original\" `Shipping Instructions`.\n\n **For the rest of this description and in all examples the value `si-123` will be used as `shippingInstructionsReference`**\n\n3. The response depends on which use case is the reason for calling this endPoint (what the `shippingInstructionsStatus` is):\n\n - If `shippingInstructionsStatus` **is** `RECEIVED`, then this endPoint is being used in addition to **UseCase 1 - Submit Shipping Instructions**. In this case the consumer would like to make an update to an already sent `Shipping Instructions`. This is done via **UseCase 3 - Submit updated Shipping Instructions**. The `shippingInstructionsStatus` stays as `RECEIVED`, `updatedShippingInstructionsStatus` is set to `UPDATE_RECEIVED`\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n shippingInstructionsReference: 'si-123',\n shippingInstructionsStatus: 'RECEIVED',\n updatedShippingInstructionsStatus: 'UPDATE_RECEIVED'\n }\n ```\n\n - If `shippingInstructionsStatus` is `PENDING_UPDATE`, then this endPoint is being used as a response to **UseCase 2 - Request to update Shipping Instructions** in this case the provider has requested an update to a `Shipping Instructions`. The `shippingInstructionsStatus` remains `PENDING_UPDATE`, `updatedShippingInstructionsStatus` is set to `UPDATE_RECEIVED`.\n \n A `200` (OK) response is returned with the following payload:\n ```\n {\n shippingInstructionsReference: 'si-123',\n shippingInstructionsStatus: 'PENDING_UPDATE',\n updatedShippingInstructionsStatus: 'UPDATE_RECEIVED'\n }\n ```\n4. All '_relevant_' subscribers will be notified via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\n\nFor `PUT` `Shipping Instructions` responding with `200` (OK) the process ends here. The updated `Shipping Instructions`:\n - is now stored in the provider system\n - a `200` (OK) response is sent to the consumer with the status of the `Shipping Instructions` and the `Updated Shipping Instructions` with one of the following combinations (depending on the use case):\n - `shippingInstructionsStatus='RECEIVED'` and `updatedShippingInstructionsStatus='UPDATE_RECEIVED'` (if endPoint 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 used as a response to **UseCase 2 - Request to update Shipping Instructions**)\n\n A subsequent `GET` request to the `Shipping Instructions` will fetch the status along with the `Shipping Instructions`\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 `Shipping Instructions` and `Updated 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 \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\n## Flow for a `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` responding with `200` (OK) 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": [ - { - "name": "documentReference", - "in": "path", - "description": "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "e0559d83-00e2-438e-afd9-fdd610c1a008" - } - }, - { - "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": { - "description": "Parameters used to update the `Shipping Instructions`\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateShippingInstructions" - }, - "examples": { - "regularSTDExample": { - "summary": "Update Shipping Instructions\n", - "description": "An update for a `Shipping Instructions` with standard Dry cargo. The `Shipping Instructions` update now wait to be confirmed by the provider.\n", - "value": { - "shippingInstructionsReference": "fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9", - "transportDocumentTypeCode": "BOL", - "isShippedOnBoardType": true, - "freightPaymentTermCode": "PRE", - "isElectronic": true, - "isToOrder": true, - "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" - } - ] - } - }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" - } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } - ], - "equipmentReference": "NARU3472484" - } - ] - } - } - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "The `Updated Shipping Instructions` has been successfully stored in the provider system with one of the following combinations (depending on the use case):\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 status of the `Updated Shipping Instructions` can be monitored on the\n\n GET /v3/shipping-instructions/{documentReference}\n\nendPoint where the \"original\" `Shipping Instructions` is returned by the consumer.\n\nIf the consumer wants to get the content of the `Update Shipping Instructions` the `GET` endPoint needs to be used in combination with the `?updatedContent=true` queryParameter:\n\n GET /v3/shipping-instructions/{documentReference}?updatedContent=true\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShippingInstructionsRefStatus" - }, - "examples": { - "receivedExample": { - "summary": "Shipping Instructions updated by consumer\n", - "description": "An `Updated Shipping Instructions` is received and stored in provider system, the `Updated Shipping Instructions` now awaits provider action.\n\n shippingInstructionsStatus='RECEIVED'\n updatedShippingInstructionsStatus='UPDATE_RECEIVED'\n", - "value": { - "shippingInstructionsReference": "si-123", - "shippingInstructionsStatus": "RECEIVED", - "updatedShippingInstructionsStatus": "UPDATE_RECEIVED" - } - }, - "pendingUpdateExample": { - "summary": "Shipping Instructions updated because of consumer requirement\n", - "description": "An updated `Shipping Instructions` received and stored in provider system as a response to a provider initiated update request (a response to **UseCase 2 - Request to update Shipping Instructions**). The `Updated Shipping Instructions` now awaits provider action\n\n shippingInstructionsStatus='PENDING_UPDATE'\n updatedShippingInstructionsStatus='UPDATE_RECEIVED'\n", - "value": { - "shippingInstructionsReference": "si-123", - "shippingInstructionsStatus": "PENDING_UPDATE", - "updatedShippingInstructionsStatus": "UPDATE_RECEIVED" - } - }, - "amendmentExample": { - "summary": "Request amendment to Transport Document\n", - "description": "An `Updated Shipping Instructions` received and stored in provider system as an amendment to a `Transport Document` with `transportDocumentReference='td-987'`. The `Updated Shipping Instructions` now awaits provider action\n\n shippingInstructionsStatus='RECEIVED'\n updatedShippingInstructionsStatus='UPDATE_RECEIVED'\n", - "value": { - "shippingInstructionsReference": "si-123", - "transportDocumentReference": "td-987", - "shippingInstructionsStatus": "RECEIVED", - "updatedShippingInstructionsStatus": "UPDATE_RECEIVED" - } - } - } - } - } - }, - "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.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "examples": { - "receivedExample": { - "summary": "Shipping Instructions updated by consumer\n", - "description": "An `Updated Shipping Instructions` received and accepted by provider, the `Updated Shipping Instructions` now awaits provider action, the `shippingInstructionStatus` does not change.\n" + } + }, + "description" : "In case the `Notification` does not schema validate a `400` (Bad Request) is returned\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - } - } - } - }, - "400": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Shipping Instructions missing isElectronic\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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)\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Not found request\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Conflicting Shipping Instructions update\n", - "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", - "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" + "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" + } } - } - } - } - }, - "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 `Shipping Instructions`\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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" - } - ] - } + }, + "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" + } } - } - } - } - }, - "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 Shipping Instructions\n", - "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", - "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" + }, + "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" } - ] - } - } - } - } - } - } - } - }, - "patch": { - "tags": [ - "Shipping Instructions" - ], - "summary": "Cancels an update to a Shipping Instructions\n", - "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 `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:\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. The `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED`.\n4. All '_relevant_' subscribers will be notified via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\n\n## Flow for a `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\n", - "operationId": "patch-shipping-instructions", - "parameters": [ - { - "name": "documentReference", - "in": "path", - "description": "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "e0559d83-00e2-438e-afd9-fdd610c1a008" - } - }, - { - "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": { - "description": "Cancel the `Update Shipping Instructions`\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/shippinginstructions_documentReference_body" - }, - "examples": { - "cancelUpdateExample": { - "summary": "Cancel a Shipping Instructions update\n", - "description": "Consumer wants to cancel an update provided to a `Shipping Instructions`. The `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED`\n", - "value": { - "updatedShippingInstructionsStatus": "UPDATE_CANCELLED" - } - } - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "The `Updated Shipping Instructions` is now cancelled. The `updatedShippingInstructionsStatus` is now `UPDATE_CANCELLED`. The `shippingInstructionsStatus` is left unchanged.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShippingInstructionsRefCancelStatus" - }, - "examples": { - "cancelUpdateExample": { - "summary": "Cancel a Shipping Instructions update\n", - "description": "Consumer wants to cancel an update provided to a `Shipping Instructions`. In this case the `shippingInstructionsStatus` stays as `RECEIVED` and the `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED`. An optional `reason` can be provided.\n", - "value": { - "shippingInstructionsReference": "si-123", - "shippingInstructionsStatus": "RECEIVED", - "updatedShippingInstructionsStatus": "UPDATE_CANCELLED" - } - }, - "cancelRequestedUpdateExample": { - "summary": "Cancel a Shipping Instructions update requested by provider\n", - "description": "Consumer wants to cancel an update provided to a `Shipping Instructions`. The update was requested by the provider. The `shippingInstructionsStatus` stays as `PENDING_UPDATE` and the `updatedShippingInstructionsStatus` is set to `UPDATE_CANCELLED`. An optional `reason` can be provided.\n", - "value": { - "shippingInstructionsReference": "si-123", - "shippingInstructionsStatus": "PENDING_UPDATE", - "updatedShippingInstructionsStatus": "UPDATE_CANCELLED" - } - } - } - } - } - }, - "202": { - "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" - } - }, - "content": { - "application/json": { - "examples": { - "cancelUpdateExample": { - "summary": "Cancel a Shipping Instructions update\n", - "description": "Consumer wants to cancel an update provided to a `Shipping Instructions`.\n" + } + }, + "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" + } } - } - } - } - }, - "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 Update Shipping Instructions status\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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`.\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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notUpdateFoundExample": { - "summary": "Shipping Instructions update not found\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "conflictExample": { - "summary": "Conflicting Shipping Instructions cancellation\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "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 cancelling the `Shipping Instructions`\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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" + "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/shippinginstructions_documentReference_body" + } } - } - } - } - }, - "default": { - "description": "For other errors the error object should be populated with relevant information\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + }, + "description" : "Cancel the `Update Shipping Instructions`\n", + "required" : true }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "tooManyRequestsExample": { - "summary": "Patching the `Shipping Instructions` too many times\n", - "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", - "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\n", - "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" + "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" + } } - } - } - } - } - } - } - }, - "/v3/transport-documents/{transportDocumentReference}": { - "get": { - "tags": [ - "Transport Document" - ], - "summary": "Gets the Transport Document\n", - "description": "Retrieves the `Transport Document` with the `transportDocumentReference` in the path.\n", - "operationId": "get-transport-document", - "parameters": [ - { - "name": "transportDocumentReference", - "in": "path", - "description": "The `transportDocumentReference` of the `Transport Document`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "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" - } - }, - { - "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" - } - } - ], - "responses": { - "200": { - "description": "The `Transport Document`\n", - "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\n", - "description": "A `DRAFT` Transport Document waiting for consumer approval.\n", - "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\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", - "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", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" + }, + "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" } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } - ], - "equipment": { - "ISOEquipmentCode": "22G1", - "equipmentReference": "NARU3472484" - } - } - ] - } - }, - "reeferExample": { - "summary": "Approved Transport Document with reefer cargo\n", - "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", - "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\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", - "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 + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" } - ], - "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" - } - ] + } + }, + "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" + } + } }, - "issuingParty": { - "partyName": "Mediterranean Shipping Company", - "address": { - "street": "Chemin Rieu", - "streetNumber": "12-14", - "city": "Geneva", - "countryCode": "CH" - }, - "identifyingCodes": [ - { - "codeListProvider": "SMDG", - "codeListName": "LCL", - "partyCode": "MSC" - } - ] + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" } - }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REEFER", - "descriptionOfGoods": [ - "Dairy products" - ], - "HSCodes": [ - "04052090" - ], - "cargoItems": [ - { - "equipmentReference": "KKFU6671914", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "BQ", - "description": "Bottles" + } + }, + "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" } - } - ] - } - ], - "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\n", - "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", - "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\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", - "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 + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" } - ], - "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" - } - ] + } + }, + "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" + } + } }, - "issuingParty": { - "partyName": "Hapag Lloyd", - "address": { - "street": "Ballindamm", - "streetNumber": "25", - "postCode": "D-20095", - "city": "Hamburg", - "countryCode": "DE" - }, - "identifyingCodes": [ - { - "codeListProvider": "SMDG", - "codeListName": "LCL", - "partyCode": "HLC" - } - ] + "schema" : { + "$ref" : "#/components/schemas/ErrorResponse" } - }, - "consignmentItems": [ - { - "carrierBookingReference": "RTM1234567", - "descriptionOfGoods": [ - "Environmentally hazardous substance", - "liquid, N.O.S (Propiconazole)" - ], - "HSCodes": [ - "293499" - ], - "cargoItems": [ - { - "equipmentReference": "HLXU1234567", - "grossWeight": { - "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" - } - ] + } + }, + "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" } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" - } - ], - "cargoGrossWeight": 12000, - "cargoGrossWeightUnit": "KGM", - "equipment": { - "ISOEquipmentCode": "22G1", - "equipmentReference": "HLXU1234567" - } + } + }, + "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" + } } - } - } - } - }, - "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": { - "description": "In case the consumer is requesting a `transportDocumentReference` that does not exist.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "documentReference not found\n", - "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", - "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" + "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" + } } - } - } - } - }, - "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" - } + }, + "description" : "Parameters used to update the `Shipping Instructions`\n", + "required" : true }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while fetching the Transport Document\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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" + "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" + } } - } - } - } - }, - "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": "Fetching too many `Transport Document` requests\n", - "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", - "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\n", - "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" + }, + "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" + } } - } - } - } - } - } - }, - "patch": { - "tags": [ - "Transport Document" - ], - "summary": "Approve a Transport Document\n", - "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 `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 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. The `transportDocumentStatus` is set to `APPROVED`.\n4. All '_relevant_' subscribers will be notified via a [Transport Document Notification](#/TransportDocumentNotification).\n\nThe provider will now start asynchronous processing. Once processed, the new status of the `Transport Document` (`ISSUED`) will be communicated via a [Transport Document Notification](#/TransportDocumentNotification). 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` in the `Transport Document` has changed.\n\n## Flow for a `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.\n", - "operationId": "approve-transport-document", - "parameters": [ - { - "name": "transportDocumentReference", - "in": "path", - "description": "The `transportDocumentReference` of the `Transport Document`\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "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" - } - }, - { - "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/transportdocuments_transportDocumentReference_body" - } - } - } - }, - "responses": { - "200": { - "description": "The `Transport Document` has been successfully `APPROVED`\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TransportDocumentRefStatus" - }, - "examples": { - "approveExample": { - "summary": "Approve Draft Transport Document\n", - "description": "Consumer approves the drafted `Transport Document`.\n", - "value": { - "transportDocumentReference": "td-987", - "transportDocumentStatus": "APPROVED" - } + }, + "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" + } } - } - } - } - }, - "202": { - "description": "The `Transport Document` has been accepted and now awaits further processing\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "examples": { - "approveExample": { - "summary": "Approve Draft Transport Document\n", - "description": "Consumer approves the drafted `Transport Document` and now awaits further processing by provider.\n" + }, + "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" + } } - } - } - } - }, - "400": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequestExample": { - "summary": "Wrong Transport Document status\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "404": { - "description": "In case the consumer is requesting a `transportDocumentReference` that does not exist.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "documentReference not found\n", - "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", - "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" + }, + "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" + } } - } - } - } - }, - "409": { - "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" - } + } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFoundExample": { - "summary": "documentReference is being processed\n", - "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", - "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" + "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" + } } - } - } - } - }, - "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" - } + }, + "description" : "The payload used to create a [`Transport Document Notification`](#/TransportDocumentNotification)\n" }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "internalServerErrorExample": { - "summary": "Internal Server Error while approving the `Draft Transport Document`\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**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", - "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" - } - ] - } + "responses" : { + "204" : { + "description" : "No Content\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - } - } - } - }, - "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": "Too many Patch `Transport Document` requests\n", - "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", - "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\n", - "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" + }, + "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" } - ] - } - } - } - } - } - } - } - } - }, - "/v3/shipping-instructions-notifications": { - "post": { - "tags": [ - "Notifications" - ], - "summary": "Send a new Shipping Instructions Notification", - "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": [ - { - "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": { - "description": "The payload used to create a [`Shipping Instructions Notification`](#/ShippingInstructionsNotification)\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShippingInstructionsNotification" - }, - "examples": { - "receivedLightweightExample": { - "summary": "Shipping Instructions request received (Lightweight)\n", - "description": "A lightweight notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`).\n", - "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" - } + } + }, + "description" : "In case the `Notification` does not schema validate a `400` (Bad Request) is returned\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - }, - "receivedFullStateTransferExample": { - "summary": "Shipping Instructions request received (Full State Transfer)\n", - "description": "A full state transfer notification explaining that a new `Shipping Instructions` has been received and stored in provider system (`shippingInstructionsStatus='RECEIVED'`).\n", - "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" + }, + "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" + } + } }, - "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" + "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" } - ] - } + } }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "weight": 12000, - "weightUnit": "KGM", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "value": 12000, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" - } + "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", + "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" + } + ] + } + ] } - ] - } - ], - "utilizedTransportEquipments": [ - { - "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" + } + ] + } + ] } - ], - "equipmentReference": "NARU3472484" - } - ] - } - } + } + }, + "schema" : { + "$ref" : "#/components/schemas/TransportDocument" + } + } + }, + "description" : "The `Transport Document`\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - }, - "declinedLightweightExample": { - "summary": "Shipping Instructions update declined (Lightweight)\n", - "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", - "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" - } + }, + "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" + } } - }, - "declinedFullStateTransferExample": { - "summary": "Shipping Instructions update declined (Full State Transfer)\n", - "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", - "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" - }, - "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" + }, + "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" } - ] - } + } }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "weight": 12, - "weightUnit": "KGM", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "value": 12, - "unit": "KGM" - }, - "outerPackaging": { - "numberOfPackages": 400, - "packageCode": "4G", - "description": "Fibreboard boxes" - } - } - ] - } - ], - "utilizedTransportEquipments": [ - { - "isShipperOwned": false, - "seals": [ - { - "number": "DCSA-CTK-1234" + "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" } - ], - "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" + } }, - "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" + "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" } - ] - } + } }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "weight": 120000, - "weightUnit": "KGM", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "commoditySubreference": "RegSubRef001", - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "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\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": "Shipping Instructions missing shippingInstructionsReference\n", - "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", - "value": { - "httpMethod": "POST", - "requestUri": "/v3/shipping-instructions-notifications", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "shippingInstructionsReference not found - mandatory to provide in a Notification\n", - "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\n" + "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" + } } - } - } - } - }, - "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": "/v3/shipping-instructions-notifications", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Shipping Instructions\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2024-09-04T09:41:00Z", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Internal Error occurred", - "errorCodeMessage": "Internal Error occurred" - } - ] - } + "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" : [ + { + "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/transportdocuments_transportDocumentReference_body" + } } - } - } - } - }, - "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 /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", - "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\n", - "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" + "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" + } } - ] - } - } - } - } - } - } - } - } - }, - "/v3/transport-document-notifications": { - "post": { - "tags": [ - "Notifications" - ], - "summary": "Send a new Transport Document Notification", - "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": [ - { - "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": { - "description": "The payload used to create a [`Transport Document Notification`](#/TransportDocumentNotification)\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TransportDocumentNotification" - }, - "examples": { - "draftLightweightExample": { - "summary": "Transport Document Draft created (Lightweight)\n", - "description": "A lightweight notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`).\n", - "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" - } + } + }, + "description" : "The approval of the `Transport Document` has been accepted and now awaits further processing\n", + "headers" : { + "API-Version" : { + "$ref" : "#/components/headers/API-Version" + } } - }, - "draftFullStateTransferExample": { - "summary": "Transport Document Draft created (Full State Transfer)\n", - "description": "A full state transfer notification explaining that a new `Draft Transport Document` has been created and stored in provider system (`transportDocumentStatus='DRAFT'`).\n", - "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\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", - "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" + }, + "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" } - ] - }, - "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", - "grossWeight": { - "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)\n", - "description": "A lightweight notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`)\n", - "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" - } + "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" + } } - }, - "issuedFullStateTransferExample": { - "summary": "Transport Document has been issued (Full State Transfer)\n", - "description": "A full state transfer notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`)\n", - "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\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", - "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" + }, + "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" } - ] - } + } }, - "consignmentItems": [ - { - "carrierBookingReference": "CBR_123_REGULAR", - "descriptionOfGoods": [ - "Shoes - black" - ], - "HSCodes": [ - "640510" - ], - "cargoItems": [ - { - "equipmentReference": "NARU3472484", - "grossWeight": { - "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" - } - } - ] - } - } + "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" + } } - } - } - } - } - }, - "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": "Transport Document missing transportDocumentReference\n", - "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", - "value": { - "httpMethod": "POST", - "requestUri": "/v3/transport-document-notifications", - "statusCode": 400, - "statusCodeText": "Bad Request", - "statusCodeMessage": "transportDocumentReference not found - mandatory to provide in a Notification\n", - "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\n" + }, + "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": { - "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": "/v3/transport-document-notifications", - "statusCode": 500, - "statusCodeText": "Internal Server Error", - "statusCodeMessage": "Internal Server Error occurred while processing Transport Document\n", - "providerCorrelationReference": "4426d965-0dd8-4005-8c63-dc68b01c4962", - "errorDateTime": "2024-09-04T09:41:00Z", - "errors": [ - { - "errorCode": 7003, - "errorCodeText": "Internal Error occurred", - "errorCodeMessage": "Internal Error occurred" + }, + "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": { - "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 /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", - "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\n", - "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" + }, + "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" + } } - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "ShippingInstructionsNotification": { - "title": "Shipping Instructions 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.shipping-instructions.v3", - "enum": [ - "org.dcsa.shipping-instructions.v3" - ] - }, - "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/Data" - } - }, - "description": "`CloudEvent` specific properties for the `Notification`.\n" - }, - "TransportDocumentNotification": { - "title": "Transport Document 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.transport-document.v3", - "enum": [ - "org.dcsa.transport-document.v3" - ] - }, - "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/Data_1" - } - }, - "description": "`CloudEvent` specific properties for the `Notification`.\n" - }, - "CreateShippingInstructions": { - "title": "Create Shipping Instructions", - "required": [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "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" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "example": true - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "Indicates the shipper’s platform on which the eBL should be issued. 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` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Mandatory for electronic Bill of Lading (`isElectronic=true`).\n", - "example": "WAVE" - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/Place of Issue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "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" - } - }, - "isCarriersAgentAtDestinationRequired": { - "type": "boolean", - "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example": false - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "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", - "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/ConsignmentItemShipper" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipmentShipper" - } - }, - "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" - } - }, - "advanceManifestFilings": { - "type": "array", - "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" - } - }, - "isHBLIssued": { - "type": "boolean", - "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 - }, - "houseBillOfLadings": { - "type": "array", - "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", - "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\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierCertificate" - } - }, - "requestedCarrierClauses": { - "type": "array", - "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierClause" - } - } - }, - "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" - }, - "UpdateShippingInstructions": { - "title": "Update Shipping Instructions", - "required": [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsReference", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "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" - }, - "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" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "example": true - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "Indicates the shipper’s platform on which the eBL should be issued. 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` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Mandatory for electronic Bill of Lading (`isElectronic=true`).\n", - "example": "WAVE" - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/Place of Issue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "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" - } - }, - "isCarriersAgentAtDestinationRequired": { - "type": "boolean", - "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example": false - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "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", - "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/ConsignmentItemShipper" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipmentShipper" - } - }, - "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" - } - }, - "advanceManifestFilings": { - "type": "array", - "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" - } - }, - "isHBLIssued": { - "type": "boolean", - "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 - }, - "houseBillOfLadings": { - "type": "array", - "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", - "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\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierCertificate" - } - }, - "requestedCarrierClauses": { - "type": "array", - "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierClause" - } - } - }, - "description": "The `Shipping Instructions` to update.\n" - }, - "ShippingInstructions": { - "title": "Shipping Instructions", - "required": [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsStatus", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "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" - }, - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "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" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "example": true - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "Indicates the shipper’s platform on which the eBL should be issued. 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` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Mandatory for electronic Bill of Lading (`isElectronic=true`).\n", - "example": "WAVE" - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/Place of Issue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "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" - } - }, - "isCarriersAgentAtDestinationRequired": { - "type": "boolean", - "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example": false - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "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", - "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/ConsignmentItemShipper" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipmentShipper" - } - }, - "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" - } - }, - "advanceManifestFilings": { - "type": "array", - "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" - } - }, - "isHBLIssued": { - "type": "boolean", - "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 - }, - "houseBillOfLadings": { - "type": "array", - "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", - "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\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierCertificate" - } - }, - "requestedCarrierClauses": { - "type": "array", - "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierClause" - } - }, - "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 `Shipping Instructions` as provided by the Shipper.\n" - }, - "ShippingInstructionsRefStatus": { - "title": "Shipping Instructions Response", - "required": [ - "shippingInstructionsStatus" - ], - "type": "object", - "properties": { - "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" - }, - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "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 `shippingInstructionsReference`, possibly the `transportDocumentReference` along with the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus`, an optional list of `Feedback` to be applied to the `Shipping Instructions` and and optional `reason` field is returned.\n" - }, - "ShippingInstructionsRefCancelStatus": { - "title": "Shipping Instructions Cancel Response", - "required": [ - "shippingInstructionsStatus" - ], - "type": "object", - "properties": { - "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" - }, - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED`\n", - "example": "UPDATE_CANCELLED" - }, - "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 `shippingInstructionsReference`, possibly the `transportDocumentReference` along with the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` and and optional `reason` field is returned.\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": "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://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": "N/A" - }, - "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" - }, - "City": { - "title": "City", - "required": [ - "city", - "countryCode" - ], - "type": "object", - "properties": { - "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.\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- 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) - for `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`\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" - }, - "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- `CSR` (Consolidator)\n- `MFR` (Manufacturer)\n- `WHK` (Warehouse Keeper)\n", - "example": "DDS" - } - }, - "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n" - }, - "OtherDocumentPartyHBL": { - "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- `CSR` (Consolidator)\n- `MFR` (Manufacturer)\n- `WHK` (Warehouse Keeper)\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", - "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" - }, - "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\n**Condition:** Either the `address` or the `displayedAddress` must be included in the `Transport Document`.\n" - }, - "ShipperHBL": { - "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" - }, - "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 `Shipper` on the `House Bill of Lading`.\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", - "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" - }, - "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\n**Condition:** Mandatory for non-negotiable BL (`isToOrder=false`)\n" - }, - "ConsigneeHBL": { - "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" - }, - "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 ultimate recipient of the cargo. It must be different from the freight forwarder, (de)consolidator, postal operator, or customs agent.\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", - "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" - }, - "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\n**Condition:** Mandatory for eBL (Is Electronic = TRUE).\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", - "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" - }, - "NotifyPartyHBL": { - "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" - }, - "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 person to be notified when a shipment arrives at its destination.\n" - }, - "Seller": { - "title": "Seller", - "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" - }, - "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 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" - }, - "Buyer": { - "title": "Buyer", - "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" - }, - "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 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" - }, - "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" - }, - "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": "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" - }, - "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" - }, - "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", - "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", - "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/Reference" - } - }, - "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" - }, - "ConsignmentItemShipper": { - "title": "Consignment Item (Shipper)", - "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" - }, - "commoditySubreference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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" - }, - "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", - "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", - "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/CargoItemShipper" - } - }, - "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": "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": [ - "equipmentReference", - "grossWeight", - "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://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" - }, - "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" - }, - "grossVolume": { - "$ref": "#/components/schemas/Gross Volume" - }, - "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" - }, - "CargoItemShipper": { - "title": "Cargo Item (Shipper)", - "required": [ - "equipmentReference", - "grossWeight" - ], - "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://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" - }, - "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" - }, - "grossVolume": { - "$ref": "#/components/schemas/Gross Volume" - }, - "outerPackaging": { - "$ref": "#/components/schemas/OuterPackagingShipper" - }, - "nationalCommodityCodes": { - "type": "array", - "description": "A list of `National Commodity Codes` that apply to this `cargoItem`\n", - "items": { - "$ref": "#/components/schemas/NationalCommodityCode" - } - }, - "houseBillOfLadingReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Link to the House Bill of Lading this cargoItem is connected to.\n", - "example": "ABC123" - }, - "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" - }, - "OuterPackagingShipper": { - "title": "Outer Packaging (Shipper)", - "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" - }, - "numberOfPackages": { - "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" - } - }, - "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" - }, - "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": { - "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/Gross Weight_1" - }, - "netWeight": { - "$ref": "#/components/schemas/Net Weight" - }, - "netExplosiveContent": { - "$ref": "#/components/schemas/Net Explosive Content" - }, - "netVolume": { - "$ref": "#/components/schemas/Net Volume" - }, - "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" - } - } - } - ] - }, - "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\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", - "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" - }, - "UtilizedTransportEquipmentShipper": { - "title": "Utilized Transport Equipment (Shipper)", - "required": [ - "seals" - ], - "type": "object", - "properties": { - "shippingMarks": { - "maxItems": 50, - "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\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`), `Seals` and `References`\n", - "discriminator": { - "propertyName": "isShipperOwned", - "mapping": { - "true": "#/components/schemas/UTEquipment", - "false": "#/components/schemas/UTEquipmentReference" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/UTEquipment" - }, - { - "$ref": "#/components/schemas/UTEquipmentReference" - } - ] - }, - "UTEquipment": { - "title": "Shipper Owned Equipment (SoC)", - "required": [ - "equipment", - "isShipperOwned" - ], - "type": "object", - "properties": { - "isShipperOwned": { - "type": "boolean", - "description": "Indicates whether the container is shipper owned (SOC).\n", - "example": true - }, - "equipment": { - "$ref": "#/components/schemas/RequiredEquipment" - } - }, - "description": "To be used for SoC (Shipper owned Containers). If `isShipperOwned` is true then the equipment used needs to be specified\n" - }, - "UTEquipmentReference": { - "title": "Carrier Owned Equipment", - "required": [ - "equipmentReference", - "isShipperOwned" - ], - "type": "object", - "properties": { - "isShipperOwned": { - "type": "boolean", - "description": "Indicates whether the container is shipper owned (SOC).\n", - "example": false - }, - "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://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" - } - }, - "description": "To be used when referring to carrier owned containers (`isShipperOwned` is false). In this case it is only necessary to provide `equipmentReference`\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://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" - }, - "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": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "weightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n\n**Condition:** Mandatory to provide if `tareWeight` is provided\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "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" - }, - "RequiredEquipment": { - "title": "Equipment (Required Properties)", - "required": [ - "ISOEquipmentCode", - "equipmentReference", - "tareWeight", - "weightUnit" - ], - "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://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" - }, - "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": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "weightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n\n**Condition:** Mandatory to provide if `tareWeight` is provided\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "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" - }, - "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" - }, - "AdvanceManifestFiling": { - "title": "Advance Manifest Filing", - "required": [ - "advanceManifestFilingsHouseBLPerformedBy", - "countryCode", - "manifestTypeCode" - ], - "type": "object", - "properties": { - "manifestTypeCode": { - "maxLength": 50, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The Manifest type code as defined by the provider.\n", - "example": "ENS" - }, - "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" - }, - "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:\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", - "example": "SELF", - "enum": [ - "SELF", - "CARRIER" - ] - }, - "selfFilerCode": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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" - }, - "supplementaryDeclarantEORINumber": { - "maxLength": 17, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The Economic Operators Registration and Identification (EORI) number of the house filer responsible for the `ENS` filing.\n\n**Conditional:** only applicable if `manifestTypeCode` is `ENS`.\n", - "example": "FLXP-123321" - } - }, - "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": { - "manifestTypeCode": "ACE", - "countryCode": "US", - "advanceManifestFilingsHouseBLPerformedBy": "SELF", - "selfFilerCode": "FLXP123" - } - }, - "HouseBillOfLading": { - "title": "House Bill of Lading", - "required": [ - "houseBillOfLadingReference" - ], - "type": "object", - "properties": { - "houseBillOfLadingReference": { - "maxLength": 20, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "A unique number allocated by the Ocean Transport Intermediary (OTI) to the `House Bill of Lading`.\n", - "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\n", - "example": false - }, - "placeOfAcceptance": { - "$ref": "#/components/schemas/PlaceOfAcceptance" - }, - "placeOfFinalDelivery": { - "$ref": "#/components/schemas/PlaceOfFinalDelivery" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties_2" - } - }, - "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" - }, - "PlaceOfAcceptance": { - "title": "Place of Acceptance", - "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 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": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "PlaceOfFinalDelivery": { - "title": "Place of Final 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 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": { - "locationName": "Hamburg", - "UNLocationCode": "DEHAM" - } - }, - "RequestedCarrierCertificate": { - "title": "Requested Carrier Certificate", - "maxLength": 100, - "type": "string", - "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" - }, - "RequestedCarrierClause": { - "title": "Requested Carrier Clause", - "maxLength": 100, - "type": "string", - "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" - }, - "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.", - "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. Only applicable for physical (paper) documents", - "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", - "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", - "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", - "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", - "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" + "summary" : "Approve a Transport Document\n", + "tags" : [ + "Transport Document" ] - }, - "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 `NMFTA` or `SMDG` code of the issuing carrier of the `Transport Document`\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" - ] - }, - "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/Place of Issue" - }, - "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" - } - } - } - ] - }, - "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/Document Parties_1" - }, - "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", - "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" - }, - "TransportDocumentRefStatus": { - "title": "Transport Document Response", - "required": [ - "transportDocumentReference", - "transportDocumentStatus" - ], - "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" - }, - "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" - } - }, - "description": "The `transportDocumentReference` along with the `transportDocumentStatus` for the `Transport Document` is returned.\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" - }, - "Shipping Instructions Response": { - "title": "Shipping Instructions Response", - "required": [ - "shippingInstructionsReference", - "shippingInstructionsStatus" - ], - "type": "object", - "properties": { - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Shipping Instructions`. Possible values are:\n- `RECEIVED` (Shipping Instructions 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 `shippingInstructionsReference` along with the `shippingInstructionsStatus` and an optional `feedbacks` is returned.\n" - }, - "Shipping Instructions Response_1": { - "title": "Shipping Instructions Response", - "required": [ - "shippingInstructionsReference" - ], - "type": "object", - "properties": { - "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" - } - }, - "description": "**Only** the `shippingInstructionsReference` is returned.\n" - }, - "shippinginstructions_documentReference_body": { - "required": [ - "updatedShippingInstructionsStatus" - ], - "type": "object", - "properties": { - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED`\n", - "example": "UPDATE_CANCELLED" - } - } - }, - "transportdocuments_transportDocumentReference_body": { - "required": [ - "transportDocumentStatus" - ], - "type": "object", - "properties": { - "transportDocumentStatus": { - "maxLength": 50, - "type": "string", - "description": "The status of the `Transport Document`. It can only be `APPROVED`\n", - "example": "APPROVED" - } - } - }, - "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" - }, - "Place of Issue": { - "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" - } - } - } - ] - }, - "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)", - "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" - }, - "Document Parties": { - "title": "Document Parties", - "required": [ - "shipper" - ], - "type": "object", - "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": { - "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**Condition:** Mandatory for To Order BLs, `isToOrder=true`\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" - }, - "Shipping Instructions": { - "title": "Shipping Instructions", - "required": [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsStatus", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "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" - }, - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "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" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "example": true - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "Indicates the shipper’s platform on which the eBL should be issued. 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` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Mandatory for electronic Bill of Lading (`isElectronic=true`).\n", - "example": "WAVE" - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/Place of Issue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "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" - } - }, - "isCarriersAgentAtDestinationRequired": { - "type": "boolean", - "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example": false - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "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", - "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/ConsignmentItemShipper" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipmentShipper" - } - }, - "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" - } - }, - "advanceManifestFilings": { - "type": "array", - "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" - } - }, - "isHBLIssued": { - "type": "boolean", - "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 - }, - "houseBillOfLadings": { - "type": "array", - "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", - "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\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierCertificate" - } - }, - "requestedCarrierClauses": { - "type": "array", - "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierClause" - } - }, - "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 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" - }, - "Updated Shipping Instructions": { - "title": "Updated Shipping Instructions", - "required": [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsStatus", - "transportDocumentTypeCode", - "utilizedTransportEquipments" - ], - "type": "object", - "properties": { - "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" - }, - "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" - }, - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "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" - ] - }, - "originChargesPaymentTerm": { - "$ref": "#/components/schemas/Origin Charges Payment Term" - }, - "destinationChargesPaymentTerm": { - "$ref": "#/components/schemas/Destination Charges Payment Term" - }, - "methodOfPayment": { - "maxLength": 1, - "type": "string", - "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" - }, - "isElectronic": { - "type": "boolean", - "description": "An indicator whether the transport document is electronically transferred.\n", - "example": true - }, - "sendToPlatform": { - "maxLength": 4, - "pattern": "^\\S+$", - "type": "string", - "description": "Indicates the shipper’s platform on which the eBL should be issued. 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` (TRACE Original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Mandatory for electronic Bill of Lading (`isElectronic=true`).\n", - "example": "WAVE" - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "items": { - "maxLength": 35, - "type": "string", - "description": "A line of the address to be displayed on the transport document.\n", - "example": "Strawinskylaan 4117" - } - }, - "placeOfIssue": { - "$ref": "#/components/schemas/Place of Issue" - }, - "invoicePayableAt": { - "$ref": "#/components/schemas/Invoice Payable At" - }, - "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" - } - }, - "isCarriersAgentAtDestinationRequired": { - "type": "boolean", - "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n", - "example": false - }, - "documentParties": { - "$ref": "#/components/schemas/Document Parties" - }, - "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", - "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/ConsignmentItemShipper" - } - }, - "utilizedTransportEquipments": { - "minItems": 1, - "type": "array", - "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", - "items": { - "$ref": "#/components/schemas/UtilizedTransportEquipmentShipper" - } - }, - "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" - } - }, - "advanceManifestFilings": { - "type": "array", - "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" - } - }, - "isHBLIssued": { - "type": "boolean", - "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 - }, - "houseBillOfLadings": { - "type": "array", - "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", - "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\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierCertificate" - } - }, - "requestedCarrierClauses": { - "type": "array", - "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", - "items": { - "$ref": "#/components/schemas/RequestedCarrierClause" - } - }, - "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 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" - }, - "Data": { - "title": "Data", - "required": [ - "shippingInstructionsStatus" - ], - "type": "object", - "properties": { - "shippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "updatedShippingInstructionsStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "shippingInstructionsReference": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "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" - }, - "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\n**Condition:** `shippingInstructionsReference` and/or `transportDocumentReference` is required to provide\n", - "example": "HHL71800000" - }, - "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" - } - }, - "shippingInstructions": { - "$ref": "#/components/schemas/Shipping Instructions" - }, - "updatedShippingInstructions": { - "$ref": "#/components/schemas/Updated Shipping Instructions" - } - }, - "description": "`Shipping Instructions` specific properties for the `Notification`\n" - }, - "Document Parties_1": { - "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**Condition:** Mandatory for To Order BLs, `isToOrder=true`\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" - }, - "Transport Document": { - "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.", - "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.", - "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", - "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", - "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", - "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", - "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 `NMFTA` or `SMDG` code of the issuing carrier of the `Transport Document`\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" - ] - }, - "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/Place of Issue" - }, - "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" - } - } - } - ] - }, - "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/Document Parties_1" - }, - "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", - "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": "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" - }, - "Data_1": { - "title": "Data", - "required": [ - "transportDocumentReference", - "transportDocumentStatus" - ], - "type": "object", - "properties": { - "transportDocumentStatus": { - "maxLength": 50, - "type": "string", - "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" - }, - "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" - }, - "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" - }, - "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" - } - }, - "transportDocument": { - "$ref": "#/components/schemas/Transport Document" - } - }, - "description": "`Transport Document` specific properties for the `Notification`\n" - }, - "Gross Weight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, including packaging. Excludes the tare weight of the container(s).\n", - "format": "float", - "example": 2.4 - }, - "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 total weight of the cargo including packaging items being carried in the container(s). Excludes the tare weight of the container(s).\n" - }, - "Gross Volume": { - "title": "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.\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" - }, - "Gross Weight_1": { - "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" - }, - "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\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\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\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" - }, - "Document Parties_2": { - "title": "Document Parties", - "type": "object", - "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" - } - } - }, - "description": "All `Parties` with associated roles for this `House Bill of Lading`.\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" - } + }, + "servers" : [ + { + "url" : "/" + } + ], + "tags" : [ + { + "description" : "The Shipping Instructions endPoints to be implemented by **providers** of the Bill of Lading API\n", + "name" : "Shipping Instructions" }, - "documentReference": { - "name": "documentReference", - "in": "path", - "description": "An identifier for a `Shipping Instructions`. It can either be a `shippingInstructionsReference` or a `transportDocumentReference`.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "e0559d83-00e2-438e-afd9-fdd610c1a008" - } + { + "description" : "The Transport Document endPoints to be implemented by **providers** of the Bill of Lading API\n", + "name" : "Transport Document" }, - "updatedContent": { - "name": "updatedContent", - "in": "query", - "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", - "required": false, - "style": "form", - "explode": true, - "schema": { - "type": "boolean", - "example": false, - "default": false - } - } - }, - "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" - } + { + "description" : "The Notifications to be implemented by the **consumers** of the Bill of Lading API", + "name" : "Notifications" } - } - } + ] } diff --git a/pint/src/main/resources/standards/pint/messages/pint-3.0.0-transport-document.json b/pint/src/main/resources/standards/pint/messages/pint-3.0.0-transport-document.json index 84f64a77..be2a4e92 100644 --- a/pint/src/main/resources/standards/pint/messages/pint-3.0.0-transport-document.json +++ b/pint/src/main/resources/standards/pint/messages/pint-3.0.0-transport-document.json @@ -68,7 +68,7 @@ "cargoItems": [ { "equipmentReference": "NARU3472484", - "grossWeight": { + "cargoGrossWeight": { "value": 12000, "unit": "KGM" }, 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 index 79a77c54..076d339a 100644 --- 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 @@ -1,3559 +1,3674 @@ { - "openapi": "3.0.3", - "info": { - "title": "DCSA eBL Platform Interoperability API", - "description": "

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

\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).\nPlease [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": "3.0.0" - }, - "servers": [ - { - "url": "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_PINT/3.0.0", - "description": "SwaggerHub API Auto Mocking" - } - ], - "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" - ], - "summary": "Start the eBL envelope transfer", - "description": "Start the eBL envelope transfer.\n", - "operationId": "post-envelopes", - "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/EblEnvelope" - } - } - }, - "required": true - }, - "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.\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" - } - }, - "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.\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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferStartedResponse" - } - } - } - }, - "422": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - } - }, - "default": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v3/envelopes/{envelopeReference}/additional-documents/{documentChecksum}": { - "put": { - "tags": [ - "Transfer additional document" - ], - "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.\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": [ - { - "name": "envelopeReference", - "in": "path", - "description": "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "type": "string", - "example": "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU" - } - }, - { - "name": "documentChecksum", - "in": "path", - "description": "The checksum of the document computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "example": "7d00064ed0b90467ff7aff6032d8e2d94845745b6590895cd95708d2ee4243d8" - } - }, - { - "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": { - "type": "string", - "description": "A Base64 encoded payload containing the file to transfer.\n", - "format": "byte", - "example": "UmF3IGNvbnRlbnQgb2YgdGhlIGZpbGUgYmVpbmcgdHJhbnNmZXJyZWQ=" - } - } - }, - "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": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - } - }, - "422": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - } - }, - "default": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v3/envelopes/{envelopeReference}/finish-transfer": { - "put": { - "tags": [ - "Finish envelope transfer" - ], - "summary": "Finish the eBL envelope transfer", - "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": [ - { - "name": "envelopeReference", - "in": "path", - "description": "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "type": "string", - "example": "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU" - } - }, - { - "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" - } - } - ], - "responses": { - "200": { - "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" - } - }, - "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.\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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - } - }, - "422": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnvelopeTransferFinishedResponseSignedContent" - } - } - } - }, - "default": { - "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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v3/receiver-validation": { - "post": { - "tags": [ - "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\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": [ - { - "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/IdentifyingCode" - } - } - }, - "required": true - }, - "responses": { - "200": { - "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" - } - }, - "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\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" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Request failed for the unexpected reason. The unsigned response contains all the error details.\n", - "headers": { - "API-Version": { - "$ref": "#/components/headers/API-Version" - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "DocumentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "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": "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://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" - }, - "EblEnvelope": { - "title": "Ebl Envelope", - "required": [ - "envelopeManifestSignedContent", - "envelopeTransferChain", - "transportDocument" - ], - "type": "object", - "properties": { - "transportDocument": { - "$ref": "#/components/schemas/TransportDocument" - }, - "envelopeManifestSignedContent": { - "$ref": "#/components/schemas/EnvelopeManifestSignedContent" - }, - "envelopeTransferChain": { - "type": "array", - "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" - } - } - } - }, - "ReceiverValidationResponse": { - "title": "Receiver Validation Response", - "required": [ - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Globeteam" - } - }, - "description": "Response to a receiver validation response, where the party code could successfully identified.\n" - }, - "EnvelopeManifest": { - "title": "Envelope Manifest", - "required": [ - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "supportingDocuments", - "transportDocumentChecksum" - ], - "type": "object", - "properties": { - "transportDocumentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "lastEnvelopeTransferChainEntrySignedContentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "eBLVisualisationByCarrier": { - "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", - "allOf": [ - { - "$ref": "#/components/schemas/DocumentMetadata" - } - ] - }, - "supportingDocuments": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentMetadata" - } - } - } - }, - "EnvelopeManifestSignedContent": { - "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 [EnvelopeManifest](#/EnvelopeManifest).\n", - "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA" - }, - "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 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" - }, - "eBLVisualisationByCarrierChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "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" - }, - "EnvelopeTransferChainEntry": { - "title": "Envelope Transfer Chain Entry", - "required": [ - "eblPlatform", - "transactions", - "transportDocumentChecksum" - ], - "type": "object", - "properties": { - "eblPlatform": { - "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" - }, - "transportDocumentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "previousEnvelopeTransferChainEntrySignedContentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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", - "nullable": true, - "example": "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9" - }, - "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).\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" - }, - "transactions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Transaction" - } - } - } - }, - "EnvelopeTransferChainEntrySignedContent": { - "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 [EnvelopeTransferChainEntry](#/EnvelopeTransferChainEntry).\n", - "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudEhhc2giOiI4ZGM5OWQ4YWM5MjIyNDBjNTVjMDM4NDVmNDlkZWY2NDE4NzE0NjY1MWJhZTRmOWE2MzEzMTI3N2NmMDBkOWRmIiwicHJldmlvdXNFbnZlbG9wZUhhc2giOm51bGwsInRyYW5zYWN0aW9ucyI6W3siYWN0aW9uIjoiSVNTVSIsImNvbW1lbnRzIjoiVGhlIEIvTCBoYXMgYmVlbiBpc3N1ZWQuIiwidGltZXN0YW1wIjoxNjU4Mzg1MTY2MzAyNDQyMjAwLCJpc1RvT3JkZXIiOnRydWUsInBsYXRmb3JtSG9zdCI6ImxvY2FsaG9zdDo4NDQzIiwidHJhbnNmZXJlZSI6IjQzNTQ5ODUwMjQ4QGxvY2FsaG9zdDo4NDQzIn1dfQ.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA" - }, - "EnvelopeTransferStartedResponse": { - "title": "Envelope Transfer Started Response", - "required": [ - "envelopeReference", - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "missingAdditionalDocumentChecksums", - "transportDocumentChecksum" - ], - "type": "object", - "properties": { - "envelopeReference": { - "maxLength": 100, - "type": "string", - "description": "Opaque receiving platform-provided identifier for a given eBL envelope.\n", - "example": "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU" - }, - "transportDocumentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "lastEnvelopeTransferChainEntrySignedContentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "missingAdditionalDocumentChecksums": { - "type": "array", - "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" - } - } - } - }, - "EnvelopeTransferFinishedResponse": { - "required": [ - "lastEnvelopeTransferChainEntrySignedContentChecksum", - "responseCode" - ], - "type": "object", - "properties": { - "lastEnvelopeTransferChainEntrySignedContentChecksum": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "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" - }, - "responseCode": { - "type": "string", - "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", - "example": "RECE", - "enum": [ - "RECE", - "DUPE", - "BSIG", - "BENV", - "MDOC", - "DISE" - ] - }, - "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", - "allOf": [ - { - "$ref": "#/components/schemas/EnvelopeTransferChainEntrySignedContent" - } - ] - }, - "reason": { - "maxLength": 255, - "type": "string", - "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", - "nullable": true - }, - "missingAdditionalDocumentChecksums": { - "type": "array", - "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" - } - }, - "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.\n\nFor other response codes, this attribute should be omitted.\n", - "items": { - "$ref": "#/components/schemas/DocumentChecksum" - } - } - }, - "example": { - "lastEnvelopeTransferChainEntrySignedContentChecksum": "d56a93a7e9f86a2d895df818e0440bdca6ffe03246e2fee14131f2e66c84c75a", - "responseCode": "RECE" - } - }, - "EnvelopeTransferFinishedResponseSignedContent": { - "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 [EnvelopeTransferFinishedResponse](#/EnvelopeTransferFinishedResponse).\n", - "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJyZXNwb25zZVRvRW52ZWxvcGVIYXNoIjoiZDU2YTkzYTdlOWY4NmEyZDg5NWRmODE4ZTA0NDBiZGNhNmZmZTAzMjQ2ZTJmZWUxNDEzMWYyZTY2Yzg0Yzc1YSIsInJlc3BvbnNlQ29kZSI6IlJFQ1YifQ.P2_evKyvHH25BrvW4eIxp7xo9S73oK90QomKEjZDrn3AX8drv7aeVrNYYPPh4vqK78fTVair-0Ww9G7czX9Q3xlATTPlTQrNPuThh_-nPOvNDqHBwZuq_nop6lQwIS210OQa__C4z-oGvO8m56pfXvpgfTIC9nesnIuNFtrdr1lU81q4ZQnnZI0GvWaB_4Q320PoAXmKN4EwjY5gTqdKMAvz9a5PNnWfGPkIrM-CBm_MNLpl9NAcpJONRdwI9i9zTi42NZCUnbowHuHnYNuz3WfWzVA43U4IdEBDU6XeIem0Zm331KlBAukOhZiyN8Bp7ZK7XGx50a6XcY3190lX5Q" - }, - "DocumentMetadata": { - "required": [ - "documentChecksum", - "mediaType", - "name", - "size" - ], - "type": "object", - "properties": { - "name": { - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "example": "Carrier rendered copy of the original B/L document.pdf" - }, - "size": { - "minimum": 1, - "pattern": "^\\d+$", - "type": "number", - "description": "the Size of the document in bytes", - "example": 4194304 - }, - "mediaType": { - "type": "string", - "description": "The Media Type (MIME type) of the document", - "example": "application/pdf" - }, - "documentChecksum": { - "$ref": "#/components/schemas/DocumentChecksum" - } - }, - "description": "The document metadata that describes the document.\n" - }, - "Transaction": { - "required": [ - "action", - "actor", - "recipient", - "timestamp" - ], - "type": "object", - "properties": { - "action": { - "type": "string", - "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", - "example": "ISSU", - "enum": [ - "ISSU", - "ENDO", - "TRNS", - "RESD", - "RESA", - "SACC", - "SREJ" - ] - }, - "actor": { - "$ref": "#/components/schemas/TransactionParty" - }, - "recipient": { - "$ref": "#/components/schemas/TransactionParty" - }, - "timestamp": { - "type": "integer", - "description": "Unix epoch with millisecond precision of when the transaction was created.", - "format": "int64", - "example": 1713342679531 - }, - "reason": { - "maxLength": 4, - "type": "string", - "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" - }, - "comments": { - "maxLength": 255, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Free text comment for the party receiving the transaction.", - "example": "The B/L has been issued." - } - } - }, - "TransactionParty": { - "title": "Transaction Party", - "required": [ - "eblPlatform", - "partyName" - ], - "type": "object", - "properties": { - "partyName": { - "maxLength": 70, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "Name of the party.\n", - "example": "Globeteam" - }, - "eblPlatform": { - "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": "Refers to a company or a legal entity." - }, - "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.", - "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.", - "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", - "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", - "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", - "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", - "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 `NMFTA` or `SMDG` code of the issuing carrier of the `Transport Document`\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" - ] - }, - "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/Place of Issue" - }, - "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" - } - } - } - ] - }, - "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/Document Parties" - }, - "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", - "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 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" - }, - "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" + "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" ], - "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" + "title" : "Address", + "type" : "object" + }, + "Cargo Gross Volume" : { + "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" ], - "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" - }, - "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", - "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", - "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/Reference" - } - }, - "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" + "title" : "Cargo Gross Volume", + "type" : "object" + }, + "Cargo Gross Weight" : { + "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" ], - "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": [ - "equipmentReference", - "grossWeight", - "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://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" - }, - "grossWeight": { - "$ref": "#/components/schemas/Gross Weight" - }, - "grossVolume": { - "$ref": "#/components/schemas/Gross Volume" - }, - "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" - }, - "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": { - "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/Gross Weight_1" - }, - "netWeight": { - "$ref": "#/components/schemas/Net Weight" - }, - "netExplosiveContent": { - "$ref": "#/components/schemas/Net Explosive Content" - }, - "netVolume": { - "$ref": "#/components/schemas/Net Volume" - }, - "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" + "title" : "Cargo Gross Weight", + "type" : "object" + }, + "Cargo Net Volume" : { + "description" : "Calculated by multiplying the width, height, and length of the packed 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 packed cargo, excluding packaging.\n", + "example" : 2.4, + "exclusiveMinimum" : true, + "format" : "float", + "minimum" : 0, + "type" : "number" + } + }, + "required" : [ + "unit", + "value" ], - "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" + "title" : "Cargo Net Volume", + "type" : "object" + }, + "Cargo Net Weight" : { + "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" ], - "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": "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\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", - "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://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" - }, - "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": "22GP" - }, - "tareWeight": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "The weight of an empty container (gross container weight).\n", - "format": "float", - "example": 4800 - }, - "weightUnit": { - "type": "string", - "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n\n**Condition:** Mandatory to provide if `tareWeight` is provided\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" - ] - } - }, - "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" - }, - "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 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": "N/A" - }, - "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" - }, - "City": { - "title": "City", - "required": [ - "city", - "countryCode" - ], - "type": "object", - "properties": { - "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.\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- 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) - for `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 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" - }, - "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", - "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" - }, - "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\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", - "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" - }, - "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\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", - "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", - "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" - }, - "Place of Issue": { - "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" + "title" : "Cargo Net 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/Cargo Gross Volume" + }, + "cargoGrossWeight" : { + "$ref" : "#/components/schemas/Cargo Gross Weight" + }, + "cargoNetVolume" : { + "$ref" : "#/components/schemas/Cargo Net Volume" + }, + "cargoNetWeight" : { + "$ref" : "#/components/schemas/Cargo Net Weight" + }, + "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" ], - "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" + "title" : "Cargo Item", + "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" ], - "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" - } - } - } - ] - }, - "Document Parties": { - "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**Condition:** Mandatory for To Order BLs, `isToOrder=true`\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" - }, - "Gross Weight": { - "title": "Gross Weight", - "required": [ - "unit", - "value" - ], - "type": "object", - "properties": { - "value": { - "minimum": 0, - "exclusiveMinimum": true, - "type": "number", - "description": "Total weight of the goods carried, including packaging. Excludes the tare weight of the container(s).\n", - "format": "float", - "example": 2.4 - }, - "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 total weight of the cargo including packaging items being carried in the container(s). Excludes the tare weight of the container(s).\n" - }, - "Gross Volume": { - "title": "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.\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" - }, - "Gross Weight_1": { - "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" + "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", + "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", + "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", + "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/Gross Weight" + }, + "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/Net Explosive Content" + }, + "netVolume" : { + "$ref" : "#/components/schemas/Net Volume" + }, + "netWeight" : { + "$ref" : "#/components/schemas/Net Weight" + }, + "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" + }, + "Document Parties" : { + "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:** Mandatory for To Order BLs, `isToOrder=true`\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" + }, + "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" + }, + "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", + "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/Tare Weight" + } + }, + "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" + }, + "Gross Weight" : { + "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" + }, + "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" + }, + "Net Explosive Content" : { + "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" + }, + "Net Volume" : { + "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" + }, + "Net Weight" : { + "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", + "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" + }, + "Place of Issue" : { + "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" + }, + "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" + }, + "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", + "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" + }, + "Tare Weight" : { + "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", + "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", + "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", + "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", + "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/Document Parties" + }, + "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" : { + "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" + }, + "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/Place of Issue" + }, + "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", + "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", + "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) standard

\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).\nPlease [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\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" ] - } - }, - "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\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR" + } + }, + "/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" ] - } - }, - "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\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n- `GRM` (Grams)\n- `ONZ` (Ounce)\n", - "example": "KGM", - "enum": [ - "KGM", - "LBR", - "GRM", - "ONZ" + } + }, + "/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" ] - } - }, - "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\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n- `LTR` (Litre)\n", - "example": "MTQ", - "enum": [ - "MTQ", - "FTQ", - "LTR" + } + }, + "/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" ] - } - }, - "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": "3" - } - }, - "envelopeReference": { - "name": "envelopeReference", - "in": "path", - "description": "The receiving platform-provided unique identifier for the given eBL envelope.\n", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 100, - "type": "string", - "example": "4TkP5nvgTly0MwFrDxfIkR2rvOjkUIgzibBoKABU" - } - }, - "documentChecksum": { - "name": "documentChecksum", - "in": "path", - "description": "The checksum of the document computed using SHA-256 hash algorithm according to [RFC 6234](https://datatracker.ietf.org/doc/html/rfc6234).", - "required": true, - "style": "simple", - "explode": false, - "schema": { - "maxLength": 64, - "minLength": 64, - "pattern": "^[0-9a-f]+$", - "type": "string", - "example": "7d00064ed0b90467ff7aff6032d8e2d94845745b6590895cd95708d2ee4243d8" - } + }, + "servers" : [ + { + "description" : "SwaggerHub API Auto Mocking", + "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_PINT/3.0.0" } - }, - "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" - } + ], + "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" } - } - } + ] } From 0d2cde4c9f241f2fb2b13e9402900eb8b50ef0cc Mon Sep 17 00:00:00 2001 From: Niels Thykier Date: Thu, 26 Sep 2024 11:30:06 +0200 Subject: [PATCH 2/5] DT-1437: Add custom error codes to issuance response --- .../party/EblIssuancePlatform.java | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java index c5ad378d..9964aa0a 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.eblissuance.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.*; @@ -19,13 +20,10 @@ import org.dcsa.conformance.core.traffic.ConformanceRequest; import org.dcsa.conformance.core.traffic.ConformanceResponse; import org.dcsa.conformance.standards.ebl.crypto.Checksums; -import org.dcsa.conformance.standards.ebl.crypto.PayloadSignerFactory; import org.dcsa.conformance.standards.eblissuance.action.IssuanceResponseAction; import org.dcsa.conformance.standards.eblissuance.action.IssuanceResponseCode; import org.dcsa.conformance.standards.eblissuance.action.SupplyScenarioParametersAction; -import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; - @Slf4j public class EblIssuancePlatform extends ConformanceParty { private final Map eblStatesByTdr = new HashMap<>(); @@ -94,8 +92,8 @@ protected Map, Consumer> getActionP private void sendIssuanceResponse(JsonNode actionPrompt) { log.info( "EblIssuancePlatform.sendIssuanceResponse(%s)".formatted(actionPrompt.toPrettyString())); - String tdr = actionPrompt.get("tdr").asText(); - String irc = actionPrompt.get("irc").asText(); + String tdr = actionPrompt.path("tdr").asText(); + String irc = actionPrompt.path("irc").asText(); if (eblStatesByTdr.containsKey(tdr)) { if (Objects.equals(IssuanceResponseCode.ACCEPTED.standardCode, irc)) { @@ -106,13 +104,22 @@ private void sendIssuanceResponse(JsonNode actionPrompt) { knownChecksums.remove(checksum); } } + var response = OBJECT_MAPPER + .createObjectNode() + .put("transportDocumentReference", tdr) + .put("issuanceResponseCode", irc); + + if (irc.equals("BREQ")) { + response.putArray("errors") + .addObject() + .put("reason", "Rejected as required by the conformance scenario") + .put("errorCode", "CTK-1234"); + } syncCounterpartPost( "/v%s/ebl-issuance-responses".formatted(apiVersion.charAt(0)), - OBJECT_MAPPER - .createObjectNode() - .put("transportDocumentReference", tdr) - .put("issuanceResponseCode", irc)); + response + ); addOperatorLogEntry( "Sent issuance response with issuanceResponseCode '%s' for eBL with transportDocumentReference '%s'" From f27a9b3006580f3061feeaf52669844aff3b9467 Mon Sep 17 00:00:00 2001 From: "J. Koster" Date: Fri, 27 Sep 2024 10:13:16 +0200 Subject: [PATCH 3/5] Generic projects updates (#169) * use one objectMapper everywhere * use "Api-Version" from one location * fix some typos of copy-paste issues from the past * give better error message, when schema file is not found * update deps --- .../model/PersistableCarrierBooking.java | 9 +--- .../booking/party/BookingCarrier.java | 33 +++++---------- .../booking/party/BookingShipper.java | 7 ++-- .../party/CarrierScenarioParameters.java | 5 ++- .../party/DynamicScenarioParameters.java | 8 ++-- cdk/pom.xml | 6 --- .../standards/cs/action/CsAction.java | 4 +- .../standards/cs/party/CsPublisher.java | 7 ++-- .../cs/party/DynamicScenarioParameters.java | 5 ++- .../cs/party/SuppliedScenarioParameters.java | 5 ++- .../core/check/ApiHeaderCheck.java | 32 +++++---------- .../core/check/JsonSchemaValidator.java | 24 +++++++---- .../core/party/ConformanceParty.java | 41 +++++++++---------- .../core/scenario/ScenarioListBuilder.java | 1 - .../core/state/StateManagementUtil.java | 13 +++--- .../party/CarrierScenarioParameters.java | 5 ++- .../party/DynamicScenarioParameters.java | 5 ++- .../eblissuance/party/EblIssuanceCarrier.java | 10 ++--- .../party/EblIssuancePlatform.java | 10 ++--- .../party/SuppliedScenarioParameters.java | 5 ++- .../party/EblSurrenderCarrier.java | 26 ++++++------ .../party/EblSurrenderPlatform.java | 20 ++++----- .../party/SuppliedScenarioParameters.java | 5 ++- ebl/pom.xml | 2 +- .../standards/ebl/checks/EBLChecks.java | 2 +- .../ebl/checks/ToStringComparator.java | 2 +- .../standards/ebl/party/EblCarrier.java | 23 +++++------ .../standards/ebl/party/EblShipper.java | 2 +- .../standards/jit/party/JitPublisher.java | 7 ++-- .../jit/party/SuppliedScenarioParameters.java | 5 ++- .../dcsa/conformance/lambda/ApiLambda.java | 8 ++-- .../conformance/lambda/SandboxTaskLambda.java | 5 ++- .../dcsa/conformance/lambda/WebuiLambda.java | 8 ++-- .../standards/ovs/party/OvsPublisher.java | 9 ++-- .../ovs/party/SuppliedScenarioParameters.java | 5 ++- .../party/PintReceivingPlatform.java | 18 ++++---- .../eblinterop/party/PintSendingPlatform.java | 2 +- pom.xml | 2 +- spring-boot/pom.xml | 2 +- .../conformance/manual/ManualTestBase.java | 5 ++- .../tnt/party/SuppliedScenarioParameters.java | 15 +++---- .../standards/tnt/party/TntPublisher.java | 11 ++--- 42 files changed, 200 insertions(+), 219 deletions(-) diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/model/PersistableCarrierBooking.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/model/PersistableCarrierBooking.java index 27d890dd..c1b8f27f 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/model/PersistableCarrierBooking.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/model/PersistableCarrierBooking.java @@ -1,13 +1,12 @@ package org.dcsa.conformance.standards.booking.model; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; import static org.dcsa.conformance.standards.booking.party.BookingCancellationState.*; import static org.dcsa.conformance.standards.booking.party.BookingState.*; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; - import java.time.LocalDate; import java.time.OffsetDateTime; import java.time.ZoneOffset; @@ -15,7 +14,6 @@ import java.util.*; import java.util.function.*; import java.util.stream.StreamSupport; - import org.dcsa.conformance.core.state.JsonNodeMap; import org.dcsa.conformance.standards.booking.party.BookingCancellationState; import org.dcsa.conformance.standards.booking.party.BookingState; @@ -79,7 +77,6 @@ public class PersistableCarrierBooking { private static final String BOOKING_DATA_FIELD = "booking"; private static final String AMENDED_BOOKING_DATA_FIELD = "amendedBooking"; - private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper(); private final ObjectNode state; private PersistableCarrierBooking(ObjectNode state) { @@ -191,9 +188,7 @@ public void rejectBooking(String reference, String rejectReason) { rejectReason = "default message of rejection(reason not provided by carrier)"; } final var reason = rejectReason; - mutateBookingAndAmendment((bookingContent, isAmendedContent) -> { - bookingContent.put("reason", reason); - }); + mutateBookingAndAmendment((bookingContent, isAmendedContent) -> bookingContent.put("reason", reason)); } public void confirmBookingCompleted(String reference, boolean resetAmendedBooking) { diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingCarrier.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingCarrier.java index 4c719876..78fee301 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingCarrier.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingCarrier.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.booking.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.time.Instant; import java.util.*; @@ -23,8 +24,6 @@ import org.dcsa.conformance.standards.booking.checks.ScenarioType; import org.dcsa.conformance.standards.booking.model.PersistableCarrierBooking; -import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; - @Slf4j public class BookingCarrier extends ConformanceParty { private static final Random RANDOM = new Random(); @@ -57,8 +56,8 @@ public BookingCarrier( @Override protected void exportPartyJsonState(ObjectNode targetObjectNode) { - targetObjectNode.set("cbrrToCbr", StateManagementUtil.storeMap(OBJECT_MAPPER, cbrrToCbr)); - targetObjectNode.set("cbrToCbrr", StateManagementUtil.storeMap(OBJECT_MAPPER, cbrToCbrr)); + targetObjectNode.set("cbrrToCbr", StateManagementUtil.storeMap(cbrrToCbr)); + targetObjectNode.set("cbrToCbrr", StateManagementUtil.storeMap(cbrToCbrr)); } @Override @@ -91,18 +90,6 @@ protected Map, Consumer> getActionP Map.entry(UC14CarrierProcessBookingCancellationAction.class, this::processConfirmedBookingCancellation)); } - private char computeVesselIMONumberCheckDigit(String vesselIMONumberSansCheckDigit) { - int sum = 0; - assert vesselIMONumberSansCheckDigit.length() == 6; - for (int i = 0; i < 6; i++) { - char c = vesselIMONumberSansCheckDigit.charAt(i); - assert c >= '0' && c <= '9'; - sum += (7 - i) * Character.getNumericValue(c); - } - String s = String.valueOf(sum); - return s.charAt(s.length() - 1); - } - private void supplyScenarioParameters(JsonNode actionPrompt) { log.info("Carrier.supplyScenarioParameters(%s)".formatted(actionPrompt.toPrettyString())); var scenarioType = ScenarioType.valueOf(actionPrompt.required("scenarioType").asText()); @@ -391,7 +378,7 @@ private ConformanceResponse return405(ConformanceRequest request, String... allo return request.createResponse( 405, Map.of( - "Api-Version", List.of(apiVersion), "Allow", List.of(String.join(",", allowedMethods))), + API_VERSION, List.of(apiVersion), "Allow", List.of(String.join(",", allowedMethods))), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -401,7 +388,7 @@ private ConformanceResponse return405(ConformanceRequest request, String... allo private ConformanceResponse return400(ConformanceRequest request, String message) { return request.createResponse( 400, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode().put("message", message))); } @@ -412,14 +399,14 @@ private ConformanceResponse return404(ConformanceRequest request) { private ConformanceResponse return404(ConformanceRequest request, String message) { return request.createResponse( 404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode().put("message", message))); } private ConformanceResponse return409(ConformanceRequest request, String message) { return request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode().put("message", message))); } @@ -595,7 +582,7 @@ private ConformanceResponse returnBookingStatusResponse( ConformanceResponse response = request.createResponse( responseCode, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(statusObject)); addOperatorLogEntry( "Responded %d to %s booking '%s' (resulting state '%s')" @@ -634,7 +621,7 @@ private ConformanceResponse _handleGetBookingRequest(ConformanceRequest request) } ConformanceResponse response = request.createResponse( - 200, Map.of("Api-Version", List.of(apiVersion)), new ConformanceMessageBody(body)); + 200, Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(body)); addOperatorLogEntry( "Responded to GET booking request '%s' (in state '%s')" .formatted( diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingShipper.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingShipper.java index 4ca675a8..1d4f9912 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingShipper.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/BookingShipper.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.booking.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.*; import java.util.function.Consumer; @@ -20,8 +21,6 @@ import org.dcsa.conformance.standards.booking.checks.ScenarioType; import org.dcsa.conformance.standards.booking.model.InvalidBookingMessageType; -import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; - @Slf4j public class BookingShipper extends ConformanceParty { @@ -230,7 +229,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { ConformanceResponse response = request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); addOperatorLogEntry( diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/CarrierScenarioParameters.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/CarrierScenarioParameters.java index d44ebc86..10d49e90 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/CarrierScenarioParameters.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/CarrierScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.booking.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; public record CarrierScenarioParameters( @@ -17,7 +18,7 @@ public record CarrierScenarioParameters( String podUNLocationCode ) { public ObjectNode toJson() { - return new ObjectMapper() + return OBJECT_MAPPER .createObjectNode() .put("serviceContractReference", serviceContractReference()) .put("contractQuotationReference", contractQuotationReference()) diff --git a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/DynamicScenarioParameters.java b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/DynamicScenarioParameters.java index d38b9c51..031d28ea 100644 --- a/booking/src/main/java/org/dcsa/conformance/standards/booking/party/DynamicScenarioParameters.java +++ b/booking/src/main/java/org/dcsa/conformance/standards/booking/party/DynamicScenarioParameters.java @@ -1,14 +1,14 @@ package org.dcsa.conformance.standards.booking.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; +import java.util.function.Function; import lombok.NonNull; import lombok.With; import org.dcsa.conformance.standards.booking.checks.ScenarioType; -import java.util.function.Function; - @With public record DynamicScenarioParameters( @NonNull @@ -22,7 +22,7 @@ public record DynamicScenarioParameters( JsonNode updatedBooking ) { public ObjectNode toJson() { - ObjectNode dspNode = new ObjectMapper().createObjectNode(); + ObjectNode dspNode = OBJECT_MAPPER.createObjectNode(); dspNode.put("scenarioType", scenarioType.name()); if (carrierBookingRequestReference != null) { dspNode.put("carrierBookingRequestReference", carrierBookingRequestReference); diff --git a/cdk/pom.xml b/cdk/pom.xml index a416c502..4ad0d041 100644 --- a/cdk/pom.xml +++ b/cdk/pom.xml @@ -33,11 +33,5 @@ 2.159.1 compile - - software.constructs - constructs - 10.3.0 - compile - diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/action/CsAction.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/action/CsAction.java index d4a5d1de..adec8a62 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/action/CsAction.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/action/CsAction.java @@ -24,7 +24,7 @@ public abstract class CsAction extends ConformanceAction { protected final int expectedStatus; private final OverwritingReference dsp; - public CsAction( + protected CsAction( String sourcePartyName, String targetPartyName, CsAction previousAction, @@ -100,7 +100,7 @@ private String getHashString(String actualResponse) { byte[] hashBytes = digest.digest(actualResponse.getBytes()); responseHash = HexFormat.of().formatHex(hashBytes); } catch (NoSuchAlgorithmException e) { - log.error("Hashing of the response failed." + e); + log.error("Hashing of the response failed.", e); } return responseHash; } diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/CsPublisher.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/CsPublisher.java index 2f58e312..161734d1 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/CsPublisher.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/CsPublisher.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.cs.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.*; import java.util.function.Consumer; @@ -55,7 +56,7 @@ protected void importPartyJsonState(ObjectNode sourceObjectNode) { public ConformanceResponse handleRequest(ConformanceRequest request) { log.info("CsPublisher.handleRequest(%s)".formatted(request)); String filePath; - Map> initialIMap = Map.of("Api-Version", List.of(apiVersion)); + Map> initialIMap = Map.of(API_VERSION, List.of(apiVersion)); Map> headers = new HashMap<>(initialIMap); if (request.queryParams().containsKey("limit") && !request.queryParams().containsKey("cursor")) { @@ -139,7 +140,7 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { }))); asyncOrchestratorPostPartyInput( - new ObjectMapper() + OBJECT_MAPPER .createObjectNode() .put("actionId", actionPrompt.required("actionId").asText()) .set("input", responseSsp.toJson())); diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/DynamicScenarioParameters.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/DynamicScenarioParameters.java index 186ae644..07ec8483 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/DynamicScenarioParameters.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/DynamicScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.cs.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.With; @@ -17,7 +18,7 @@ public static DynamicScenarioParameters fromJson(JsonNode jsonNode) { } public ObjectNode toJson() { - ObjectNode dspNode = new ObjectMapper().createObjectNode(); + ObjectNode dspNode = OBJECT_MAPPER.createObjectNode(); if (cursor != null) { dspNode.put("cursor", cursor); } diff --git a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/SuppliedScenarioParameters.java b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/SuppliedScenarioParameters.java index 87254cba..d3275462 100644 --- a/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/SuppliedScenarioParameters.java +++ b/commercial-schedules/src/main/java/org/dcsa/conformance/standards/cs/party/SuppliedScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.cs.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.Arrays; import java.util.Collections; @@ -35,7 +36,7 @@ public static SuppliedScenarioParameters fromJson(JsonNode jsonNode) { } public ObjectNode toJson() { - ObjectNode objectNode = new ObjectMapper().createObjectNode(); + ObjectNode objectNode = OBJECT_MAPPER.createObjectNode(); map.forEach( (csFilterParameter, value) -> objectNode.put(csFilterParameter.getQueryParamName(), value)); return objectNode; diff --git a/core/src/main/java/org/dcsa/conformance/core/check/ApiHeaderCheck.java b/core/src/main/java/org/dcsa/conformance/core/check/ApiHeaderCheck.java index 852bb7f6..a406dbc8 100644 --- a/core/src/main/java/org/dcsa/conformance/core/check/ApiHeaderCheck.java +++ b/core/src/main/java/org/dcsa/conformance/core/check/ApiHeaderCheck.java @@ -3,6 +3,7 @@ import java.util.*; import java.util.function.Function; import java.util.function.Predicate; +import org.dcsa.conformance.core.party.ConformanceParty; import org.dcsa.conformance.core.traffic.ConformanceExchange; import org.dcsa.conformance.core.traffic.HttpMessageType; @@ -47,21 +48,6 @@ public ApiHeaderCheck( this("", isRelevantForRoleName, matchedExchangeUuid, httpMessageType, expectedVersion, false); } - public ApiHeaderCheck( - String titlePrefix, - Predicate isRelevantForRoleName, - UUID matchedExchangeUuid, - HttpMessageType httpMessageType, - String expectedVersion) { - this( - titlePrefix, - isRelevantForRoleName, - matchedExchangeUuid, - httpMessageType, - expectedVersion, - false); - } - private ApiHeaderCheck( String titlePrefix, Predicate isRelevantForRoleName, @@ -71,8 +57,8 @@ private ApiHeaderCheck( boolean isNotification) { super( titlePrefix, - "The HTTP %s has a correct Api-Version header" - .formatted(httpMessageType.name().toLowerCase()), + "The HTTP %s has a correct %s header" + .formatted(httpMessageType.name().toLowerCase(), ConformanceParty.API_VERSION), isRelevantForRoleName, matchedExchangeUuid, httpMessageType); @@ -88,16 +74,16 @@ protected Set checkConformance(Function getEx exchange.getMessage(httpMessageType).headers(); String headerName = headers.keySet().stream() - .filter(key -> key.equalsIgnoreCase("api-version")) + .filter(key -> key.equalsIgnoreCase(ConformanceParty.API_VERSION)) .findFirst() - .orElse("api-version"); + .orElse(ConformanceParty.API_VERSION); Collection headerValues = headers.get(headerName); if (headerValues == null || headerValues.isEmpty()) { return httpMessageType.equals(HttpMessageType.RESPONSE) && !isNotification - ? Set.of("Missing Api-Version header") + ? Set.of("Missing %s header".formatted(ConformanceParty.API_VERSION)) : Collections.emptySet(); } - if (headerValues.size() > 1) return Set.of("Duplicate Api-Version headers"); + if (headerValues.size() > 1) return Set.of("Duplicate %s headers".formatted(ConformanceParty.API_VERSION)); String exchangeApiVersion = headerValues.stream().findFirst().orElseThrow(); if (exchangeApiVersion.contains("-")) { exchangeApiVersion = exchangeApiVersion.substring(0, exchangeApiVersion.indexOf("-")); @@ -132,6 +118,8 @@ private Set _checkResponseApiVersionHeader( private Set _checkApiVersionHeaderValue(String expectedValue, String actualValue) { return Objects.equals(expectedValue, actualValue) ? Set.of() - : Set.of("Expected Api-Version '%s' but found '%s'".formatted(expectedValue, actualValue)); + : Set.of( + "Expected %s '%s' but found '%s'" + .formatted(ConformanceParty.API_VERSION, expectedValue, actualValue)); } } 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 5790a2bb..a05e8f15 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 @@ -7,7 +7,6 @@ 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 java.util.HashMap; @@ -34,16 +33,26 @@ public static synchronized JsonSchemaValidator getInstance(String filePath, Stri @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 - InputStream schemaFileInputStream = JsonSchemaValidator.class.getResourceAsStream(filePath); + JsonSchemaFactory jsonSchemaFactory = JsonSchemaFactory.builder(JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V7)) .objectMapper(JSON_FACTORY_OBJECT_MAPPER) .build(); SchemaValidatorsConfig schemaValidatorsConfig = new SchemaValidatorsConfig(); schemaValidatorsConfig.setTypeLoose(false); - JsonSchema rootJsonSchema = - jsonSchemaFactory.getSchema(schemaFileInputStream, schemaValidatorsConfig); + + JsonSchema rootJsonSchema; + try (InputStream schemaFileInputStream = + JsonSchemaValidator.class.getResourceAsStream(filePath)) { + + if (schemaFileInputStream == null || schemaFileInputStream.available() == 0) { + throw new IllegalArgumentException("Schema file not found: " + filePath); + } + rootJsonSchema = jsonSchemaFactory.getSchema(schemaFileInputStream, schemaValidatorsConfig); + } + ValidationContext validationContext = new ValidationContext( jsonSchemaFactory.getUriFactory(), @@ -53,15 +62,12 @@ private JsonSchemaValidator(String filePath, String schemaName) { schemaValidatorsConfig); // Prevent warnings on unknown keywords Map keywords = validationContext.getMetaSchema().getKeywords(); - Arrays.asList( - "example", - "discriminator", - "exclusiveMinimum") + Arrays.asList("example", "discriminator", "exclusiveMinimum") .forEach(keyword -> keywords.put(keyword, new NonValidationKeyword(keyword))); jsonSchema = jsonSchemaFactory.create( validationContext, - "#/components/schemas/" + schemaName, + "#/components/schemas/" + schemaName, rootJsonSchema.getSchemaNode().get("components").get("schemas").get(schemaName), rootJsonSchema); jsonSchema.initializeValidators(); diff --git a/core/src/main/java/org/dcsa/conformance/core/party/ConformanceParty.java b/core/src/main/java/org/dcsa/conformance/core/party/ConformanceParty.java index da9431df..45e2a252 100644 --- a/core/src/main/java/org/dcsa/conformance/core/party/ConformanceParty.java +++ b/core/src/main/java/org/dcsa/conformance/core/party/ConformanceParty.java @@ -1,5 +1,7 @@ package org.dcsa.conformance.core.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; @@ -14,7 +16,6 @@ import java.util.stream.Collectors; import java.util.stream.Stream; import java.util.stream.StreamSupport; - import lombok.Setter; import lombok.SneakyThrows; import lombok.extern.slf4j.Slf4j; @@ -27,10 +28,10 @@ import org.dcsa.conformance.core.traffic.ConformanceRequest; import org.dcsa.conformance.core.traffic.ConformanceResponse; -import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; - @Slf4j public abstract class ConformanceParty implements StatefulEntity { + public static final String API_VERSION = "Api-Version"; + protected final String apiVersion; protected final PartyConfiguration partyConfiguration; protected final CounterpartConfiguration counterpartConfiguration; @@ -131,8 +132,9 @@ public String getCounterpartRole() { protected void asyncOrchestratorPostPartyInput(JsonNode jsonPartyInput) { if (partyConfiguration.isInManualMode()) { log.info( - "Party %s NOT posting its input automatically (it is in manual mode): %s" - .formatted(partyConfiguration.getName(), jsonPartyInput.toPrettyString())); + "Party {} NOT posting its input automatically (it is in manual mode): {}", + partyConfiguration.getName(), + jsonPartyInput.toPrettyString()); return; } webClient.asyncRequest( @@ -193,13 +195,14 @@ protected void asyncCounterpartNotification(String actionId, String path, JsonNo } else { if (actionId != null) { log.info( - "Party %s notifying orchestrator that action %s is completed instead of sending notification: no counterpart URL is configured" - .formatted(actionId, partyConfiguration.getName())); + "Party {} notifying orchestrator that action {} is completed instead of sending notification: no counterpart URL is configured", + actionId, + partyConfiguration.getName()); asyncOrchestratorPostPartyInput(OBJECT_MAPPER.createObjectNode().put("actionId", actionId)); } else { log.info( - "Party %s NOT sending a notification and NOT notifying orchestrator either: no counterpart URL is configured" - .formatted(partyConfiguration.getName())); + "Party {} NOT sending a notification and NOT notifying orchestrator either: no counterpart URL is configured", + partyConfiguration.getName()); } } } @@ -224,7 +227,7 @@ private ConformanceRequest _createConformanceRequest( Stream.concat( Stream.concat( Stream.of( - Map.entry("Api-Version", List.of(apiVersionHeaderValue)), + Map.entry(API_VERSION, List.of(apiVersionHeaderValue)), Map.entry("Content-Type", List.of(JsonToolkit.JSON_UTF_8))), counterpartConfiguration.getAuthHeaderName().isBlank() ? Stream.of() @@ -251,8 +254,7 @@ private ConformanceRequest _createConformanceRequest( public void handleNotification() { log.info( - "%s[%s].handleNotification()" - .formatted(getClass().getSimpleName(), partyConfiguration.getName())); + "{}[{}].handleNotification()", getClass().getSimpleName(), partyConfiguration.getName()); JsonNode partyPrompt = _syncGetPartyPrompt(); if (!partyPrompt.isEmpty()) { StreamSupport.stream(partyPrompt.spliterator(), false).forEach(actionPromptsQueue::addLast); @@ -261,7 +263,7 @@ public void handleNotification() { } public void reset() { - log.info("%s[%s].reset()".formatted(getClass().getSimpleName(), partyConfiguration.getName())); + log.info("{}[{}].reset()", getClass().getSimpleName(), partyConfiguration.getName()); this.actionPromptsQueue.clear(); this.operatorLog.clear(); doReset(); @@ -271,9 +273,7 @@ public void reset() { @SneakyThrows private JsonNode _syncGetPartyPrompt() { - log.info( - "%s[%s].getPartyPrompt()" - .formatted(getClass().getSimpleName(), partyConfiguration.getName())); + log.info("{}[{}].getPartyPrompt()", getClass().getSimpleName(), partyConfiguration.getName()); URI uri = URI.create( partyConfiguration.getOrchestratorUrl() @@ -295,11 +295,10 @@ private void _handleNextActionPrompt() { JsonNode actionPrompt = actionPromptsQueue.removeFirst(); if (actionPrompt == null) return; log.info( - "%s[%s]._handleNextActionPrompt() handling %s" - .formatted( - getClass().getSimpleName(), - partyConfiguration.getName(), - actionPrompt.toPrettyString())); + "{}[{}]._handleNextActionPrompt() handling {}", + getClass().getSimpleName(), + partyConfiguration.getName(), + actionPrompt.toPrettyString()); getActionPromptHandlers().entrySet().stream() .filter( entry -> diff --git a/core/src/main/java/org/dcsa/conformance/core/scenario/ScenarioListBuilder.java b/core/src/main/java/org/dcsa/conformance/core/scenario/ScenarioListBuilder.java index 00b38b5c..3ffd9227 100644 --- a/core/src/main/java/org/dcsa/conformance/core/scenario/ScenarioListBuilder.java +++ b/core/src/main/java/org/dcsa/conformance/core/scenario/ScenarioListBuilder.java @@ -3,7 +3,6 @@ import java.util.Arrays; import java.util.LinkedList; import java.util.List; -import java.util.UUID; import java.util.concurrent.atomic.AtomicInteger; import java.util.function.Function; import java.util.stream.Stream; diff --git a/core/src/main/java/org/dcsa/conformance/core/state/StateManagementUtil.java b/core/src/main/java/org/dcsa/conformance/core/state/StateManagementUtil.java index d6cea3e7..6a8e0c7b 100755 --- a/core/src/main/java/org/dcsa/conformance/core/state/StateManagementUtil.java +++ b/core/src/main/java/org/dcsa/conformance/core/state/StateManagementUtil.java @@ -1,7 +1,6 @@ package org.dcsa.conformance.core.state; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; @@ -9,19 +8,21 @@ import java.util.function.Function; import java.util.stream.StreamSupport; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + public class StateManagementUtil { private StateManagementUtil() {} - public static JsonNode storeMap(ObjectMapper objectMapper, Map hashMap) { - return storeMap(objectMapper, hashMap, Function.identity()); + public static JsonNode storeMap(Map hashMap) { + return storeMap(hashMap, Function.identity()); } - public static JsonNode storeMap(ObjectMapper objectMapper, Map hashMap, Function toString) { - ArrayNode arrayNode = objectMapper.createArrayNode(); + public static JsonNode storeMap(Map hashMap, Function toString) { + ArrayNode arrayNode = OBJECT_MAPPER.createArrayNode(); hashMap.forEach( (key, value) -> { - ObjectNode entryNode = objectMapper.createObjectNode(); + ObjectNode entryNode = OBJECT_MAPPER.createObjectNode(); entryNode.put("key", key); entryNode.put("value", toString.apply(value)); arrayNode.add(entryNode); diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/CarrierScenarioParameters.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/CarrierScenarioParameters.java index 2ee46174..fe5aa5e1 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/CarrierScenarioParameters.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/CarrierScenarioParameters.java @@ -1,14 +1,15 @@ package org.dcsa.conformance.standards.eblissuance.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; public record CarrierScenarioParameters( String carrierSigningKeyPEM ) { public ObjectNode toJson() { - return new ObjectMapper() + return OBJECT_MAPPER .createObjectNode() .put("carrierSigningKeyPEM", carrierSigningKeyPEM); } diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/DynamicScenarioParameters.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/DynamicScenarioParameters.java index affcee5a..8a341ae2 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/DynamicScenarioParameters.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/DynamicScenarioParameters.java @@ -1,16 +1,17 @@ package org.dcsa.conformance.standards.eblissuance.party; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.With; import org.dcsa.conformance.standards.eblissuance.action.EblType; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + @With public record DynamicScenarioParameters( EblType eblType) { public ObjectNode toJson() { - return new ObjectMapper() + return OBJECT_MAPPER .createObjectNode() .put("eblType", eblType.name()); } diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuanceCarrier.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuanceCarrier.java index e43a67aa..79d19c51 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuanceCarrier.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuanceCarrier.java @@ -54,9 +54,9 @@ public EblIssuanceCarrier( protected void exportPartyJsonState(ObjectNode targetObjectNode) { targetObjectNode.set( "eblStatesByTdr", - StateManagementUtil.storeMap(OBJECT_MAPPER, eblStatesByTdr, EblIssuanceState::name)); - targetObjectNode.set("sirsByTdr", StateManagementUtil.storeMap(OBJECT_MAPPER, sirsByTdr)); - targetObjectNode.set("brsByTdr", StateManagementUtil.storeMap(OBJECT_MAPPER, brsByTdr)); + StateManagementUtil.storeMap(eblStatesByTdr, EblIssuanceState::name)); + targetObjectNode.set("sirsByTdr", StateManagementUtil.storeMap(sirsByTdr)); + targetObjectNode.set("brsByTdr", StateManagementUtil.storeMap(brsByTdr)); } @Override @@ -208,12 +208,12 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { return request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); } else { return request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java index 9964aa0a..b7c3ec95 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/EblIssuancePlatform.java @@ -58,8 +58,8 @@ protected void exportPartyJsonState(ObjectNode targetObjectNode) { }); targetObjectNode.set("eblStatesByTdr", arrayNodeEblStatesById); - targetObjectNode.set("tdr2PendingChecksum", StateManagementUtil.storeMap(OBJECT_MAPPER, tdr2PendingChecksum)); - targetObjectNode.set("knownChecksums", StateManagementUtil.storeMap(OBJECT_MAPPER, knownChecksums, String::valueOf)); + targetObjectNode.set("tdr2PendingChecksum", StateManagementUtil.storeMap(tdr2PendingChecksum)); + targetObjectNode.set("knownChecksums", StateManagementUtil.storeMap(knownChecksums, String::valueOf)); } @Override @@ -166,7 +166,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { .formatted(tdr)); return request.createResponse( 400, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -182,7 +182,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { response = request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); } else { String message; @@ -196,7 +196,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { response = request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() diff --git a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/SuppliedScenarioParameters.java b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/SuppliedScenarioParameters.java index c7eb56a1..d84a6f04 100644 --- a/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/SuppliedScenarioParameters.java +++ b/ebl-issuance/src/main/java/org/dcsa/conformance/standards/eblissuance/party/SuppliedScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.eblissuance.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; public record SuppliedScenarioParameters( @@ -14,7 +15,7 @@ public record SuppliedScenarioParameters( String consigneeOrEndorseeCodeListName ) { public ObjectNode toJson() { - return new ObjectMapper() + return OBJECT_MAPPER .createObjectNode() .put("sendToPlatform", sendToPlatform) .put("issueToLegalName", issueToLegalName) 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 4ec9cb9a..afe7a116 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 @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.eblsurrender.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.*; @@ -24,7 +25,6 @@ @Slf4j public class EblSurrenderCarrier extends ConformanceParty { private final Map eblStatesById = new HashMap<>(); - private final ObjectMapper objectMapper = new ObjectMapper(); public EblSurrenderCarrier( String apiVersion, @@ -44,11 +44,10 @@ public EblSurrenderCarrier( @Override protected void exportPartyJsonState(ObjectNode targetObjectNode) { - ObjectMapper objectMapper = new ObjectMapper(); - ArrayNode arrayNode = objectMapper.createArrayNode(); + ArrayNode arrayNode = OBJECT_MAPPER.createArrayNode(); eblStatesById.forEach( (key, value) -> { - ObjectNode entryNode = objectMapper.createObjectNode(); + ObjectNode entryNode = OBJECT_MAPPER.createObjectNode(); entryNode.put("key", key); entryNode.put("value", value.name()); arrayNode.add(entryNode); @@ -88,10 +87,11 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { eblStatesById.put(tdr, EblSurrenderState.AVAILABLE_FOR_SURRENDER); SuppliedScenarioParameters suppliedScenarioParameters = - new SuppliedScenarioParameters(tdr, "XMPL", "Example carrier party code", "Example party code", "Example code list"); + new SuppliedScenarioParameters( + tdr, "XMPL", "Example carrier party code", "Example party code", "Example code list"); asyncOrchestratorPostPartyInput( - objectMapper + OBJECT_MAPPER .createObjectNode() .put("actionId", actionPrompt.required("actionId").asText()) .set("input", suppliedScenarioParameters.toJson())); @@ -111,7 +111,7 @@ private void voidAndReissue(JsonNode actionPrompt) { } eblStatesById.put(tdr, EblSurrenderState.AVAILABLE_FOR_SURRENDER); asyncOrchestratorPostPartyInput( - objectMapper.createObjectNode().put("actionId", actionPrompt.get("actionId").asText())); + OBJECT_MAPPER.createObjectNode().put("actionId", actionPrompt.get("actionId").asText())); addOperatorLogEntry( "Voided and reissued the eBL with transportDocumentReference '%s'".formatted(tdr)); } @@ -141,7 +141,7 @@ private void sendSurrenderResponse(JsonNode actionPrompt) { } syncCounterpartPost( "/v%s/ebl-surrender-responses".formatted(apiVersion.charAt(0)), - objectMapper + OBJECT_MAPPER .createObjectNode() .put("surrenderRequestReference", srr) .put("action", accept ? "SURR" : "SREJ")); @@ -179,18 +179,18 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { return request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( - objectMapper + OBJECT_MAPPER .createObjectNode() .put("surrenderRequestReference", srr) .put("transportDocumentReference", tdr))); } else { return request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( - objectMapper + OBJECT_MAPPER .createObjectNode() .put( "comments", diff --git a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderPlatform.java b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderPlatform.java index 4d7f10dd..79bef25c 100644 --- a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderPlatform.java +++ b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/EblSurrenderPlatform.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.eblsurrender.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.time.Instant; import java.util.*; @@ -24,7 +25,6 @@ public class EblSurrenderPlatform extends ConformanceParty { private final Map eblStatesById = new HashMap<>(); private final Map tdrsBySrr = new HashMap<>(); - private final ObjectMapper objectMapper = new ObjectMapper(); public EblSurrenderPlatform( String apiVersion, @@ -46,8 +46,8 @@ public EblSurrenderPlatform( protected void exportPartyJsonState(ObjectNode targetObjectNode) { targetObjectNode.set( "eblStatesById", - StateManagementUtil.storeMap(objectMapper, eblStatesById, EblSurrenderState::name)); - targetObjectNode.set("tdrsBySrr", StateManagementUtil.storeMap(objectMapper, tdrsBySrr)); + StateManagementUtil.storeMap(eblStatesById, EblSurrenderState::name)); + targetObjectNode.set("tdrsBySrr", StateManagementUtil.storeMap(tdrsBySrr)); } @Override @@ -125,8 +125,8 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { response = request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), - new ConformanceMessageBody(objectMapper.createObjectNode())); + Map.of(API_VERSION, List.of(apiVersion)), + new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); } else if (Objects.equals( EblSurrenderState.DELIVERY_SURRENDER_REQUESTED, eblStatesById.get(tdr))) { eblStatesById.put( @@ -137,15 +137,15 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { response = request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), - new ConformanceMessageBody(objectMapper.createObjectNode())); + Map.of(API_VERSION, List.of(apiVersion)), + new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); } else { response = request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( - objectMapper + OBJECT_MAPPER .createObjectNode() .put( "comments", diff --git a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/SuppliedScenarioParameters.java b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/SuppliedScenarioParameters.java index ea175798..e10ddfa5 100644 --- a/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/SuppliedScenarioParameters.java +++ b/ebl-surrender/src/main/java/org/dcsa/conformance/standards/eblsurrender/party/SuppliedScenarioParameters.java @@ -1,13 +1,14 @@ package org.dcsa.conformance.standards.eblsurrender.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; public record SuppliedScenarioParameters( String transportDocumentReference, String eblPlatform, String carrierPartyCode, String surrenderPartyCode, String codeListName) { public ObjectNode toJson() { - return new ObjectMapper() + return OBJECT_MAPPER .createObjectNode() .put("transportDocumentReference", transportDocumentReference) .put("eblPlatform", eblPlatform) diff --git a/ebl/pom.xml b/ebl/pom.xml index 0082bdf9..957e302f 100644 --- a/ebl/pom.xml +++ b/ebl/pom.xml @@ -26,7 +26,7 @@ com.nimbusds nimbus-jose-jwt - 9.24.4 + 9.41.1 io.setl diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/EBLChecks.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/EBLChecks.java index 87e4f86f..2e5bae42 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/EBLChecks.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/EBLChecks.java @@ -740,7 +740,7 @@ private static JsonContentMatchedValidation checkCSPValueBasedOnOtherValue( for (var node : nodes) { pathBuilder.setLength(contextPath.length()); pathBuilder.append('[').append(index).append(']'); - var refPath = pathBuilder.toString() + "." + referenceAttributeName; + var refPath = pathBuilder + "." + referenceAttributeName; var valueNode = resolveValue != null ? resolveValue.apply(node, pathBuilder) : node; index++; if (valueNode == null || !valueNode.isTextual()) { diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/ToStringComparator.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/ToStringComparator.java index 63cdd8f5..dba21c8c 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/ToStringComparator.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/checks/ToStringComparator.java @@ -54,6 +54,6 @@ private static void stringify(StringBuffer builder, JsonNode node) { builder.append("}"); } default -> builder.append(node); - }; + } } } diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java index 3970dece..2a7ee17f 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java @@ -1,10 +1,10 @@ package org.dcsa.conformance.standards.ebl.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; import static org.dcsa.conformance.standards.ebl.checks.EBLChecks.SI_ARRAY_ORDER_DEFINITIONS; import static org.dcsa.conformance.standards.ebl.party.EblShipper.siFromScenarioType; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.time.Instant; import java.util.*; @@ -30,7 +30,6 @@ @Slf4j public class EblCarrier extends ConformanceParty { - private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper(); private final Map tdrToSir = new HashMap<>(); public EblCarrier( @@ -51,7 +50,7 @@ public EblCarrier( @Override protected void exportPartyJsonState(ObjectNode targetObjectNode) { - targetObjectNode.set("tdrToSir", StateManagementUtil.storeMap(OBJECT_MAPPER, tdrToSir)); + targetObjectNode.set("tdrToSir", StateManagementUtil.storeMap(tdrToSir)); } @Override @@ -451,7 +450,7 @@ private ConformanceResponse return405(ConformanceRequest request, String... allo return request.createResponse( 405, Map.of( - "Api-Version", List.of(apiVersion), "Allow", List.of(String.join(",", allowedMethods))), + API_VERSION, List.of(apiVersion), "Allow", List.of(String.join(",", allowedMethods))), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -461,7 +460,7 @@ private ConformanceResponse return405(ConformanceRequest request, String... allo private ConformanceResponse return400(ConformanceRequest request, String message) { return request.createResponse( 400, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode().put("message", message))); } @@ -471,7 +470,7 @@ private ConformanceResponse return404(ConformanceRequest request) { private ConformanceResponse return404(ConformanceRequest request, String message) { return request.createResponse( 404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -481,7 +480,7 @@ private ConformanceResponse return404(ConformanceRequest request, String message private ConformanceResponse return409(ConformanceRequest request, String message) { return request.createResponse( 409, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode().put("message", message))); } @@ -528,7 +527,7 @@ private ConformanceResponse _handleGetShippingInstructionsRequest(ConformanceReq ConformanceResponse response = request.createResponse( 200, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(body)); addOperatorLogEntry( "Responded to GET shipping instructions request '%s' (in state '%s')" @@ -554,7 +553,7 @@ private ConformanceResponse _handleGetTransportDocument(ConformanceRequest reque ConformanceResponse response = request.createResponse( 200, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(body)); addOperatorLogEntry( "Responded to GET transport document request '%s' (in state '%s')" @@ -635,7 +634,7 @@ private ConformanceResponse returnShippingInstructionsReferenceResponse( ConformanceResponse response = request.createResponse( responseCode, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(statusObject)); addOperatorLogEntry( "Responded %d to %s SI '%s' (resulting state '%s')" @@ -649,7 +648,7 @@ private ConformanceResponse returnEmpty202Response(ConformanceRequest request, O ConformanceResponse response = request.createResponse( 202, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody("")); addOperatorLogEntry( "Responded %d to %s SI '%s' (resulting state '%s')" @@ -670,7 +669,7 @@ private ConformanceResponse returnTransportDocumentRefStatusResponse( ConformanceResponse response = request.createResponse( responseCode, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(statusObject)); addOperatorLogEntry( "Responded %d to %s TD '%s' (resulting state '%s')" diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java index 283090d2..64c918e3 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblShipper.java @@ -256,7 +256,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { ConformanceResponse response = request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(OBJECT_MAPPER.createObjectNode())); addOperatorLogEntry( diff --git a/jit/src/main/java/org/dcsa/conformance/standards/jit/party/JitPublisher.java b/jit/src/main/java/org/dcsa/conformance/standards/jit/party/JitPublisher.java index 624b795a..f96c1510 100644 --- a/jit/src/main/java/org/dcsa/conformance/standards/jit/party/JitPublisher.java +++ b/jit/src/main/java/org/dcsa/conformance/standards/jit/party/JitPublisher.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.jit.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; @@ -90,7 +91,7 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { }))); asyncOrchestratorPostPartyInput( - new ObjectMapper() + OBJECT_MAPPER .createObjectNode() .put("actionId", actionPrompt.required("actionId").asText()) .set("input", responseSsp.toJson())); @@ -112,7 +113,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { return request.createResponse( 200, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(jsonResponseBody)); } } diff --git a/jit/src/main/java/org/dcsa/conformance/standards/jit/party/SuppliedScenarioParameters.java b/jit/src/main/java/org/dcsa/conformance/standards/jit/party/SuppliedScenarioParameters.java index 71366280..24000267 100644 --- a/jit/src/main/java/org/dcsa/conformance/standards/jit/party/SuppliedScenarioParameters.java +++ b/jit/src/main/java/org/dcsa/conformance/standards/jit/party/SuppliedScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.jit.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.Arrays; import java.util.Collections; @@ -20,7 +21,7 @@ private SuppliedScenarioParameters(Map map) { } public ObjectNode toJson() { - ObjectNode objectNode = new ObjectMapper().createObjectNode(); + ObjectNode objectNode = OBJECT_MAPPER.createObjectNode(); map.forEach( (jitFilterParameter, value) -> objectNode.put(jitFilterParameter.getQueryParamName(), value)); diff --git a/lambda/src/main/java/org/dcsa/conformance/lambda/ApiLambda.java b/lambda/src/main/java/org/dcsa/conformance/lambda/ApiLambda.java index 27b4a502..27315c38 100644 --- a/lambda/src/main/java/org/dcsa/conformance/lambda/ApiLambda.java +++ b/lambda/src/main/java/org/dcsa/conformance/lambda/ApiLambda.java @@ -1,16 +1,16 @@ package org.dcsa.conformance.lambda; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent; import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent; +import com.fasterxml.jackson.databind.JsonNode; import java.util.Collections; import java.util.List; import java.util.Map; import java.util.Objects; - -import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import lombok.extern.slf4j.Slf4j; import org.dcsa.conformance.sandbox.ConformanceSandbox; import org.dcsa.conformance.sandbox.ConformanceWebRequest; @@ -25,7 +25,7 @@ public APIGatewayProxyResponseEvent handleRequest( final APIGatewayProxyRequestEvent event, final Context context) { try { System.out.println("event = " + event + ", context = " + context); - JsonNode jsonEvent = new ObjectMapper().valueToTree(event); + JsonNode jsonEvent = OBJECT_MAPPER.valueToTree(event); log.info("jsonEvent = " + jsonEvent.toPrettyString()); ConformancePersistenceProvider persistenceProvider = diff --git a/lambda/src/main/java/org/dcsa/conformance/lambda/SandboxTaskLambda.java b/lambda/src/main/java/org/dcsa/conformance/lambda/SandboxTaskLambda.java index 1e3dca41..69068a3f 100644 --- a/lambda/src/main/java/org/dcsa/conformance/lambda/SandboxTaskLambda.java +++ b/lambda/src/main/java/org/dcsa/conformance/lambda/SandboxTaskLambda.java @@ -1,9 +1,10 @@ package org.dcsa.conformance.lambda; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestStreamHandler; import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.io.*; import java.nio.charset.StandardCharsets; @@ -34,7 +35,7 @@ public void handleRequest(InputStream inputStream, OutputStream outputStream, Co LambdaToolkit.createDeferredSandboxTaskConsumer(persistenceProvider), jsonInput); - ObjectNode jsonOutput = new ObjectMapper().createObjectNode(); + ObjectNode jsonOutput = OBJECT_MAPPER.createObjectNode(); log.info("jsonOutput = " + jsonOutput.toPrettyString()); try (BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, StandardCharsets.UTF_8))) { diff --git a/lambda/src/main/java/org/dcsa/conformance/lambda/WebuiLambda.java b/lambda/src/main/java/org/dcsa/conformance/lambda/WebuiLambda.java index c0927489..464e3e65 100644 --- a/lambda/src/main/java/org/dcsa/conformance/lambda/WebuiLambda.java +++ b/lambda/src/main/java/org/dcsa/conformance/lambda/WebuiLambda.java @@ -1,13 +1,13 @@ package org.dcsa.conformance.lambda; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent; import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent; -import java.util.*; - import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; +import java.util.*; import lombok.extern.slf4j.Slf4j; import org.dcsa.conformance.core.toolkit.JsonToolkit; import org.dcsa.conformance.sandbox.ConformanceAccessException; @@ -24,7 +24,7 @@ public APIGatewayProxyResponseEvent handleRequest( System.out.println("event = " + event + ", context = " + context); log.info("event.getPath() = " + event.getPath()); - JsonNode jsonEvent = new ObjectMapper().valueToTree(event); + JsonNode jsonEvent = OBJECT_MAPPER.valueToTree(event); log.info("JSON event = " + jsonEvent.toString()); String cognitoIdAsEnvironmentId = diff --git a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/OvsPublisher.java b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/OvsPublisher.java index a7489eda..31db731d 100644 --- a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/OvsPublisher.java +++ b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/OvsPublisher.java @@ -1,16 +1,15 @@ package org.dcsa.conformance.standards.ovs.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; - import java.text.SimpleDateFormat; import java.util.*; import java.util.function.Consumer; import java.util.function.Function; import java.util.stream.Collectors; import java.util.stream.StreamSupport; - import lombok.extern.slf4j.Slf4j; import org.dcsa.conformance.core.party.ConformanceParty; import org.dcsa.conformance.core.party.CounterpartConfiguration; @@ -90,7 +89,7 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { }))); asyncOrchestratorPostPartyInput( - new ObjectMapper() + OBJECT_MAPPER .createObjectNode() .put("actionId", actionPrompt.required("actionId").asText()) .set("input", responseSsp.toJson())); @@ -112,7 +111,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { return request.createResponse( 200, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(jsonResponseBody)); } } diff --git a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/SuppliedScenarioParameters.java b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/SuppliedScenarioParameters.java index b85aa777..de4a8ba0 100644 --- a/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/SuppliedScenarioParameters.java +++ b/ovs/src/main/java/org/dcsa/conformance/standards/ovs/party/SuppliedScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.ovs.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.Arrays; import java.util.Collections; @@ -20,7 +21,7 @@ private SuppliedScenarioParameters(Map map) { } public ObjectNode toJson() { - ObjectNode objectNode = new ObjectMapper().createObjectNode(); + ObjectNode objectNode = OBJECT_MAPPER.createObjectNode(); map.forEach( (ovsFilterParameter, value) -> objectNode.put(ovsFilterParameter.getQueryParamName(), value)); diff --git a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintReceivingPlatform.java b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintReceivingPlatform.java index 40e90449..25a9edae 100644 --- a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintReceivingPlatform.java +++ b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintReceivingPlatform.java @@ -150,7 +150,7 @@ public ConformanceResponse handleInitiateTransferRequest(ConformanceRequest requ receiveState.save(persistentMap); return request.createResponse( responseCode.getHttpResponseCode(), - Map.of("API-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(signedPayloadJsonNode) ); } @@ -168,7 +168,7 @@ public ConformanceResponse handleInitiateTransferRequest(ConformanceRequest requ receiveState.save(persistentMap); return request.createResponse( 201, - Map.of("API-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(unsignedPayload) ); } @@ -177,7 +177,7 @@ public ConformanceResponse handleInitiateTransferRequest(ConformanceRequest requ protected void exportPartyJsonState(ObjectNode targetObjectNode) { targetObjectNode.set( "envelopeReferences", - StateManagementUtil.storeMap(OBJECT_MAPPER, envelopeReferences)); + StateManagementUtil.storeMap(envelopeReferences)); } @Override @@ -218,19 +218,19 @@ public ConformanceResponse handleEnvelopeRequest(ConformanceRequest request) { var payload = receiveState.generateSignedResponse(INCD, payloadSigner); return request.createResponse( INCD.getHttpResponseCode(), - Map.of("API-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(payload) ); } receiveState.save(persistentMap); return request.createResponse( 204, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody("") ); } return request.createResponse(404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -253,13 +253,13 @@ public ConformanceResponse handleEnvelopeRequest(ConformanceRequest request) { receiveState.save(persistentMap); return request.createResponse( responseCode.getHttpResponseCode(), - Map.of("API-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(signedPayloadJsonNode) ); } return request.createResponse(404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() @@ -281,7 +281,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { } else { response = request.createResponse( 404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() diff --git a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintSendingPlatform.java b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintSendingPlatform.java index f2da5d80..82f495af 100644 --- a/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintSendingPlatform.java +++ b/pint/src/main/java/org/dcsa/conformance/standards/eblinterop/party/PintSendingPlatform.java @@ -422,7 +422,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { log.info("EblInteropSendingPlatform.handleRequest(%s)".formatted(request)); return request.createResponse( 404, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody( OBJECT_MAPPER .createObjectNode() diff --git a/pom.xml b/pom.xml index e0824f66..d84f4b1c 100644 --- a/pom.xml +++ b/pom.xml @@ -15,7 +15,7 @@ UTF-8 2.20.0 - 5.11.0 + 5.11.1 1.18.34 !WebUI diff --git a/spring-boot/pom.xml b/spring-boot/pom.xml index 00f6f9ed..972bb564 100644 --- a/spring-boot/pom.xml +++ b/spring-boot/pom.xml @@ -54,7 +54,7 @@ org.seleniumhq.selenium selenium-java - 4.24.0 + 4.25.0 test diff --git a/spring-boot/src/test/java/org/dcsa/conformance/manual/ManualTestBase.java b/spring-boot/src/test/java/org/dcsa/conformance/manual/ManualTestBase.java index 341ffdac..66be681f 100644 --- a/spring-boot/src/test/java/org/dcsa/conformance/manual/ManualTestBase.java +++ b/spring-boot/src/test/java/org/dcsa/conformance/manual/ManualTestBase.java @@ -1,5 +1,6 @@ package org.dcsa.conformance.manual; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -25,7 +26,7 @@ public abstract class ManualTestBase { private static final String USER_ID = "unit-test"; - protected final ObjectMapper mapper = new ObjectMapper(); + protected final ObjectMapper mapper = OBJECT_MAPPER; protected long lambdaDelay = 0L; @Autowired protected ConformanceApplication app; @@ -326,7 +327,7 @@ record Sandbox( String sandboxName) {} // Possible result of getAllSandboxes - record SandboxItem(String id, String name, String operatorLog, boolean canNotifyParty) {} + protected record SandboxItem(String id, String name, String operatorLog, boolean canNotifyParty) {} public record SandboxConfig( String sandboxId, diff --git a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/SuppliedScenarioParameters.java b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/SuppliedScenarioParameters.java index 10528ec6..b399aa77 100644 --- a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/SuppliedScenarioParameters.java +++ b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/SuppliedScenarioParameters.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.tnt.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.Arrays; import java.util.Collections; @@ -20,10 +21,10 @@ private SuppliedScenarioParameters(Map map) { } public ObjectNode toJson() { - ObjectNode objectNode = new ObjectMapper().createObjectNode(); + ObjectNode objectNode = OBJECT_MAPPER.createObjectNode(); map.forEach( - (ovsFilterParameter, value) -> - objectNode.put(ovsFilterParameter.getQueryParamName(), value)); + (tntFilterParameter, value) -> + objectNode.put(tntFilterParameter.getQueryParamName(), value)); return objectNode; } @@ -34,11 +35,11 @@ public static SuppliedScenarioParameters fromMap(Map public static SuppliedScenarioParameters fromJson(JsonNode jsonNode) { return new SuppliedScenarioParameters( Arrays.stream(TntFilterParameter.values()) - .filter(ovsFilterParameter -> jsonNode.has(ovsFilterParameter.getQueryParamName())) + .filter(tntFilterParameter -> jsonNode.has(tntFilterParameter.getQueryParamName())) .collect( Collectors.toUnmodifiableMap( Function.identity(), - ovsFilterParameter -> - jsonNode.required(ovsFilterParameter.getQueryParamName()).asText()))); + tntFilterParameter -> + jsonNode.required(tntFilterParameter.getQueryParamName()).asText()))); } } diff --git a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/TntPublisher.java b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/TntPublisher.java index cb16fd01..19fb50bb 100644 --- a/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/TntPublisher.java +++ b/tnt/src/main/java/org/dcsa/conformance/standards/tnt/party/TntPublisher.java @@ -1,7 +1,8 @@ package org.dcsa.conformance.standards.tnt.party; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + import com.fasterxml.jackson.databind.JsonNode; -import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; @@ -66,8 +67,8 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { actionPrompt.required("tntFilterParametersQueryParamNames").spliterator(), false) .map( - jsonOvsFilterParameter -> - TntFilterParameter.byQueryParamName.get(jsonOvsFilterParameter.asText())) + jsonTntFilterParameter -> + TntFilterParameter.byQueryParamName.get(jsonTntFilterParameter.asText())) .collect( Collectors.toMap( Function.identity(), @@ -102,7 +103,7 @@ private void supplyScenarioParameters(JsonNode actionPrompt) { }))); asyncOrchestratorPostPartyInput( - new ObjectMapper() + OBJECT_MAPPER .createObjectNode() .put("actionId", actionPrompt.required("actionId").asText()) .set("input", responseSsp.toJson())); @@ -122,7 +123,7 @@ public ConformanceResponse handleRequest(ConformanceRequest request) { return request.createResponse( 200, - Map.of("Api-Version", List.of(apiVersion)), + Map.of(API_VERSION, List.of(apiVersion)), new ConformanceMessageBody(jsonResponseBody)); } } From 5d17311d64824b49d30bc7f9547c781608a93988 Mon Sep 17 00:00:00 2001 From: Niels Thykier Date: Fri, 27 Sep 2024 09:21:58 +0200 Subject: [PATCH 4/5] DT-1678: Require manual input from carrier from TD-only scenarios --- ...r_PublishDraftTransportDocumentAction.java | 23 ++++++++++++++++++- .../standards/ebl/party/EblCarrier.java | 8 +++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC6_Carrier_PublishDraftTransportDocumentAction.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC6_Carrier_PublishDraftTransportDocumentAction.java index 32e43c0c..ce752fdb 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC6_Carrier_PublishDraftTransportDocumentAction.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/action/UC6_Carrier_PublishDraftTransportDocumentAction.java @@ -1,12 +1,16 @@ package org.dcsa.conformance.standards.ebl.action; +import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.stream.Stream; import lombok.Getter; +import org.dcsa.conformance.core.UserFacingException; import org.dcsa.conformance.core.check.*; import org.dcsa.conformance.core.traffic.ConformanceExchange; import org.dcsa.conformance.standards.ebl.party.TransportDocumentStatus; +import static org.dcsa.conformance.core.toolkit.JsonToolkit.OBJECT_MAPPER; + @Getter public class UC6_Carrier_PublishDraftTransportDocumentAction extends StateChangingSIAction { private final JsonSchemaValidator notificationSchemaValidator; @@ -26,7 +30,7 @@ public UC6_Carrier_PublishDraftTransportDocumentAction( @Override public String getHumanReadablePrompt() { if (skipSI) { - return "UC6: Publish draft transport document matching the scenario parameters provided in the previous step"; + return "UC6: Publish draft transport document matching the scenario parameters provided in the previous step and provide its transport document reference here"; } return ("UC6: Publish draft transport document for shipping instructions with reference %s" .formatted(getDspSupplier().get().shippingInstructionsReference())); @@ -47,6 +51,23 @@ protected void doHandleExchange(ConformanceExchange exchange) { getDspConsumer().accept(dsp.withNewTransportDocumentContent(true)); } + @Override + public boolean isInputRequired() { + return this.skipSI; + } + + @Override + public void handlePartyInput(JsonNode partyInput) throws UserFacingException { + super.handlePartyInput(partyInput); + getDspConsumer().accept(getDspSupplier().get().withTransportDocumentReference(partyInput.path("transportDocumentReference").asText())); + } + + @Override + public JsonNode getJsonForHumanReadablePrompt() { + return OBJECT_MAPPER.createObjectNode() + .put("transportDocumentReference", "Insert TDR here"); + } + @Override public ObjectNode asJsonNode() { var dsp = getDspSupplier().get(); diff --git a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java index 2a7ee17f..874887ac 100644 --- a/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java +++ b/ebl/src/main/java/org/dcsa/conformance/standards/ebl/party/EblCarrier.java @@ -288,6 +288,14 @@ private void publishDraftTransportDocument(JsonNode actionPrompt) { si.publishDraftTransportDocument(documentReference, scenarioType); si.save(persistentMap); tdrToSir.put(si.getTransportDocumentReference(), si.getShippingInstructionsReference()); + if (skipSI) { + asyncOrchestratorPostPartyInput( + OBJECT_MAPPER + .createObjectNode() + .put("actionId", actionPrompt.required("actionId").asText()) + .putObject("input") + .put("transportDocumentReference", si.getTransportDocumentReference())); + } generateAndEmitNotificationFromTransportDocument(actionPrompt, si, true); addOperatorLogEntry("Published draft transport document '%s'".formatted(documentReference)); From 53f00cd3655f6645e57ef389f4f0ec4154083bd3 Mon Sep 17 00:00:00 2001 From: Niels Thykier Date: Fri, 27 Sep 2024 11:58:52 +0200 Subject: [PATCH 5/5] DT-1584: Update schema --- .../schemas/eblissuance-v3.0.0.json | 321 +-- .../schemas/eblsurrender-v3.0.0.json | 4 +- .../standards/ebl/EblScenarioListBuilder.java | 6 +- .../standards/ebl/schemas/ebl-api-3.0.0.json | 2028 +++++------------ .../standards/pint/schemas/pint-3.0.0.json | 395 ++-- 5 files changed, 947 insertions(+), 1807 deletions(-) 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 index 41f31271..2862b764 100644 --- 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 @@ -177,7 +177,7 @@ "title" : "Address", "type" : "object" }, - "Cargo Gross Volume" : { + "CargoGrossVolume" : { "description" : "Calculated by multiplying the width, height, and length of the packed cargo.\n", "properties" : { "unit" : { @@ -205,7 +205,7 @@ "title" : "Cargo Gross Volume", "type" : "object" }, - "Cargo Gross Weight" : { + "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" : { @@ -233,8 +233,56 @@ "title" : "Cargo Gross Weight", "type" : "object" }, - "Cargo Net Volume" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "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", @@ -246,7 +294,7 @@ "type" : "string" }, "value" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", "example" : 2.4, "exclusiveMinimum" : true, "format" : "float", @@ -261,7 +309,7 @@ "title" : "Cargo Net Volume", "type" : "object" }, - "Cargo Net Weight" : { + "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" : { @@ -289,54 +337,6 @@ "title" : "Cargo Net 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/Cargo Gross Volume" - }, - "cargoGrossWeight" : { - "$ref" : "#/components/schemas/Cargo Gross Weight" - }, - "cargoNetVolume" : { - "$ref" : "#/components/schemas/Cargo Net Volume" - }, - "cargoNetWeight" : { - "$ref" : "#/components/schemas/Cargo Net Weight" - }, - "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" - }, "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" : { @@ -473,7 +473,7 @@ "$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", + "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", @@ -581,7 +581,7 @@ "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", + "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", @@ -607,7 +607,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "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", @@ -741,7 +741,7 @@ "type" : "string" }, "grossWeight" : { - "$ref" : "#/components/schemas/Gross Weight" + "$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", @@ -812,13 +812,13 @@ "$ref" : "#/components/schemas/Limits" }, "netExplosiveContent" : { - "$ref" : "#/components/schemas/Net Explosive Content" + "$ref" : "#/components/schemas/NetExplosiveContent" }, "netVolume" : { - "$ref" : "#/components/schemas/Net Volume" + "$ref" : "#/components/schemas/NetVolume" }, "netWeight" : { - "$ref" : "#/components/schemas/Net Weight" + "$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", @@ -923,7 +923,7 @@ "title" : "Detailed Error", "type" : "object" }, - "Document Parties" : { + "DocumentParties" : { "description" : "All `Parties` with associated roles.\n", "properties" : { "carriersAgentAtDestination" : { @@ -939,7 +939,7 @@ "$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:** Mandatory for To Order BLs, `isToOrder=true`\n", + "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" }, @@ -974,7 +974,7 @@ "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", + "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)?$", @@ -1007,7 +1007,7 @@ "$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", + "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", @@ -1069,7 +1069,7 @@ "type" : "string" }, "tareWeight" : { - "$ref" : "#/components/schemas/Tare Weight" + "$ref" : "#/components/schemas/TareWeight" } }, "required" : [ @@ -1200,7 +1200,7 @@ "title" : "Geo Coordinate", "type" : "object" }, - "Gross Weight" : { + "GrossWeight" : { "description" : "Total weight of the goods carried, including packaging.\n", "properties" : { "unit" : { @@ -1286,6 +1286,45 @@ "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" + }, "IssuanceError" : { "properties" : { "errorCode" : { @@ -1583,7 +1622,7 @@ "title" : "National Commodity Code", "type" : "object" }, - "Net Explosive Content" : { + "NetExplosiveContent" : { "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", "properties" : { "unit" : { @@ -1613,7 +1652,7 @@ "title" : "Net Explosive Content", "type" : "object" }, - "Net Volume" : { + "NetVolume" : { "description" : "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n", "properties" : { "unit" : { @@ -1642,7 +1681,7 @@ "title" : "Net Volume", "type" : "object" }, - "Net Weight" : { + "NetWeight" : { "description" : "Total weight of the goods carried, excluding packaging.\n", "properties" : { "unit" : { @@ -1677,7 +1716,7 @@ "$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", + "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", @@ -1966,7 +2005,7 @@ "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", + "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)?$", @@ -2017,7 +2056,42 @@ "title" : "Party Contact Detail", "type" : "object" }, - "Place of Issue" : { + "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" : [ { @@ -2067,41 +2141,6 @@ "title" : "Place of Issue", "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" - }, "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" : { @@ -2282,7 +2321,7 @@ "$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", + "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", @@ -2361,7 +2400,7 @@ }, "contentType" : { "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).\n\n**Conditional:** This property is mandatory to provide if it differs from `application/pdf`\n", + "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", "maxLength" : 100, "type" : "string" @@ -2379,7 +2418,7 @@ "title" : "Supporting Document", "type" : "object" }, - "Tare Weight" : { + "TareWeight" : { "description" : "The weight of an empty container (gross container weight).\n", "properties" : { "unit" : { @@ -2539,7 +2578,7 @@ "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", + "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", @@ -2550,7 +2589,7 @@ "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", + "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", @@ -2561,7 +2600,7 @@ "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", + "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", @@ -2572,7 +2611,7 @@ "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", + "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", @@ -2590,7 +2629,7 @@ "type" : "string" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties" + "$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", @@ -2602,43 +2641,7 @@ "type" : "string" }, "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" + "$ref" : "#/components/schemas/InvoicePayableAt" }, "isElectronic" : { "description" : "An indicator whether the transport document is electronically transferred.\n", @@ -2705,7 +2708,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$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", @@ -2732,7 +2735,7 @@ "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", + "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", @@ -2928,7 +2931,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", + "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", @@ -2988,12 +2991,12 @@ "name" : "Digital Container Shipping Association (DCSA)", "url" : "https://dcsa.org" }, - "description" : "This API is intended as an API between a carrier and a EBL Solution Platform.\n\nThe EBL Solution Provider is to implement\n\n /v3/ebl-issuance-requests\n\nfor the carrier to call and the carrier is to implement\n\n /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\nAPI specification issued by DCSA.org.\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", + "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", "license" : { "name" : "Apache 2.0", "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "title" : "DCSA OpenAPI specification for Issuance an EBL to an EBL platform.\n", + "title" : "DCSA eBL Issuance API", "version" : "3.0.0" }, "openapi" : "3.0.3", @@ -3117,7 +3120,7 @@ } } }, - "description" : "Request successful", + "description" : "Request failed for some reason.", "headers" : { "API-Version" : { "$ref" : "#/components/headers/API-Version" 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 index 8c447c6b..4216d088 100644 --- 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 @@ -375,12 +375,12 @@ "name" : "Digital Container Shipping Association (DCSA)", "url" : "https://dcsa.org" }, - "description" : "This 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 /v3/ebl-surrender-requests\n\nwhich will be processed asynchronously. Responses to the surrender requests will be submitted by the carrier via \n\n /v3/ebl-surrender-responses\n\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", + "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", "license" : { "name" : "Apache 2.0", "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "title" : "DCSA EBL Surrender API", + "title" : "DCSA eBL Surrender API", "version" : "3.0.0" }, "openapi" : "3.0.3", 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 b11c1cd3..94902e14 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 @@ -44,9 +44,9 @@ class EblScenarioListBuilder extends ScenarioListBuilder private static final String GET_TD_SCHEMA_NAME = "TransportDocument"; private static final String POST_EBL_SCHEMA_NAME = "CreateShippingInstructions"; private static final String PUT_EBL_SCHEMA_NAME = "UpdateShippingInstructions"; - private static final String PATCH_SI_SCHEMA_NAME = "shippinginstructions_documentReference_body"; - private static final String PATCH_TD_SCHEMA_NAME = "transportdocuments_transportDocumentReference_body"; - private static final String RESPONSE_POST_SHIPPING_INSTRUCTIONS_SCHEMA_NAME = "Shipping Instructions Response"; + private static final String PATCH_SI_SCHEMA_NAME = "CancelShippingInstructionsUpdate"; + private static final String PATCH_TD_SCHEMA_NAME = "ApproveTransportDocument"; + private static final String RESPONSE_POST_SHIPPING_INSTRUCTIONS_SCHEMA_NAME = "CreateShippingInstructionsResponse"; private static final String EBL_SI_NOTIFICATION_SCHEMA_NAME = "ShippingInstructionsNotification"; private static final String EBL_TD_NOTIFICATION_SCHEMA_NAME = "TransportDocumentNotification"; 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 index f66ad736..a8e4d50e 100644 --- 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 @@ -245,7 +245,7 @@ "type" : "string" }, "supplementaryDeclarantEORINumber" : { - "description" : "The Economic Operators Registration and Identification (EORI) number of the house filer responsible for the `ENS` filing.\n\n**Conditional:** only applicable if `manifestTypeCode` is `ENS`.\n", + "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)?$", @@ -260,6 +260,21 @@ "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" : { @@ -300,64 +315,23 @@ "title" : "Buyer", "type" : "object" }, - "Cargo Gross Volume" : { - "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" - }, - "Cargo Gross Weight" : { - "description" : "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container.\n", + "CancelShippingInstructionsUpdate" : { "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", + "updatedShippingInstructionsStatus" : { + "description" : "The status of the `Updated Shipping Instructions`. It can only be `UPDATE_CANCELLED`\n", + "example" : "UPDATE_CANCELLED", + "maxLength" : 50, "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" + "updatedShippingInstructionsStatus" ], - "title" : "Cargo Gross Weight", + "title" : "Cancel Shipping Instructions Update", "type" : "object" }, - "Cargo Net Volume" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "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", @@ -369,7 +343,7 @@ "type" : "string" }, "value" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "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", @@ -381,11 +355,11 @@ "unit", "value" ], - "title" : "Cargo Net Volume", + "title" : "Cargo Gross Volume", "type" : "object" }, - "Cargo Net Weight" : { - "description" : "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container.\n", + "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", @@ -397,7 +371,7 @@ "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", + "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", @@ -409,23 +383,23 @@ "unit", "value" ], - "title" : "Cargo Net Weight", + "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/Cargo Gross Volume" + "$ref" : "#/components/schemas/CargoGrossVolume" }, "cargoGrossWeight" : { - "$ref" : "#/components/schemas/Cargo Gross Weight" + "$ref" : "#/components/schemas/CargoGrossWeight" }, "cargoNetVolume" : { - "$ref" : "#/components/schemas/Cargo Net Volume" + "$ref" : "#/components/schemas/CargoNetVolume" }, "cargoNetWeight" : { - "$ref" : "#/components/schemas/Cargo Net Weight" + "$ref" : "#/components/schemas/CargoNetWeight" }, "customsReferences" : { "description" : "A list of `Customs references`\n", @@ -464,16 +438,16 @@ "description" : "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", "properties" : { "cargoGrossVolume" : { - "$ref" : "#/components/schemas/Cargo Gross Volume" + "$ref" : "#/components/schemas/CargoGrossVolume" }, "cargoGrossWeight" : { - "$ref" : "#/components/schemas/Cargo Gross Weight" + "$ref" : "#/components/schemas/CargoGrossWeight" }, "cargoNetVolume" : { - "$ref" : "#/components/schemas/Cargo Net Volume" + "$ref" : "#/components/schemas/CargoNetVolume" }, "cargoNetWeight" : { - "$ref" : "#/components/schemas/Cargo Net Weight" + "$ref" : "#/components/schemas/CargoNetWeight" }, "customsReferences" : { "description" : "A list of `Customs references`\n", @@ -514,6 +488,62 @@ "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" : { @@ -650,7 +680,7 @@ "$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", + "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", @@ -805,7 +835,7 @@ "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", + "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", @@ -831,7 +861,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "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", @@ -897,7 +927,7 @@ "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", + "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", @@ -923,7 +953,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "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", @@ -972,7 +1002,7 @@ "$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", + "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", @@ -983,7 +1013,7 @@ "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", + "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", @@ -994,7 +1024,7 @@ "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", + "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", @@ -1005,7 +1035,7 @@ "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", + "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", @@ -1016,7 +1046,7 @@ "type" : "array" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties" + "$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", @@ -1035,7 +1065,7 @@ "type" : "array" }, "invoicePayableAt" : { - "$ref" : "#/components/schemas/Invoice Payable At" + "$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", @@ -1108,7 +1138,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$ref" : "#/components/schemas/PlaceOfIssue" }, "references" : { "description" : "A list of `References`\n", @@ -1138,7 +1168,7 @@ "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", + "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", @@ -1181,6 +1211,23 @@ "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" : { @@ -1295,7 +1342,7 @@ "type" : "string" }, "grossWeight" : { - "$ref" : "#/components/schemas/Gross Weight" + "$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", @@ -1366,13 +1413,13 @@ "$ref" : "#/components/schemas/Limits" }, "netExplosiveContent" : { - "$ref" : "#/components/schemas/Net Explosive Content" + "$ref" : "#/components/schemas/NetExplosiveContent" }, "netVolume" : { - "$ref" : "#/components/schemas/Net Volume" + "$ref" : "#/components/schemas/NetVolume" }, "netWeight" : { - "$ref" : "#/components/schemas/Net Weight" + "$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", @@ -1428,96 +1475,6 @@ "title" : "Dangerous Goods", "type" : "object" }, - "Data" : { - "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/Shipping Instructions" - }, - "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/Updated Shipping Instructions" - }, - "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" - }, - "Data_1" : { - "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/Transport Document" - }, - "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" - }, "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" : { @@ -1601,11 +1558,11 @@ "title" : "Detailed Error", "type" : "object" }, - "Document Parties" : { + "DocumentParties" : { "description" : "All `Parties` with associated roles.\n", "properties" : { - "buyer" : { - "$ref" : "#/components/schemas/Buyer" + "carriersAgentAtDestination" : { + "$ref" : "#/components/schemas/CarriersAgentAtDestination" }, "consignee" : { "$ref" : "#/components/schemas/Consignee" @@ -1613,11 +1570,11 @@ "endorsee" : { "$ref" : "#/components/schemas/Endorsee" }, - "issueTo" : { - "$ref" : "#/components/schemas/IssueToParty" + "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:** Mandatory for To Order BLs, `isToOrder=true`\n", + "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" }, @@ -1631,76 +1588,73 @@ }, "type" : "array" }, - "seller" : { - "$ref" : "#/components/schemas/Seller" - }, "shipper" : { "$ref" : "#/components/schemas/Shipper" } }, "required" : [ + "issuingParty", "shipper" ], "title" : "Document Parties", "type" : "object" }, - "Document Parties_1" : { - "description" : "All `Parties` with associated roles.\n", + "DocumentPartiesHouseBL" : { + "description" : "All `Parties` with associated roles for this `House Bill of Lading`.\n", "properties" : { - "carriersAgentAtDestination" : { - "$ref" : "#/components/schemas/CarriersAgentAtDestination" + "buyer" : { + "$ref" : "#/components/schemas/Buyer" }, "consignee" : { - "$ref" : "#/components/schemas/Consignee" - }, - "endorsee" : { - "$ref" : "#/components/schemas/Endorsee" + "$ref" : "#/components/schemas/ConsigneeHBL" }, - "issuingParty" : { - "$ref" : "#/components/schemas/IssuingParty" + "notifyParty" : { + "$ref" : "#/components/schemas/NotifyPartyHBL" }, - "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:** Mandatory for To Order BLs, `isToOrder=true`\n", + "other" : { + "description" : "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", "items" : { - "$ref" : "#/components/schemas/NotifyParty" + "$ref" : "#/components/schemas/OtherDocumentPartyHBL" }, - "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" + "$ref" : "#/components/schemas/ShipperHBL" } }, - "required" : [ - "issuingParty", - "shipper" - ], "title" : "Document Parties", "type" : "object" }, - "Document Parties_2" : { - "description" : "All `Parties` with associated roles for this `House Bill of Lading`.\n", + "DocumentPartiesShippingInstructions" : { + "description" : "All `Parties` with associated roles.\n", "properties" : { "buyer" : { "$ref" : "#/components/schemas/Buyer" }, "consignee" : { - "$ref" : "#/components/schemas/ConsigneeHBL" + "$ref" : "#/components/schemas/Consignee" }, - "notifyParty" : { - "$ref" : "#/components/schemas/NotifyPartyHBL" + "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/OtherDocumentPartyHBL" + "$ref" : "#/components/schemas/OtherDocumentParty" }, "type" : "array" }, @@ -1708,9 +1662,12 @@ "$ref" : "#/components/schemas/Seller" }, "shipper" : { - "$ref" : "#/components/schemas/ShipperHBL" + "$ref" : "#/components/schemas/Shipper" } }, + "required" : [ + "shipper" + ], "title" : "Document Parties", "type" : "object" }, @@ -1724,7 +1681,7 @@ "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", + "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)?$", @@ -1757,7 +1714,7 @@ "$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", + "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", @@ -1819,7 +1776,7 @@ "type" : "string" }, "tareWeight" : { - "$ref" : "#/components/schemas/Tare Weight" + "$ref" : "#/components/schemas/TareWeight" } }, "required" : [ @@ -1993,7 +1950,7 @@ "title" : "Geo Coordinate", "type" : "object" }, - "Gross Weight" : { + "GrossWeight" : { "description" : "Total weight of the goods carried, including packaging.\n", "properties" : { "unit" : { @@ -2025,7 +1982,7 @@ "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/Document Parties_2" + "$ref" : "#/components/schemas/DocumentPartiesHouseBL" }, "houseBillOfLadingReference" : { "description" : "A unique number allocated by the Ocean Transport Intermediary (OTI) to the `House Bill of Lading`.\n", @@ -2116,7 +2073,46 @@ "title" : "Inner Packaging", "type" : "object" }, - "Invoice Payable At" : { + "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" : { @@ -2151,7 +2147,7 @@ "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**Conditional:** only applicable when `isElectronic=true` and `transportDocumentTypeCode=BOL`. The property **must** be absent for paper B/Ls (`isElectronic=false`)\n", + "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+$", @@ -2306,7 +2302,7 @@ "title" : "National Commodity Code", "type" : "object" }, - "Net Explosive Content" : { + "NetExplosiveContent" : { "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", "properties" : { "unit" : { @@ -2336,7 +2332,7 @@ "title" : "Net Explosive Content", "type" : "object" }, - "Net Volume" : { + "NetVolume" : { "description" : "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n", "properties" : { "unit" : { @@ -2365,7 +2361,7 @@ "title" : "Net Volume", "type" : "object" }, - "Net Weight" : { + "NetWeight" : { "description" : "Total weight of the goods carried, excluding packaging.\n", "properties" : { "unit" : { @@ -2400,7 +2396,7 @@ "$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", + "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", @@ -2829,7 +2825,7 @@ "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", + "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)?$", @@ -2880,56 +2876,6 @@ "title" : "Party Contact Detail", "type" : "object" }, - "Place of Issue" : { - "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" - }, "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" : { @@ -3035,6 +2981,56 @@ "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" : { @@ -3199,7 +3195,7 @@ "type" : "string" }, "tareWeight" : { - "$ref" : "#/components/schemas/Tare Weight" + "$ref" : "#/components/schemas/TareWeight" } }, "required" : [ @@ -3284,7 +3280,7 @@ "$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", + "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", @@ -3400,8 +3396,8 @@ "title" : "Shipper", "type" : "object" }, - "Shipping Instructions" : { - "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", + "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", @@ -3429,7 +3425,7 @@ "$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", + "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", @@ -3440,7 +3436,7 @@ "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", + "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", @@ -3451,7 +3447,7 @@ "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", + "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", @@ -3462,7 +3458,7 @@ "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", + "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", @@ -3473,7 +3469,7 @@ "type" : "array" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties" + "$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", @@ -3499,7 +3495,7 @@ "type" : "array" }, "invoicePayableAt" : { - "$ref" : "#/components/schemas/Invoice Payable At" + "$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", @@ -3547,14 +3543,14 @@ "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", + "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", + "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, @@ -3572,7 +3568,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$ref" : "#/components/schemas/PlaceOfIssue" }, "references" : { "description" : "A list of `References`\n", @@ -3602,7 +3598,7 @@ "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", + "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", @@ -3672,366 +3668,136 @@ "title" : "Shipping Instructions", "type" : "object" }, - "Shipping Instructions Response" : { - "description" : "**Only** the `shippingInstructionsReference` is returned.\n", + "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", + "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" : [ - "shippingInstructionsReference" + "shippingInstructionsStatus" ], - "title" : "Shipping Instructions Response", + "title" : "Data", "type" : "object" }, - "ShippingInstructions" : { - "description" : "The `Shipping Instructions` as provided by the Shipper.\n", + "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" : { - "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" + "data" : { + "$ref" : "#/components/schemas/ShippingInstructionsData" }, - "consignmentItems" : { - "description" : "A list of `ConsignmentItems`\n", - "items" : { - "$ref" : "#/components/schemas/ConsignmentItemShipper" - }, - "minItems" : 1, - "type" : "array" + "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" }, - "customsReferences" : { - "description" : "A list of `Customs references`\n", - "items" : { - "$ref" : "#/components/schemas/CustomsReference" - }, - "type" : "array" + "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" }, - "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", - "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", - "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", - "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", - "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/Document Parties" - }, - "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" + "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" }, - "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", + "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" : [ - "PRE", - "COL" + "1.0" ], - "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/Invoice Payable At" - }, - "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, + "example" : "1.0", "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/Place of Issue" - }, - "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", - "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", + "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" }, - "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)?$", + "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" }, - "transportDocumentTypeCode" : { - "description" : "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", + "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" : [ - "BOL", - "SWB" + "org.dcsa.shipping-instructions.v3" ], - "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, + "example" : "org.dcsa.shipping-instructions.v3", "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" + "data", + "datacontenttype", + "id", + "source", + "specversion", + "subscriptionReference", + "time", + "type" ], - "title" : "Shipping Instructions", + "title" : "Shipping Instructions Notification", "type" : "object" }, - "ShippingInstructionsNotification" : { - "description" : "`CloudEvent` specific properties for the `Notification`.\n", - "properties" : { - "data" : { - "$ref" : "#/components/schemas/Data" - }, - "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" - }, - "Tare Weight" : { - "description" : "The weight of an empty container (gross container weight).\n", + "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", @@ -4080,401 +3846,16 @@ "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" - }, - "Transport Document" : { - "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", - "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", - "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", - "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", - "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", - "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/Document Parties_1" - }, - "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" : { - "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" - }, - "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/Place of Issue" - }, - "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", - "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" + "pattern" : "^\\S(?:.*\\S)?$", + "type" : "string" + } + }, + "required" : [ + "countryCode", + "type", + "value" ], - "title" : "Transport Document", + "title" : "Tax & Legal Reference", "type" : "object" }, "TransportDocument" : { @@ -4575,7 +3956,7 @@ "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", + "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", @@ -4586,7 +3967,7 @@ "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", + "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", @@ -4597,7 +3978,7 @@ "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", + "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", @@ -4608,7 +3989,7 @@ "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", + "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", @@ -4626,7 +4007,7 @@ "type" : "string" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties_1" + "$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", @@ -4638,43 +4019,7 @@ "type" : "string" }, "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" + "$ref" : "#/components/schemas/InvoicePayableAt" }, "isElectronic" : { "description" : "An indicator whether the transport document is electronically transferred.\n", @@ -4741,7 +4086,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$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", @@ -4768,7 +4113,7 @@ "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", + "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", @@ -4862,11 +4207,62 @@ "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/Data_1" + "$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", @@ -4937,350 +4333,104 @@ "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", - "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", - "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", - "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", - "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/Document Parties" - }, - "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/Invoice Payable At" - }, - "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" + "type" : "string" }, - "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" + "onwardInlandRouting" : { + "$ref" : "#/components/schemas/OnwardInlandRouting" }, - "isShippedOnBoardType" : { - "description" : "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n", - "example" : true, - "type" : "boolean" + "placeOfDelivery" : { + "$ref" : "#/components/schemas/PlaceOfDelivery" }, - "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" + "placeOfReceipt" : { + "$ref" : "#/components/schemas/PlaceOfReceipt" }, - "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, + "plannedArrivalDate" : { + "description" : "The planned date of arrival.\n", + "example" : "2024-06-07", + "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" + "plannedDepartureDate" : { + "description" : "The planned date of departure.\n", + "example" : "2024-06-03", + "format" : "date", + "type" : "string" }, - "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" + "portOfDischarge" : { + "$ref" : "#/components/schemas/PortOfDischarge" }, - "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" + "portOfLoading" : { + "$ref" : "#/components/schemas/PortOfLoading" }, - "originChargesPaymentTerm" : { - "$ref" : "#/components/schemas/OriginChargesPaymentTerm" + "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" }, - "partyContactDetails" : { - "description" : "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", + "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/PartyContactDetail" + "$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" }, - "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" - }, - "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", - "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, + "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" }, - "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" + "isShipperOwned" : { + "description" : "Indicates whether the container is shipper owned (SOC).\n", + "example" : false, + "type" : "boolean" } }, "required" : [ - "consignmentItems", - "documentParties", - "freightPaymentTermCode", - "isElectronic", - "isShippedOnBoardType", - "isToOrder", - "partyContactDetails", - "shippingInstructionsReference", - "transportDocumentTypeCode", - "utilizedTransportEquipments" + "equipmentReference", + "isShipperOwned" ], - "title" : "Update Shipping Instructions", + "title" : "Carrier Owned Equipment", "type" : "object" }, - "Updated Shipping Instructions" : { - "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", + "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", @@ -5308,7 +4458,7 @@ "$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", + "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", @@ -5319,7 +4469,7 @@ "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", + "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", @@ -5330,7 +4480,7 @@ "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", + "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", @@ -5341,7 +4491,7 @@ "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", + "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", @@ -5352,14 +4502,7 @@ "type" : "array" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties" - }, - "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" + "$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", @@ -5378,7 +4521,7 @@ "type" : "array" }, "invoicePayableAt" : { - "$ref" : "#/components/schemas/Invoice Payable At" + "$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", @@ -5426,14 +4569,14 @@ "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", + "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", + "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, @@ -5451,7 +4594,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$ref" : "#/components/schemas/PlaceOfIssue" }, "references" : { "description" : "A list of `References`\n", @@ -5481,7 +4624,7 @@ "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", + "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", @@ -5499,19 +4642,6 @@ "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" : [ @@ -5521,12 +4651,6 @@ "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" : { @@ -5544,10 +4668,20 @@ "isShippedOnBoardType", "isToOrder", "partyContactDetails", - "shippingInstructionsStatus", + "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" }, @@ -5593,7 +4727,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", + "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", @@ -5653,7 +4787,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", + "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", @@ -5702,34 +4836,6 @@ ], "title" : "Vessel/Voyage", "type" : "object" - }, - "shippinginstructions_documentReference_body" : { - "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" - ], - "type" : "object" - }, - "transportdocuments_transportDocumentReference_body" : { - "properties" : { - "transportDocumentStatus" : { - "description" : "The status of the `Transport Document`. It can only be `APPROVED`\n", - "example" : "APPROVED", - "maxLength" : 50, - "type" : "string" - } - }, - "required" : [ - "transportDocumentStatus" - ], - "type" : "object" } } }, @@ -5739,12 +4845,12 @@ "name" : "Digital Container Shipping Association (DCSA)", "url" : "https://dcsa.org" }, - "description" : "API specification issued by DCSA.org.\n\nFor explanation of specific values or objects please refer to the [Information Model v2024.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 Bill of Lading 3.0](https://dcsa.org/standards/bill-of-lading/documentation-bill-of-lading-3) to address this. **All use cases mentioned in this API specification refer to use cases defined in the eBL IFS**.\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", + "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 specification for Shipping Instructions and Transport Document", + "title" : "DCSA Shipping Instructions and Transport Document API", "version" : "3.0.0" }, "openapi" : "3.0.3", @@ -5865,7 +4971,7 @@ } }, "schema" : { - "$ref" : "#/components/schemas/Shipping Instructions Response" + "$ref" : "#/components/schemas/CreateShippingInstructionsResponse" } } }, @@ -6974,7 +6080,7 @@ } }, "schema" : { - "$ref" : "#/components/schemas/shippinginstructions_documentReference_body" + "$ref" : "#/components/schemas/CancelShippingInstructionsUpdate" } } }, @@ -7997,7 +7103,7 @@ }, "/v3/transport-documents/{transportDocumentReference}" : { "get" : { - "description" : "Retrieves the `Transport Document` with the `transportDocumentReference` in the path.\n", + "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" : [ { @@ -8575,7 +7681,34 @@ "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", @@ -8607,7 +7740,7 @@ "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/transportdocuments_transportDocumentReference_body" + "$ref" : "#/components/schemas/ApproveTransportDocument" } } } @@ -8828,7 +7961,8 @@ }, "servers" : [ { - "url" : "/" + "description" : "SwaggerHub API Auto Mocking", + "url" : "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL/3.0.0" } ], "tags" : [ 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 index 076d339a..1d88a9fd 100644 --- 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 @@ -205,7 +205,7 @@ "title" : "Address", "type" : "object" }, - "Cargo Gross Volume" : { + "CargoGrossVolume" : { "description" : "Calculated by multiplying the width, height, and length of the packed cargo.\n", "properties" : { "unit" : { @@ -233,7 +233,7 @@ "title" : "Cargo Gross Volume", "type" : "object" }, - "Cargo Gross Weight" : { + "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" : { @@ -261,8 +261,56 @@ "title" : "Cargo Gross Weight", "type" : "object" }, - "Cargo Net Volume" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "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", @@ -274,7 +322,7 @@ "type" : "string" }, "value" : { - "description" : "Calculated by multiplying the width, height, and length of the packed cargo, excluding packaging.\n", + "description" : "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", "example" : 2.4, "exclusiveMinimum" : true, "format" : "float", @@ -289,7 +337,7 @@ "title" : "Cargo Net Volume", "type" : "object" }, - "Cargo Net Weight" : { + "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" : { @@ -317,54 +365,6 @@ "title" : "Cargo Net 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/Cargo Gross Volume" - }, - "cargoGrossWeight" : { - "$ref" : "#/components/schemas/Cargo Gross Weight" - }, - "cargoNetVolume" : { - "$ref" : "#/components/schemas/Cargo Net Volume" - }, - "cargoNetWeight" : { - "$ref" : "#/components/schemas/Cargo Net Weight" - }, - "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" - }, "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" : { @@ -501,7 +501,7 @@ "$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", + "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", @@ -609,7 +609,7 @@ "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", + "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", @@ -635,7 +635,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "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", @@ -769,7 +769,7 @@ "type" : "string" }, "grossWeight" : { - "$ref" : "#/components/schemas/Gross Weight" + "$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", @@ -840,13 +840,13 @@ "$ref" : "#/components/schemas/Limits" }, "netExplosiveContent" : { - "$ref" : "#/components/schemas/Net Explosive Content" + "$ref" : "#/components/schemas/NetExplosiveContent" }, "netVolume" : { - "$ref" : "#/components/schemas/Net Volume" + "$ref" : "#/components/schemas/NetVolume" }, "netWeight" : { - "$ref" : "#/components/schemas/Net Weight" + "$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", @@ -951,47 +951,6 @@ "title" : "Detailed Error", "type" : "object" }, - "Document Parties" : { - "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:** Mandatory for To Order BLs, `isToOrder=true`\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" - }, "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", @@ -1033,6 +992,47 @@ "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" : { @@ -1067,7 +1067,7 @@ "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", + "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)?$", @@ -1100,7 +1100,7 @@ "$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", + "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", @@ -1207,7 +1207,7 @@ "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", + "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, @@ -1370,7 +1370,7 @@ "type" : "string" }, "tareWeight" : { - "$ref" : "#/components/schemas/Tare Weight" + "$ref" : "#/components/schemas/TareWeight" } }, "required" : [ @@ -1501,7 +1501,7 @@ "title" : "Geo Coordinate", "type" : "object" }, - "Gross Weight" : { + "GrossWeight" : { "description" : "Total weight of the goods carried, including packaging.\n", "properties" : { "unit" : { @@ -1587,6 +1587,45 @@ "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" : { @@ -1757,7 +1796,7 @@ "title" : "National Commodity Code", "type" : "object" }, - "Net Explosive Content" : { + "NetExplosiveContent" : { "description" : "The total weight of the explosive substances, without the packaging’s, casings, etc.\n", "properties" : { "unit" : { @@ -1787,7 +1826,7 @@ "title" : "Net Explosive Content", "type" : "object" }, - "Net Volume" : { + "NetVolume" : { "description" : "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n", "properties" : { "unit" : { @@ -1816,7 +1855,7 @@ "title" : "Net Volume", "type" : "object" }, - "Net Weight" : { + "NetWeight" : { "description" : "Total weight of the goods carried, excluding packaging.\n", "properties" : { "unit" : { @@ -1851,7 +1890,7 @@ "$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", + "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", @@ -2140,7 +2179,7 @@ "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", + "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)?$", @@ -2191,7 +2230,42 @@ "title" : "Party Contact Detail", "type" : "object" }, - "Place of Issue" : { + "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" : [ { @@ -2241,41 +2315,6 @@ "title" : "Place of Issue", "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" - }, "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" : { @@ -2473,7 +2512,7 @@ "$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", + "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", @@ -2542,7 +2581,7 @@ "title" : "Shipper", "type" : "object" }, - "Tare Weight" : { + "TareWeight" : { "description" : "The weight of an empty container (gross container weight).\n", "properties" : { "unit" : { @@ -2791,7 +2830,7 @@ "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", + "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", @@ -2802,7 +2841,7 @@ "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", + "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", @@ -2813,7 +2852,7 @@ "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", + "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", @@ -2824,7 +2863,7 @@ "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", + "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", @@ -2842,7 +2881,7 @@ "type" : "string" }, "documentParties" : { - "$ref" : "#/components/schemas/Document Parties" + "$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", @@ -2854,43 +2893,7 @@ "type" : "string" }, "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" + "$ref" : "#/components/schemas/InvoicePayableAt" }, "isElectronic" : { "description" : "An indicator whether the transport document is electronically transferred.\n", @@ -2957,7 +2960,7 @@ "type" : "array" }, "placeOfIssue" : { - "$ref" : "#/components/schemas/Place of Issue" + "$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", @@ -2984,7 +2987,7 @@ "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", + "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", @@ -3180,7 +3183,7 @@ "type" : "array" }, "shippingMarks" : { - "description" : "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", + "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", @@ -3240,7 +3243,7 @@ "name" : "Digital Container Shipping Association (DCSA)", "url" : "https://dcsa.org" }, - "description" : "

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

\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).\nPlease [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n", + "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"