@golemio/energetics 1.13.0 → 1.13.1-dev.2769672204

package/docs/openapi-output.yaml

@@ -166,6 +166,25 @@ paths:
                 address, or consumption point, the response is 200 with the missing parts as `null` or
                 empty arrays (e.g. `building: null` when only consumption points or addresses are known).
                 404 is returned only when no source holds any data for the GID.
+
+                `consumption_history` carries monthly and yearly consumption per commodity, at building
+                level and again per consumption point. Sources are returned **in parallel** rather than
+                merged into one canonical series: metered readings and invoiced amounts legitimately
+                disagree, and which one a client wants depends on what it shows. `is_metered`
+                distinguishes them.
+
+                Coverage differs sharply by commodity and is a property of the data, not of the endpoint.
+                Gas has roughly three years of invoice history for about three quarters of its points.
+                Electricity is metered-only and starts in 2025, covering under a tenth of its points, so
+                most months come back `null`. Heat and water exist only as Porsenna yearly figures.
+                `measurement_data_from` and the per-series `data_from` say when data actually begins, so a
+                run of leading `null`s is explicable rather than looking like a fault.
+
+                Every aggregate carries its own provenance, so a client never has to present a summed
+                figure as if it were exact: `points_total`/`points_with_data` say how many consumption
+                points stand behind a period, `invoice_ids` names the billing documents an allocated
+                period came from, `coverage_count`/`expected_count` mark a partial period, and a point's
+                `shared_with` names the other buildings its meters also serve.
             parameters:
                 - in: path
                   name: gid
@@ -173,6 +192,19 @@ paths:
                   schema:
                       type: string
                       example: GID100
+                - in: query
+                  name: months
+                  required: false
+                  description: >-
+                      Months of consumption history to return, counted back from the last **complete**
+                      month. The current, partial month is always excluded: it is mid-accumulation and on a
+                      trend chart reads as a collapse rather than as incomplete data. The maximum matches
+                      the window the underlying index is built over.
+                  schema:
+                      type: integer
+                      minimum: 1
+                      maximum: 48
+                      default: 36
             responses:
                 "200":
                     description: OK
@@ -603,7 +635,6 @@ components:
                 registration_unit:
                     allOf:
                         - $ref: "#/components/schemas/EnergeticsEnoRegistrationUnit"
-                    nullable: true
                     description: >-
                         Evidenční jednotka (eno_ciselnik_evidencni_jednotka) resolved through eno_majetek;
                         null when the building has no majetek record. Its name is part of the search vector.
@@ -714,9 +745,13 @@ components:
 
         EnergeticsEnoRegistrationUnit:
             type: object
+            # nullable lives here, next to `type`: OpenAPI 3.0 ignores a `nullable` that sits beside
+            # an allOf reference, and portman turns that shape into an invalid JSON Schema.
+            nullable: true
             description: >-
                 Evidenční jednotka (eno_ciselnik_evidencni_jednotka) resolved through the building's
                 eno_majetek record. The same shape is returned by the search and the detail endpoint.
+                Null when the building has no majetek record.
             properties:
                 id:
                     type: number
@@ -746,17 +781,37 @@ components:
                 gid:
                     type: string
                     example: GID100
+                name:
+                    type: string
+                    nullable: true
+                    description: >-
+                        Display name of the building: `building.nazev`, then the Porsenna building name,
+                        then null. `building` is null for a substantial share of GIDs and the card still
+                        has to render a header, so the fallback is resolved here — the same chain the
+                        search endpoint uses — rather than in every client, where the versions would
+                        disagree.
+                    example: ZŠ Testovací
+                address:
+                    type: string
+                    nullable: true
+                    description: >-
+                        Main address of the building: the first described `addresses[]` entry (they are
+                        ordered main-address first), then the Porsenna address, then null.
+                    example: Testovací 123/4, 100 00 Praha 10
                 building:
                     type: object
                     nullable: true
                     description: >-
                         All available eno_budova attributes (Czech identifiers mirror the upstream ENO source).
                         Null when the GID has no ENO building record and is known only through the
-                        consumption-point mapping.
+                        consumption-point mapping. Every property below is always present when the object
+                        is; `additionalProperties` stays open so an upstream ENO addition is not breaking.
                     properties:
                         zdroj:
                             type: string
                             nullable: true
+                            description: ENO source system the row was read from (mhmp / stat).
+                            example: mhmp
                         nazev:
                             type: string
                             nullable: true
