openapi: 3.0.3
info:
  title: Oflync Cashflow Connector API
  version: 1.0.0
  description: |
    Server-to-server API for posting cashflow to a **single Oflync outlet**.

    Authenticate with a partner API key (`oflk_…`), not a Partner Portal login.
    Each key is bound to one outlet. Line-item detail can stay in your own system;
    send period totals and Oflync computes net cashflow.

    Create, rotate, and revoke keys only in the Partner Portal under **API connectors**.
    There is no public API to manage keys.
  contact:
    name: Oflync Help Center
    url: https://docs.oflync.com/docs/products/api-connectors
  license:
    name: Oflync Partner API
    url: https://docs.oflync.com/docs/integrations/cashflow-connector-api

servers:
  - url: https://service.oflync.com
    description: Production
  - url: http://localhost:1997
    description: Local development

tags:
  - name: External cashflow
    description: API-key authenticated capture for the outlet bound to the key

security:
  - ApiKeyHeader: []
  - ApiKeyBearer: []

paths:
  /ordering-service/v1/external/cashflow/summary:
    post:
      tags: [External cashflow]
      operationId: postCashflowSummary
      summary: Post aggregated inflow and outflow
      description: |
        Recommended monthly job. Send period **inflow** and **outflow** totals.
        Oflync stores those two amounts and returns **netCashflow** (`inflow − outflow`).

        Re-posting the same `externalReference` updates the period instead of duplicating it.
        `outletId` must match the outlet bound to the API key.
      security:
        - ApiKeyHeader: []
        - ApiKeyBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashflowSummaryRequest'
            examples:
              monthlyTotals:
                summary: Monthly period totals
                value:
                  outletId: f9128203-e2f1-4f20-8b0a-dae3cb13c27d
                  period: '2026-08'
                  inflow: 185000.00
                  outflow: 42000.00
                  currency: INR
                  description: Monthly totals from the connected system
                  externalReference: connector-2026-08
      responses:
        '201':
          description: New period totals created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashflowSummaryResponse'
              example:
                outletId: f9128203-e2f1-4f20-8b0a-dae3cb13c27d
                period: '2026-08'
                transactionDate: '2026-08-31'
                inflow: 185000.00
                outflow: 42000.00
                netCashflow: 143000.00
                currency: INR
                externalReference: connector-2026-08
                incomeTransactionId: 3a1c0b12-9e44-4c21-8f11-0d2a4b6c8e90
                expenseTransactionId: 7b2d1c23-ae55-4d32-9a22-1e3b5c7d9f01
                updated: false
        '200':
          description: Existing `externalReference` was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashflowSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /ordering-service/v1/external/cashflow:
    post:
      tags: [External cashflow]
      operationId: postCashflowEntry
      summary: Capture a single cashflow entry
      description: |
        Creates one INCOME or EXPENSE row for the bound outlet.
        Prefer `/summary` when you only have period totals.

        If `externalReference` already exists for that outlet, the row is updated.
      security:
        - ApiKeyHeader: []
        - ApiKeyBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashflowCaptureRequest'
            examples:
              income:
                summary: Period income
                value:
                  outletId: f9128203-e2f1-4f20-8b0a-dae3cb13c27d
                  type: INCOME
                  amount: 185000.00
                  currency: INR
                  category: Connected system sales
                  period: '2026-08'
                  externalReference: connector-2026-08-income
      responses:
        '201':
          description: New entry created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashflowCaptureResponse'
        '200':
          description: Existing `externalReference` was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashflowCaptureResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Partner API key starting with `oflk_`. Issued in the Partner Portal only.
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: oflk
      description: Same key as `Authorization: Bearer oflk_…`

  responses:
    BadRequest:
      description: Validation failed (missing fields, negative amounts, both totals zero, bad period)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: inflow and outflow cannot both be zero
    Unauthorized:
      description: Missing, unknown, revoked, or expired API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorResponse'
          example:
            error: AUTHENTICATION_FAILED
            message: Invalid or revoked API key
            status: 401
    Forbidden:
      description: Wrong outlet, Cashflow not on the plan, or login token used on an external path
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 403
            message: This API key can only post cashflow for its bound outlet

  schemas:
    CashflowSummaryRequest:
      type: object
      required: [outletId, inflow, outflow, externalReference]
      properties:
        outletId:
          type: string
          format: uuid
          description: Must match the outlet bound to this API key
        inflow:
          type: number
          format: double
          minimum: 0
          description: Total money in for the period
          example: 185000.00
        outflow:
          type: number
          format: double
          minimum: 0
          description: Total money out for the period
          example: 42000.00
        currency:
          type: string
          minLength: 3
          maxLength: 3
          default: INR
        category:
          type: string
          maxLength: 100
          default: Period totals
        description:
          type: string
          maxLength: 500
        transactionDate:
          type: string
          format: date
          description: If omitted, last day of `period`, else today
        period:
          type: string
          pattern: '^\d{4}-\d{2}$'
          example: '2026-08'
          description: Year-month for a monthly job
        externalReference:
          type: string
          maxLength: 100
          example: connector-2026-08
          description: Idempotency key. Reuse to update the same period.

    CashflowSummaryResponse:
      type: object
      properties:
        outletId:
          type: string
          format: uuid
        period:
          type: string
          example: '2026-08'
        transactionDate:
          type: string
          format: date
        inflow:
          type: number
          format: double
        outflow:
          type: number
          format: double
        netCashflow:
          type: number
          format: double
          description: Calculated by Oflync as inflow − outflow
        currency:
          type: string
        externalReference:
          type: string
        incomeTransactionId:
          type: string
          format: uuid
          nullable: true
        expenseTransactionId:
          type: string
          format: uuid
          nullable: true
        updated:
          type: boolean
          description: true when an existing period total was updated

    CashflowCaptureRequest:
      type: object
      required: [outletId, type, amount, externalReference]
      properties:
        outletId:
          type: string
          format: uuid
        type:
          type: string
          enum: [INCOME, EXPENSE]
        amount:
          type: number
          format: double
          minimum: 0.01
        currency:
          type: string
          default: INR
        category:
          type: string
          maxLength: 100
        description:
          type: string
          maxLength: 500
        transactionDate:
          type: string
          format: date
        period:
          type: string
          pattern: '^\d{4}-\d{2}$'
        externalReference:
          type: string
          maxLength: 120

    CashflowCaptureResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        vendorOutletId:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        type:
          type: string
          enum: [INCOME, EXPENSE]
        amount:
          type: number
        currency:
          type: string
        category:
          type: string
        description:
          type: string
        transactionDate:
          type: string
          format: date
        referenceType:
          type: string
          example: EXTERNAL_API
        referenceId:
          type: string
        externalReference:
          type: string
        updated:
          type: boolean
        createdBy:
          type: string
        createdDate:
          type: string
          format: date-time
        updatedBy:
          type: string
        updatedDate:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        traceId:
          type: string
        spanId:
          type: string

    AuthErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
        timestamp:
          type: string
          format: date-time
        path:
          type: string