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

# Get billing summary for a period

> Get billing summary for a specific period. If client_id is provided, returns detailed data for that client. Otherwise, returns aggregated summary for all clients.



## OpenAPI

````yaml /generated/specs/finance.json get /api/v1/facturacion-2/summary
openapi: 3.0.0
info:
  title: Raul API - Finanzas
  description: >-
    Facturas, boletas, ejecuciones de billing, cuentas por pagar y medios de
    pago.
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.raul.ugps.io
    description: Production
security: []
tags: []
paths:
  /api/v1/facturacion-2/summary:
    get:
      tags:
        - Facturacion 2.0
      summary: Get billing summary for a period
      description: >-
        Get billing summary for a specific period. If client_id is provided,
        returns detailed data for that client. Otherwise, returns aggregated
        summary for all clients.
      operationId: Facturacion2Controller_getSummary
      parameters:
        - name: periodo
          required: true
          in: query
          description: Period in format YYYY-MM
          schema:
            type: string
            example: 2026-01
        - name: client_id
          required: false
          in: query
          description: >-
            Client ID (optional, if not provided returns summary for all
            clients)
          schema:
            type: string
            example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Billing summary retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryResponseDto'
        '400':
          description: Invalid period format
        '404':
          description: Client not found
components:
  schemas:
    BillingSummaryResponseDto:
      type: object
      properties:
        periodo:
          type: string
          example: 2026-01
        subscripciones:
          type: number
          example: 1500000.5
          description: Total subscriptions in CLP
        visitas:
          type: number
          example: 250000
          description: Total visits in CLP
        ventas_dispositivos:
          type: number
          example: 0
          description: Total device sales in CLP
        total_neto:
          type: number
          example: 1750000.5
          description: Net total in CLP
        valor_uf:
          type: number
          example: 38000
        total_clients:
          type: number
          example: 45
        prorrateos:
          example: []
          type: array
          items:
            type: object
        facturas_detalladas:
          type: array
          items:
            $ref: '#/components/schemas/ClientBillingDetailDto'
        source:
          type: string
          example: calculo_tiempo_real
          description: 'Source of data: facturas_generadas or calculo_tiempo_real'
          enum:
            - facturas_generadas
            - calculo_tiempo_real
        warnings:
          example:
            - 'SOSPECHOSO: Plan "Premium" (ID:123) tiene precio 50 UF - Verificar'
          description: Array of warning messages for suspicious or critical data issues
          type: array
          items:
            type: string
        metadata:
          description: Metadata about processing statistics
          allOf:
            - $ref: '#/components/schemas/BillingProcessingMetadataDto'
      required:
        - periodo
        - valor_uf
    ClientBillingDetailDto:
      type: object
      properties:
        client_id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        client_name:
          type: string
          example: Cliente Ejemplo S.A.
          description: Client name
        total_subs:
          type: number
          example: 150000.5
          description: Total amount for subscriptions in CLP
        total_visits:
          type: number
          example: 25000
          description: Total amount for visits in CLP
        total_device_sales:
          type: number
          example: 0
          description: Total amount for device sales in CLP
        total_factura:
          type: number
          example: 175000.5
          description: Total invoice amount in CLP
        subs_count:
          type: number
          example: 5
          description: Number of subscriptions
        visits_count:
          type: number
          example: 2
          description: Number of visits
        sales_count:
          type: number
          example: 0
          description: Number of device sales
        subscriptions_by_plan:
          description: Breakdown of subscriptions by plan with individual proration
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionPlanBreakdownDto'
      required:
        - client_id
        - client_name
        - total_subs
        - total_visits
        - total_device_sales
        - total_factura
        - subs_count
        - visits_count
        - sales_count
    BillingProcessingMetadataDto:
      type: object
      properties:
        totalPlansProcessed:
          type: number
          example: 150
          description: Total number of subscription plans processed
        plansSkipped:
          type: number
          example: 5
          description: Number of plans skipped due to critical price threshold
        plansWithWarnings:
          type: number
          example: 10
          description: Number of plans with suspicious prices (warnings)
      required:
        - totalPlansProcessed
        - plansSkipped
        - plansWithWarnings
    SubscriptionPlanBreakdownDto:
      type: object
      properties:
        plan_name:
          type: string
          example: Básico GPS
        price_uf:
          type: number
          example: 0.38
          description: Price per unit in UF
        price_clp:
          type: number
          example: 15088
          description: Price per unit in CLP (prorated)
        count:
          type: number
          example: 10
          description: Number of devices
        total_clp:
          type: number
          example: 150880
          description: Total amount in CLP (prorated)
        avg_days:
          type: number
          example: 30
          description: Average billable days (for display)
      required:
        - plan_name
        - price_uf
        - price_clp
        - count
        - total_clp
        - avg_days

````