@@ -766,6 +821,8 @@ components:
                         druh_vytapeni:
                             type: string
                             nullable: true
+                            description: Heating type as recorded in ENO.
+                            example: ústřední dálkové
                         pripojka_elektro:
                             type: string
                             nullable: true
@@ -775,6 +832,71 @@ components:
                         pripojka_kanalizace:
                             type: string
                             nullable: true
+                        budova_rozdelena_byt_nebyt:
+                            type: string
+                            nullable: true
+                        celkova_plocha_budova:
+                            type: number
+                            nullable: true
+                            description: Total floor area, m².
+                        celkova_plocha_byt_budova:
+                            type: number
+                            nullable: true
+                        celkova_plocha_nebyt_budova:
+                            type: number
+                            nullable: true
+                        zastavena_plocha:
+                            type: number
+                            nullable: true
+                            description: Built-up area, m².
+                        obestaveny_prostor:
+                            type: number
+                            nullable: true
+                            description: Enclosed volume, m³.
+                        pocet_byt:
+                            type: number
+                            nullable: true
+                        pocet_nebyt_budova:
+                            type: number
+                            nullable: true
+                        pocet_nadzem_podlazi:
+                            type: number
+                            nullable: true
+                        pocet_podzem_podlazi:
+                            type: number
+                            nullable: true
+                        pocet_podkrovi:
+                            type: number
+                            nullable: true
+                        vytah:
+                            type: boolean
+                            nullable: true
+                        czcc:
+                            type: number
+                            nullable: true
+                        id_cuzk:
+                            type: number
+                            nullable: true
+                        id_objekt:
+                            type: number
+                            nullable: true
+                        kod_vyuziti:
+                            type: string
+                            nullable: true
+                        nazev_vyuziti:
+                            type: string
+                            nullable: true
+                            example: budova občanské vybavenosti
+                        kod_ochrana:
+                            type: string
+                            nullable: true
+                        nazev_ochrana:
+                            type: string
+                            nullable: true
+                        platnost_od:
+                            type: string
+                            format: date-time
+                            nullable: true
                     additionalProperties: true
                 property:
                     type: object
@@ -786,7 +908,6 @@ components:
                         registration_unit:
                             allOf:
                                 - $ref: "#/components/schemas/EnergeticsEnoRegistrationUnit"
-                            nullable: true
                             description: Evidenční jednotka (eno_ciselnik_evidencni_jednotka).
                         managers:
                             type: object
@@ -852,7 +973,7 @@ components:
                     properties:
                         source:
                             type: string
-                            example: porsenna_p7
+                            example: prague-7
                         building_name:
                             type: string
                             nullable: true
@@ -863,13 +984,180 @@ components:
                             type: number
                         devices_active:
                             type: number
+                        data_to:
+                            type: string
+                            format: date
+                            nullable: true
+                            description: >-
+                                Most recent date any of this building's Porsenna devices reported; null when
+                                none of them has consumption. Porsenna aggregates carry a covered-day count
+                                rather than a reading timestamp, so this is the period start plus its covered
+                                days, clamped to the end of the period. A meter count without an as-of date is
+                                a claim with no expiry.
+                            example: 2026-08-12
+                consumption_history:
+                    $ref: "#/components/schemas/EnergeticsEnoConsumptionHistory"
                 consumption_points:
                     type: array
                     items:
                         $ref: "#/components/schemas/EnergeticsEnoConsumptionPoint"
