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 82932980..be0dfc1e 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 @@ -424,7 +424,7 @@ "example": "W3C" }, "partyCode": { - "maxLength": 100, + "maxLength": 150, "type": "string", "description": "Code to identify the party as provided by the code list provider\n", "example": "MSK" @@ -462,7 +462,7 @@ "example": "DK" }, "value": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the `taxLegalReference`\n", @@ -553,28 +553,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -628,6 +628,13 @@ "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", @@ -696,7 +703,7 @@ "declaredValue": { "minimum": 0, "type": "number", - "description": "The value of the cargo that the shipper declares 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", + "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 }, @@ -913,7 +920,8 @@ "example": "CR" }, "value": { - "maxLength": 100, + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the reference. \n", "example": "HHL00103004" @@ -1013,7 +1021,7 @@ "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 Noemclature)\n- `CUS` (Customs Union and Statistics)\n", + "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": { @@ -1050,7 +1058,7 @@ "required": [ "countryCode", "type", - "value" + "values" ], "type": "object", "properties": { @@ -1069,12 +1077,16 @@ "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", "example": "DK" }, - "value": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `customsReference`\n", - "example": "4988470982020120017" + "values": { + "minItems": 1, + "type": "array", + "items": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The value of the `customsReference`\n", + "example": "4988470982020120017" + } } }, "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA (small) list of examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n\nAllowed combinations of `type` and `country` are maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/customsreferences-v300.csv).\n" @@ -1133,6 +1145,13 @@ "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", @@ -1547,7 +1566,7 @@ }, "shippingMarks": { "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", "items": { "maxLength": 500, "type": "string", @@ -1636,7 +1655,7 @@ }, "source": { "type": "string", - "description": "The source of the seal, namely who has affixed the seal. This attribute links to the Seal Source ID defined in the Seal Source reference data entity.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n", + "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", @@ -2301,7 +2320,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -2332,14 +2350,14 @@ } }, "shippersReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Shipper`.\n", "example": "HHL007" }, "shippersPurchaseOrderReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Shipper Purchase Order`.\n", @@ -2367,7 +2385,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -2398,14 +2415,14 @@ } }, "consigneesReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Consignee`.\n", "example": "HHL007" }, "consigneesPurchaseOrderReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Consignee Purchase Order`.\n", @@ -2433,7 +2450,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -2533,7 +2549,7 @@ } }, "reference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Party`.\n", @@ -2583,6 +2599,26 @@ }, "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": [ @@ -2614,6 +2650,14 @@ "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" + } } } }, 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 e0550a06..b9591951 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 @@ -49,7 +49,7 @@ { "type": "CTN", "countryCode": "SN", - "value": "12345" + "values": ["12345"] } ], "utilizedTransportEquipments": [ 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 099c1486..f1d65ebd 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 @@ -41,7 +41,7 @@ { "type": "CTN", "countryCode": "SN", - "value": "12345" + "values": ["12345"] } ], "utilizedTransportEquipments": [ 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 95bdbff3..733d03f1 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 @@ -2,7 +2,7 @@ "openapi": "3.0.3", "info": { "title": "DCSA OpenAPI specification for Electronic Bill of Lading", - "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\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### 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\nAll 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### Stats API\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Electronic Bill of Lading API. Further details can be found [here](https://labs.dcsa.org/#/http/guides/api-guides/stats-api/introduction)\n\nFor a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ebl/v3#v300). Please [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.\n", + "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 implmented by the provider.\n\n### Notifications (Implemented by consumer)\nIt is possible to have notifications pushed to you whenever the provider needs input and/or a state change. The format of the notification is defined by the [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### Stats API\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Electronic Bill of Lading API. Further details can be found [here](https://labs.dcsa.org/#/http/guides/api-guides/stats-api/introduction)\n\nFor a changelog, please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/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", @@ -40,7 +40,7 @@ "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) if the payload schema validates or a `400` (Bad Request) if it does not.\n\n## Flow\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!**\n\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 stored along with 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 the following payload:\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` the process ends here. The `Shipping Instructions`\n\n - is now stored in the provider system\n - has status `RECEIVED`\n - awaits further processing by the provider\n - a `201` (Created) response is sent to the consumer with a payload containing `documentStatus=RECEIVED`\n - '_relevant_' subscribers have been notified.\n\nThe provider wil now start asynchronous processing. Once processed, the new status of the `Shipping Instructions` will be communicated via a `Shipping Instructions Notification`. 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", + "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": [ { @@ -147,7 +147,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ShippingInstructionsRefStatus" + "$ref": "#/components/schemas/Shipping Instructions Response" }, "examples": { "receExample": { @@ -162,6 +162,30 @@ } } }, + "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" + } + }, + "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": { @@ -238,7 +262,7 @@ } }, "default": { - "description": "Unexpected error", + "description": "For other errors the error object should be populated with relevant information\n", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" @@ -283,7 +307,7 @@ "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 accessable.\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", + "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 accessable.\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": [ { @@ -584,8 +608,16 @@ } } }, + "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", + "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" @@ -597,7 +629,7 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "notFoundExample": { + "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": { @@ -616,6 +648,63 @@ } ] } + }, + "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": "2023-04-13T07:41:00+08:30", + "errors": [ + { + "errorCode": 7003, + "errorCodeText": "documentReference not found", + "errorCodeMessage": "The Shipping Instructions does not exist" + } + ] + } + } + } + } + } + }, + "409": { + "description": "In case the provider is processing the `Shipping Instructions` - it is possible for the provider to reject new incomming requests by returning a `409` (Conflict)\n", + "headers": { + "API-Version": { + "$ref": "#/components/headers/API-Version" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "conflictExample": { + "summary": "Conflicting request\n", + "description": "The provider is already processing a request and needs to finish this process before any new requests are processed\n\n**NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a \"random example\"\n", + "value": { + "httpMethod": "GET", + "requestUri": "/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": "2023-04-13T07:41:00+08:30", + "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" + } + ] + } } } } @@ -659,7 +748,7 @@ } }, "default": { - "description": "Unexpected error", + "description": "For other errors the error object should be populated with relevant information\n", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" @@ -671,22 +760,22 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "getError": { - "summary": "GET non-existing Shipping Instructions\n", - "description": "Calling\n\n GET /v3/shipping-instructions/si-123\n \nresults in an error as `Shipping Instructions` `si-123` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", + "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 timeperiod.\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": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "The requested shippingInstructionsReference does not exist", + "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": "2023-04-13T07:41:00+08:30", "errors": [ { "errorCode": 7003, - "errorCodeText": "Non existent shippingInstructionsReference", - "errorCodeMessage": "shippingInstructionsReference `si-123` does not exist" + "errorCodeText": "Max Shipping Instructions requests reached", + "errorCodeMessage": "A maximum of 10 Shipping Instructions can be requested per hour" } ] } @@ -702,7 +791,7 @@ "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) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow\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 corresponding to the following payload is returned:\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 corresponding to the following payload is returned:\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` the process ends here. The `Updated Shipping Instructions`\n\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 - awaits further processing by the provider\n - '_relevant_' subscribers have been notified.\n\nThe provider wil 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`. 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` and `updatedShippingInstructionsStatus` of the `Shipping Instructions` has changed.\n \n If the consumer wants to get the content of the `Update Shipping Instructions` provided via this `PUT` endPoint, the `GET` endPoint needs to be used in combination with the `?updatedContent=true` queryParameter:\n \n GET /v3/shipping-instructions/{documentReference}?updatedContent=true\n \n It 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", + "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": [ { @@ -859,6 +948,24 @@ } } }, + "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" + } + } + } + } + }, "400": { "description": "In case the updated `Shipping Instructions` does not schema validate a `400` (Bad Request) is returned\n", "headers": { @@ -897,6 +1004,43 @@ } } }, + "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": "2023-04-13T07:41:00+08:30", + "errors": [ + { + "errorCode": 7003, + "errorCodeText": "shippingInstructionsReference not found", + "errorCodeMessage": "The Shipping Instructions does not exist" + } + ] + } + } + } + } + } + }, "409": { "description": "In case the provider is already processing the `Shipping Instructions` matching `shippingInstructionsReference='si-123'` or for any other reason cannot process the request, it is possible to reject the `PUT` request with a `409` (Conflict) response\n", "headers": { @@ -1015,7 +1159,7 @@ "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) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow\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\n3. The `updatedShippingInstructionsStatus` is set to `UPDATE CANCELLED`.\n4. All '_relevant_' subscribers will be notified via a [Shipping Instructions Notification](#/ShippingInstructionsNotification).\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": [ { @@ -1102,8 +1246,26 @@ } } }, + "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" + } + } + } + } + }, "400": { - "description": "In case the Cancel payload does not schema validate a `400` (Bad Request) is returned\n", + "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" @@ -1142,7 +1304,7 @@ } }, "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", + "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" @@ -1253,7 +1415,7 @@ } }, "default": { - "description": "Unexpected error", + "description": "For other errors the error object should be populated with relevant information\n", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" @@ -1265,22 +1427,22 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "getError": { - "summary": "GET non-existing Shipping Instructions\n", - "description": "Calling\n\n PATCH /v3/shipping-instructions/si-123\n \nresults in an error as `Shipping Instructions` `si-123` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", + "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 timeperiod.\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": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "The requested shippingInstructionsReference does not exist", + "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": "2023-04-13T07:41:00+08:30", "errors": [ { "errorCode": 7003, - "errorCodeText": "Non existent shippingInstructionsReference", - "errorCodeMessage": "shippingInstructionsReference `si-123` does not exist" + "errorCodeText": "Max Shipping Instructions requests reached", + "errorCodeMessage": "A maximum of 10 Shipping Instructions patches can be requested per hour" } ] } @@ -1736,6 +1898,51 @@ } } }, + "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": "2023-04-13T07:41:00+08:30", + "errors": [ + { + "errorCode": 7003, + "errorCodeText": "documentReference not found", + "errorCodeMessage": "The Transport Document does not exist" + } + ] + } + } + } + } + } + }, "500": { "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", "headers": { @@ -1774,7 +1981,7 @@ } }, "default": { - "description": "Unexpected error", + "description": "For other errors the error object should be populated with relevant information\n", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" @@ -1786,22 +1993,22 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "getError": { - "summary": "GET non-existing Transport Document\n", - "description": "Calling\n\n GET /v3/transport-documents/td-987\n \nresults in an error as `Transport Document` `td-987` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", + "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 timeperiod.\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": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "The requested transportDocumentReference does not exist", + "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": "2023-04-13T07:41:00+08:30", "errors": [ { "errorCode": 7003, - "errorCodeText": "Non existent transportDocumentReference", - "errorCodeMessage": "transportDocumentReference `td-987` does not exist" + "errorCodeText": "Max Transport Document requests reached", + "errorCodeMessage": "A maximum of 10 Transport Document can be requested per hour" } ] } @@ -1817,7 +2024,7 @@ "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) if the payload schema-validates or a `400` (Bad Request) if it does not.\n\n## Flow\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\n3. The `transportDocumentStatus` is set to `APPROVED`.\n4. All '_relevant_' subscribers will be notified via a [Transport Document Notification](#/TransportDocumentNotification).\n\nThe provider wil now start asynchronous processing. Once processed, the new status of the `Transport Document` (`ISSUED`) will be communicated via a `Transport Document Notification`. 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", + "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": [ { @@ -1883,6 +2090,24 @@ } } }, + "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" + } + } + } + } + }, "400": { "description": "In case the Approve payload does not schema validate a `400` (Bad Request) is returned\n", "headers": { @@ -1922,6 +2147,80 @@ } } }, + "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": "2023-04-13T07:41:00+08:30", + "errors": [ + { + "errorCode": 7003, + "errorCodeText": "documentReference not found", + "errorCodeMessage": "The Transport Document does not exist" + } + ] + } + } + } + } + } + }, + "409": { + "description": "In case the consumer is requesting a `transportDocumentReference` that is being processed it is possible to return a `409` (Conflict).\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": "2023-04-13T07:41:00+08:30", + "errors": [ + { + "errorCode": 7003, + "errorCodeText": "documentReference being processed", + "errorCodeMessage": "The Transport Document is currently being processed" + } + ] + } + } + } + } + } + }, "500": { "description": "In case a server error occurs in provider system a `500` (Internal Server Error) is returned\n", "headers": { @@ -1960,7 +2259,7 @@ } }, "default": { - "description": "Unexpected error\n", + "description": "For other errors the error object should be populated with relevant information\n", "headers": { "API-Version": { "$ref": "#/components/headers/API-Version" @@ -1972,22 +2271,22 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "getError": { - "summary": "GET non-existing Transport Document\n", - "description": "Calling\n\n PATCH /v3/transport-documents/td-987\n \nresults in an error as `Transport Document` `td-987` does not exist.\n\n**NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a \"random example\".\n", + "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 timeperiod.\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": 404, - "statusCodeText": "Not Found", - "statusCodeMessage": "The requested transportDocumentReference does not exist", + "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": "2023-04-13T07:41:00+08:30", "errors": [ { "errorCode": 7003, - "errorCodeText": "Non existent transportDocumentReference", - "errorCodeMessage": "transportDocumentReference `td-987` does not exist" + "errorCodeText": "Max Transport Document requests reached", + "errorCodeMessage": "A maximum of 10 Transport Document can be patched per hour" } ] } @@ -3101,28 +3400,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -3318,28 +3617,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -3554,28 +3853,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -3759,7 +4058,7 @@ "example": "Rejected because of of wrong equipmentReference" } }, - "description": "The `shippingInstructionsReference`, possibly the `transportDocumentReference` along with the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus`, an optional list of `requestedChanges` to be applied to the `Shipping Instructions` and and optional `reason`field is returned.\n" + "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", @@ -3801,7 +4100,7 @@ "example": "Rejected because of of wrong equipmentReference" } }, - "description": "The `shippingInstructionsReference`, possibly the `transportDocumentReference` along with the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` and and optional `reason`field is returned.\n" + "description": "The `shippingInstructionsReference`, possibly the `transportDocumentReference` along with the `shippingInstructionsStatus` and `updatedShippingInstructionsStatus` and and optional `reason` field is returned.\n" }, "Feedback": { "title": "Feedback", @@ -3821,7 +4120,7 @@ "code": { "maxLength": 50, "type": "string", - "description": "A code used to describe the feedback. Possible values are: {Descriptions for each pseudo-enum should be provided}\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", + "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": { @@ -4212,7 +4511,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -4243,14 +4541,14 @@ } }, "shippersReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Shipper`.\n", "example": "HHL007" }, "shippersPurchaseOrderReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Shipper Purchase Order`.\n", @@ -4278,7 +4576,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -4309,14 +4606,14 @@ } }, "consigneesReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Consignee`.\n", "example": "HHL007" }, "consigneesPurchaseOrderReference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Consignee Purchase Order`.\n", @@ -4344,7 +4641,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -4406,6 +4702,44 @@ }, "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": 100, + "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\nMust be a code this list [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/eblsolutionproviders-v3.0.0.csv).\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.\n" + }, "Party": { "title": "Party", "required": [ @@ -4444,7 +4778,7 @@ } }, "reference": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "A reference linked to the `Party`.\n", @@ -4566,7 +4900,7 @@ "example": "W3C" }, "partyCode": { - "maxLength": 100, + "maxLength": 150, "type": "string", "description": "Code to identify the party as provided by the code list provider\n", "example": "MSK" @@ -4604,7 +4938,7 @@ "example": "NL" }, "value": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the `taxLegalReference`\n", @@ -4628,7 +4962,8 @@ "example": "CR" }, "value": { - "maxLength": 100, + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the reference. \n", "example": "HHL00103004" @@ -4721,7 +5056,6 @@ "HSCodes", "cargoItems", "carrierBookingReference", - "commoditySubreference", "descriptionOfGoods" ], "type": "object", @@ -4815,7 +5149,7 @@ "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 Noemclature)\n- `CUS` (Customs Union and Statistics)\n", + "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": { @@ -4852,7 +5186,7 @@ "required": [ "countryCode", "type", - "value" + "values" ], "type": "object", "properties": { @@ -4871,12 +5205,16 @@ "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" }, - "value": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `customsReference`\n", - "example": "4988470982020120017" + "values": { + "minItems": 1, + "type": "array", + "items": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The value of the `customsReference`\n", + "example": "4988470982020120017" + } } }, "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA (small) list of examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n\nAllowed combinations of `type` and `country` are maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/customsreferences-v300.csv).\n" @@ -4935,6 +5273,13 @@ "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", @@ -4998,6 +5343,13 @@ "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" + } + }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", @@ -5450,7 +5802,7 @@ }, "shippingMarks": { "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", "items": { "maxLength": 500, "type": "string", @@ -5492,7 +5844,7 @@ "properties": { "shippingMarks": { "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", "items": { "maxLength": 500, "type": "string", @@ -5682,7 +6034,7 @@ }, "source": { "type": "string", - "description": "The source of the seal, namely who has affixed the seal. This attribute links to the Seal Source ID defined in the Seal Source reference data entity.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n", + "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", @@ -5926,28 +6278,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -6001,6 +6353,13 @@ "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", @@ -6069,7 +6428,7 @@ "declaredValue": { "minimum": 0, "type": "number", - "description": "The value of the cargo that the shipper declares 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", + "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 }, @@ -6559,6 +6918,54 @@ }, "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\nThis property is **conditional** on the `shippingInstructionsStatus='PENDING UPDATE'`.\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" @@ -6739,6 +7146,9 @@ "endorsee": { "$ref": "#/components/schemas/Endorsee" }, + "issueTo": { + "$ref": "#/components/schemas/IssueToParty" + }, "other": { "type": "array", "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", @@ -6840,28 +7250,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -7089,28 +7499,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -7405,28 +7815,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -7480,6 +7890,13 @@ "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", @@ -7548,7 +7965,7 @@ "declaredValue": { "minimum": 0, "type": "number", - "description": "The value of the cargo that the shipper declares 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", + "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 }, 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 e0a445a7..4e7e9492 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 @@ -45,7 +45,7 @@ "locationType": "UNLO", "UNLocationCode": "NLRTM" }, - "vesselVoyage": [ + "vesselVoyages": [ { "carrierExportVoyageNumber": "2433W", "vesselName": "COFFEE BEANS" 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 544ca621..851aa537 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 @@ -2,7 +2,7 @@ "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 non-repudiable transfer of eBL document 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:\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### Stats API\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to this API. Further details can be found [here](https://labs.dcsa.org/#/http/guides/api-guides/stats-api/introduction)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/pint/v3#v300B2).\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) standard

\n\n

The Envelope Transfer

\n\nThe PINT API is designed to support non-repudiable transfer of eBL document 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### Stats API\nThe Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to this API. Further details can be found [here](https://labs.dcsa.org/#/http/guides/api-guides/stats-api/introduction)\n\nFor a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/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", @@ -12,15 +12,19 @@ "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "3.0.0-Beta-3" + "version": "3.0.0" }, "servers": [ { - "url": "https://virtserver.swaggerhub.com/dcsaorg/DCSA_EBL_PINT/3.0.0-Beta-3", + "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" @@ -439,7 +443,7 @@ "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", + "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": { @@ -508,27 +512,60 @@ "type": "array", "description": "An array of errors providing more detail about the root cause.\n", "items": { - "$ref": "#/components/schemas/Detailed Error" + "$ref": "#/components/schemas/DetailedError" } } }, "description": "Unexpected error" }, - "ReceiverValidationResponse": { + "DetailedError": { + "title": "Detailed Error", "required": [ - "partyName" + "errorCodeMessage", + "errorCodeText" ], "type": "object", "properties": { - "partyName": { + "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, - "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "Name of the party.\n", - "example": "Globeteam" + "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": 200, + "type": "string", + "description": "A long description corresponding to the `errorCode` with additional information.\n", + "example": "Spaces not allowed in facility code" } }, - "description": "Response to a receiver validation response, where the party code could successfully identified.\n" + "description": "A detailed description of what has caused the error.\n" }, "EblEnvelope": { "required": [ @@ -553,6 +590,22 @@ } } }, + "ReceiverValidationResponse": { + "required": [ + "partyName" + ], + "type": "object", + "properties": { + "partyName": { + "maxLength": 100, + "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": { "required": [ "lastEnvelopeTransferChainEntrySignedContentChecksum", @@ -641,9 +694,9 @@ "properties": { "eblPlatform": { "maxLength": 4, - "pattern": "\\S+", + "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\nMust be a code this list [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/eblsolutionproviders-v3.0.0-Beta-3.csv).\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\nMust be a code this list [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/eblsolutionproviders-v3.0.0.csv).\n", "example": "BOLE" }, "transportDocumentChecksum": { @@ -662,18 +715,10 @@ "nullable": true, "example": "20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9" }, - "eBLVisualisationByCarrier": { - "description": "actual type: [`DocumentMetadata`](#\\DocumentMetadata)\n\nThis attribute is used to transfer metadata of the **'Digital copy of the original physical B/L document' document** a.k.a. **eBLVisualisationByCarrier document**. If this attribute is defined with the initial eBL envelope transfer(in the first `EnvelopeTransferChainEntrySignedContent` entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list), 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 (in other words, for each `EnvelopeTransferChainEntrySignedContent` entry in the [`EblEnvelope.envelopeTransferChain[]`](#/EblEnvelope) list, JWS-signed payload `EnvelopeTransferChainEntry.eBLVisualisationByCarrier` attribute must have the identical value).\n", - "allOf": [ - { - "$ref": "#/components/schemas/DocumentMetadata" - } - ] - }, - "IssuanceManifestSignedContent": { + "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).\n\nThe field is conditional and must be provided in the first EnvelopeTransferChainEntry. The value must be signed by the carrier.\n", + "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": { @@ -807,6 +852,7 @@ "type": "object", "properties": { "name": { + "pattern": "^\\S(?:.*\\S)?$", "type": "string", "example": "Carrier rendered copy of the original B/L document.pdf" }, @@ -840,6 +886,7 @@ "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 documment 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` resonse), 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 documment 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 notificaiton for the non-repudiation purposes.\n", + "example": "ISSU", "enum": [ "ISSU", "ENDO", @@ -870,6 +917,7 @@ }, "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." @@ -895,7 +943,7 @@ "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\nMust be a code this list [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/eblsolutionproviders-v3.0.0-Beta-3.csv).\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\nMust be a code this list [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reference-data/eblsolutionproviders-v3.0.0.csv).\n", "example": "BOLE" }, "identifyingCodes": { @@ -929,7 +977,7 @@ "example": "W3C" }, "partyCode": { - "maxLength": 100, + "maxLength": 150, "type": "string", "description": "Code to identify the party as provided by the code list provider\n", "example": "MSK" @@ -967,7 +1015,7 @@ "example": "DK" }, "value": { - "maxLength": 100, + "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the `taxLegalReference`\n", @@ -1058,28 +1106,28 @@ "numberOfCopiesWithCharges": { "minimum": 0, "type": "integer", - "description": "The requested number of copies of the Transport document to be issued by the carrier including charges. Only applicable for physical (paper) documents", + "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", + "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. Only applicable for physical documents.\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", "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. Only applicable for physical documents.\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", "format": "int32", "example": 1 }, @@ -1133,6 +1181,13 @@ "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", @@ -1201,7 +1256,7 @@ "declaredValue": { "minimum": 0, "type": "number", - "description": "The value of the cargo that the shipper declares 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", + "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 }, @@ -1261,45 +1316,7 @@ } }, "placeOfIssue": { - "title": "Place of Issue", - "type": "object", - "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" - } - } - } - ] + "$ref": "#/components/schemas/Place of Issue" }, "invoicePayableAt": { "title": "Invoice Payable At", @@ -1452,11 +1469,12 @@ "type": { "maxLength": 3, "type": "string", - "description": "The reference type codes defined by DCSA. Possible values are:\n- `FF` (Freight Forwarder’s Reference)\n- `SI` (Shipper’s Reference)\n- `SPO` (Shippers Purchase Order Reference)\n- `CPO` (Consignees Purchase Order Reference)\n- `CR` (Customer’s Reference)\n- `AAO` (Consignee’s Reference)\n- `ECR` (Empty container release reference)\n- `CSI` (Customer shipment ID)\n- `BPR` (Booking party reference number)\n- `BID` (Booking Request ID)\n- `SAC` (Shipping Agency Code)\n", - "example": "FF" + "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": 100, + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", "type": "string", "description": "The value of the reference. \n", "example": "HHL00103004" @@ -1501,6 +1519,13 @@ "example": "851713" } }, + "nationalCommodityCodes": { + "type": "array", + "description": "A list of `National Commodity Codes` that apply to this `commodity`\n", + "items": { + "$ref": "#/components/schemas/NationalCommodityCode" + } + }, "shippingMarks": { "type": "array", "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", @@ -1536,12 +1561,57 @@ }, "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", - "value" + "values" ], "type": "object", "properties": { @@ -1560,12 +1630,16 @@ "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", "example": "DK" }, - "value": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The value of the `customsReference`\n", - "example": "4988470982020120017" + "values": { + "minItems": 1, + "type": "array", + "items": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The value of the `customsReference`\n", + "example": "4988470982020120017" + } } }, "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA (small) list of examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n\nAllowed combinations of `type` and `country` are maintained in [GitHub](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/domain/documentation/reference-data/customsreferences-v300.csv).\n" @@ -1624,6 +1698,13 @@ "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", @@ -1671,6 +1752,12 @@ "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", @@ -2032,7 +2119,7 @@ }, "shippingMarks": { "type": "array", - "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n", + "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n", "items": { "maxLength": 500, "type": "string", @@ -2121,7 +2208,7 @@ }, "source": { "type": "string", - "description": "The source of the seal, namely who has affixed the seal. This attribute links to the Seal Source ID defined in the Seal Source reference data entity.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n", + "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", @@ -2227,7 +2314,7 @@ "plannedDepartureDate", "portOfDischarge", "portOfLoading", - "vesselVoyage" + "vesselVoyages" ], "type": "object", "properties": { @@ -2246,13 +2333,13 @@ "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", + "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", + "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": { @@ -2316,139 +2403,162 @@ "PlaceOfReceipt": { "title": "Place of Receipt", "type": "object", - "description": "General purpose 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 **one** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n", - "example": { - "locationName": "Hamburg", - "locationType": "UNLO", - "UNLocationCode": "DEHAM" - }, - "discriminator": { - "propertyName": "locationType", - "mapping": { - "ADDR": "#/components/schemas/AddressLocation", - "FACI": "#/components/schemas/FacilityLocation", - "UNLO": "#/components/schemas/UNLocationLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/AddressLocation" + "properties": { + "locationName": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The name of the location.", + "example": "Port of Amsterdam" }, - { - "$ref": "#/components/schemas/FacilityLocation" + "address": { + "$ref": "#/components/schemas/Address" }, - { - "$ref": "#/components/schemas/UNLocationLocation" + "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", + "example": { + "locationName": "Hamburg", + "UNLocationCode": "DEHAM" + } }, "PortOfLoading": { "title": "Port of Loading", "type": "object", - "description": "General purpose 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 **one** of the following ways: `UN Location Code` or `City and Country`.\n", + "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", "example": { "locationName": "Hamburg", - "locationType": "UNLO", "UNLocationCode": "DEHAM" - }, - "discriminator": { - "propertyName": "locationType", - "mapping": { - "CITY": "#/components/schemas/CityLocation", - "UNLO": "#/components/schemas/UNLocationLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/CityLocation" - }, - { - "$ref": "#/components/schemas/UNLocationLocation" - } - ] + } }, "PortOfDischarge": { "title": "Port of Discharge", "type": "object", - "description": "General purpose 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 **one** of the following ways: `UN Location Code` or `City and Country`.\n", + "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", "example": { "locationName": "Hamburg", - "locationType": "UNLO", "UNLocationCode": "DEHAM" - }, - "discriminator": { - "propertyName": "locationType", - "mapping": { - "CITY": "#/components/schemas/CityLocation", - "UNLO": "#/components/schemas/UNLocationLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/CityLocation" - }, - { - "$ref": "#/components/schemas/UNLocationLocation" - } - ] + } }, "PlaceOfDelivery": { "title": "Place of Delivery", "type": "object", - "description": "General purpose 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 **one** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n", - "example": { - "locationName": "Hamburg", - "locationType": "UNLO", - "UNLocationCode": "DEHAM" - }, - "discriminator": { - "propertyName": "locationType", - "mapping": { - "ADDR": "#/components/schemas/AddressLocation", - "FACI": "#/components/schemas/FacilityLocation", - "UNLO": "#/components/schemas/UNLocationLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/AddressLocation" + "properties": { + "locationName": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The name of the location.", + "example": "Port of Amsterdam" }, - { - "$ref": "#/components/schemas/FacilityLocation" + "address": { + "$ref": "#/components/schemas/Address" }, - { - "$ref": "#/components/schemas/UNLocationLocation" + "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", + "example": { + "locationName": "Hamburg", + "UNLocationCode": "DEHAM" + } }, "OnwardInlandRouting": { "title": "Onward Inland Routing", "type": "object", - "description": "General purpose 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 **one** of the following ways: `UN Location Code`, `Facility` or an `Address`.\n", - "example": { - "locationName": "Hamburg", - "locationType": "UNLO", - "UNLocationCode": "DEHAM" - }, - "discriminator": { - "propertyName": "locationType", - "mapping": { - "ADDR": "#/components/schemas/AddressLocation", - "FACI": "#/components/schemas/FacilityLocation", - "UNLO": "#/components/schemas/UNLocationLocation" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/AddressLocation" + "properties": { + "locationName": { + "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "The name of the location.", + "example": "Port of Amsterdam" }, - { - "$ref": "#/components/schemas/FacilityLocation" + "address": { + "$ref": "#/components/schemas/Address" }, - { - "$ref": "#/components/schemas/UNLocationLocation" + "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", + "example": { + "locationName": "Hamburg", + "UNLocationCode": "DEHAM" + } }, "Charge": { "title": "Charge", @@ -2518,40 +2628,12 @@ }, "description": "Addresses the monetary value of freight and other service charges for a `Booking`.\n" }, - "AddressLocation": { - "title": "Address Location", - "required": [ - "address", - "locationType" - ], - "type": "object", - "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, - "type": "string", - "description": "Discriminator used to identify this as an `Address` location interface.", - "example": "ADDR" - }, - "address": { - "$ref": "#/components/schemas/Address" - } - }, - "description": "An interface used to express a location using an `Address` object." - }, "Address": { "title": "Address", "required": [ "city", "countryCode", - "street", - "streetNumber" + "street" ], "type": "object", "properties": { @@ -2604,63 +2686,46 @@ }, "description": "An object for storing address related information\n" }, - "CityLocation": { - "title": "City Location", + "City": { + "title": "City", "required": [ "city", - "locationType" + "countryCode" ], "type": "object", "properties": { - "locationName": { - "maxLength": 100, + "city": { + "maxLength": 65, "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" + "description": "The city name of the party’s address.\n", + "example": "Amsterdam" }, - "locationType": { - "maxLength": 4, + "stateRegion": { + "maxLength": 65, "type": "string", - "description": "Discriminator used to identify this as a `City Location` interface\n", - "example": "CITY" + "description": "The state/region of the party’s address.\n", + "example": "North Holland" }, - "city": { - "$ref": "#/components/schemas/CityLocation_city" + "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 interface used to express a location using a `City`, `state/region` and `country`\n" + "description": "An object for storing city, state/region and country related information\n" }, - "FacilityLocation": { - "title": "Facility Location", + "Facility": { + "title": "Facility", "required": [ "facilityCode", - "facilityCodeListProvider", - "locationType" + "facilityCodeListProvider" ], "type": "object", "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, - "type": "string", - "description": "Discriminator used to identify this as a `Facility Location` interface\n", - "example": "FACI" - }, - "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\nThis field is **conditionally mandatory** depending on the value of the `facilityCodeListProvider` field.", - "example": "NLAMS" - }, "facilityCode": { "maxLength": 6, "pattern": "^\\S(?:.*\\S)?$", @@ -2678,40 +2743,30 @@ ] } }, - "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" + "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" }, - "UNLocationLocation": { - "title": "UNLocation Location", + "GeoCoordinate": { + "title": "Geo Coordinate", "required": [ - "UNLocationCode", - "locationType" + "latitude", + "longitude" ], "type": "object", "properties": { - "locationName": { - "maxLength": 100, - "pattern": "^\\S(?:.*\\S)?$", - "type": "string", - "description": "The name of the location.", - "example": "Port of Amsterdam" - }, - "locationType": { - "maxLength": 4, + "latitude": { + "maxLength": 10, "type": "string", - "description": "Discriminator used to identify this as a `UNLocation` location interface.", - "example": "UNLO" + "description": "Geographic coordinate that specifies the north–south position of a point on the Earth's surface.", + "example": "48.8585500" }, - "UNLocationCode": { - "maxLength": 5, - "minLength": 5, - "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", + "longitude": { + "maxLength": 11, "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": "Geographic coordinate that specifies the east–west position of a point on the Earth's surface.", + "example": "2.294492036" } }, - "additionalProperties": false, - "description": "An interface used to express a location using a `Un Location Code`." + "description": "An object used to express a location using `latitude` and `longitude`.\n" }, "OtherDocumentParty": { "title": "Other Document Party", @@ -2738,8 +2793,7 @@ "required": [ "city", "countryCode", - "street", - "streetNumber" + "street" ], "type": "object", "properties": { @@ -2819,7 +2873,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -2848,6 +2901,20 @@ "items": { "$ref": "#/components/schemas/PartyContactDetail" } + }, + "shippersReference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference linked to the `Shipper`.\n", + "example": "HHL007" + }, + "shippersPurchaseOrderReference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference linked to the `Shipper Purchase Order`.\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" @@ -2871,7 +2938,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -2900,6 +2966,20 @@ "items": { "$ref": "#/components/schemas/PartyContactDetail" } + }, + "consigneesReference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference linked to the `Consignee`.\n", + "example": "HHL007" + }, + "consigneesPurchaseOrderReference": { + "maxLength": 35, + "pattern": "^\\S(?:.*\\S)?$", + "type": "string", + "description": "A reference linked to the `Consignee Purchase Order`.\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" @@ -2923,7 +3003,6 @@ }, "displayedAddress": { "maxItems": 999, - "minItems": 1, "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`. For physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters. No limit for electronic BL (`isElectronic=true`).\n\n**Condition:** if provided, the displayed address must be included in the Transport Document.\n", "items": { @@ -3021,6 +3100,13 @@ "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" @@ -3066,53 +3152,55 @@ }, "description": "Refers to a company or a legal entity.\n" }, - "Detailed Error": { - "title": "Detailed Error", - "required": [ - "errorCodeMessage", - "errorCodeText" - ], + "Place of Issue": { + "title": "Place of Issue", "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": { + "locationName": { "maxLength": 100, + "pattern": "^\\S(?:.*\\S)?$", "type": "string", - "description": "A standard short description corresponding to the `errorCode`.\n", - "example": "invalidData" + "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" + } + } }, - "errorCodeMessage": { - "maxLength": 200, - "type": "string", - "description": "A long description corresponding to the `errorCode` with additional information.\n", - "example": "Spaces not allowed in facility code" + { + "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" + } + } } - } + ] }, "Document Parties": { "title": "Document Parties", @@ -3257,37 +3345,6 @@ } }, "description": "The volume of the referenced dangerous goods.\n\n**Condition:** only applicable to liquids and gas.\n" - }, - "CityLocation_city": { - "required": [ - "city", - "countryCode" - ], - "type": "object", - "properties": { - "city": { - "maxLength": 65, - "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 coutry related information\n" } }, "parameters": { @@ -3339,7 +3396,7 @@ "explode": false, "schema": { "type": "string", - "example": "3.0.0-Beta-3" + "example": "3.0.0" } } }