openapi-phase1.yaml

openapi: 3.1.0
info:
  title: BasicBankingSystem Phase 1 Service APIs
  version: 1.0.0
  description: |
    Phase 1 API contract for the public backend service APIs in BasicBankingSystem.
    This document intentionally covers the documented service endpoints only.
    Gateway routes, Customer Portal BFF routes, demo endpoints, and internal-only service
    operations are protected by integration tests unless they are explicitly added here.
    The platform applies shared request-rate protection to all endpoints and
    replay-aware protection to idempotent write operations that use
    `Idempotency-Key`.
servers:
  - url: http://localhost:8080
    description: Local gateway
tags:
  - name: Customers
  - name: Accounts
  - name: Deposits
  - name: Audits
  - name: Platform
components:
  securitySchemes:
    externalApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    CorrelationIdHeader:
      name: X-Correlation-Id
      in: header
      required: false
      schema:
        type: string
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 100
    PageNumber:
      name: pageNumber
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
  headers:
    CorrelationIdResponse:
      description: Correlation identifier for the request.
      schema:
        type: string
    RetryAfter:
      description: Number of seconds the caller should wait before retrying.
      schema:
        type: string
    IdempotentReplay:
      description: Indicates the response is a replay of an earlier idempotent write.
      schema:
        type: string
        enum: ['true']
    IdempotencyReplayAttempt:
      description: Indicates which replay attempt was observed for the same idempotent write.
      schema:
        type: string
  schemas:
    ProblemDetails:
      type: object
      required: [title, status]
      properties:
        type:
          type: [string, "null"]
        title:
          type: string
        status:
          type: integer
        code:
          type: [string, "null"]
        detail:
          type: [string, "null"]
        traceId:
          type: [string, "null"]
        correlationId:
          type: [string, "null"]
        errors:
          type: [object, "null"]
          additionalProperties:
            type: array
            items:
              type: string
    Address:
      type: object
      required: [country, province, city, line1, postalCode]
      properties:
        country:
          type: string
          maxLength: 2
        province:
          type: string
          maxLength: 100
        city:
          type: string
          maxLength: 100
        line1:
          type: string
          maxLength: 200
        postalCode:
          type: string
          maxLength: 20
    CustomerStatus:
      type: string
      enum: [Pending, Active, Frozen, Closed]
    AccountStatus:
      type: string
      enum: [Active, Frozen, Closed]
    AccountPostingType:
      type: string
      enum: [DepositCredit, DepositReversal, WithdrawalDebit]
    DepositStatus:
      type: string
      enum: [Received, Processing, Succeeded, Rejected, Failed, PendingReview]
    Channel:
      type: string
      enum: [Counter, Online, Atm, Batch]
    DepositSagaStepStatus:
      type: string
      enum: [NotStarted, InProgress, Succeeded, Failed, Compensated, Skipped]
    DepositReviewResolution:
      type: string
      enum: [None, RetryRequested, ReversedExternally, FailedExternally]
    PendingReviewSortBy:
      type: string
      enum: [ReviewRequiredAt, LastCompensationAttemptAt, RequestedAt]
    CreateCustomerRequest:
      type: object
      required: [fullName, identityType, identityNumber, mobile, address, riskLevel]
      properties:
        fullName:
          type: string
          maxLength: 200
        identityType:
          type: string
          maxLength: 50
        identityNumber:
          type: string
          maxLength: 50
        mobile:
          type: string
          maxLength: 30
        email:
          type: [string, "null"]
          format: email
        address:
          $ref: '#/components/schemas/Address'
        riskLevel:
          type: string
          maxLength: 30
    CustomerPortalSignInRequest:
      type: object
      required: [customerNumber, identityLast4]
      properties:
        customerNumber:
          type: string
        identityLast4:
          type: string
          minLength: 4
          maxLength: 4
    Customer:
      type: object
      required: [customerId, customerNumber, fullName, identityType, identityNumberMasked, portalIdentityLast4, mobile, address, riskLevel, status, createdAt, updatedAt]
      properties:
        customerId:
          type: string
        customerNumber:
          type: string
        fullName:
          type: string
        identityType:
          type: string
        identityNumberMasked:
          type: string
        portalIdentityLast4:
          type: string
        mobile:
          type: string
        email:
          type: [string, "null"]
          format: email
        address:
          $ref: '#/components/schemas/Address'
        riskLevel:
          type: string
        status:
          $ref: '#/components/schemas/CustomerStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CustomerSummary:
      type: object
      required: [customerId, customerNumber, fullName, identityNumberMasked, portalIdentityLast4, mobile, status, createdAt]
      properties:
        customerId:
          type: string
        customerNumber:
          type: string
        fullName:
          type: string
        identityNumberMasked:
          type: string
        portalIdentityLast4:
          type: string
        mobile:
          type: string
        status:
          $ref: '#/components/schemas/CustomerStatus'
        createdAt:
          type: string
          format: date-time
    CustomerPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSummary'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    ChangeCustomerStatusRequest:
      type: object
      required: [targetStatus, reason]
      properties:
        targetStatus:
          $ref: '#/components/schemas/CustomerStatus'
        reason:
          type: string
          maxLength: 500
    ChangeCustomerStatusResponse:
      type: object
      required: [customerId, previousStatus, currentStatus, effectiveAt]
      properties:
        customerId:
          type: string
        previousStatus:
          $ref: '#/components/schemas/CustomerStatus'
        currentStatus:
          $ref: '#/components/schemas/CustomerStatus'
        effectiveAt:
          type: string
          format: date-time
    OpenAccountRequest:
      type: object
      required: [customerId, accountType, currency]
      properties:
        customerId:
          type: string
        accountType:
          type: string
          maxLength: 30
        currency:
          type: string
          minLength: 3
          maxLength: 3
    CreateWithdrawalRequest:
      type: object
      required: [amount, currency, referenceNumber]
      properties:
        amount:
          type: number
          exclusiveMinimum: 0
        currency:
          type: string
          minLength: 3
          maxLength: 3
        referenceNumber:
          type: string
          minLength: 1
          maxLength: 100
        correlationId:
          type: [string, "null"]
        note:
          type: [string, "null"]
          maxLength: 500
    Account:
      type: object
      required: [accountId, accountNumber, customerId, accountType, currency, status, availableBalance, ledgerBalance, openedAt]
      properties:
        accountId:
          type: string
        accountNumber:
          type: string
        customerId:
          type: string
        accountType:
          type: string
        currency:
          type: string
        status:
          $ref: '#/components/schemas/AccountStatus'
        availableBalance:
          type: number
        ledgerBalance:
          type: number
        openedAt:
          type: string
          format: date-time
        closedAt:
          type: [string, "null"]
          format: date-time
    AccountSummary:
      type: object
      required: [accountId, accountNumber, accountType, currency, status, availableBalance, ledgerBalance]
      properties:
        accountId:
          type: string
        accountNumber:
          type: string
        accountType:
          type: string
        currency:
          type: string
        status:
          $ref: '#/components/schemas/AccountStatus'
        availableBalance:
          type: number
        ledgerBalance:
          type: number
    AccountPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AccountSummary'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    AccountActivity:
      type: object
      required: [postingReference, accountId, postingType, amount, currency, createdAt]
      properties:
        postingReference:
          type: string
        accountId:
          type: string
        postingType:
          $ref: '#/components/schemas/AccountPostingType'
        amount:
          type: number
        currency:
          type: string
        correlationId:
          type: [string, "null"]
        reversalOfPostingReference:
          type: [string, "null"]
        createdAt:
          type: string
          format: date-time
    AccountActivityPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AccountActivity'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    CreateDepositRequest:
      type: object
      required: [customerId, accountId, amount, currency, channel]
      properties:
        customerId:
          type: string
        accountId:
          type: string
        amount:
          type: number
          exclusiveMinimum: 0
        currency:
          type: string
          minLength: 3
          maxLength: 3
        channel:
          $ref: '#/components/schemas/Channel'
        referenceNumber:
          type: [string, "null"]
          maxLength: 100
        note:
          type: [string, "null"]
          maxLength: 500
    Deposit:
      type: object
      required: [transactionId, transactionNumber, customerId, accountId, amount, currency, channel, status, accountPostingStatus, auditStatus, compensationStatus, reviewResolution, correlationId, compensationRetryCount, requestedAt]
      properties:
        transactionId:
          type: string
        transactionNumber:
          type: string
        customerId:
          type: string
        accountId:
          type: string
        amount:
          type: number
        currency:
          type: string
        referenceNumber:
          type: [string, "null"]
        channel:
          $ref: '#/components/schemas/Channel'
        status:
          $ref: '#/components/schemas/DepositStatus'
        accountPostingStatus:
          $ref: '#/components/schemas/DepositSagaStepStatus'
        auditStatus:
          $ref: '#/components/schemas/DepositSagaStepStatus'
        compensationStatus:
          $ref: '#/components/schemas/DepositSagaStepStatus'
        reviewResolution:
          $ref: '#/components/schemas/DepositReviewResolution'
        correlationId:
          type: string
        failureCode:
          type: [string, "null"]
        failureReason:
          type: [string, "null"]
        compensationRetryCount:
          type: integer
        reviewLastActionBy:
          type: [string, "null"]
        reviewNote:
          type: [string, "null"]
        requestedAt:
          type: string
          format: date-time
        postedAt:
          type: [string, "null"]
          format: date-time
        reversedAt:
          type: [string, "null"]
          format: date-time
        reviewRequiredAt:
          type: [string, "null"]
          format: date-time
        reviewResolvedAt:
          type: [string, "null"]
          format: date-time
        lastCompensationAttemptAt:
          type: [string, "null"]
          format: date-time
        lastProcessedAt:
          type: [string, "null"]
          format: date-time
    DepositSummary:
      type: object
      required: [transactionId, transactionNumber, customerId, accountId, amount, currency, channel, status, requestedAt]
      properties:
        transactionId:
          type: string
        transactionNumber:
          type: string
        customerId:
          type: string
        accountId:
          type: string
        amount:
          type: number
        currency:
          type: string
        referenceNumber:
          type: [string, "null"]
        channel:
          $ref: '#/components/schemas/Channel'
        status:
          $ref: '#/components/schemas/DepositStatus'
        requestedAt:
          type: string
          format: date-time
        postedAt:
          type: [string, "null"]
          format: date-time
    DepositPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DepositSummary'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    PendingReviewDepositSummary:
      type: object
      required: [transactionId, transactionNumber, customerId, accountId, accountNumber, amount, currency, compensationStatus, reviewResolution, compensationRetryCount, requestedAt]
      properties:
        transactionId:
          type: string
        transactionNumber:
          type: string
        customerId:
          type: string
        accountId:
          type: string
        accountNumber:
          type: string
        amount:
          type: number
        currency:
          type: string
        compensationStatus:
          $ref: '#/components/schemas/DepositSagaStepStatus'
        reviewResolution:
          $ref: '#/components/schemas/DepositReviewResolution'
        failureCode:
          type: [string, "null"]
        failureReason:
          type: [string, "null"]
        compensationRetryCount:
          type: integer
        reviewLastActionBy:
          type: [string, "null"]
        reviewNote:
          type: [string, "null"]
        requestedAt:
          type: string
          format: date-time
        reviewRequiredAt:
          type: [string, "null"]
          format: date-time
        lastCompensationAttemptAt:
          type: [string, "null"]
          format: date-time
        lastProcessedAt:
          type: [string, "null"]
          format: date-time
    PendingReviewDepositPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PendingReviewDepositSummary'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    RetryDepositReviewRequest:
      type: object
      properties:
        operatorId:
          type: [string, "null"]
        note:
          type: [string, "null"]
    ResolveDepositReviewRequest:
      type: object
      required: [resolution, operatorId, note]
      properties:
        resolution:
          $ref: '#/components/schemas/DepositReviewResolution'
        operatorId:
          type: string
        note:
          type: string
    AuditSummary:
      type: object
      required: [auditId, actorType, actorId, action, aggregateType, aggregateId, correlationId, occurredAt]
      properties:
        auditId:
          type: string
        actorType:
          type: string
        actorId:
          type: string
        action:
          type: string
        aggregateType:
          type: string
        aggregateId:
          type: string
        correlationId:
          type: string
        occurredAt:
          type: string
          format: date-time
    AuditDetail:
      allOf:
        - $ref: '#/components/schemas/AuditSummary'
        - type: object
          required: [beforeSnapshot, afterSnapshot, causationId]
          properties:
            beforeSnapshot:
              type: [object, "null"]
              additionalProperties: true
            afterSnapshot:
              type: [object, "null"]
              additionalProperties: true
            causationId:
              type: [string, "null"]
    AuditPagedResponse:
      type: object
      required: [items, pageNumber, pageSize, totalCount, totalPages]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditSummary'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
    HealthResponse:
      type: object
      required: [status, service, timestamp]
      properties:
        status:
          type: string
        service:
          type: string
        timestamp:
          type: string
          format: date-time
    ReadyResponse:
      type: object
      required: [status, dependencies]
      properties:
        status:
          type: string
        dependencies:
          type: object
          additionalProperties:
            type: string
    PlatformServiceStatus:
      type: object
      required: [name, basePath, health, swaggerUrl, openApiUrl]
      properties:
        name:
          type: string
        basePath:
          type: string
        health:
          type: string
        statusCode:
          type: [integer, "null"]
        swaggerUrl:
          type: string
        openApiUrl:
          type: string
    PlatformDependencyStatus:
      type: object
      required: [name, status, checkedBy]
      properties:
        name:
          type: string
        status:
          type: string
        checkedBy:
          type: string
    DepositPendingReviewItem:
      type: object
      required: [transactionId, transactionNumber, customerId, accountId, accountNumber, amount, currency, compensationStatus, reviewResolution, compensationRetryCount, requestedAt]
      properties:
        transactionId:
          type: string
        transactionNumber:
          type: string
        customerId:
          type: string
        accountId:
          type: string
        accountNumber:
          type: string
        amount:
          type: number
        currency:
          type: string
        compensationStatus:
          type: string
        reviewResolution:
          type: string
        failureCode:
          type: [string, "null"]
        failureReason:
          type: [string, "null"]
        compensationRetryCount:
          type: integer
        reviewLastActionBy:
          type: [string, "null"]
        reviewNote:
          type: [string, "null"]
        requestedAt:
          type: string
          format: date-time
        reviewRequiredAt:
          type: [string, "null"]
          format: date-time
        lastCompensationAttemptAt:
          type: [string, "null"]
          format: date-time
        lastProcessedAt:
          type: [string, "null"]
          format: date-time
    DepositWorkflowSummary:
      type: object
      required: [checkedAt, receivedCount, succeededCount, failedCount, pendingReviewCount, pendingReviewItems]
      properties:
        checkedAt:
          type: string
          format: date-time
        receivedCount:
          type: integer
        succeededCount:
          type: integer
        failedCount:
          type: integer
        pendingReviewCount:
          type: integer
        pendingReviewItems:
          type: array
          items:
            $ref: '#/components/schemas/DepositPendingReviewItem'
    DepositOutboxMessageItem:
      type: object
      required: [messageId, transactionId, messageType, occurredAt]
      properties:
        messageId:
          type: string
        transactionId:
          type: string
        messageType:
          type: string
        occurredAt:
          type: string
          format: date-time
        processedAt:
          type: [string, "null"]
          format: date-time
        lastError:
          type: [string, "null"]
    DepositWorkerRuntimeStatus:
      type: object
      required: [workerName, mode, enabled, pollingIntervalMilliseconds, backlogCount, notes]
      properties:
        workerName:
          type: string
        mode:
          type: string
        enabled:
          type: boolean
        pollingIntervalMilliseconds:
          type: integer
        backlogCount:
          type: integer
        notes:
          type: string
    DepositRuntimeStatus:
      type: object
      required: [checkedAt, messageTransport, pendingReviewCount, pendingOutboxCount, workers]
      properties:
        checkedAt:
          type: string
          format: date-time
        messageTransport:
          type: string
        pendingReviewCount:
          type: integer
        pendingOutboxCount:
          type: integer
        workers:
          type: array
          items:
            $ref: '#/components/schemas/DepositWorkerRuntimeStatus'
    DepositWorkflowDetail:
      type: object
      required: [transactionId, transactionNumber, customerId, accountId, amount, currency, channel, status, accountPostingStatus, auditStatus, compensationStatus, reviewResolution, correlationId, compensationRetryCount, requestedAt]
      properties:
        transactionId:
          type: string
        transactionNumber:
          type: string
        customerId:
          type: string
        accountId:
          type: string
        amount:
          type: number
        currency:
          type: string
        referenceNumber:
          type: [string, "null"]
        channel:
          type: string
        status:
          type: string
        accountPostingStatus:
          type: string
        auditStatus:
          type: string
        compensationStatus:
          type: string
        reviewResolution:
          type: string
        correlationId:
          type: string
        failureCode:
          type: [string, "null"]
        failureReason:
          type: [string, "null"]
        compensationRetryCount:
          type: integer
        reviewLastActionBy:
          type: [string, "null"]
        reviewNote:
          type: [string, "null"]
        requestedAt:
          type: string
          format: date-time
        postedAt:
          type: [string, "null"]
          format: date-time
        reversedAt:
          type: [string, "null"]
          format: date-time
        reviewRequiredAt:
          type: [string, "null"]
          format: date-time
        reviewResolvedAt:
          type: [string, "null"]
          format: date-time
        lastCompensationAttemptAt:
          type: [string, "null"]
          format: date-time
        lastProcessedAt:
          type: [string, "null"]
          format: date-time
    AuditTraceItem:
      type: object
      required: [auditId, actorType, actorId, action, aggregateType, aggregateId, correlationId, occurredAt]
      properties:
        auditId:
          type: string
        actorType:
          type: string
        actorId:
          type: string
        action:
          type: string
        aggregateType:
          type: string
        aggregateId:
          type: string
        correlationId:
          type: string
        occurredAt:
          type: string
          format: date-time
    CorrelationDiagnostics:
      type: object
      required: [correlationId, checkedAt, deposits, auditEvents]
      properties:
        correlationId:
          type: string
        checkedAt:
          type: string
          format: date-time
        deposits:
          type: array
          items:
            $ref: '#/components/schemas/DepositWorkflowDetail'
        auditEvents:
          type: array
          items:
            $ref: '#/components/schemas/AuditTraceItem'
    RetryDepositCompensationRequest:
      type: object
      required: [reason]
      properties:
        reason:
          type: string
          maxLength: 500
    PlatformResolveDepositReviewRequest:
      type: object
      required: [resolution, reason]
      properties:
        resolution:
          type: string
          enum: [ReversedExternally, FailedExternally]
        reason:
          type: string
          maxLength: 500
    RequeueOutboxMessageRequest:
      type: object
      required: [reason]
      properties:
        reason:
          type: string
          maxLength: 500
    PlatformMaintenanceAction:
      type: object
      required: [operationId, actionType, targetType, targetId, actorId, resultStatus, downstreamStatusCode, reason, occurredAt]
      properties:
        operationId:
          type: string
        actionType:
          type: string
        targetType:
          type: string
        targetId:
          type: string
        actorId:
          type: string
        resultStatus:
          type: string
        downstreamStatusCode:
          type: integer
        reason:
          type: string
        occurredAt:
          type: string
          format: date-time
    PlatformOverview:
      type: object
      required: [platform, checkedAt, services, dependencies, deposits, depositRuntime]
      properties:
        platform:
          type: string
        checkedAt:
          type: string
          format: date-time
        services:
          type: array
          items:
            $ref: '#/components/schemas/PlatformServiceStatus'
        dependencies:
          type: array
          items:
            $ref: '#/components/schemas/PlatformDependencyStatus'
        deposits:
          $ref: '#/components/schemas/DepositWorkflowSummary'
        depositRuntime:
          $ref: '#/components/schemas/DepositRuntimeStatus'
paths:
  /api/v1/customers:
    post:
      tags: [Customers]
      summary: Create a customer
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Validation error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Duplicate identity or mobile
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags: [Customers]
      summary: List customers
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Customer list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedResponse'
  /api/v1/customers/{customerId}:
    get:
      tags: [Customers]
      summary: Get customer by id
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Customer detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Customer not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/customers/portal-sign-in:
    post:
      tags: [Customers]
      summary: Sign in for the customer portal
      security:
        - externalApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPortalSignInRequest'
      responses:
        '200':
          description: Customer matched for portal sign-in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          description: Invalid sign-in details
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/customers/{customerId}/status:
    post:
      tags: [Customers]
      summary: Change customer status
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeCustomerStatusRequest'
      responses:
        '200':
          description: Customer status changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeCustomerStatusResponse'
        '400':
          description: Invalid status transition
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Customer not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/accounts:
    post:
      tags: [Accounts]
      summary: Open account
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAccountRequest'
      responses:
        '201':
          description: Account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Validation error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Customer not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Customer not eligible for account opening
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags: [Accounts]
      summary: Search accounts by customer
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: customerId
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Account search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPagedResponse'
  /api/v1/accounts/{accountId}:
    get:
      tags: [Accounts]
      summary: Get account by id
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Account not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/accounts/by-number/{accountNumber}:
    get:
      tags: [Accounts]
      summary: Get account by account number
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: accountNumber
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Account not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/accounts/{accountId}/withdrawals:
    post:
      tags: [Accounts]
      summary: Create a withdrawal
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWithdrawalRequest'
      responses:
        '200':
          description: Account after withdrawal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Account not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Account not eligible for withdrawal
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/accounts/{accountId}/activities:
    get:
      tags: [Accounts]
      summary: Get account activities
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
        - name: activityType
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AccountPostingType'
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Account activity list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountActivityPagedResponse'
        '404':
          description: Account not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/deposits:
    post:
      tags: [Deposits]
      summary: Create deposit request
      description: |
        Creates an idempotent deposit request.

        Repeating the same request with the same `Idempotency-Key` replays the
        original logical deposit result instead of creating a new financial effect.
        Repeated short-window replays may be progressively delayed and can return
        replay metadata headers.
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDepositRequest'
      responses:
        '202':
          description: Deposit accepted
          headers:
            X-Idempotent-Replay:
              $ref: '#/components/headers/IdempotentReplay'
            X-Idempotency-Replay-Attempt:
              $ref: '#/components/headers/IdempotencyReplayAttempt'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '400':
          description: Validation error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Customer or account not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Deposit conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Request rate exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags: [Deposits]
      summary: Search deposits
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/DepositStatus'
        - name: customerId
          in: query
          required: false
          schema:
            type: string
        - name: accountId
          in: query
          required: false
          schema:
            type: string
        - name: correlationId
          in: query
          required: false
          schema:
            type: string
        - name: failureCode
          in: query
          required: false
          schema:
            type: string
        - name: requestedFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: requestedTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Deposit search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositPagedResponse'
        '429':
          description: Request rate exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/deposits/{transactionId}:
    get:
      tags: [Deposits]
      summary: Get deposit by id
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deposit detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '404':
          description: Deposit not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Request rate exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/deposits/review/pending:
    get:
      tags: [Deposits]
      summary: List pending review deposits
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: sortBy
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PendingReviewSortBy'
        - name: descending
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Pending review queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingReviewDepositPagedResponse'
  /api/v1/deposits/{transactionId}/review/retry-compensation:
    post:
      tags: [Deposits]
      summary: Retry compensation for a pending review deposit
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryDepositReviewRequest'
      responses:
        '200':
          description: Deposit after retry request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '404':
          description: Deposit not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Deposit review action is invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/deposits/{transactionId}/review/resolve:
    post:
      tags: [Deposits]
      summary: Resolve a pending review deposit
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
              schema:
                $ref: '#/components/schemas/PlatformResolveDepositReviewRequest'
      responses:
        '200':
          description: Deposit after manual resolution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deposit'
        '404':
          description: Deposit not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Deposit review action is invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/audits:
    get:
      tags: [Audits]
      summary: Search audit logs
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Audit search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditPagedResponse'
  /api/v1/audits/{auditId}:
    get:
      tags: [Audits]
      summary: Get audit detail by id
      security:
        - externalApiKey: []
      parameters:
        - $ref: '#/components/parameters/CorrelationIdHeader'
        - name: auditId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Audit detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditDetail'
        '404':
          description: Audit not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/health:
    get:
      tags: [Platform]
      summary: Liveness endpoint
      responses:
        '200':
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /api/v1/ready:
    get:
      tags: [Platform]
      summary: Readiness endpoint
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadyResponse'
  /api/platform/overview:
    get:
      tags: [Platform]
      summary: Get platform monitoring overview
      responses:
        '200':
          description: Platform overview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformOverview'
        '401':
          description: Authentication required
  /api/platform/services:
    get:
      tags: [Platform]
      summary: Get aggregated platform service status
      responses:
        '200':
          description: Platform services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlatformServiceStatus'
        '401':
          description: Authentication required
  /api/platform/workflows/deposits/summary:
    get:
      tags: [Platform]
      summary: Get deposit workflow summary
      responses:
        '200':
          description: Deposit workflow summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositWorkflowSummary'
        '401':
          description: Authentication required
  /api/platform/workflows/deposits/pending-review:
    get:
      tags: [Platform]
      summary: Get deposit pending review items
      responses:
        '200':
          description: Pending review items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DepositPendingReviewItem'
        '401':
          description: Authentication required
  /api/platform/workflows/deposits/outbox:
    get:
      tags: [Platform]
      summary: Get deposit outbox messages
      parameters:
        - name: pendingOnly
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Deposit outbox items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DepositOutboxMessageItem'
        '401':
          description: Authentication required
  /api/platform/workflows/deposits/runtime:
    get:
      tags: [Platform]
      summary: Get deposit runtime worker and backlog status
      responses:
        '200':
          description: Deposit runtime status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositRuntimeStatus'
        '401':
          description: Authentication required
  /api/platform/workflows/deposits/{transactionId}:
    get:
      tags: [Platform]
      summary: Get deposit workflow detail
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deposit workflow detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositWorkflowDetail'
        '401':
          description: Authentication required
        '404':
          description: Workflow not found
  /api/platform/diagnostics/correlation/{correlationId}:
    get:
      tags: [Platform]
      summary: Get diagnostics for a correlation id
      parameters:
        - name: correlationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Correlation diagnostics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrelationDiagnostics'
        '401':
          description: Authentication required
  /api/platform/audit/operations:
    get:
      tags: [Platform]
      summary: Get platform maintenance and operations audit events
      responses:
        '200':
          description: Platform operations audit events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditTraceItem'
        '401':
          description: Authentication required
  /api/platform/maintenance/deposits/{transactionId}/retry-compensation:
    post:
      tags: [Platform]
      summary: Retry deposit compensation from platform operations
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryDepositCompensationRequest'
      responses:
        '200':
          description: Maintenance action completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformMaintenanceAction'
        '401':
          description: Authentication required
        '403':
          description: Caller lacks platform maintenance permission
        '409':
          description: Downstream workflow rejected the retry request
  /api/platform/maintenance/deposits/{transactionId}/resolve-review:
    post:
      tags: [Platform]
      summary: Resolve deposit pending review from platform operations
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveDepositReviewRequest'
      responses:
        '200':
          description: Maintenance action completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformMaintenanceAction'
        '401':
          description: Authentication required
        '403':
          description: Caller lacks platform maintenance permission
        '409':
          description: Downstream workflow rejected the resolve request
  /api/platform/maintenance/deposits/outbox/{messageId}/requeue:
    post:
      tags: [Platform]
      summary: Requeue deposit outbox message from platform operations
      parameters:
        - name: messageId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequeueOutboxMessageRequest'
      responses:
        '200':
          description: Maintenance action completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformMaintenanceAction'
        '401':
          description: Authentication required
        '403':
          description: Caller lacks platform maintenance permission
        '409':
          description: Downstream outbox requeue request was rejected