diff --git a/bkg/v2/BKG_v2.0.5.yaml b/bkg/v2/BKG_v2.0.5.yaml index 309f0bf8..af43b447 100644 --- a/bkg/v2/BKG_v2.0.5.yaml +++ b/bkg/v2/BKG_v2.0.5.yaml @@ -5,7 +5,7 @@ info: description: |

DCSA OpenAPI specification for the Booking process

- This API is intended as an API between a carrier and anyone creating a `Booking`. The process includes: + This API is intended as an API between a provider and anyone creating a `Booking`. The process includes: - Booking request - Booking update @@ -1503,7 +1503,7 @@ paths: Cancels the Booking or cancels an Amendment operationId: cancel-booking description: | - A shipper initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. + A consumer initiated cancellation of the `Booking` or `Booking Amendment` with the `bookingReference`. The path can contain a `carrierBookingRequestReference` or a `carrierBookingReference`. This endPoint corresponds with **UseCase 11 - Cancel Booking request by shipper**, **UseCase 9 - Cancel amendment to confirmed Booking** or **UseCase 13 - Cancel confirmed Booking by shipper**. @@ -2469,7 +2469,7 @@ components: - `PENDING_AMENDMENT` (An amendment is required to the Booking) - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) - - `CANCELLED` (Booking discontinued by consumer) + - `CANCELLED` (Booking discontinued by shipper) - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) example: RECEIVED amendedBookingStatus: @@ -2480,8 +2480,8 @@ components: - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) - `AMENDMENT_CONFIRMED` (Amendment is confirmed) - - `AMENDMENT_DECLINED` (Amendment discontinued by provider) - - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + - `AMENDMENT_DECLINED` (Amendment discontinued by carrier) + - `AMENDMENT_CANCELLED` (Amendment discontinued by shipper) example: AMENDMENT_RECEIVED bookingCancellationStatus: type: string @@ -2489,8 +2489,8 @@ components: description: | The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) - - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) - - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by carrier) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by carrier) example: CANCELLATION_RECEIVED carrierBookingRequestReference: type: string @@ -3148,20 +3148,20 @@ components: transportDocumentReferences: type: array description: | - An array of `transportDocumentReference` requested by the Shipper to be associated to this Booking. + An array of `transportDocumentReference` requested by the shipper to be associated to this Booking. items: type: string pattern: ^\S(?:.*\S)?$ maxLength: 20 description: | - The `transportDocumentReference` requested by the Shipper to be associated to this Booking. + The `transportDocumentReference` requested by the shipper to be associated to this Booking. example: reserved-HHL123 requestedNumberOfTransportDocuments: type: integer format: int32 minimum: 1 description: | - The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + The number of `Transport Documents` requested to be linked to this Booking by the shipper. example: 3 bookingChannelReference: type: string @@ -3550,20 +3550,20 @@ components: transportDocumentReferences: type: array description: | - An array of `transportDocumentReference` requested by the Shipper to be associated to this Booking. + An array of `transportDocumentReference` requested by the shipper to be associated to this Booking. items: type: string pattern: ^\S(?:.*\S)?$ maxLength: 20 description: | - The `transportDocumentReference` requested by the Shipper to be associated to this Booking. + The `transportDocumentReference` requested by the shipper to be associated to this Booking. example: reserved-HHL123 requestedNumberOfTransportDocuments: type: integer format: int32 minimum: 1 description: | - The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + The number of `Transport Documents` requested to be linked to this Booking by the shipper. example: 3 bookingChannelReference: type: string @@ -3728,7 +3728,7 @@ components: - `PENDING_AMENDMENT` (An amendment is required to the Booking) - `REJECTED` (Booking discontinued by carrier before it has been Confirmed) - `DECLINED` (Booking discontinued by carrier after it has been Confirmed) - - `CANCELLED` (Booking discontinued by consumer) + - `CANCELLED` (Booking discontinued by shipper) - `COMPLETED` (The Transport Document this Booking is connected to has been Surrendered for Delivery) example: RECEIVED amendedBookingStatus: @@ -3738,8 +3738,8 @@ components: The status of latest amendment added to the `Booking`. If no amendment has been requested - then this field is empty. Possible values are: - `AMENDMENT_RECEIVED` (An amendment has been received and is awaiting to be processed) - `AMENDMENT_CONFIRMED` (Amendment is confirmed) - - `AMENDMENT_DECLINED` (Amendment discontinued by provider) - - `AMENDMENT_CANCELLED` (Amendment discontinued by consumer) + - `AMENDMENT_DECLINED` (Amendment discontinued by carrier) + - `AMENDMENT_CANCELLED` (Amendment discontinued by shipper) example: AMENDMENT_RECEIVED bookingCancellationStatus: type: string @@ -3747,8 +3747,8 @@ components: description: | The status of the latest booking cancellation. If no cancellation has been requested - then this property is empty. Possible values are: - `CANCELLATION_RECEIVED` (A request to cancel a Confirmed Booking has been received and is awaiting to be processed) - - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by provider) - - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by provider) + - `CANCELLATION_DECLINED` (Cancellation of the Confirmed Booking has been declined by carrier) + - `CANCELLATION_CONFIRMED` (Cancellation of the Confirmed Booking has been confirmed by carrier) example: CANCELLATION_RECEIVED receiptTypeAtOrigin: type: string @@ -4034,7 +4034,7 @@ components: format: int32 minimum: 1 description: | - The number of `Transport Documents` requested to be linked to this Booking by the Shipper. + The number of `Transport Documents` requested to be linked to this Booking by the shipper. example: 3 bookingChannelReference: type: string @@ -5054,7 +5054,7 @@ components: type: string maxLength: 150 description: | - Code to identify the party as provided by the code list provider + Code to identify the party as provided by the `codeListProvider`. example: MSK codeListName: type: string diff --git a/ebl/v3/EBL_v3.0.4.yaml b/ebl/v3/EBL_v3.0.4.yaml index d5eefbb5..fbbd4473 100644 --- a/ebl/v3/EBL_v3.0.4.yaml +++ b/ebl/v3/EBL_v3.0.4.yaml @@ -5,7 +5,7 @@ info: description: |

