Evergreen Marine Corp. Issuance Response API

openapi: 3.2.0
info:
  title: Evergreen Marine Issuance Response API
  version: 3.0.0
  description: 'Operations tagged Issuance Response across 2 of this provider''s published API definitions: evergreen-marine-ebl-issuance-openapi.json, evergreen-marine-ebl-issuance-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Issuance Response
  description: Issuance Response **implemented** by carrier
paths:
  /v3/ebl-issuance-responses:
    post:
      tags:
      - Issuance Response
      operationId: create-ebl-issuance-response
      summary: Respond to a transport document issuance request
      description: Submit a response to a carrier issuance request.
      parameters:
      - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssuanceResponse'
            examples:
              issuExample:
                summary: 'Issued response

                  '
                description: 'The document was successfully issued (`ISSU`) and delivered

                  '
                value:
                  transportDocumentReference: HHL7180000000
                  issuanceResponseCode: ISSU
      responses:
        '204':
          description: Carrier's acknowledgement of the Issuance Response
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
        default:
          description: Request failed for some reason.
          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
    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
    IssuanceError:
      type: object
      title: Issuance Error
      properties:
        reason:
          type: string
          maxLength: 255
          pattern: ^\S(?:.*\S)?$
          description: 'Human readable description of the rationale for an unsuccessful issuance.


            The `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`.

            '
          example: Cannot get...
        errorCode:
          type: string
          maxLength: 50
          pattern: ^\S+$
          description: 'A vendor provided error code.


            The meaning of each code is agreed bilaterally between the vendor.

            '
          example: ERR-1234
    IssuanceResponse:
      type: object
      title: Issuance Response
      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
        issuanceResponseCode:
          type: string
          description: "The platforms verdict on the issuance of the eBL  identified by the `transportDocumentReference`\n\nOptions are:\n  - `ISSU`: The document was successfully `ISSU` and successfully delivered to the initial possessor.\n  - `BREQ`: The platform reviewed the document and believe they cannot issue the document due to an error/issue with the content of the issuance request.\n  - `REFU`: The eBL issuance is rejected for a reason that the issuing eBL platform cannot resolve (for example when an Interoperable transfer fails, due to a reject of the receiving eBL platform via the `BENV` code from the interoperability standard). One reason could be that the `issueTo` referenced a valid eBL platform but the receiving platform did not recognise the recipient specified.\n\nRegardless of the response code, the issuance request is now considered handled. In case of successful issuance, the platform will still have some responsibility but that is covered by other processes and APIs (e.g., the DCSA_SUR API mentioned in the description of this API). In case of failed issuance, it is up to the carrier to resolve the issue and, if needed, submit a revised issuance request.\n"
          enum:
          - ISSU
          - BREQ
          - REFU
          example: ISSU
        reason:
          type: string
          maxLength: 255
          pattern: ^\S(?:.*\S)?$
          description: 'Human readable description of the rationale for an unsuccessful issuance.


            The `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`.

            '
          example: Cannot get...
        errors:
          type: array
          description: 'A list of errors if the issuance failed for some reason.

            '
          maxItems: 255
          items:
            $ref: '#/components/schemas/IssuanceError'
      required:
      - transportDocumentReference
      - issuanceResponseCode
  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-issuance-openapi.json
- evergreen-marine-ebl-issuance-openapi.yml