+        EnergeticsEnoConsumptionEntry:
+            type: object
+            description: >-
+                One period of one series. `value: null` means the source has no data for that period -
+                missing periods are always null, never an error and never a zero.
+            properties:
+                period:
+                    type: string
+                    description: "`YYYY-MM` for monthly entries, `YYYY` for yearly ones."
+                    example: 2026-07
+                value:
+                    type: number
+                    nullable: true
+                value_kwh:
+                    type: number
+                    nullable: true
+                    description: >-
+                        Comparable energy. For gas this is derived (normometers_nm3 * combustion_heat) and is
+                        null whenever the conversion inputs are missing; `value` + `unit` stay authoritative.
+                        A yearly entry withholds it unless every contributing month has one, so it can never
+                        imply a conversion rate that did not exist.
+                coverage_count:
+                    type: number
+                    description: Days of the period carrying data.
+                expected_count:
+                    type: number
+                    description: Days in the period, so a partial period is recognisable as one.
+                is_estimated:
+                    type: boolean
+                    description: >-
+                        True when the value was allocated pro rata from a billing period spanning more than
+                        one month, rather than read for the period itself.
+                points_total:
+                    type: number
+                    description: >-
+                        Consumption points that contributed this period at all. `0` for a period no point
+                        reported — never null, so a gap is a number a client can compare.
+                points_with_data:
+                    type: number
+                    description: >-
+                        Of those, how many carried a value. A shortfall against the series' `points` is how a
+                        client learns a building summary is missing an OM for this period rather than being
+                        genuinely lower — at point grain the counts are 1/1 or 0/0.
+                invoice_ids:
+                    type: array
+                    description: >-
+                        Billing documents this period was allocated from, sorted. Empty for metered readings,
+                        for Porsenna and for periods with no value. An allocated month is a number the
+                        platform computed rather than one anyone read, so naming the invoice is what makes it
+                        auditable. At building level a period can be allocated from several invoices (one per
+                        point), and a yearly entry usually is; at point grain a month is normally one.
+                    items:
+                        type: string
+                    example: ["DI-2026-001"]
+        EnergeticsEnoConsumptionSeries:
+            type: object
+            description: One source's view of one commodity, for one unit.
+            properties:
+                source:
+                    type: string
+                    enum:
+                        - predi_input
+                        - ppas_ave_api
+                        - ppas_distribution_invoice
+                        - ppas_commercial_invoice
+                        - porsenna
+                unit:
+                    type: string
+                    description: >-
+                        Electricity is kWh. Metered gas is m3 (from the PPAS operating difference) or Nm3
+                        where only the converted difference exists - a point whose unit changes mid-window
+                        appears as two series with complementary gaps, which is why unit is part of the key.
+                        Porsenna carries its own lowercase unit.
+                    example: m3
+                is_metered:
+                    type: boolean
+                    description: False for invoiced (billed and allocated) figures, true for meter readings.
+                points:
+                    type: array
+                    description: Consumption points contributing to this series.
+                    items:
+                        type: string
+                data_from:
+                    type: string
+                    nullable: true
+                    description: Earliest period this series has any value for; null when it has none.
+                monthly:
+                    type: array
+                    description: >-
+                        `months` entries, chronological, null-filled where the source has nothing. Empty
+                        when the source reports only yearly aggregates (Porsenna) - its data is in
+                        `yearly`.
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionEntry"
+                yearly:
+                    type: array
+                    description: >-
+                        One entry per calendar year the window touches, plus any earlier year that has data -
+                        Porsenna reaches back further than any monthly source and is not truncated to the
+                        months window.
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionEntry"
+        EnergeticsEnoConsumptionHistory:
+            type: object
+            description: >-
+                Consumption per commodity per source. An empty array for a commodity means no source knows
+                this building at all, which is distinct from a series of nulls - that means the source knows
+                the point but not those periods.
+            properties:
+                period_from:
+                    type: string
+                    example: 2023-08
+                period_to:
+                    type: string
+                    description: Always the last complete month.
+                    example: 2026-07
+                months:
+                    type: number
+                    example: 36
+                measurement_data_from:
+                    type: string
+                    nullable: true
+                    description: >-
+                        Earliest month (`YYYY-MM`) with data from a metered source; null when no metered
+                        source has monthly data. Explains the leading nulls - meter data starts in 2025
+                        platform-wide. A yearly-only series does not count; its reach-back stays visible
+                        in the series' own `data_from`.
+                    example: 2025-01
+                has_shared_points:
+                    type: boolean
+                    description: >-
+                        True when a contributing consumption point is also mapped to another building. The
+                        totals still count such a point in full - that is what its meters measured - so this
+                        flag is how a client learns the figure is not exclusive to this building. It is true
+                        for both sides of a shared point, primary or not; the points' `shared_with` says
+                        which buildings those are.
+                electricity:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
+                gas:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
+                heat:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
+                water:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
         EnergeticsEnoPorsennaBlock:
             type: object
-            description: Porsenna (e-manazer) device detail with sub-meters and yearly consumption aggregates
+            description: >-
+                Porsenna (e-manazer) device detail with sub-meters. The device's consumption is in the
+                point's `consumption_history` as the `porsenna` series.
             properties:
                 device:
                     type: object
@@ -879,22 +1167,310 @@ components:
                     items:
                         type: object
                         additionalProperties: true