DCSA OpenAPI specification for the Shipping Instructions and Transport Document process

- This API is intended as an API between a carrier and anyone creating a `Shipping Instructions` and approving a `Transport Document`. The process includes: + This API is intended as an API between a provider and anyone creating a `Shipping Instructions` and approving a `Transport Document`. The process includes: - Shipping Instructions submission - Shipping Instructions update @@ -85,7 +85,7 @@ paths: Creates a new `Shipping Instructions`. This endPoint corresponds with **UseCase 1 - Submit Shipping Instructions**. ## Precondition - The consumer has information for a `Shipping Instructions`. The empty equipment has been released to the shipper. The `Booking` is in state `CONFIRMED`. + The consumer has information for a `Shipping Instructions`. The empty equipment has been released to the consumer. The `Booking` is in state `CONFIRMED`. ## Postcondition The provider has received the `Shipping Instructions`. @@ -953,7 +953,7 @@ paths: - $ref: '#/components/parameters/documentReference' - $ref: '#/components/parameters/Api-Version-Major' description: | - A shipper initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`. + A consumer initiated cancellation of the `Shipping Instructions` or `Updated Shipping Instructions` identified by the `documentReference` path parameter. The value of `documentReference` may be either a `shippingInstructionsReference` or a `transportDocumentReference`. This endPoint corresponds with **UseCase 5 - Cancel update to Shipping Instructions** or **UseCase 15 - Cancel Shipping Instructions**. @@ -2738,7 +2738,7 @@ paths: example: HHL71800000 - $ref: '#/components/parameters/Api-Version-Major' description: | - A shipper initiated cancellation of the `Direct Transport Document` amendment identified by the `transportDocumentReference` path parameter. + A consumer initiated cancellation of the `Direct Transport Document` amendment identified by the `transportDocumentReference` path parameter. This endPoint corresponds with **UseCase 18 - Cancel Transport Document amendment**. @@ -3928,8 +3928,8 @@ components: - `RECEIVED` (Shipping Instructions have been received) - `PENDING_UPDATE` (An update is required to the Shipping Instructions) - `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery) - - `CANCELLED` (The Shipping Instructions have been cancelled by Shipper) - - `DECLINED` (The Shipping Instructions have been declined by Carrier) + - `CANCELLED` (The Shipping Instructions have been cancelled by shipper) + - `DECLINED` (The Shipping Instructions have been declined by carrier) **Condition:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use `CANCELLED` or `DECLINED` values. Recipients implementing earlier versions **MAY ignore these values or treat the request as invalid**. example: RECEIVED @@ -3940,8 +3940,8 @@ components: The status of the latest update to the `Shipping Instructions`. If no update has been requested - then this property is empty. Possible values are: - `UPDATE_RECEIVED` (An update to a Shipping Instructions has been received and is awaiting to be processed) - `UPDATE_CONFIRMED` (An update to a Shipping Instructions has been confirmed) - - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer) - - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider) + - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by shipper) + - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by carrier) example: UPDATE_RECEIVED shippingInstructionsReference: type: string @@ -4110,8 +4110,8 @@ components: The status of the `Transport Document`. Possible values are: - `DRAFT` (The Transport Document is currently a Draft) - - `APPROVED` (The Transport Document has been Approved by consumer) - - `ISSUED` (The Transport Document has been Issued by provider) + - `APPROVED` (The Transport Document has been Approved by shipper) + - `ISSUED` (The Transport Document has been Issued by carrier) - `PENDING_SURRENDER_FOR_AMENDMENT` (The Transport Document has a pending Surrender for Amendment) - `SURRENDER_FOR_AMENDMENT` (The Transport Document is Surrendered for Amendment) - `VOID` (The Transport Document has been Voided) @@ -4125,8 +4125,8 @@ components: The status of the latest amendment to the `Transport Document`. If no amendments has been requested - then this field is empty. Possible values are: - `AMENDMENT_RECEIVED` (An amendment to a Transport Document is waiting to be processed) - `AMENDMENT_CONFIRMED` (An amendment to a Transport Document has been confirmed) - - `AMENDMENT_CANCELLED` (An amendment to a Transport Document is discontinued by consumer) - - `AMENDMENT_DECLINED` (An amendment to a Transport Document is discontinued by provider) + - `AMENDMENT_CANCELLED` (An amendment to a Transport Document is discontinued by shipper) + - `AMENDMENT_DECLINED` (An amendment to a Transport Document is discontinued by carrier) **👉Important note:** When communicating with providers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use this property as it will most likely be ignored. Recipients implementing earlier versions **MAY ignore** this property. example: AMENDMENT_RECEIVED @@ -4209,7 +4209,7 @@ components: CreateShippingInstructions: type: object description: | - The `Shipping Instructions` is an enrichment to the original booking shared by the Shipper to the Carrier. The information given by the Shipper through the `Shipping Instructions` is the information required to create a `Draft Transport Document`. + The `Shipping Instructions` is an enrichment to the original booking shared by the shipper to the carrier. The information given by the shipper through the `Shipping Instructions` is the information required to create a `Draft Transport Document`. title: Create Shipping Instructions properties: shippingInstructionsRevisionNumber: @@ -4439,7 +4439,7 @@ components: advanceManifestFilings: type: array description: | - A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + A list of `Advance Manifest Filings` specified by the shipper to indicate whom is to do the Filing items: $ref: '#/components/schemas/AdvanceManifestFiling' isHouseBillOfLadingsIssued: @@ -4452,13 +4452,13 @@ components: houseBillOfLadings: type: array description: | - A list of `House Bill of Ladings` specified by the Shipper. + A list of `House Bill of Ladings` specified by the shipper. items: $ref: '#/components/schemas/HouseBillOfLading' requestedCarrierCertificates: type: array description: | - Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + Certificate(s) requested by the shipper for the carrier to include as part of the shipment documentation pack items: type: string maxLength: 100 @@ -4493,7 +4493,7 @@ components: requestedCarrierClauses: type: array description: | - Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + Clauses requested by the shipper for the carrier to include in the `Transport Document` `Carrier clauses` items: type: string maxLength: 100 @@ -4760,7 +4760,7 @@ components: advanceManifestFilings: type: array description: | - A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + A list of `Advance Manifest Filings` specified by the shipper to indicate whom is to do the Filing items: $ref: '#/components/schemas/AdvanceManifestFiling' isHouseBillOfLadingsIssued: @@ -4773,13 +4773,13 @@ components: houseBillOfLadings: type: array description: | - A list of `House Bill of Ladings` specified by the Shipper. + A list of `House Bill of Ladings` specified by the shipper. items: $ref: '#/components/schemas/HouseBillOfLading' requestedCarrierCertificates: type: array description: | - Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + Certificate(s) requested by the shipper for the carrier to include as part of the shipment documentation pack items: type: string maxLength: 100 @@ -4814,7 +4814,7 @@ components: requestedCarrierClauses: type: array description: | - Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + Clauses requested by the shipper for the carrier to include in the `Transport Document` `Carrier clauses` items: type: string maxLength: 100 @@ -4844,7 +4844,7 @@ components: ShippingInstructions: description: | - The `Shipping Instructions` as provided by the Shipper. + The `Shipping Instructions` as provided by the shipper. type: object title: Shipping Instructions properties: @@ -4875,8 +4875,8 @@ components: - `RECEIVED` (Shipping Instructions have been received) - `PENDING_UPDATE` (An update is required to the Shipping Instructions) - `COMPLETED` (The Shipping Instructions can no longer be modified - the related Transport Document has been surrendered for delivery) - - `CANCELLED` (The Shipping Instructions have been cancelled by Shipper) - - `DECLINED` (The Shipping Instructions have been declined by Carrier) + - `CANCELLED` (The Shipping Instructions have been cancelled by shipper) + - `DECLINED` (The Shipping Instructions have been declined by carrier) **Condition:** When communicating with providers **or** consumers implementing API **v3.0.2 or earlier**, a sender implementing API **v3.0.3 or later MUST NOT** use `CANCELLED` or `DECLINED` values. Recipients implementing earlier versions **MAY ignore these values or treat the request as invalid**. example: RECEIVED @@ -4887,8 +4887,8 @@ components: The status of the latest update to the `Shipping Instructions`. If no update has been requested - then this property is empty. Possible values are: - `UPDATE_RECEIVED` (An update to a Shipping Instructions has been received and is awaiting to be processed) - `UPDATE_CONFIRMED` (An update to a Shipping Instructions has been confirmed) - - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by consumer) - - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by provider) + - `UPDATE_CANCELLED` (An update to a Shipping Instructions is discontinued by shipper) + - `UPDATE_DECLINED` (An update to a Shipping Instructions is discontinued by carrier) example: UPDATE_RECEIVED transportDocumentTypeCode: type: string @@ -5105,7 +5105,7 @@ components: advanceManifestFilings: type: array description: | - A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing + A list of `Advance Manifest Filings` specified by the shipper to indicate whom is to do the Filing items: $ref: '#/components/schemas/AdvanceManifestFiling' isHouseBillOfLadingsIssued: @@ -5117,13 +5117,13 @@ components: houseBillOfLadings: type: array description: | - A list of `House Bill of Ladings` specified by the Shipper. + A list of `House Bill of Ladings` specified by the shipper. items: $ref: '#/components/schemas/HouseBillOfLading' requestedCarrierCertificates: type: array description: | - Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack + Certificate(s) requested by the shipper for the carrier to include as part of the shipment documentation pack items: type: string maxLength: 100 @@ -5158,7 +5158,7 @@ components: requestedCarrierClauses: type: array description: | - Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses` + Clauses requested by the shipper for the carrier to include in the `Transport Document` `Carrier clauses` items: type: string maxLength: 100 @@ -7650,7 +7650,7 @@ components: type: string maxLength: 150 description: | - Code to identify the party as provided by the code list provider + Code to identify the party as provided by the `codeListProvider`. example: MSK codeListName: type: string @@ -9671,7 +9671,7 @@ components: type: object title: House Bill of Lading description: | - A legal contract between the Ocean Transport Intermediary (OTI), such as a Non-Vessel Operating Common Carrier (NVOCC) or a freight forwarder, and the shipper that acknowledges the receipt of goods and outlines the terms of shipment. + A legal contract between the Ocean Transport Intermediary (OTI), such as a Non-Vessel Operating Common carrier (NVOCC) or a freight forwarder, and the shipper that acknowledges the receipt of goods and outlines the terms of shipment. properties: houseBillOfLadingReference: type: string @@ -9884,8 +9884,8 @@ components: description: | The status of the `Transport Document`. Possible values are: - `DRAFT` (the Transport Document is currently a Draft) - - `APPROVED` (the Transport Document has been Approved by consumer) - - `ISSUED` (the Transport Document has been Issued by provider) + - `APPROVED` (the Transport Document has been Approved by shipper) + - `ISSUED` (the Transport Document has been Issued by carrier) - `PENDING_SURRENDER_FOR_AMENDMENT` (the Transport Document has a pending Surrender for Amendment) - `SURRENDERED_FOR_AMENDMENT` (the Transport Document is Surrendered for Amendment) - `PENDING_SURRENDER_FOR_DELIVERY` (the Transport Document has a pending Surrender for Delivery) @@ -10046,7 +10046,7 @@ components: maxLength: 250 description: | The text to be displayed on the `Transport Document` as evidence that the goods have been received for shipment or shipped on board. - example: 'Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the Carrier' + example: 'Received for Shipment CMA CGM CONCORDE 28-Jul-2022 CMA CGM Agences France SAS As agents for the carrier' termsAndConditions: type: string maxLength: 50000 @@ -10291,8 +10291,8 @@ components: The status of the latest amendment to the `Transport Document`. If no amendments has been requested - then this field is empty. Possible values are: - `AMENDMENT_RECEIVED` (An amendment to a Transport Document is waiting to be processed) - `AMENDMENT_CONFIRMED` (An amendment to a Transport Document has been confirmed) - - `AMENDMENT_CANCELLED` (An amendment to a Transport Document is discontinued by consumer) - - `AMENDMENT_DECLINED` (An amendment to a Transport Document is discontinued by provider) + - `AMENDMENT_CANCELLED` (An amendment to a Transport Document is discontinued by shipper) + - `AMENDMENT_DECLINED` (An amendment to a Transport Document is discontinued by carrier) example: AMENDMENT_RECEIVED amendedTransportDocument: $ref: '#/components/schemas/TransportDocument' diff --git a/ebl/v3/endorsement/EBL_END_v3.0.4.yaml b/ebl/v3/endorsement/EBL_END_v3.0.4.yaml new file mode 100644 index 00000000..d3cfef73 --- /dev/null +++ b/ebl/v3/endorsement/EBL_END_v3.0.4.yaml @@ -0,0 +1,893 @@ +openapi: 3.0.3 +info: + version: 3.0.4 + title: DCSA eBL Endorsement Chain API + description: | +

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

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