openapi: 3.1.0
info:
  title: Expenses API
  version: '1.0'
  summary: Expenses API
  description: API to get and update expense reports
servers:
  - url: https://api.boyahq.com/v1
    description: Boya API server
paths:
  /expenses:
    get:
      summary: Get all expenses
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Expenses Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
        '404':
          description: Expenses Not Found
      operationId: get-business-expenses
      description: Fetch business expenses
      parameters:
        - schema:
            type: string
            format: date
          in: query
          name: fromdate
          description: yyyy-mm-dd
        - schema:
            type: string
            format: date
          in: query
          name: todate
          description: yyyy-mm-dd
        - schema:
            type: integer
            default: 1
          in: query
          name: page
        - schema:
            type: integer
            default: 50
          in: query
          name: limit
          description: Number of items per page
  /expenses/review:
    get:
      summary: Get Expenses Pending Review
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
      operationId: get-expenses-review
      description: Get expenses pending review
      parameters:
        - $ref: '#/components/parameters/fromdate'
        - $ref: '#/components/parameters/todate'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
  /expenses/accepted:
    get:
      summary: Get approved expenses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
      operationId: get-expenses-accepted
      parameters:
        - $ref: '#/components/parameters/fromdate'
        - $ref: '#/components/parameters/todate'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
  /expenses/rejected:
    get:
      summary: Get rejected expenses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
      operationId: get-expenses-rejected
      parameters:
        - $ref: '#/components/parameters/fromdate'
        - $ref: '#/components/parameters/todate'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
  /expenses/recovered:
    get:
      summary: Get recovered expenses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
      operationId: get-expenses-recovered
      parameters:
        - $ref: '#/components/parameters/fromdate'
        - $ref: '#/components/parameters/todate'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
  /expenses/refunded:
    get:
      summary: Get expenses with refunded payments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseList'
      operationId: get-expenses-refunded
      parameters:
        - $ref: '#/components/parameters/fromdate'
        - $ref: '#/components/parameters/todate'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
  /expenses/sync_status:
    patch:
      summary: Update expense sync status
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - transaction_ref
                properties:
                  transaction_ref:
                    type: string
                    description: Reference ID of the transaction
      responses:
        '200':
          description: Sync status updated successfully
        '400':
          description: Invalid request body
        '404':
          description: One or more expenses not found
      operationId: update-expenses-sync-status
      description: Update sync status for one or more expenses
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    Expense:
      type: object
      properties:
        _id:
          type: string
        amount:
          type: number
        fees:
          type: number
        charge:
          type: number
        original_currency:
          type: string
        currency:
          type: string
        original_amount:
          type: number
        transaction_ref:
          type: string
        provider_ref:
          type: string
        employee_id:
          type: string
        person:
          type: string
        transaction_date:
          type: string
          format: date-time
        MerchantCategoryCode:
          type: string
        MerchantIdentifier:
          type: string
        fx_rate:
          type: number
        card_vcn:
          type: string
        receiver:
          type: string
        accno:
          type: string
        payment_type:
          type: string
        channel:
          type: string
        subcategory:
          $ref: '#/components/schemas/Subcategory'
        team:
          $ref: '#/components/schemas/Team'
        tag:
          type: array
          items:
            type: string
        notes:
          type: string
        risk:
          type: string
        risk_notes:
          type: string
        ip:
          type: string
        attachments:
          type: array
          items:
            type: string
        payment_status:
          type: string
        status:
          type: string
        review_participants:
          type: array
          items:
            type: string
        review_mandate:
          type: integer
        review_level:
          type: integer
        events:
          type: array
          items:
            type: object
        exported:
          type: boolean
        sync_successful:
          type: boolean
        org_wallet_ref:
          type: string
        vendor:
          type: string
        customer:
          type: object
          nullable: true
        account_number:
          type: string
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        __v:
          type: integer
        id:
          type: string
    Subcategory:
      type: object
      properties:
        _id:
          type: string
        category:
          type: object
          properties:
            _id:
              type: string
            groupid:
              type: string
            name:
              type: string
        code:
          type: string
        name:
          type: string
    Team:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        code:
          type: string
    Review:
      type: object
      properties:
        person:
          type: string
        notes:
          type: string
        status:
          type: string
        _id:
          type: string
        reviewed_on:
          type: string
          format: date-time
    ExpenseList:
      type: object
      properties:
        docs:
          type: array
          items:
            $ref: '#/components/schemas/Expense'
        total:
          type: integer
        limit:
          type: integer
        page:
          type: integer
        pages:
          type: integer
  parameters:
    fromdate:
      schema:
        type: string
        format: date
      in: query
      name: fromdate
      description: Start date (yyyy-mm-dd)
    todate:
      schema:
        type: string
        format: date
      in: query
      name: todate
      description: End date (yyyy-mm-dd)
    page:
      schema:
        type: integer
        default: 1
      in: query
      name: page
      description: Page number
    limit:
      schema:
        type: integer
        default: 50
      in: query
      name: limit
      description: Number of items per page
security:
  - ApiKeyAuth: []