-                yearly_consumption:
-                    type: array
-                    items:
-                        type: object
-                        properties:
-                            period:
-                                type: string
-                                example: "2024"
-                            value:
-                                type: number
-                            unit:
-                                type: string
-                                example: GJ
-                            days_covered:
-                                type: number
-                                nullable: true
+        EnergeticsEnoElectricityMetadata:
+            type: object
+            # nullable lives here, next to `type`: OpenAPI 3.0 ignores a `nullable` that sits beside
+            # an allOf reference, and portman turns that shape into an invalid JSON Schema.
+            nullable: true
+            description: >-
+                Latest available month of PRE metadata for the EAN, i.e. the technical parameters of
+                the delivery point as PRE last reported them. Null when PRE has never reported it.
+                Every property is always present; `additionalProperties` stays open so an upstream PRE
+                addition is not breaking.
+            properties:
+                year:
+                    type: number
+                    nullable: true
+                    description: Year and month of the metadata row these values come from.
+                    example: 2026
+                month:
+                    type: number
+                    nullable: true
+                    example: 6
+                month_name:
+                    type: string
+                    nullable: true
+                    example: červen
+                days_in_stored_month:
+                    type: number
+                    nullable: true
+                consumption_point:
+                    type: string
+                    nullable: true
+                    example: OM Testovací 123
+                address:
+                    type: string
+                    nullable: true
+                location_type:
+                    type: string
+                    nullable: true
+                    example: škola
+                company_name:
+                    type: string
+                    nullable: true
+                company_id:
+                    type: string
+                    nullable: true
+                tarif_type:
+                    type: string
+                    nullable: true
+                    example: C02d
+                tarif_1t2t:
+                    type: string
+                    nullable: true
+                    example: 1T
+                phases:
+                    type: string
+                    nullable: true
+                    example: "3"
+                circuit_breaker:
+                    type: string
+                    nullable: true
+                    example: 3x125A
+                type_b_meter:
+                    type: string
+                    nullable: true
+                meter_replaced:
+                    type: string
+                    nullable: true
+                    description: >-
+                        Meter number, or a pipe-separated `date|old|new` triple for the month the meter was
+                        replaced. Free text as PRE supplies it, not a parsed structure.
+                    example: 2026-06-19|53435572|54292510
+            additionalProperties: true
+        EnergeticsEnoGasInvoice:
+            type: object
+            description: >-
+                PPAS invoice header. The distribution and commercial invoices carry the same properties;
+                only their sources differ.
+            properties:
+                id:
+                    type: string
+                    example: DI-2026-001
+                preceding_id:
+                    type: string
+                    nullable: true
+                    description: The invoice this one supersedes, when the two are linked upstream.
+                customer_id:
+                    type: string
+                    nullable: true
+                customer_company_id:
+                    type: string
+                    nullable: true
+                customer_name:
+                    type: string
+                    nullable: true
+                customer_contract_account_id:
+                    type: string
+                    nullable: true
+                customer_address_street:
+                    type: string
+                    nullable: true
+                customer_address_house_number:
+                    type: string
+                    nullable: true
+                customer_address_house_org_number:
+                    type: string
+                    nullable: true
+                customer_address_city:
+                    type: string
+                    nullable: true
+                customer_address_city_part:
+                    type: string
+                    nullable: true
+                customer_address_post_code:
+                    type: string
+                    nullable: true
+                customer_address_country:
+                    type: string
+                    nullable: true
+                customer_address_ruian_id:
+                    type: number
+                    nullable: true
+                facts_doc_date:
+                    type: string
+                    format: date
+                    nullable: true
+                facts_net_date:
+                    type: string
+                    format: date
+                    nullable: true
+                facts_billing_transaction:
+                    type: string
+                    nullable: true
+                    example: FAKTURACE
+                facts_to_pay_amount:
+                    type: number
+                    nullable: true
+                facts_currency:
+                    type: string
+                    nullable: true
+                    example: CZK
+                facts_price_brutto:
+                    type: number
+                    nullable: true
+                is_canceled:
+                    type: boolean
+                    nullable: true
+                    description: Always false here — canceled invoices are not served.
+                canceled_reason:
+                    type: string
+                    nullable: true
+            additionalProperties: true
+        EnergeticsEnoGasInstallation:
+            type: object
+            description: >-
+                The installation (odběrné místo) the invoice bills, as recorded on it. The PPAS-internal
+                place id is deliberately not exposed; it only scopes `devices` and `prices` server-side.
+            properties:
+                billing_class:
+                    type: string
+                    nullable: true
+                    example: MO
+                measurement_type:
+                    type: string
+                    nullable: true
+                contract_contract_id:
+                    type: string
+                    nullable: true
+                contract_move_in_date:
+                    type: string
+                    format: date
+                    nullable: true
+                contract_move_out_date:
+                    type: string
+                    format: date
+                    nullable: true
+                tdd_class:
+                    type: string
+                    nullable: true
+                    description: Type-day-diagram class used for the allocation of unmetered consumption.
+                    example: DOM4
+                address_street:
+                    type: string
+                    nullable: true
+                address_house_number:
+                    type: string
+                    nullable: true
+                address_house_org_number:
+                    type: string
+                    nullable: true
+                address_city:
+                    type: string
+                    nullable: true
+                address_city_part:
+                    type: string
+                    nullable: true
+                address_post_code:
+                    type: string
+                    nullable: true
+                address_country:
+                    type: string
+                    nullable: true
+                address_ruian_id:
+                    type: number
+                    nullable: true
+            additionalProperties: true
+        EnergeticsEnoGasInvoiceDevice:
+            type: object
+            description: >-
+                One billed meter period of the invoice. `kind` is a SAP code and the same gas can appear
+                under several of them in different dimensions, so these rows are the billing detail, not a
+                series to sum — the summed and month-allocated figures are in `consumption_history`.
+            properties:
+                device_serial_number:
+                    type: string
+                    example: PLYN-001
+                date_from:
+                    type: string
+                    format: date
+                date_to:
+                    type: string
+                    format: date
+                reading_type:
+                    type: string
+                    description: STANDARD or CORRECTION.
+                    example: STANDARD
+                type:
+                    type: string
+                    description: Meter type.
+                    example: G4
+                kind:
+                    type: string
+                    description: SAP code of the billed quantity (ZIZWC, ZIABN3, …).
+                    example: ZIZWC
+                reading_from:
+                    type: number
+                    nullable: true
+                reading_to:
+                    type: number
+                    nullable: true
+                consumption:
+                    type: number
+                    nullable: true
+                    description: Denominated by `unit`, which is not always m³.
+                unit:
+                    type: string
+                    nullable: true
+                    example: M3
+                meter_reading_type:
+                    type: string
+                    nullable: true
+                    example: dálkový
+                gas_consumption_kwh:
+                    type: number
+                    nullable: true
+                    description: 0 means "not supplied" rather than zero.
+                volume_coefficient:
+                    type: number
+                    nullable: true
+                combustion_heat:
+                    type: number
+                    nullable: true
+                    description: kWh/m³; 0 means "not supplied" rather than zero.
+                normometers_nm3:
+                    type: number
+                    nullable: true
+            additionalProperties: true
+        EnergeticsEnoGasInvoicePrice:
+            type: object
+            description: One priced line of the invoice for this installation.
+            properties:
+                date_from:
+                    type: string
+                    format: date
+                date_to:
+                    type: string
+                    format: date
+                kind:
+                    type: string
+                    example: distribuce
+                description:
+                    type: string
+                    example: Distribuce plynu
+                price_group:
+                    type: string
+                quantity:
+                    type: number
+                unit:
+                    type: string
+                    example: kWh
+                unit_price:
+                    type: number
+                time_slot:
+                    type: number
+                    nullable: true
+                price_netto:
+                    type: number
+                price_type:
+                    type: string
+                    example: variabilní
+                currency:
+                    type: string
+                    example: CZK
+                tax_rate:
+                    type: number
+            additionalProperties: true
         EnergeticsEnoConsumptionPoint:
             type: object
             properties:
