> ## 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.

# Crea un presupuesto recurrente para una categoría (BUD-001)



## OpenAPI

````yaml /openapi/v1.json post /v1/budgets
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/budgets:
    post:
      tags:
        - budgets
      summary: Crea un presupuesto recurrente para una categoría (BUD-001)
      operationId: BudgetsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBudgetDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetDto'
      security:
        - bearer: []
components:
  schemas:
    CreateBudgetDto:
      type: object
      properties:
        categoryId:
          type: string
          description: Categoría a la que aplica el presupuesto (agrega su subárbol).
        budgetType:
          type: string
          enum:
            - expense
            - income
          default: expense
        amount:
          type: string
          example: '4000.00'
          description: Monto por ciclo.
        repeat:
          type: string
          enum:
            - month
            - year
            - once
          default: month
        startDate:
          type: string
          example: '2026-07-01'
        repeatUntil:
          type: string
          example: '2026-12-31'
          nullable: true
        rolloverEnabled:
          type: boolean
          default: false
        accountId:
          type: string
          description: Cuenta opcional (sólo afina el Forecast).
      required:
        - categoryId
        - amount
        - repeat
        - startDate
    BudgetDto:
      type: object
      properties:
        id:
          type: string
        category:
          $ref: '#/components/schemas/BudgetCategoryRefDto'
        budgetType:
          type: string
          enum:
            - expense
            - income
        amount:
          type: string
          example: '4000.00'
        repeat:
          type: string
          enum:
            - month
            - year
            - once
            - week
            - two_weeks
        startDate:
          type: string
          example: '2026-07-01'
        repeatUntil:
          type: string
          nullable: true
        rolloverEnabled:
          type: boolean
        accountId:
          type: string
          nullable: true
        period:
          $ref: '#/components/schemas/BudgetPeriodRangeDto'
        spent:
          type: string
          example: '3500.00'
          description: Gasto (o ingreso) real del ciclo.
        rollover:
          type: string
          example: '500.00'
          description: Rollover acumulado de ciclos previos (0 si off).
        available:
          type: string
          example: '1000.00'
          description: amount + rollover − spent.
        createdAt:
          type: string
      required:
        - id
        - category
        - budgetType
        - amount
        - repeat
        - startDate
        - repeatUntil
        - rolloverEnabled
        - accountId
        - period
        - spent
        - rollover
        - available
        - createdAt
    BudgetCategoryRefDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        parentId:
          type: string
          nullable: true
      required:
        - id
        - name
        - parentId
    BudgetPeriodRangeDto:
      type: object
      properties:
        start:
          type: string
          example: '2026-07-01'
        end:
          type: string
          example: '2026-07-31'
      required:
        - start
        - end
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT (Supabase Auth)
      type: http

````