{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-fiscal-summary-response-schema.json",
  "title": "FiscalSummaryResponse",
  "description": "Comprehensive fiscal summary for a period",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-companyfiscalsummary-api-openapi.yml#/components/schemas/FiscalSummaryResponse",
  "type": "object",
  "properties": {
    "queried_period": {
      "$ref": "#/$defs/QueriedPeriod"
    },
    "total_taxable_base": {
      "type": "number",
      "format": "double",
      "description": "Total taxable base for the period"
    },
    "total_vat": {
      "type": "number",
      "format": "double",
      "description": "Total indirect tax for the period (IVA, IGIC, IPSI and other rates), not only VAT. See tax_breakdown for the split by tax type."
    },
    "tax_breakdown": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TaxBreakdownItem"
      },
      "description": "Tax breakdown by type (IVA, IGIC, IPSI) and rate. Allows a single invoice to have multiple tax types."
    },
    "vat_breakdown_by_rate": {
      "type": "object",
      "additionalProperties": {
        "type": "number",
        "format": "double"
      },
      "deprecated": true,
      "description": "DEPRECATED: Use tax_breakdown instead.\n\nIndirect tax breakdown by rate (rate -> amount). It aggregates EVERY indirect tax\n(IVA, IGIC, IPSI and other rates) by percentage alone, so two different tax types at\nthe same rate collapse into a single entry and cannot be told apart. The rate key is\nalways rendered with three decimals (\"21.000\", \"0.000\").\n\n`tax_breakdown` is the replacement: it keeps `tax_type` and `percentage` separate.\n"
    },
    "surcharge_breakdown": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SurchargeBreakdownItem"
      },
      "description": "Equivalence surcharge breakdown by rate, aggregated over the period. Same shape as\n`surcharge_breakdown` in the invoice detail. Empty (or absent) when no invoice in the\nperiod carries an equivalence surcharge.\n"
    },
    "total_equivalence_surcharge": {
      "type": "number",
      "format": "double",
      "description": "Total equivalence surcharge for the period. It is NOT part of `total_vat`: the surcharge\nis settled by the retailer, not by the issuer, and `total_vat` only carries the main\nindirect tax.\n"
    },
    "total_irpf_withheld": {
      "type": "number",
      "format": "double",
      "description": "Total IRPF withheld in the period"
    },
    "period_base": {
      "type": "number",
      "format": "double",
      "description": "Taxable base for the period"
    },
    "projected_annual_base": {
      "type": "number",
      "format": "double",
      "description": "Projected annual taxable base"
    },
    "estimated_annual_irpf": {
      "type": "number",
      "format": "double",
      "description": "Estimated annual IRPF based on projected income"
    },
    "pending_annual_irpf": {
      "type": "number",
      "format": "double",
      "description": "Pending annual IRPF (estimated - retained)"
    },
    "bracket_details": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IrpfBracket"
      },
      "description": "IRPF breakdown by tax brackets"
    },
    "invoices": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/InvoiceFiscalData"
      },
      "description": "List of invoices included in the calculation"
    },
    "total_invoices": {
      "type": "integer",
      "description": "Total number of invoices"
    }
  },
  "required": [
    "queried_period",
    "total_taxable_base",
    "total_vat",
    "total_irpf_withheld",
    "period_base",
    "projected_annual_base",
    "estimated_annual_irpf",
    "pending_annual_irpf",
    "bracket_details",
    "total_invoices"
  ],
  "$defs": {
    "InvoiceFiscalData": {
      "type": "object",
      "description": "Invoice fiscal data for summary",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Invoice ID"
        },
        "invoice_number": {
          "type": "string",
          "description": "Invoice number"
        },
        "issue_date": {
          "type": "string",
          "format": "date",
          "description": "Issue date"
        },
        "customer_name": {
          "type": "string",
          "description": "Customer name"
        },
        "taxable_base": {
          "type": "number",
          "format": "double",
          "description": "Taxable base"
        },
        "total_vat": {
          "type": "number",
          "format": "double",
          "description": "Total indirect tax amount (IVA, IGIC, IPSI and other rates), not only VAT. See tax_breakdown for the split by tax type."
        },
        "total_irpf": {
          "type": "number",
          "format": "double",
          "description": "IRPF withholding amount"
        },
        "invoice_total": {
          "type": "number",
          "format": "double",
          "description": "Total invoice amount"
        }
      },
      "required": [
        "id",
        "invoice_number",
        "issue_date",
        "taxable_base",
        "total_vat",
        "total_irpf",
        "invoice_total"
      ]
    },
    "IrpfBracket": {
      "type": "object",
      "description": "IRPF tax bracket with calculated values",
      "properties": {
        "base_from": {
          "type": "number",
          "format": "double",
          "description": "Lower bound of taxable base"
        },
        "base_to": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Upper bound of taxable base (null for unlimited)"
        },
        "rate_percentage": {
          "type": "number",
          "format": "double",
          "description": "Tax rate percentage for this bracket"
        },
        "applicable_base": {
          "type": "number",
          "format": "double",
          "description": "Portion of income falling in this bracket"
        },
        "amount": {
          "type": "number",
          "format": "double",
          "description": "Tax amount for this bracket"
        }
      },
      "required": [
        "base_from",
        "rate_percentage",
        "applicable_base",
        "amount"
      ]
    },
    "QueriedPeriod": {
      "type": "object",
      "description": "Information about the queried period",
      "properties": {
        "start_date": {
          "type": "string",
          "format": "date",
          "description": "Period start date"
        },
        "end_date": {
          "type": "string",
          "format": "date",
          "description": "Period end date"
        },
        "days_included": {
          "type": "integer",
          "description": "Number of days included in the period"
        }
      },
      "required": [
        "start_date",
        "end_date",
        "days_included"
      ]
    },
    "SurchargeBreakdownItem": {
      "type": "object",
      "description": "Equivalence surcharge breakdown by rate. Same shape as `surcharge_breakdown` in the invoice detail.",
      "properties": {
        "type": {
          "type": "number",
          "format": "double",
          "description": "Surcharge rate percentage"
        },
        "base": {
          "type": "number",
          "format": "double",
          "description": "Taxable base subject to this surcharge rate"
        },
        "amount": {
          "type": "number",
          "format": "double",
          "description": "Surcharge amount (base * rate / 100)"
        }
      },
      "required": [
        "type",
        "base",
        "amount"
      ]
    },
    "TaxBreakdownItem": {
      "type": "object",
      "description": "Tax breakdown by type (IVA, IGIC, IPSI) and rate",
      "properties": {
        "tax_type": {
          "type": "string",
          "description": "Tax type: IVA, IGIC, IPSI, OTHER",
          "enum": [
            "IVA",
            "IGIC",
            "IPSI",
            "OTHER"
          ]
        },
        "percentage": {
          "type": "number",
          "format": "double",
          "description": "Tax rate percentage"
        },
        "taxable_base": {
          "type": "number",
          "format": "double",
          "description": "Taxable base for this tax type/rate"
        },
        "tax_amount": {
          "type": "number",
          "format": "double",
          "description": "Tax amount (base * rate / 100)"
        },
        "regime_key": {
          "type": "string",
          "description": "VeriFactu regime key of the rows grouped here. Rows are grouped by\n(tax type, rate, regime key), so an invoice mixing general-regime and OSS lines\nat the same rate yields TWO rows at `percentage: 21` that only this field tells\napart (`01` vs `17`). Index by `(tax_type, percentage, regime_key)`, never by\n`(tax_type, percentage)` alone.\n"
        }
      },
      "required": [
        "tax_type",
        "percentage",
        "taxable_base",
        "tax_amount"
      ]
    }
  }
}