@@ -909,6 +1485,31 @@ components:
                     enum: [electricity, gas, heat, water]
                 is_first_gid:
                     type: boolean
+                    description: >-
+                        Whether this building is the primary holder of the point in the mapping. It says
+                        nothing about the other side — see `shared_with`, which lists the buildings the point
+                        is shared with whether this one is primary or not.
+                shared_with:
+                    type: array
+                    description: >-
+                        Other buildings the same consumption point is mapped to. Empty when the point belongs
+                        to this building alone, which is the common case. The totals still count the point in
+                        full — that is what its meters measured — so this is how a client learns the figure is
+                        not exclusive to this building, and which building it is shared with.
+                    items:
+                        type: object
+                        properties:
+                            gid:
+                                type: string
+                                example: GID200
+                            name:
+                                type: string
+                                nullable: true
+                                description: Resolved as the detail's top-level `name` is; null when neither source names it.
+                                example: MŠ Vedlejší
+                        required:
+                            - gid
+                            - name
                 is_active:
                     type: boolean
                     description: Derived from valid_to (null or in the future means the mapping is active)
@@ -932,72 +1533,91 @@ components:
                     description: Electricity-specific data (present only for commodity = electricity, omitted otherwise)
                     properties:
                         metadata:
-                            type: object
-                            nullable: true
-                            description: Latest available month of PRE metadata for the EAN
-                            additionalProperties: true
+                            allOf:
+                                - $ref: "#/components/schemas/EnergeticsEnoElectricityMetadata"
+                            description: >-
+                                Latest available month of PRE metadata for the EAN; null when PRE has never
+                                reported it.
                         porsenna:
                             $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                        consumption_history:
