openapi: '3.0.2'
info:
  description: This documentation covers the complete information about all the REST endpoints exposed by Cleardocs which provides a way to integrate third party system with Cleardocs system.
  version: 'v1.0'
  title: Cleardocs API Documentation
  termsOfService: 'urn:tos'
  contact: {}
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
tags:
  - name: Order
    description: Manage orders in Cleardocs
servers:
  - url: https://api.thomsonreuters.com/cleardocs/v1/integrations/test/
  - url: https://api.thomsonreuters.com/cleardocs/v1/integrations/
paths:
  /{thirdPartyName}/orders:
    post:
      description: To create new order with pre-fill the data in question interface.
      summary: creates new order and reutrns newly created order ID
      parameters:
        - in: path
          name: thirdPartyName   # Note the name is the same as in the path
          required: true
          schema:
            type: string
            minimum: 1
          description: The name of third party who is making call to this API. (This will be provided by Cleardocs team at the time of client registration)
      requestBody:
        content:
          application/json:
            schema:
              $ref:  "#/components/schemas/OrderResource"

      responses:
        '201':
          description: New order created
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/Response"

        '404':
          description: NOT_FOUND

        '405':
          description: METHOD_NOT_ALLOWED

        '415':
          description: UNSUPPORTED_MEDIA_TYPE

        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/ErrorResponse"

        '500':
          description: INTERNAL_SERVER_ERROR
          
        '401':
          description: UNAUTHORIZED

      tags:
        - "Order"
        
  /{thirdPartyName}/orders/{orderId}/documents:
    get:
      description: To get documents generated after completing order in cleardocs by using order ID.
      summary: returns the list of generated documents.
      parameters:
        - in: path
          name: thirdPartyName   # Note the name is the same as in the path
          required: true
          schema:
            type: string
            minimum: 1
          description: The name of third party who is making call to this API. (This will be provided by Cleardocs team at the time of client registration)
        - in: path
          name: orderId   
          required: true
          schema:
            type: integer
            minimum: 1
          description: The orderId of the order for which the list of documents will be returned
    
      responses:
        '200':
          description: Zip folder having list of documents
          content:
           application/zip:
            schema:
              type: string
              format: binary

        '404':
          description: NOT_FOUND

        '405':
          description: METHOD_NOT_ALLOWED

        '415':
          description: UNSUPPORTED_MEDIA_TYPE

        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/ErrorResponse"

        '500':
          description: INTERNAL_SERVER_ERROR
          
        '401':
          description: UNAUTHORIZED

      tags:
        - "Order"

  /{thirdPartyName}/orders/{orderId}/invoices:
    get:
      description: To get invoices by using order ID after completing order in cleardocs.
      summary: returns the list of generated invoices.
      parameters:
        - in: path
          name: thirdPartyName   # Note the name is the same as in the path
          required: true
          schema:
            type: string
            minimum: 1
          description: The name of third party who is making call to this API. (This will be provided by Cleardocs team at the time of client registration)
        - in: path
          name: orderId   
          required: true
          schema:
            type: integer
            minimum: 1
          description: The orderId of the order for which the list of invoices will be returned
    
      responses:
        '200':
          description: Zip folder having list of invoices
          content:
           application/zip:
            schema:
              type: string
              format: binary

        '404':
          description: NOT_FOUND

        '405':
          description: METHOD_NOT_ALLOWED

        '415':
          description: UNSUPPORTED_MEDIA_TYPE

        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/ErrorResponse"

        '500':
          description: INTERNAL_SERVER_ERROR
          
        '401':
          description: UNAUTHORIZED

      tags:
        - "Order"

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.thomsonreuters.com/authorize
          tokenUrl: https://auth.thomsonreuters.com/oauth/token
          scopes:
            read: Grants read access
  schemas:
    Response:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref:  "#/components/schemas/OrderResponse"
        error:
          $ref: "#/components/schemas/Error"
          
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
        data:
          type: object
          default: null
        error:
          $ref: "#/components/schemas/Error"

    Error:
      type: object
      properties:
        timestamp:
          type: string
          description: Timestamp in millis when error occurred
        message:
          type: string
        status:
          type: string
          description: HTTP Status
        validationFields:
          type: array
          items:
            properties:
              field:
                type: string
              violation:
                type: string

    OrderResponse:
      type: object
      properties:
        orderId:
          type: integer

    OrderResource:
      type: object
      properties:
        productId:
          type: number
        clientName:
          type: string
        matterName:
          type: string
        fund:
          $ref: "#/components/schemas/Fund"
        trust:
          $ref:  "#/components/schemas/Trust"
        corporation:
          $ref:  "#/components/schemas/Corporation"
        company:
          $ref: "#/components/schemas/Company"
        incorporatedAssociation:
          $ref: "#/components/schemas/IncorporatedAssociation"
        deedAmendment:
          $ref: "#/components/schemas/DeedAmendment"
      required:
        - productId
        - clientName
        - matterName

    Company:
      type: object
      properties:
        type:
          type: string
          example: company
        name:
          type: string
        extension:
          type: string
        acn:
          type: string
        address:
          $ref: "#/components/schemas/Address"
        fax:
          type: string
        stateRegistered:
          type: string
        inTrustFor:
          type: string
        representativeGivenN:
          type: string
        representativeFamily:
          type: string
        shares:
          type: array
          items:
            $ref: "#/components/schemas/Share"
        roles:
          $ref: "#/components/schemas/EntityRole"
        commonSealDetail:
          $ref: "#/components/schemas/CommonSealDetail"
        actingAsTrustee:
          type: string
        nameOfTrustee:
          type: string
        trustNameActingAsTrustee:
          type: string

    IncorporatedAssociation:
      type: object
      properties:
        type:
          type: string
          example: incorporatedAssociation
        name:
          type: string
        extension:
          type: string
        number:
          type: string
        actingAsTrustee:
          type: string
        nameOfTrustee:
          type: string
        address:
          $ref: "#/components/schemas/Address"

    Corporation:
      type: object
      properties:
        type:
          type: string
          example: corporation
        registeredOffice:
          $ref:  "#/components/schemas/Address"
        businessAddress:
          $ref:  "#/components/schemas/Address"
        name:
          type: string
        extension:
          type: string
        acn:
          type: string
        registeredState:
          type: string
        officers:
          type: array
          items:
            $ref:  "#/components/schemas/Individual"
        shareholders:
          type: array
          items:
            $ref:  "#/components/schemas/Entity"
        ultimateHoldingCompany:
          $ref:  "#/components/schemas/Company"
        consent:
          type: string
        NonDirPublicOfficer:
          $ref:  "#/components/schemas/Individual"
        constitution:
          $ref:  "#/components/schemas/Constitution"
        isXeroPull:
          type: boolean
        email:
          type: string
        registrationDate:
          type: string
          example: yyyy-MM-dd
        cType:
          $ref: "#/components/schemas/CompanyType"
        class:
          $ref: "#/components/schemas/CompanyClass"
        subclass:
          $ref: "#/components/schemas/CompanySubclass"
        ExecutionClause:
          $ref: "#/components/schemas/ExecutionClause"
        entityName:
          type: string

    Fund:
      type: object
      properties:
        type:
          type: string
          example: fund
        name:
          type: string
        date:
          type: string
          example: dd/MM/yyyy
        pensionCommencementDate:
          type: string
          example: dd/MM/yyyy
        jurisdiction:
          type: string
        members:
          type: array
          items:
            $ref: "#/components/schemas/Individual"
        trustee:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        sponsor:
          $ref: "#/components/schemas/Entity"
        participatingEmp:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        deedAmmendment:
          type: array
          items:
            $ref:  "#/components/schemas/DeedAmendment"
        lender:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        custodian:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        repaymentDetails:
          $ref: "#/components/schemas/RepaymentDetails"
        entityName:
          type: string

    Trust:
      type: object
      properties:
        type:
          type: string
          example: trust
        name:
          type: string
        establishedDate:
          type: string
          example: dd/MM/yyyy
        jurisdiction:
          type: string
        settlor:
          $ref:  "#/components/schemas/Individual"
        trustees:
          type: array
          items:
            $ref:  "#/components/schemas/Entity"
        beneficiaries:
          type: array
          items:
            $ref:  "#/components/schemas/Entity"
        appointors:
          type: array
          items:
            $ref:  "#/components/schemas/Entity"
        unitHolders:
          type: array
          items:
            $ref:  "#/components/schemas/Entity"
        loan:
          $ref: "#/components/schemas/Loan"
        trustType:
          $ref: "#/components/schemas/TrustType"

    Individual:
      type: object
      properties:
        type:
          type: string
          example: individual
        address:
          $ref:  "#/components/schemas/Address"
        surname:
          type: string
          description: Family name
        givenName:
          type: string
          description: Given name
        dob:
          type: string
          example: dd/MM/yyyy
          description: Date of birth
        cob:
          type: string
          description: City of birth
        sob:
          type: string
          description: State of birth
        countryOfBirth:
          type: string
          description: Country of birth
        occupation:
          type: string
        TFN:
          type: string
          description: Tax file number
        role:
          type: array
          items:
            $ref: "#/components/schemas/EntityRole"
        shares:
          type: array
          items:
            $ref: "#/components/schemas/Share"
        inTrustFor:
          type: string
        consent:
          type: string
        actingAsTrustee:
          type: string
        nameOfTrustee:
          type: string
        trustNameActingAsTrustee:
          type: string

    Loan:
      type: object
      properties:
        type:
          type: string
          example: loan
        asset:
          $ref: "#/components/schemas/Asset"
        borrower:
          $ref: "#/components/schemas/Entity"
        lender:
          $ref: "#/components/schemas/Entity"
        loanAmount:
          type: string
        loanMonths:
          type: string
        loanYear:
          type: string
        settlementDate:
          type: string

    DeedAmendment:
      type: object
      properties:
        type:
          type: string
          example: deedAmendment
        name:
          type: string
        date:
          type: string
          example: dd/MM/yyyy
        otherParties:
          type: string

    ExecutionClause:
      type: object
      properties:
        type:
          type: string
          example: executionClause
        executionType:
          $ref: "#/components/schemas/ExecutionClauseType"
        directors:
          type: array
          items:
            type: string
        secretary:
          type: string

    Constitution:
      type: object
      properties:
        type:
          type: string
          example: constitution
        votePerShare:
          type: string
        issueOfferMembers:
          type: string
        sellOfferMembers:
          type: string

    Address:
      type: object
      properties:
        type:
          type: string
          example: address
        floor:
          type: string
        unit:
          type: string
        buildingName:
          type: string
        streetNumberAndName:
          type: string
        suburb:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string

    CommonSealDetail:
      type: object
      properties:
        type:
          type: string
          example: commonSealDetail
        affixingCommonSeal:
          type: string
        optionName:
          type: string
        personName1:
          type: string
        personName2:
          type: string

    RepaymentDetails:
      type: object
      properties:
        type:
          type: string
          example: repaymentDetails
        interestFrequency:
          type: string
        principalFrequency:
          type: string

    EntityRole:
      type: string
      enum:
        - publicOfficer
        - secretary
        - shareholder
        - director

    TrustType:
      type: string
      enum:
        - discretionary-trust
        - unit-trust-fixed
        - unit-trust-non-fixed
        - hybrid-trust

    ShareType:
      type: string
      enum:
        - "1"
        - "2"
        - "3"
        - "4"
        - "5"
        - "6"
        - "7"
        - "8"
        - "9"
        - "10"
        - "11"
        - "12"
        - "13"
        - "14"
        - "15"

    CompanyType:
      type: string
      enum:
        - Australian Proprietary Company
        - Australian Public Company

    CompanyClass:
      type: string
      enum:
        - Limited by Shares
        - Limited by Guarantee

    CompanySubclass:
      type: string
      enum:
        - Superannuation Trustee Company
        - Non Profit Company
        - Proprietary Company
        - Unlisted Public Company

    ExecutionClauseType:
      type: string
      enum:
        - sole_director_secretary_witness
        - sole_director_witness
        - sole_director_secretary_sign
        - sole_director_sign
        - directors_witness
        - director_secretary_witness
        - directors_sign
        - director_secretary_sign
        - sole_director_sole_secretary_sign
        - executive_sign

    Property:
      description: Subclass of asset
      type: object
      properties:
        assetType:
          type: string
        address:
          $ref:  "#/components/schemas/Address"
        prefix:
          type: string
        volumeNumber:
          type: string
        folioNumber:
          type: string
        lotNumber:
          type: string
        dpNumber:
          type: string
        country:
          type: string
        parish:
          type: string
        titleReference:
          type: string
        location:
          type: string
        planReference:
          type: string
        jurisdiction:
          type: string

    Share:
      description: subclass of asset
      type: object
      properties:
        assetType:
          type: string
        shareType:
          $ref: "#/components/schemas/ShareType"
        company:
          $ref: "#/components/schemas/Company"
        certificateNumber:
          type: integer
        quantity:
          type: number
          description: Decimal number is allowed
        paid:
          type: number
          description: Decimal number is allowed
        owing:
          type: number
          description: Decimal number is allowed

    Units:
      type: object
      properties:
        assetType:
          type: string
        name:
          type: string
        arsn:
          type: string
        abn:
          type: string
        amount:
          type: number
          description: Decimal number is allowed
        classCode:
          type: string
        stateRegistered:
          type: string

    Asset:
      type:  object
      oneOf:
        - $ref: "#/components/schemas/Property"
        - $ref: "#/components/schemas/Share"
        - $ref: "#/components/schemas/Units"

    Entity:
      type: object
      oneOf:
        - $ref: "#/components/schemas/Company"
        - $ref: "#/components/schemas/Fund"
        - $ref: "#/components/schemas/IncorporatedAssociation"
        - $ref: "#/components/schemas/Corporation"
        - $ref: "#/components/schemas/DeedAmendment"
        - $ref: "#/components/schemas/Individual"
        - $ref: "#/components/schemas/Loan"
        - $ref: "#/components/schemas/Trust"
        - $ref: "#/components/schemas/Constitution"
        - $ref: "#/components/schemas/RepaymentDetails"
        - $ref: "#/components/schemas/CommonSealDetail"

  responses:
    ApiRespose:
      description: A JSON object contaning api Response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Response"