openapi: 3.0.0
info:
  version: 1.0.0
  title: ows-abacus-worksheet API Specifications
servers:
  - url: 'https://qa-ows-abacus-worksheet.theorchard.io'
    description: QA server
paths:
  /hello/:
    get:
      summary: Check the health of the application.
      responses:
        200:
          description: 200 OK

  /worksheet-correction/bulk/:
    post:
      summary: Bulk create worksheet correction entries
      requestBody:
        description: Array of the bulk endpoint
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/WorksheetCorrectionPost'
      responses:
        201:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorksheetCorrectionItem'

  /worksheet-correction/statement-period/{statement_period_id}/{correction_type}/unapplied/:
    get:
      summary: Get a list of unapplied worksheet corrections
      parameters:
      - description: id of the statement period
        name: statement_period_id
        in: path
        required: true
        schema:
          type: integer
      - description: correction type
        name: correction_type
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetCorrectionItem'

  /worksheet-adjustments/statement-period-adjustment-file/{statement_period_adjustment_file_id}/:
    get:
      summary: Get a list of worksheet adjustments
      parameters:
      - description: id of the statement_period_adjustment_file
        name: statement_period_adjustment_file_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentList'
    delete:
      summary: Deletes worksheet adjustments and adjustment details.
      parameters:
        - description: ID of the statement_period_adjustment_file
          name: statement_period_adjustment_file_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Success

  /worksheet-adjustments/pending/:
    get:
      summary: Get a list of pending worksheet adjustments
      parameters:
        - description: id of the statement_period
          name: statement_period
          in: query
          required: false
          schema:
            type: integer
        - description: id of the reference_payment_entity_id
          name: reference_payment_entity_id
          in: query
          required: false
          schema:
            type: integer
        - description: pagination limit
          name: limit
          in: query
          required: false
          schema:
            type: integer
        - description: pagination offset
          name: offset
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentList'

  /worksheet-adjustment/{worksheet_adjustment_id}/details/:
    get:
      summary: Get a list of worksheet adjustment details
      parameters:
        - description: id of the worksheet adjustment
          name: worksheet_adjustment_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentDetailsItem'

  /worksheet-adjustments/import/:
    post:
      summary: create worksheet adjustments and adjustment details
      requestBody:
        description: Payload to create worksheet adjustments and adjustment details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorksheetAdjustmentImport'
      responses:
        '201':
          description: POST success

  /worksheet-adjustment/statement-period-adjustment-file/{statement_period_adjustment_file_id}/adjustments-and-details/:
    get:
      summary: Get a list of worksheet adjustments and details
      parameters:
        - description: id of the statement_period_adjustment_file
          name: statement_period_adjustment_file_id
          in: path
          required: true
          schema:
            type: integer
        - description: comme separated contract ids
          name: contract_ids
          in: query
          required: false
          schema:
            type: string
        - description: comme separated account ids
          name: contract_ids
          in: query
          required: false
          schema:
            type: string
        - description: comme separated apply_to_flowthrough_payment filter values 0,1 or null
          name: apply_to_flowthrough_payment
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentAdjustmentAndDetail'
        '400':
          description: Bad request
        '404':
          description: StatementPeriodAdjustmentFile Not found

  /worksheet-adjustments/statement-period-adjustment-file/{statement_period_adjustment_file_id}/contracts/:
    get:
      summary: Get a list of contract ids for adjustments
      parameters:
        - description: either contract_id or contract_name
          name: contract_search_term
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentContractsList'
        '400':
          description: Bad request
        '404':
          description: StatementPeriodAdjustmentFile Not found

  /worksheet-adjustments/statement-period-adjustment-file/{statement_period_adjustment_file_id}/accounts/:
    get:
      summary: Get a list of account ids for adjustments
      parameters:
        - description: either account_id or account_name
          name: account_search_term
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    example: 1
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorksheetAdjustmentAccountsList'
        '400':
          description: Bad request
        '404':
          description: StatementPeriodAdjustmentFile Not found