+                            type: array
+                            description: Per-source series for this point; empty when no source knows it.
+                            items:
+                                $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
                 gas:
                     type: object
                     description: Gas-specific data (present only for commodity = gas, omitted otherwise)
                     properties:
                         porsenna:
                             $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                        consumption_history:
+                            type: array
+                            description: Per-source series for this point; empty when no source knows it.
+                            items:
+                                $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
                         distribution:
                             type: object
                             nullable: true
-                            description: Latest non-canceled PPAS distribution invoice with its installation, devices and prices
+                            description: >-
+                                Latest non-canceled PPAS distribution invoice for this EIC with its
+                                installation, billed meter periods and priced lines. Devices and prices are
+                                scoped to this point's installation, so another installation on the same
+                                invoice does not leak in. Null when no distribution invoice knows the point.
                             properties:
                                 invoice:
-                                    type: object
-                                    additionalProperties: true
+                                    $ref: "#/components/schemas/EnergeticsEnoGasInvoice"
                                 installation:
-                                    type: object
-                                    additionalProperties: true
+                                    $ref: "#/components/schemas/EnergeticsEnoGasInstallation"
                                 devices:
                                     type: array
                                     items:
-                                        type: object
-                                        additionalProperties: true
+                                        $ref: "#/components/schemas/EnergeticsEnoGasInvoiceDevice"
                                 prices:
                                     type: array
                                     items:
-                                        type: object
-                                        additionalProperties: true
+                                        $ref: "#/components/schemas/EnergeticsEnoGasInvoicePrice"
                         commercial:
                             type: object
                             nullable: true
-                            description: Latest non-canceled PPAS commercial invoice with its installation, devices and prices
+                            description: >-
+                                Latest non-canceled PPAS commercial invoice for this EIC, in the same shape as
+                                `distribution`. Null when no commercial invoice knows the point.
                             properties:
                                 invoice:
-                                    type: object
-                                    additionalProperties: true
+                                    $ref: "#/components/schemas/EnergeticsEnoGasInvoice"
                                 installation:
-                                    type: object
-                                    additionalProperties: true
+                                    $ref: "#/components/schemas/EnergeticsEnoGasInstallation"
                                 devices:
                                     type: array
                                     items:
-                                        type: object
-                                        additionalProperties: true
+                                        $ref: "#/components/schemas/EnergeticsEnoGasInvoiceDevice"
                                 prices:
                                     type: array
                                     items:
-                                        type: object
-                                        additionalProperties: true
+                                        $ref: "#/components/schemas/EnergeticsEnoGasInvoicePrice"
                 heat:
                     type: object
                     description: Heat-specific data (present only for commodity = heat, omitted otherwise; Porsenna-sourced)
                     properties:
                         porsenna:
                             $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                        consumption_history:
+                            type: array
+                            description: Per-source series for this point; empty when no source knows it.
+                            items:
+                                $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
                 water:
                     type: object
                     description: Water-specific data (present only for commodity = water, omitted otherwise; Porsenna-sourced)
                     properties:
                         porsenna:
                             $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                        consumption_history:
+                            type: array
+                            description: Per-source series for this point; empty when no source knows it.
+                            items:
+                                $ref: "#/components/schemas/EnergeticsEnoConsumptionSeries"
         EnergeticsBuildingShort:
             type: object
             properties: