Evergreen Marine Corp. Surrender Requests API

openapi: 3.2.0
info:
  title: Evergreen Marine Surrender Requests API
  version: 3.0.0
  description: 'Operations tagged Surrender Requests across 2 of this provider''s published API definitions: evergreen-marine-ebl-surrender-openapi.json, evergreen-marine-ebl-surrender-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Surrender Requests
  description: The Surrender Requests **implemented** by carrier
paths:
  /v3/ebl-surrender-requests:
    post:
      tags:
      - Surrender Requests
      operationId: create-surrender-request
      summary: Creates a Surrender Request
      description: 'The eBL Solution Platform uses this endpoint to submit a surrender request.


        The carrier''s answer to the surrender request will be returned via a callback response (see the `Callbacks` tab)'
      parameters:
      - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurrenderRequestDetails'
      responses:
        '204':
          description: 'Submission registered successfully.


            The carrier will later follow up via the callback with a response.

            '
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
        default:
          description: Error
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      title: Error Response
      type: object
      description: Unexpected error
      properties:
        httpMethod:
          description: 'The HTTP method used to make the request e.g. `GET`, `POST`, etc

            '
          type: string
          example: POST
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - DELETE
          - OPTION
          - PATCH
        requestUri:
          description: 'The URI that was requested.

            '
          type: string
          example: /v1/events
        statusCode:
          description: 'The HTTP status code returned.

            '
          type: integer
          format: int32
          example: 400
        statusCodeText:
          description: 'A standard short description corresponding to the HTTP status code.

            '
          type: string
          maxLength: 50
          example: Bad Request
        statusCodeMessage:
          description: 'A long description corresponding to the HTTP status code with additional information.

            '
          type: string
          maxLength: 200
          example: The supplied data could not be accepted
        providerCorrelationReference:
          description: 'A unique identifier to the HTTP request within the scope of the API provider.

            '
          type: string
          maxLength: 100
          example: 4426d965-0dd8-4005-8c63-dc68b01c4962
        errorDateTime:
          description: 'The DateTime corresponding to the error occurring. Must be formatted using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

            '
          type: string
          format: date-time
          example: '2024-09-04T09:41:00Z'
        errors:
          type: array
          description: 'An array of errors providing more detail about the root cause.

            '
          minItems: 1
          items:
            $ref: '#/components/schemas/DetailedError'
      required:
      - httpMethod
      - requestUri
      - statusCode
      - statusCodeText
      - errorDateTime
      - errors
    IdentifyingCode:
      type: object
      title: Identifying Code
      properties:
        codeListProvider:
          type: string
          maxLength: 100
          description: 'A list of codes identifying a party. Possible values are:

            - `WAVE` (Wave)

            - `CARX` (CargoX)

            - `ESSD` (EssDOCS)

            - `IDT` (ICE Digital Trade)

            - `BOLE` (Bolero)

            - `EDOX` (EdoxOnline)

            - `IQAX` (IQAX)

            - `SECR` (Secro)

            - `TRGO` (TradeGO)

            - `ETEU` (eTEU)

            - `TRAC` (Enigio trace:original)

            - `BRIT` (BRITC eBL)

            - `GSBN` (Global Shipping Business Network)

            - `WISE` (WiseTech)

            - `GLEIF` (Global Legal Entity Identifier Foundation)

            - `W3C` (World Wide Web Consortium)

            - `DNB` (Dun and Bradstreet)

            - `FMC` (Federal Maritime Commission)

            - `DCSA` (Digital Container Shipping Association)

            - `ZZZ` (Mutually defined)

            '
          example: W3C
        partyCode:
          type: string
          description: 'Code to identify the party as provided by the `codeListProvider`

            '
          maxLength: 150
          example: MSK
        codeListName:
          type: string
          maxLength: 100
          description: 'The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:

            - `DID` (Decentralized Identifier) for `codeListProvider` `W3C`

            - `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`

            - `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`

            '
          example: DID
      required:
      - codeListProvider
      - partyCode
    SurrenderRequestDetails:
      type: object
      title: Surrender Request Details
      description: "A concrete surrender request related to a transport document.\n\nThe platform guarantees *all* of the following:\n\n  1) The surrender request was submitted by the sole possessor of the eBL.\n  2) Depending on the eBL type:\n   * For non-negotiable (\"straight\") eBLs, the surrender request was submitted by either the original shipper OR the consignee.\n   * For negotiable eBLs with a named titleholder, the surrender request was submitted by the named titleholder.\n   * For negotiable eBLs without a named titleholder / blank eBLs, possession is sufficient for the entity surrendering the eBL.\n  3) The carrier holds possession of the eBL with this surrender request  until it responds to this surrender request.\n"
      properties:
        surrenderRequestReference:
          type: string
          maxLength: 100
          pattern: ^\S(?:.*\S)?$
          description: 'A server defined reference for a concrete surrender request. Surrender request references MUST NOT be reused.

            '
          example: Z12345
        transportDocumentReference:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 20
          description: 'A unique number allocated by the shipping line to the transport document and the main number used for the tracking of the status of the shipment.

            '
          example: HHL71800000
        transportDocumentSubReference:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 100
          description: 'Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`.

            '
          example: Version_1
        surrenderRequestCode:
          type: string
          description: 'Surrender Request codes:

            - `SREQ` (Requested to surrender for Delivery)

            - `AREQ` (Requested to surrender for Amendment)


            The surrender request code determines the type of surrender request. Any parallel negotiation between the consignee and the carrier related to any of these type surrender are handled outside this API. Examples could be the shipment release related to a surrender for delivery or the actual contents of the amendment in a surrender related to an amendment.


            Note that "Switch to paper" is considered an amendment in how it is modelled via the DCSA eBL data standard.

            '
          enum:
          - SREQ
          - AREQ
          example: SREQ
        reasonCode:
          type: string
          maxLength: 4
          description: "A code defined by DCSA indicating the reason for requesting a surrender for amendment. Possible values are:\n-\t`SWTP` (Switch to paper)\n"
          example: SWTP
        comments:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 255
          description: Optional free text comment associated with the surrender request transaction.
          example: As requested...
        endorsementChain:
          type: array
          description: "A list of one or more endorsement related actions that were performed on or after the issuance of the eBL. It is equivalent to the \"back side\" of the physical bill of lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below:\n\n - **Issue:** The act of issuing an eBL i.e. making the eBL available to the receiver.\n - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a specific named party, allowing them to claim or deal with the goods. The user in control of the eBL may endorse the eBL in their turn to another named party. Only applicable to To-Order eBL (`isToOrder=true`).\n - **Sign:** A general-purpose signature that can be used by any party to mark their possession of the eBL. Similar to how any possessor in the physical world can put a physical signature on the paper bill of lading. The endorsement chain as defined by DCSA does not record any transfer of possession of the eBL, unless a signature is added to it.\n - **Request surrender for amendment:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of amending the eBL.\n - **Request surrender for delivery:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of claiming delivery of the goods.\n\n **Note:** DCSA member carriers have agreed that the name `endorsementChain` is still the correct name for this list of actions.\n"
          items:
            $ref: '#/components/schemas/EndorsementChainLink'
      required:
      - surrenderRequestReference
      - transportDocumentReference
      - surrenderRequestCode
    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.\n\n  - `7000-7999` Technical error codes\n  - `8000-8999` Functional error codes\n  - `9000-9999` API provider-specific error codes            \n\n[Error codes as specified by DCSA](https://developer.dcsa.org/standard-error-codes).\n"
          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
    EndorsementChainLink:
      type: object
      title: Endorsement Chain Link
      properties:
        actionDateTime:
          type: string
          format: date-time
          description: Date time when the action occurred.
          example: '2024-09-04T09:41:00Z'
        actionCode:
          type: string
          maxLength: 50
          description: 'The action performed by the party. This should be one of:

            - `ISSUE` (The actor issued the document to the recipient)

            - `ENDORSE` (The actor endorsed the document to the recipient)

            - `SIGN` (The actor signed or performed an "assignment" to the recipient)

            - `SURRENDER_FOR_DELIVERY` (The actor requested this surrender request for delivery to the recipient)

            - `SURRENDER_FOR_AMENDMENT` (The actor requested this surrender request for amendment to the recipient)

            Not all actions are applicable to all surrender requests.

            '
          example: ISSUE
        actor:
          $ref: '#/components/schemas/TransactionParty'
        recipient:
          $ref: '#/components/schemas/TransactionParty'
      description: 'Entry in the endorsement chain.

        '
      required:
      - actionDateTime
      - actionCode
      - actor
      - recipient
    TransactionParty:
      type: object
      title: Transaction Party
      description: Refers to a company or a legal entity.
      properties:
        eblPlatform:
          type: string
          pattern: ^\S+$
          maxLength: 4
          description: 'The eBL platform of the transaction party. The value **MUST** be one of:

            - `WAVE` (Wave)

            - `CARX` (CargoX)

            - `ESSD` (EssDOCS)

            - `IDT` (ICE Digital Trade)

            - `BOLE` (Bolero)

            - `EDOX` (EdoxOnline)

            - `IQAX` (IQAX)

            - `SECR` (Secro)

            - `TRGO` (TradeGO)

            - `ETEU` (eTEU)

            - `TRAC` (Enigio trace:original)

            - `BRIT` (BRITC eBL)

            '
          example: BOLE
        partyName:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 70
          description: 'Name of the party.

            '
          example: Globeteam
        identifyingCodes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/IdentifyingCode'
        taxLegalReferences:
          description: 'A list of `Tax References` for a `Party`

            '
          type: array
          items:
            $ref: '#/components/schemas/TaxLegalReference'
      required:
      - partyName
      - eblPlatform
      - identifyingCodes
    TaxLegalReference:
      type: object
      title: Tax & Legal Reference
      description: 'Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.


        A small list of **potential** examples:


        | Type  | Country | Description |

        |-------|:-------:|-------------|

        |EORI|NL|Economic Operators Registration and Identification|

        |PAN|IN|Goods and Services Tax Identification Number in India|

        |GSTIN|IN|Goods and Services Tax Identification Number in India|

        |IEC|IN|Importer-Exported Code in India|

        |RUC|EC|Registro Único del Contribuyente in Ecuador|

        |RUC|PE|Registro Único del Contribuyente in Peru|

        |NIF|MG|Numéro d''Identification Fiscal in Madagascar|

        |NIF|DZ|Numéro d''Identification Fiscal in Algeria|

        '
      properties:
        type:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 50
          description: 'The reference type code as defined by the relevant tax and/or legal authority.

            '
          example: PAN
        countryCode:
          type: string
          pattern: ^[A-Z]{2}$
          minLength: 2
          maxLength: 2
          description: 'The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)

            '
          example: IN
        value:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 35
          description: 'The value of the `taxLegalReference`

            '
          example: AAAAA0000A
      required:
      - type
      - countryCode
      - value
  headers:
    API-Version:
      schema:
        type: string
        example: 3.0.0
      description: 'SemVer used to indicate the version of the contract (API version) returned.

        '
  parameters:
    Api-Version-Major:
      in: header
      name: API-Version
      required: false
      schema:
        type: string
        example: '3'
      description: 'An API-Version header **MAY** be added to the request (optional); if added it **MUST** only contain **MAJOR** version. API-Version header **MUST** be aligned with the URI version.

        '
x-refined-from:
- evergreen-marine-ebl-surrender-openapi.json
- evergreen-marine-ebl-surrender-openapi.yml