components:
  schemas:
    WorksheetCorrectionPost:
      type: object
      properties:
        account_id:
          type: integer
          description: id of the account
        contract_id:
          type: integer
          description: id of the contract
        statement_period_id:
          type: integer
          description: id of the statement period this is happening in
        correction_statement_period_id:
          type: integer
          description: id of the statement period this is correcting
        correction_type:
          type: string
          description: type of correction (reversal or correction)
        currency_code:
          type: string
          description: type of currency
        gross_revenue:
          type: number
          description: the gross revenue of the correction; up to 18 decimal places
        distribution_fee:
          type: number
          description: the fee to be applied to the gross revenue of the correction; up to 18 decimal places
        mechanical_deduction_total:
          type: number
          description: total amount of mechanical deductions for contract
        mechanical_deduction_admin_fee_total:
          type: number
          description: total amount of mechanical deduction admin fees for contract
        net_revenue:
          type: number
          description: the net amount of the correction after fees; up to 18 decimal places
        note:
          type: string
      required:
        - account_id
        - statement_period_id
        - correction_statement_period_id
        - correction_type
        - currency_code
        - gross_revenue
        - distribution_fee
        - net_revenue
      example:
        account_id: 1
        contract_id: 2
        correction_statement_period_id: 280
        correction_type: royalty_reversal
        currency_code: 'USD'
        gross_revenue: 20040.223344
        distribution_fee: 4008.0446688
        mechanical_deduction_total: 40.00
        mechanical_deduction_admin_fee_total: 10.00
        net_revenue: 16032.1786752
        statement_period_id: 287
        note: 'random note'

    WorksheetCorrectionItem:
      allOf:
        - $ref: '#/components/schemas/WorksheetCorrectionPost'
        - type: object
          properties:
            worksheet_correction_id:
              type: number
              description: id of correction
      example:
        account_id: 1
        contract_id: 2
        correction_statement_period_id: 280
        correction_type: royalty_reversal
        currency_code: 'USD'
        gross_revenue: 20040.223344
        distribution_fee: 4008.0446688
        mechanical_deduction_total: 40.00
        mechanical_deduction_admin_fee_total: 10.00
        net_revenue: 16032.1786752
        statement_period_id: 287
        note: 'random note'
        worksheet_correction_id: 1

    WorksheetAdjustmentItem:
      title: Worksheet Adjustment Detail
      type: object
      properties:
        worksheet_adjustment_id:
          type: integer
          description: id (pk) of the worksheet adjustment
        statement_period_adjustment_file_id:
          type: integer
          description: id (pk) of the statement period adjustment file
        abacus_event_id:
          type: integer
          description: id (fk) of the corresponding abacus event
        account_id:
          type: integer
          description: id (fk) of the corresponding abacus account
        contract_id:
          type: integer
          description: id (fk) of the corresponding abacus contract
        activity_statement_period_id:
          type: integer
          description: id (fk) of the statement period, when adjustment took place
        apply_to_statement_period_id:
          type: integer
          description: id (fk) of the statement period to apply adjustment to
        reference_adjustment_type_id:
          type: integer
          description: id (fk) of the corresponding reference adjustment type
        apply_to_flowthrough_payment:
          type: boolean
          description: true for flowthrough payments; false otherwise.
        adjustment_amount:
          type: number
          description: total amount of adjustments
        adjustment_currency_code:
          type: string
          description: iso-standard of adjustment's currency code
        note:
          type: string
          description: optional text note
        internal_note:
          type: string
          description: optional text note
      example:
        worksheet_adjustment_id: 1
        statement_period_adjustment_file_id: 1
        abacus_event_id: 1
        account_id: 1
        contract_id: 1
        activity_statement_period_id: 1
        apply_to_statement_period_id: 2
        reference_adjustment_type_id: 1
        apply_to_flowthrough_payment: false
        adjustment_amount: '125.42'
        adjustment_currency_code: 'USD'
        note: 'informative message'
        internal_note: 'informative message'

    WorksheetAdjustmentDetailsItem:
      title: Worksheet Adjustment Details Item
      type: object
      properties:
        worksheet_adjustment_detail_id:
          type: integer
          description: id (pk) of the worksheet adjustment detail
        worksheet_adjustment_id:
          type: integer
          description: id (pk) of the worksheet adjustment
        statement_period_adjustment_file_id:
          type: integer
          description: id (pk) of the statement period adjustment file
        account_id:
          type: integer
          description: id (fk) of the corresponding abacus account
        contract_id:
          type: integer
          description: id (fk) of the corresponding abacus contract
        activity_statement_period_id:
          type: integer
          description: id (fk) of the statement period, when adjustment took place
        apply_to_statement_period_id:
          type: integer
          description: id (fk) of the statement period to apply adjustment to
        reference_adjustment_type_id:
          type: integer
          description: id (fk) of the corresponding reference adjustment type
        apply_to_flowthrough_payment:
          type: boolean
          description: true for flowthrough payments; false otherwise.
        currency_code:
          type: string
          description: iso-standard of adjustment's currency code
        amount:
          type: number
          description: total amount of adjustment details
        upc:
          type: string
          description: upc code
        distribution_type:
          type: string
          description: distribution type
          enum: [digital, physical]
        note:
          type: string
          description: optional text note
        internal_note:
          type: string
          description: optional internal text note
      example:
        worksheet_adjustment_detail_id: 1
        worksheet_adjustment_id: 1
        statement_period_adjustment_file_id: 1
        account_id: 1
        contract_id: 1
        activity_statement_period_id: 1
        apply_to_statement_period_id: 2
        reference_adjustment_type_id: 1
        apply_to_flowthrough_payment: false
        currency_code: 'USD'
        amount: '125.42'
        upc: '555444333222111'
        distribution_type: 'digital'
        note: 'informative message'
        internal_note: 'informative internal message'

    WorksheetAdjustmentImport:
      type: object
      properties:
        abacus_event_id:
          type: integer
          description: id of the related abacus_event
        statement_period_adjustment_file_id:
          type: integer
          description: id of the related statement_period_adjustment_file
      required:
        - abacus_event_id
        - statement_period_adjustment_file_id
      example:
        abacus_event_id: 1
        statement_period_adjustment_file_id: 1

    WorksheetAdjustmentAdjustmentAndDetail:
      allOf:
        - $ref: '#/components/schemas/WorksheetAdjustmentItem'
        - type: object
          properties:
            distribution_type:
              type: string
              description: distribution type
              enum: [digital, physical]
            upc:
              type: string
              description: upc code
            worksheet_adjustment_detail_id:
              type: integer
              description: id (pk) of the worksheet adjustment detail
      example:
        worksheet_adjustment_id: 1
        worksheet_adjustment_detail_id: 1
        statement_period_adjustment_file_id: 1
        abacus_event_id: 1
        account_id: 1
        contract_id: 1
        activity_statement_period_id: 1
        apply_to_statement_period_id: 2
        reference_adjustment_type_id: 1
        apply_to_flowthrough_payment: false
        adjustment_amount: '125.42'
        adjustment_currency_code: 'USD'
        upc: '555444333222111'
        distribution_type: 'digital'
        note: 'informative message'
        internal_note: 'informative message'

    WorksheetAdjustmentList:
      allOf:
        - $ref: '#/components/schemas/WorksheetAdjustmentItem'
        - type: object
          properties:
            account_currency_code:
              type: string
              description: related account's preferred currency_code
            account_payment_entity_id:
              type: integer
              description: releated account's payment_entity_id 
            details:
              type: array
              description: list of worksheet adjustment detail
              items:
                $ref: '#/components/schemas/WorksheetAdjustmentDetailsItem'
      example:
        worksheet_adjustment_id: 1
        statement_period_adjustment_file_id: 1
        abacus_event_id: 1
        account_id: 1
        contract_id: 1
        activity_statement_period_id: 1
        apply_to_statement_period_id: 2
        reference_adjustment_type_id: 1
        adjustment_amount: '125.42'
        adjustment_currency_code: 'USD'
        apply_to_flowthrough_payment: false
        note: 'informative message'
        internal_note: 'informative message'
        account_currency_code: 'USD'
        account_payment_term_id: 1
        details:
          - worksheet_adjustment_detail_id: 1
            worksheet_adjustment_id: 1
            statement_period_adjustment_file_id: 1
            account_id: 1
            contract_id: 1
            activity_statement_period_id: 1
            apply_to_statement_period_id: 2
            reference_adjustment_type_id: 1
            apply_to_flowthrough_payment: false
            currency_code: 'USD'
            amount: '125.42'
            upc: '555444333222111'
            distribution_type: 'digital'
            note: 'informative message'
            internal_note: 'informative internal message'

    WorksheetAdjustmentContractsList:
      type: object
      properties:
        contract_id:
          type: integer
          description: id of the related contract
      required:
        - contract_id
      example:
        contract_id: 1

    WorksheetAdjustmentAccountsList:
      type: object
      properties:
        contract_id:
          type: integer
          description: id of the related account
      required:
        - account_id
      example:
        account_id: 1