EBL 3.0: SD-1936: Update examples

ebl/v3/issuance/EBL_ISS_v3.0.3.yaml

@@ -62,6 +62,130 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/IssuanceRequest'
+            examples:
+              regularSTDExample:
+                summary: |
+                  Issuing a Transport Document with regular Dry cargo
+                description: |
+                  A **Transport Document** being issued.
+
+                  **Note:** The `content` in the `eBLVisualisationByCarrier` and `issuanceManifestSignedContent` are not "real" values but rather random strings (this example cannot be used as is).
+                value:
+                  document:
+                    transportDocumentReference: 62CD536BA8D34C469AFD
+                    shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9
+                    transportDocumentStatus: DRAFT
+                    transportDocumentTypeCode: BOL
+                    isShippedOnBoardType: true
+                    freightPaymentTermCode: PRE
+                    isElectronic: true
+                    isToOrder: true
+                    shippedOnBoardDate: '2023-12-20'
+                    termsAndConditions: |
+                      You agree that this transport document exist is name only for the sake of
+                      testing your conformance with the DCSA eBL API. This transport document is NOT backed
+                      by a real shipment with ANY carrier and NONE of the requested services will be
+                      carried out in real life.
+
+                      Unless required by applicable law or agreed to in writing, DCSA provides
+                      this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+                      ANY KIND, either express or implied, including, without limitation, any
+                      warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
+                      or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+                      determining the appropriateness of using or redistributing this JSON
+                      data and assume any risks associated with Your usage of this data.
+
+                      In no event and under no legal theory, whether in tort (including negligence),
+                      contract, or otherwise, unless required by applicable law (such as deliberate
+                      and grossly negligent acts) or agreed to in writing, shall DCSA be liable to
+                      You for damages, including any direct, indirect, special, incidental, or
+                      consequential damages of any character arising as a result of this terms or conditions
+                      or out of the use or inability to use the provided JSON data (including but not limited
+                      to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any
+                      and all other commercial damages or losses), even if DCSA has been advised of the
+                      possibility of such damages.
+                    receiptTypeAtOrigin: CY
+                    deliveryTypeAtDestination: CY
+                    cargoMovementTypeAtOrigin: FCL
+                    cargoMovementTypeAtDestination: FCL
+                    serviceContractReference: SCR-1234-REGULAR
+                    carrierCode: MSC
+                    carrierCodeListProvider: SMDG
+                    transports:
+                      plannedDepartureDate: '2023-12-20'
+                      plannedArrivalDate: '2023-12-22'
+                      portOfLoading:
+                        UNLocationCode: DKAAR
+                      portOfDischarge:
+                        UNLocationCode: DEBRV
+                      vesselVoyages:
+                        - vesselName: MSC Gülsün
+                          carrierExportVoyageNumber: 402E
+                    charges:
+                      - chargeName: Fictive transport document fee
+                        currencyAmount: 1
+                        currencyCode: EUR
+                        paymentTermCode: COL
+                        calculationBasis: Per transport document
+                        unitPrice: 1
+                        quantity: 1
+                    invoicePayableAt:
+                      UNLocationCode: DKAAR
+                    partyContactDetails:
+                      - name: DCSA test person
+                        email: no-reply@dcsa.example.org
+                    documentParties:
+                      shipper:
+                        partyName: DCSA CTK
+                        displayedAddress:
+                          - Strawinskylaan 4117
+                        partyContactDetails:
+                          - name: DCSA test person
+                            email: no-reply@dcsa.example.org
+                      issuingParty:
+                        partyName: Mediterranean Shipping Company
+                        address:
+                          street: Chemin Rieu
+                          streetNumber: 12-14
+                          city: Geneva
+                          countryCode: CH
+                        identifyingCodes:
+                          - codeListProvider: GLEIF
+                            codeListName: LEI
+                            partyCode: 529900T8BM49AURSDO55
+                    consignmentItems:
+                      - carrierBookingReference: CBR_123_REGULAR
+                        descriptionOfGoods:
+                          - 'Shoes - black'
+                        HSCodes:
+                          - '640510'
+                        cargoItems:
+                          - equipmentReference: NARU3472484
+                            cargoGrossWeight:
+                              value: 12000
+                              unit: KGM
+                            outerPackaging:
+                              numberOfPackages: 400
+                              packageCode: 4G
+                              description: Fibreboard boxes
+                    utilizedTransportEquipments:
+                      - isShipperOwned: false
+                        seals:
+                          - number: DCSA-CTK-1234
+                        equipment:
+                          ISOEquipmentCode: 22G1
+                          equipmentReference: NARU3472484
+                  issueTo:
+                    partyName: HHL Invest
+                    sendToPlatform: BOLE
+                    identifyingCodes:
+                      - codeListProvider: BOLE
+                        partyCode: BOLE001
+                  eBLVisualisationByCarrier:
+                    name: Carrier rendered copy of the EBL.pdf
+                    content: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAGaSURBVDhPnZO/S0JRFMe/zygxwgqcfZtz0N7SFNgPaKlJpTFLCqwotV9qRYN/gIOL1FK22NISWENT0BTUkNLgIL2iHxYRnc697/kKzdA+cOD8uOec77uXB/oHngMPnd2eSb/pAf5DP2EWhGlQ8ChIikiiQa7vruFacwHdHHwC9nY7mhqgRBTdsbDdA/nVvHQbYnxvHHhnp4XtFZjon4DapTam4Lx4jt7NXlO6WEsreltDA5RFlt4qHDaWXlgrwNnplDX5CcWnIo5vjmWimsGdQV7HjjjJ0gMDAbNZopU1wgwfmQSlL9JCkEkunyMEuLbMFgZZ161G5RsFES5WNrC8lC8Fb49XDlcWWLNVOHqttFGCo90haxUsyeEk8GhEfEm+lA/ZqyyGdof0ocJegMhIpKZZIC8xfhLH0v6SfstCzRubeK42tg9Od3RDm9c4qMV8hWguinAmDHTJvC5bVB6A8nYZtlabTFcjX0EQ6gshNhqTDSbPQGIsUbdZIhT8ZOt0izDFu+dAakI1svX59W/MXGbIveM2or8g+gL+Fn3DwcYf+gAAAABJRU5ErkJggg==
+                    contentType: application/pdf
+                  issuanceManifestSignedContent: eyJhbGciOiJSUzI1NiIsImtpZCI6IlVhRVdLNmt2ZkRITzNZT2NwUGl2M1RCT2JQTzk2SFZhR2U0czFhUUxBZU0ifQ.eyJkb2N1bWVudENoZWNrc3VtIjogIjhkYzk5ZDhhYzkyMjI0MGM1NWMwMzg0NWY0OWRlZjY0MTg3MTQ2NjUxYmFlNGY5YTYzMTMxMjc3Y2YwMGQ5ZGYiLCJlQkxWaXN1YWxpc2F0aW9uQnlDYXJyaWVyQ2hlY2tzdW0iOiAiNzZhN2QxNGM4M2Q3MjY4ZDY0M2FlNzM0NWM0NDhkZTYwNzAxZjk1NWQyNjRhNzQzZTY5MjhhMGI4MjY4YjI0ZiIsImlzc3VlVG9DaGVja3N1bSI6ICI3NmE3ZDE0YzgzZDcyNjhkNjQzYWU3MzQ1YzQ0OGRlNjA3MDFmOTU1ZDI2NGE3NDNlNjkyOGEwYjgyNjhiMjRmIn0.c4SJ9-61fE6RmeIuZ3EI-TSM0M6qXuOudtr3YhpDjqVMaYk_RYpaWYvw75ssTbjgGFKTBKCy5lpmOfb8Fq--Qu2k0MWbH6qdX5jTYwl0DX946RQg-hnmVTg9np3bmqVeKqKURyV-UUdG-KK_XCGzPZ-lZkeUlpMcIthQFs0pCODR9GPytv7ZXLPZFOmHM9fn3FD2yRqVhQzcs7HdcxMjCx6hkBW8Z-jW4qteVy2_E9uqjkKwlu_cQLoY83Z0mcjn0PZNQvKF10x7q1_Jjf_Su19UigTUu3pFMrzo4iPS_jcrFoIb3TSZNSzbgAwtujSBFOufPDyEmxlx1sH0ZowMvA
       responses:
         '204':
           description: |
@@ -112,6 +236,26 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                errorExample:
+                  summary: |
+                    Internal Error
+                  description: |
+                    An Internal error occurred.
+
+                    **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".
+                  value:
+                    httpMethod: PUT
+                    requestUri: /v3/ebl-issuance-requests
+                    statusCode: 500
+                    statusCodeText: Internal Error
+                    statusCodeMessage: Internal Error
+                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
+                    errorDateTime: '2025-11-26T09:41:00Z'
+                    errors:
+                      - errorCode: 7003
+                        errorCodeText: Internal Error
+                        errorCodeMessage: Internal Error
   /v3/ebl-issuance-responses:
     post:
       tags:
@@ -139,6 +283,18 @@ paths:
                 value:
                   transportDocumentReference: HHL7180000000
                   issuanceResponseCode: ISSU
+              rejectedExample:
+                summary: |
+                  Rejected response
+                description: |
+                  The document was rejected as `BOLE001` is an unknown party on the receiving platform
+                value:
+                  transportDocumentReference: HHL7180000000
+                  issuanceResponseCode: REFU
+                  reason: 'IssueTo party not recognized by receiving platform'
+                  errors:
+                    - reason: '"HHL Invest" with partyCode BOLE001 is unknown'
+                      errorCode: PAR12345
       responses:
         '204':
           description: Carrier's acknowledgement of the Issuance Response
@@ -154,7 +310,26 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                errorExample:
+                  summary: |
+                    Internal Error
+                  description: |
+                    An Internal error occurred.
 
+                    **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".
+                  value:
+                    httpMethod: POST
+                    requestUri: /v3/ebl-issuance-responses
+                    statusCode: 500
+                    statusCodeText: Internal Error
+                    statusCodeMessage: Internal Error
+                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
+                    errorDateTime: '2025-11-26T09:41:00Z'
+                    errors:
+                      - errorCode: 7003
+                        errorCodeText: Internal Error
+                        errorCodeMessage: Internal Error
 components:
   headers:
     API-Version:

ebl/v3/surrender/EBL_SUR_v3.0.3.yaml

@@ -68,6 +68,43 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/SurrenderRequestDetails'
+            examples:
+              surrenderExample:
+                summary: |
+                  Surrender for Delivery request
+                description: |
+                  Request to surrender a Transport Document for delivery
+                value:
+                  surrenderRequestReference: Z12345
+                  transportDocumentReference: HHL71800000
+                  transportDocumentSubReference: Version_1
+                  surrenderRequestCode: SREQ
+                  endorsementChain:
+                    - actionDateTime: 2024-09-04T09:41:00Z
+                      actionCode: ISSUE
+                      actor:
+                        eblPlatform: BOLE
+                        partyName: Globeteam
+                        identifyingCodes:
+                          - codeListProvider: BOLE
+                            partyCode: BOLE007
+                        representedParty:
+                          partyName: DHL
+                          identifyingCodes:
+                            - codeListProvider: BOLE
+                              partyCode: B987
+                      recipient:
+                        eblPlatform: BOLE
+                        partyName: DCSA
+                        identifyingCodes:
+                          - codeListProvider: BOLE
+                            partyCode: DCSA123
+                        representedParty:
+                          partyName: DHL
+                          identifyingCodes:
+                            - codeListProvider: BOLE
+                              partyCode: B987
+                      auditReference: AUDIT0007
       responses:
         '204':
           description: |
@@ -86,6 +123,26 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                errorExample:
+                  summary: |
+                    Internal Error
+                  description: |
+                    An Internal error occurred.
+
+                    **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".
+                  value:
+                    httpMethod: POST
+                    requestUri: /v3/ebl-surrender-requests
+                    statusCode: 500
+                    statusCodeText: Internal Error
+                    statusCodeMessage: Internal Error
+                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
+                    errorDateTime: '2025-11-26T09:41:00Z'
+                    errors:
+                      - errorCode: 7003
+                        errorCodeText: Internal Error
+                        errorCodeMessage: Internal Error
   /v3/ebl-surrender-responses:
     post:
       tags:
@@ -117,6 +174,26 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                errorExample:
+                  summary: |
+                    Internal Error
+                  description: |
+                    An Internal error occurred.
+
+                    **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".
+                  value:
+                    httpMethod: POST
+                    requestUri: /v3/ebl-surrender-responses
+                    statusCode: 500
+                    statusCodeText: Internal Error
+                    statusCodeMessage: Internal Error
+                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
+                    errorDateTime: '2025-11-26T09:41:00Z'
+                    errors:
+                      - errorCode: 7003
+                        errorCodeText: Internal Error
+                        errorCodeMessage: Internal Error
         default:
           description: Error
           headers: