> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finzaria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lista transacciones con filtros y cursor (TXN-007/008)



## OpenAPI

````yaml /openapi/v1.json get /v1/transactions
openapi: 3.0.0
info:
  title: Finzaria API
  description: >-
    API REST de Finzaria — finanzas personales para México, dev-first y
    agent-first. Autentícate con tu API key bxm_ (o un token OAuth).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.finzaria.com/v1
    description: Producción
security: []
tags: []
paths:
  /v1/transactions:
    get:
      tags:
        - transactions
      summary: Lista transacciones con filtros y cursor (TXN-007/008)
      operationId: TransactionsController_list
      parameters:
        - name: accountId
          required: false
          in: query
          schema:
            type: string
        - name: categoryId
          required: false
          in: query
          description: Filtra por categoría (incluye su subárbol, CAT-003).
          schema:
            type: string
        - name: importId
          required: false
          in: query
          description: Filtra por lote de importación (08).
          schema:
            type: string
        - name: contactId
          required: false
          in: query
          description: IOU donde participa este contacto (IOU-T32).
          schema:
            type: string
        - name: noCategory
          required: false
          in: query
          description: true = sólo transacciones sin categoría (TXN-008).
          schema:
            type: boolean
        - name: type
          required: false
          in: query
          schema:
            type: string
            enum:
              - expense
              - income
              - transfer
              - refund
              - shared_bill
              - paid_for_friend
              - loan
              - settlement
              - investment_buy
              - investment_sell
              - investment_dividend
              - capital_gain
              - capital_loss
        - name: status
          required: false
          in: query
          schema:
            type: string
            enum:
              - cleared
              - pending
              - reconciled
        - name: startDate
          required: false
          in: query
          schema:
            type: string
            example: '2026-07-01'
        - name: endDate
          required: false
          in: query
          schema:
            type: string
            example: '2026-07-31'
        - name: q
          required: false
          in: query
          description: Búsqueda de texto libre en la descripción.
          schema:
            type: string
        - name: cursor
          required: false
          in: query
          description: Cursor opaco de la página anterior.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          schema:
            maximum: 100
            default: 50
            type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPageDto'
      security:
        - bearer: []
components:
  schemas:
    TransactionPageDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransactionDto'
        nextCursor:
          type: string
          nullable: true
      required:
        - items
        - nextCursor
    TransactionDto:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
        memo:
          type: string
          nullable: true
        amount:
          type: string
          example: '450.50'
        date:
          type: string
          example: '2026-07-02'
        type:
          type: string
          enum:
            - expense
            - income
            - transfer
            - refund
            - shared_bill
            - paid_for_friend
            - loan
            - settlement
            - investment_buy
            - investment_sell
            - investment_dividend
            - capital_gain
            - capital_loss
        status:
          type: string
          enum:
            - cleared
            - pending
            - reconciled
        accountId:
          type: string
          nullable: true
        fromAccountId:
          type: string
          nullable: true
        toAccountId:
          type: string
          nullable: true
        currency:
          type: string
        exchangeRate:
          type: string
          nullable: true
          description: 'Transfer entre divisas: 1 currency = exchangeRate toCurrency (09).'
        toAmount:
          type: string
          nullable: true
          description: Monto que llegó al destino, en toCurrency (09).
        toCurrency:
          type: string
          nullable: true
          description: Moneda de la cuenta destino en un transfer entre divisas (09).
        repeatingTransactionId:
          type: string
          nullable: true
          description: Regla recurrente que generó esta ocurrencia (09).
        category:
          nullable: true
          description: Categoría 0..1; null = sin categoría (CAT-002).
          type: object
          allOf:
            - $ref: '#/components/schemas/CategoryRefDto'
        participants:
          description: Participantes del IOU; null en tipos no-IOU (08-iou).
          type: array
          items:
            $ref: '#/components/schemas/TransactionParticipantDto'
        deletedAt:
          type: string
          nullable: true
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - id
        - description
        - memo
        - amount
        - date
        - type
        - status
        - accountId
        - fromAccountId
        - toAccountId
        - currency
        - exchangeRate
        - toAmount
        - toCurrency
        - repeatingTransactionId
        - category
        - deletedAt
        - createdAt
        - updatedAt
    CategoryRefDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Ruta completa "Padre / Hijo" de la categoría.
        emoji:
          type: string
          nullable: true
          description: Emoji de la categoría (hoja); null si no tiene.
      required:
        - id
        - name
        - emoji
    TransactionParticipantDto:
      type: object
      properties:
        contactId:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        role:
          type: string
          enum:
            - payer
            - sharer
            - beneficiary
            - lender
            - borrower
            - receiver
        amount:
          type: string
          example: '50.00'
        debtDelta:
          type: string
          example: '50.00'
          description: + = debe, − = se le debe.
      required:
        - contactId
        - name
        - role
        - amount
        - debtDelta
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT (Supabase Auth)
      type: http

````