> ## Documentation Index > Fetch the complete documentation index at: https://podpora.cubee.cz/llms.txt > Use this file to discover all available pages before exploring further. # Extract invoice data > Extracts structured data from an uploaded energy invoice PDF (multipart/form-data, field `file`) — the meta, distribution, buy/sell contract and observations the savings calculator consumes, plus any non-fatal validation warnings. Every upload first passes a cheap pre-flight gate that rejects anything that isn't an energy invoice. ## OpenAPI ````yaml /api-reference/swagger-partner.json post /api/v1/invoice-extraction openapi: 3.0.4 info: title: Partner API description: API for partner services version: v1 servers: - url: https://api.partner.cubee.cz description: Partnerý API server security: [] tags: - name: Aggregated Data - name: Authentication - name: Calculator - name: CalculatorControllerV1 - name: InvoiceExtraction - name: Public - name: Reference data - name: Studies paths: /api/v1/invoice-extraction: post: tags: - InvoiceExtraction summary: Extract invoice data description: >- Extracts structured data from an uploaded energy invoice PDF (multipart/form-data, field `file`) — the meta, distribution, buy/sell contract and observations the savings calculator consumes, plus any non-fatal validation warnings. Every upload first passes a cheap pre-flight gate that rejects anything that isn't an energy invoice. operationId: Extract Invoice requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary encoding: file: style: form responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/InvoiceExtractionResponseModel' examples: fix-two-tariff: summary: Fixed two-tariff supply (VT/NT) value: fileName: vyuctovani-elektrina.pdf invoice: meta: supplierName: Pražská energetika, a. s. invoiceNumber: '2025000123' issueDate: '2025-09-05' billingPeriodFrom: '2025-08-01' billingPeriodTo: '2025-08-31' ean: '859182400000000123' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: PRE PROUD PARTNER contractEndDate: '2025-12-31' energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: explicit distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 721.45 distributorFeeLowPerMWh: 206 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 600 buying: buyingType: FIX monthlyFeeCzk: 109 fixedBuyPriceCzkPerMwh: 3590 fixedBuyPriceCzkPerMwhLowTariff: 3290 spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 36 ntKwh: 504 totalKwh: 540 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 5010 buyAveragePricePerMwhNt: 4190 buyTotalCzkNoVat: 3011.91 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 3644 fieldConfidence: supplier_name: 1 distributor_key: 1 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 fixed_buy_price_czk_per_mwh: 1 distributor_fee_high_per_mwh: 1 distributor_fee_low_per_mwh: 1 monthly_fee_czk: 0.95 warnings: [] spot-both-sides: summary: Spot tariff, buy and sell value: fileName: vyuctovani-spot.pdf invoice: meta: supplierName: bezDodavatele invoiceNumber: '2025000456' issueDate: '2025-02-13' billingPeriodFrom: '2025-01-01' billingPeriodTo: '2025-01-31' ean: '859182400000000456' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: EL | D | Spot | 2T contractEndDate: null energyType: electricity invoiceDirection: both currency: CZK customerType: residential distribution: distributorKey: EGD distributorKeySource: poruchova_linka distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 718.76 distributorFeeLowPerMWh: 222.64 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 556 buying: buyingType: SPOT monthlyFeeCzk: 129.58 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: 450 spotTraderFeeType: PerMWh vtKwh: 234 ntKwh: 1326 totalKwh: 1560 yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 35.01 observations: buyAveragePricePerMwhVt: 5200 buyAveragePricePerMwhNt: 4700 buyTotalCzkNoVat: 8148.84 sellAveragePricePerMwh: 2743.22 sellTotalCzkNoVat: 96.04 balanceDueCzkWithVat: 7743.89 fieldConfidence: supplier_name: 1 distributor_key: 0.95 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 0.9 warnings: [] feed-in-only: summary: PV feed-in (výkup) only value: fileName: vykup-prebytku.pdf invoice: meta: supplierName: TRAMACO ENERGY s.r.o. (Electree) invoiceNumber: F2025000789 issueDate: '2025-06-12' billingPeriodFrom: '2025-03-20' billingPeriodTo: '2025-05-31' ean: '859182400000000789' customerName: Ukázka s.r.o. supplyPointAddress: Ukázková 123, 100 00 Praha productName: Mikro FVE contractEndDate: null energyType: electricity invoiceDirection: sell currency: CZK customerType: business distribution: distributorKey: null distributorKeySource: unknown distributionRate: null breakerSizeCode: null breakerAmps: null breakerPhases: null distributorFeeHighPerMWh: null distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: null systemServicesFeePerMWh: null circuitBreakerMonthlyFeeCzkInvoice: null buying: buyingType: null monthlyFeeCzk: null fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: null ntKwh: null totalKwh: null yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: 180 fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 86.84 observations: buyAveragePricePerMwhVt: null buyAveragePricePerMwhNt: null buyTotalCzkNoVat: null sellAveragePricePerMwh: null sellTotalCzkNoVat: 34.83 balanceDueCzkWithVat: -394.85 fieldConfidence: supplier_name: 0.8 distributor_key: 0 buying_type: 0 warnings: [] with-warning: summary: Extraction that raised a warning value: fileName: vyuctovani-jednotarif.pdf invoice: meta: supplierName: EnerSpot a.s. invoiceNumber: '2025000321' issueDate: '2025-06-16' billingPeriodFrom: '2025-05-17' billingPeriodTo: '2025-05-31' ean: '859182400000000321' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: Chytrá D-CuB-SPOT 250/247 contractEndDate: null energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: derived_from_address distributionRate: D02d breakerSizeCode: 3x25 breakerAmps: 25 breakerPhases: 3 distributorFeeHighPerMWh: 2099.63 distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 246 buying: buyingType: SPOT monthlyFeeCzk: 247 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 31 ntKwh: null totalKwh: 31 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 1670.79 buyAveragePricePerMwhNt: null buyTotalCzkNoVat: 608.69 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 736.51 fieldConfidence: supplier_name: 1 distributor_key: 0.75 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 1 warnings: - field: observations.buy_total_czk_no_vat level: warn reason: >- Reconstructed buy total 294.75 Kč (per-kWh 51.79 + per-month 242.96) is 52% off from extracted total 608.69 Kč. Possible extraction error in prices, consumption, monthly fees, or the total itself. extractedValue: 608.69 expectedHint: ~294.75 application/json: schema: $ref: '#/components/schemas/InvoiceExtractionResponseModel' examples: fix-two-tariff: summary: Fixed two-tariff supply (VT/NT) value: fileName: vyuctovani-elektrina.pdf invoice: meta: supplierName: Pražská energetika, a. s. invoiceNumber: '2025000123' issueDate: '2025-09-05' billingPeriodFrom: '2025-08-01' billingPeriodTo: '2025-08-31' ean: '859182400000000123' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: PRE PROUD PARTNER contractEndDate: '2025-12-31' energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: explicit distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 721.45 distributorFeeLowPerMWh: 206 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 600 buying: buyingType: FIX monthlyFeeCzk: 109 fixedBuyPriceCzkPerMwh: 3590 fixedBuyPriceCzkPerMwhLowTariff: 3290 spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 36 ntKwh: 504 totalKwh: 540 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 5010 buyAveragePricePerMwhNt: 4190 buyTotalCzkNoVat: 3011.91 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 3644 fieldConfidence: supplier_name: 1 distributor_key: 1 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 fixed_buy_price_czk_per_mwh: 1 distributor_fee_high_per_mwh: 1 distributor_fee_low_per_mwh: 1 monthly_fee_czk: 0.95 warnings: [] spot-both-sides: summary: Spot tariff, buy and sell value: fileName: vyuctovani-spot.pdf invoice: meta: supplierName: bezDodavatele invoiceNumber: '2025000456' issueDate: '2025-02-13' billingPeriodFrom: '2025-01-01' billingPeriodTo: '2025-01-31' ean: '859182400000000456' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: EL | D | Spot | 2T contractEndDate: null energyType: electricity invoiceDirection: both currency: CZK customerType: residential distribution: distributorKey: EGD distributorKeySource: poruchova_linka distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 718.76 distributorFeeLowPerMWh: 222.64 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 556 buying: buyingType: SPOT monthlyFeeCzk: 129.58 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: 450 spotTraderFeeType: PerMWh vtKwh: 234 ntKwh: 1326 totalKwh: 1560 yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 35.01 observations: buyAveragePricePerMwhVt: 5200 buyAveragePricePerMwhNt: 4700 buyTotalCzkNoVat: 8148.84 sellAveragePricePerMwh: 2743.22 sellTotalCzkNoVat: 96.04 balanceDueCzkWithVat: 7743.89 fieldConfidence: supplier_name: 1 distributor_key: 0.95 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 0.9 warnings: [] feed-in-only: summary: PV feed-in (výkup) only value: fileName: vykup-prebytku.pdf invoice: meta: supplierName: TRAMACO ENERGY s.r.o. (Electree) invoiceNumber: F2025000789 issueDate: '2025-06-12' billingPeriodFrom: '2025-03-20' billingPeriodTo: '2025-05-31' ean: '859182400000000789' customerName: Ukázka s.r.o. supplyPointAddress: Ukázková 123, 100 00 Praha productName: Mikro FVE contractEndDate: null energyType: electricity invoiceDirection: sell currency: CZK customerType: business distribution: distributorKey: null distributorKeySource: unknown distributionRate: null breakerSizeCode: null breakerAmps: null breakerPhases: null distributorFeeHighPerMWh: null distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: null systemServicesFeePerMWh: null circuitBreakerMonthlyFeeCzkInvoice: null buying: buyingType: null monthlyFeeCzk: null fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: null ntKwh: null totalKwh: null yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: 180 fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 86.84 observations: buyAveragePricePerMwhVt: null buyAveragePricePerMwhNt: null buyTotalCzkNoVat: null sellAveragePricePerMwh: null sellTotalCzkNoVat: 34.83 balanceDueCzkWithVat: -394.85 fieldConfidence: supplier_name: 0.8 distributor_key: 0 buying_type: 0 warnings: [] with-warning: summary: Extraction that raised a warning value: fileName: vyuctovani-jednotarif.pdf invoice: meta: supplierName: EnerSpot a.s. invoiceNumber: '2025000321' issueDate: '2025-06-16' billingPeriodFrom: '2025-05-17' billingPeriodTo: '2025-05-31' ean: '859182400000000321' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: Chytrá D-CuB-SPOT 250/247 contractEndDate: null energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: derived_from_address distributionRate: D02d breakerSizeCode: 3x25 breakerAmps: 25 breakerPhases: 3 distributorFeeHighPerMWh: 2099.63 distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 246 buying: buyingType: SPOT monthlyFeeCzk: 247 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 31 ntKwh: null totalKwh: 31 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 1670.79 buyAveragePricePerMwhNt: null buyTotalCzkNoVat: 608.69 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 736.51 fieldConfidence: supplier_name: 1 distributor_key: 0.75 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 1 warnings: - field: observations.buy_total_czk_no_vat level: warn reason: >- Reconstructed buy total 294.75 Kč (per-kWh 51.79 + per-month 242.96) is 52% off from extracted total 608.69 Kč. Possible extraction error in prices, consumption, monthly fees, or the total itself. extractedValue: 608.69 expectedHint: ~294.75 text/json: schema: $ref: '#/components/schemas/InvoiceExtractionResponseModel' examples: fix-two-tariff: summary: Fixed two-tariff supply (VT/NT) value: fileName: vyuctovani-elektrina.pdf invoice: meta: supplierName: Pražská energetika, a. s. invoiceNumber: '2025000123' issueDate: '2025-09-05' billingPeriodFrom: '2025-08-01' billingPeriodTo: '2025-08-31' ean: '859182400000000123' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: PRE PROUD PARTNER contractEndDate: '2025-12-31' energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: explicit distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 721.45 distributorFeeLowPerMWh: 206 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 600 buying: buyingType: FIX monthlyFeeCzk: 109 fixedBuyPriceCzkPerMwh: 3590 fixedBuyPriceCzkPerMwhLowTariff: 3290 spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 36 ntKwh: 504 totalKwh: 540 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 5010 buyAveragePricePerMwhNt: 4190 buyTotalCzkNoVat: 3011.91 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 3644 fieldConfidence: supplier_name: 1 distributor_key: 1 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 fixed_buy_price_czk_per_mwh: 1 distributor_fee_high_per_mwh: 1 distributor_fee_low_per_mwh: 1 monthly_fee_czk: 0.95 warnings: [] spot-both-sides: summary: Spot tariff, buy and sell value: fileName: vyuctovani-spot.pdf invoice: meta: supplierName: bezDodavatele invoiceNumber: '2025000456' issueDate: '2025-02-13' billingPeriodFrom: '2025-01-01' billingPeriodTo: '2025-01-31' ean: '859182400000000456' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: EL | D | Spot | 2T contractEndDate: null energyType: electricity invoiceDirection: both currency: CZK customerType: residential distribution: distributorKey: EGD distributorKeySource: poruchova_linka distributionRate: D45d breakerSizeCode: 3x32 breakerAmps: 32 breakerPhases: 3 distributorFeeHighPerMWh: 718.76 distributorFeeLowPerMWh: 222.64 renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 556 buying: buyingType: SPOT monthlyFeeCzk: 129.58 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: 450 spotTraderFeeType: PerMWh vtKwh: 234 ntKwh: 1326 totalKwh: 1560 yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 35.01 observations: buyAveragePricePerMwhVt: 5200 buyAveragePricePerMwhNt: 4700 buyTotalCzkNoVat: 8148.84 sellAveragePricePerMwh: 2743.22 sellTotalCzkNoVat: 96.04 balanceDueCzkWithVat: 7743.89 fieldConfidence: supplier_name: 1 distributor_key: 0.95 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 0.9 warnings: [] feed-in-only: summary: PV feed-in (výkup) only value: fileName: vykup-prebytku.pdf invoice: meta: supplierName: TRAMACO ENERGY s.r.o. (Electree) invoiceNumber: F2025000789 issueDate: '2025-06-12' billingPeriodFrom: '2025-03-20' billingPeriodTo: '2025-05-31' ean: '859182400000000789' customerName: Ukázka s.r.o. supplyPointAddress: Ukázková 123, 100 00 Praha productName: Mikro FVE contractEndDate: null energyType: electricity invoiceDirection: sell currency: CZK customerType: business distribution: distributorKey: null distributorKeySource: unknown distributionRate: null breakerSizeCode: null breakerAmps: null breakerPhases: null distributorFeeHighPerMWh: null distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: null systemServicesFeePerMWh: null circuitBreakerMonthlyFeeCzkInvoice: null buying: buyingType: null monthlyFeeCzk: null fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: null ntKwh: null totalKwh: null yearlyConsumptionKwhEstimated: null selling: sellingType: SPOT monthlyFeeCzk: 180 fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: 86.84 observations: buyAveragePricePerMwhVt: null buyAveragePricePerMwhNt: null buyTotalCzkNoVat: null sellAveragePricePerMwh: null sellTotalCzkNoVat: 34.83 balanceDueCzkWithVat: -394.85 fieldConfidence: supplier_name: 0.8 distributor_key: 0 buying_type: 0 warnings: [] with-warning: summary: Extraction that raised a warning value: fileName: vyuctovani-jednotarif.pdf invoice: meta: supplierName: EnerSpot a.s. invoiceNumber: '2025000321' issueDate: '2025-06-16' billingPeriodFrom: '2025-05-17' billingPeriodTo: '2025-05-31' ean: '859182400000000321' customerName: Jan Novák supplyPointAddress: Ukázková 123, 100 00 Praha productName: Chytrá D-CuB-SPOT 250/247 contractEndDate: null energyType: electricity invoiceDirection: buy currency: CZK customerType: residential distribution: distributorKey: CEZ distributorKeySource: derived_from_address distributionRate: D02d breakerSizeCode: 3x25 breakerAmps: 25 breakerPhases: 3 distributorFeeHighPerMWh: 2099.63 distributorFeeLowPerMWh: null renewableEnergyFeePerMWh: 495 systemServicesFeePerMWh: 170.92 circuitBreakerMonthlyFeeCzkInvoice: 246 buying: buyingType: SPOT monthlyFeeCzk: 247 fixedBuyPriceCzkPerMwh: null fixedBuyPriceCzkPerMwhLowTariff: null spotTraderFeePerMwh: null spotTraderFeeType: null vtKwh: 31 ntKwh: null totalKwh: 31 yearlyConsumptionKwhEstimated: null selling: sellingType: null monthlyFeeCzk: null fixedSellPriceCzkPerMwh: null spotTraderFeePerMwh: null spotTraderFeeType: null soldKwh: null observations: buyAveragePricePerMwhVt: 1670.79 buyAveragePricePerMwhNt: null buyTotalCzkNoVat: 608.69 sellAveragePricePerMwh: null sellTotalCzkNoVat: null balanceDueCzkWithVat: 736.51 fieldConfidence: supplier_name: 1 distributor_key: 0.75 distribution_rate: 1 breaker_size_code: 1 buying_type: 0.95 monthly_fee_czk: 1 warnings: - field: observations.buy_total_czk_no_vat level: warn reason: >- Reconstructed buy total 294.75 Kč (per-kWh 51.79 + per-month 242.96) is 52% off from extracted total 608.69 Kč. Possible extraction error in prices, consumption, monthly fees, or the total itself. extractedValue: 608.69 expectedHint: ~294.75 '400': description: Bad Request content: text/plain: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' text/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '401': description: Unauthorized content: text/plain: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' text/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '422': description: Unprocessable Content content: text/plain: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' text/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '500': description: Internal Server Error '503': description: Service Unavailable security: - {} components: schemas: InvoiceExtractionResponseModel: type: object properties: fileName: type: string description: Original file name of the uploaded invoice. nullable: true invoice: $ref: '#/components/schemas/ExtractedInvoice' warnings: type: array items: $ref: '#/components/schemas/ValidationWarning' description: >- Non-fatal warnings flagged during extraction (e.g. arithmetic mismatch, missing EAN). Empty when none. nullable: true additionalProperties: false description: >- Successful result of extracting a Czech energy invoice PDF: the structured data the savings calculator consumes, plus any non-fatal validation warnings raised during extraction (arithmetic/structural checks). ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} HttpValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: object additionalProperties: type: array items: type: string nullable: true additionalProperties: {} ExtractedInvoice: type: object properties: meta: $ref: '#/components/schemas/InvoiceMeta' distribution: $ref: '#/components/schemas/ExtractedDistribution' buying: $ref: '#/components/schemas/ExtractedBuying' selling: $ref: '#/components/schemas/ExtractedSelling' observations: $ref: '#/components/schemas/ExtractedObservations' fieldConfidence: type: object additionalProperties: type: number format: double description: >- Model confidence per field, keyed by field name (e.g. "distributor_key"), each 0.0–1.0. nullable: true additionalProperties: false description: >- Structured data extracted from a single Czech energy invoice, consumed by the Cubee savings calculator. ValidationWarning: type: object properties: field: type: string description: >- Field path the warning concerns (e.g. "buying.nt_kwh", "observations.buy_total_czk_no_vat"); may be a wildcard like "selling.*". nullable: true level: type: string description: 'Severity: "warn" (worth reviewing) or "error" (likely wrong).' nullable: true reason: type: string description: Human-readable explanation of the mismatch. nullable: true extractedValue: type: number description: >- The extracted value that triggered the warning, when numeric. Null when not applicable. format: double nullable: true expectedHint: type: string description: >- Short hint at what was expected instead (e.g. "null", "non-null", "[500-10000]"). Null when not applicable. nullable: true additionalProperties: false description: >- A non-fatal issue raised by the post-extraction sanity checks (arithmetic, tariff structure, ranges, EAN). InvoiceMeta: type: object properties: supplierName: type: string description: >- Supplier company name as printed. On "sell" invoices this is the buyer purchasing electricity from the customer. nullable: true invoiceNumber: type: string description: Invoice number / variabilní symbol. Null if not found. nullable: true issueDate: type: string description: Issue date, ISO format (YYYY-MM-DD). Null if not found. nullable: true billingPeriodFrom: type: string description: >- Start of the billing period, ISO format (YYYY-MM-DD). Null if not found. nullable: true billingPeriodTo: type: string description: >- End of the billing period, ISO format (YYYY-MM-DD). Null if not found. nullable: true ean: type: string description: >- 18-digit EAN of the supply point (odběrné místo). Null if not present. nullable: true customerName: type: string description: >- Customer full name or company name. On "sell" invoices this is the producer (výrobce). Null if not found. nullable: true supplyPointAddress: type: string description: Full address of the metered supply point. Null if not found. nullable: true productName: type: string description: >- Product/tariff name verbatim as printed (e.g. "elektřina Dynamik", "T-SPOT INDIVIDUAL"). Null if not found. nullable: true contractEndDate: type: string description: >- Contract end date / datum řádného ukončení závazku, ISO format (YYYY-MM-DD). Null if not found. nullable: true energyType: type: string description: 'Commodity billed: "electricity", "gas", or "both".' nullable: true invoiceDirection: type: string description: >- "buy" (standard bill), "sell" (výkup/buyback by an FVE producer), or "both" (one invoice with buy and sell sides). nullable: true currency: type: string description: >- Currency the invoice is denominated in: "CZK" (default) or "EUR" (some innogy B2B industrial invoices). nullable: true customerType: type: string description: >- "residential" (fyzická osoba, default) or "business" (právnická osoba with IČO/DIČ printed). nullable: true additionalProperties: false description: Invoice header and identity fields. ExtractedDistribution: type: object properties: distributorKey: type: string description: >- Distribution-grid operator: "CEZ", "EGD", or "PRE". Null if undetermined. Valid keys come from `GET /api/v1/reference/distributors`. nullable: true distributorKeySource: type: string description: >- How DistributorKey was derived: "explicit" (named in the regulated-services detail), "poruchova_linka" (footer fault line), "derived_from_address" (from PSČ, last resort), or "unknown". nullable: true distributionRate: type: string description: >- Distribution sazba code with lowercase 'd' suffix (e.g. "D02d", "D45d", "D57d"). Null if not found. Valid rates come from `GET /api/v1/reference/distribution-rates`. nullable: true breakerSizeCode: type: string description: >- Main-breaker size, strict enum: UP_TO_3x10, 3x16, 3x20, 3x25, 3x32, 3x40, 3x50, 3x63, 3x80, 3x100, 3x125, 3x160. Null if not found. Valid codes come from `GET /api/v1/reference/circuit-breakers`. nullable: true breakerAmps: type: integer description: >- Raw main-breaker amperage (amps) as printed (e.g. 25, 32, 63). Null if not found. format: int32 nullable: true breakerPhases: type: integer description: 'Number of phases: 1 or 3. Null if not found.' format: int32 nullable: true distributorFeeHighPerMWh: type: number description: >- VT (high-tariff) distribution fee in CZK/MWh, excl. VAT. Null if not found. Prefill baseline: `GET /api/v1/reference/fees` (field `distributorFeeHighPerMWh`). format: double nullable: true distributorFeeLowPerMWh: type: number description: >- NT (low-tariff) distribution fee in CZK/MWh, excl. VAT. Null for single-tariff sazby. Prefill baseline: `GET /api/v1/reference/fees` (field `distributorFeeLowPerMWh`). format: double nullable: true renewableEnergyFeePerMWh: type: number description: >- POZE / podpora výkupu z OZE fee in CZK/MWh, excl. VAT. Null if not found. Prefill baseline: `GET /api/v1/reference/fees` (field `renewableEnergyFeePerMWh`). format: double nullable: true systemServicesFeePerMWh: type: number description: >- Systémové služby (ČEPS) fee in CZK/MWh, excl. VAT. Null if not found. Prefill baseline: `GET /api/v1/reference/fees` (field `systemServicesFeePerMWh`). format: double nullable: true circuitBreakerMonthlyFeeCzkInvoice: type: number description: >- Monthly breaker charge (poplatek za jistič / stálý měsíční plat za příkon) in CZK/month, excl. VAT. Null if not found. Reference monthly fees per breaker size: `GET /api/v1/reference/circuit-breakers` (field `monthlyFeeCzk`). format: double nullable: true additionalProperties: false description: Regulated distribution terms parsed from the invoice. ExtractedBuying: type: object properties: buyingType: type: string description: >- Supply pricing model: "FIX" (single fixed silová price) or "SPOT" (spot-linked). Null on pure sell invoices. nullable: true monthlyFeeCzk: type: number description: >- Monthly supplier fee (stálý měsíční plat za dodávku) in CZK/month, excl. VAT; per-day fees normalized to per-month. Null if not found. format: double nullable: true fixedBuyPriceCzkPerMwh: type: number description: >- FIX only: VT silová elektřina price in CZK/MWh, excl. VAT. Null for SPOT. format: double nullable: true fixedBuyPriceCzkPerMwhLowTariff: type: number description: >- FIX only: NT silová elektřina price in CZK/MWh, excl. VAT. Null for SPOT or single-tariff. format: double nullable: true spotTraderFeePerMwh: type: number description: >- SPOT only: trader margin, extracted only when the invoice breaks it out as a separate line. Unit follows SpotTraderFeeType: CZK/MWh when "PerMWh", a percentage when "Percentage". Null for FIX or when the margin is bundled into the silová price. format: double nullable: true spotTraderFeeType: type: string description: >- SPOT only: how SpotTraderFeePerMwh is denominated: "PerMWh" (usual) or "Percentage". Null when no separate trader fee. nullable: true vtKwh: type: number description: >- VT (vysoký tarif / T1) energy bought during the billing period, in kWh. Null if not found. format: double nullable: true ntKwh: type: number description: >- NT (nízký tarif / T2) energy bought during the billing period, in kWh. Null for single-tariff sazby (D01d/D02d). format: double nullable: true totalKwh: type: number description: >- Total energy bought from the grid during the billing period, in kWh. Null if not found. format: double nullable: true yearlyConsumptionKwhEstimated: type: number description: >- Annualised consumption estimate in kWh, filled only when historic invoice data supports a reliable extrapolation. Null otherwise. format: double nullable: true additionalProperties: false description: >- Buy-side (dodávka) contract terms and consumption. All fields null on pure "sell" invoices. ExtractedSelling: type: object properties: sellingType: type: string description: >- Buyback pricing model: "FIX" (flat contract rate, rare) or "SPOT" (OTE spot weighted by production, common). Null on pure buy invoices. nullable: true monthlyFeeCzk: type: number description: >- Monthly admin/aggregator fee on the sell side in CZK/month, excl. VAT, recorded as a positive value. Null if not shown. format: double nullable: true fixedSellPriceCzkPerMwh: type: number description: >- FIX selling only: fixed per-MWh buyback rate from the contract, in CZK/MWh, excl. VAT. Null for SPOT. format: double nullable: true spotTraderFeePerMwh: type: number description: >- SPOT selling only: trader margin deducted from the raw spot price, only if shown as a separate line. Unit follows SpotTraderFeeType: CZK/MWh when "PerMWh", a percentage when "Percentage". Null otherwise. format: double nullable: true spotTraderFeeType: type: string description: >- SPOT selling only: how SpotTraderFeePerMwh is denominated: "PerMWh" or "Percentage". Null when no separate trader fee. nullable: true soldKwh: type: number description: >- Total energy sold to the grid (from FVE production) during the billing period, in kWh. Null if not found. format: double nullable: true additionalProperties: false description: >- Sell-side (výkup) contract terms and sold energy. All fields null on pure "buy" invoices. The realized per-MWh buyback average is intentionally not extracted here (the calculator computes it from OTE data). ExtractedObservations: type: object properties: buyAveragePricePerMwhVt: type: number description: >- Achieved weighted-average VT buy price for the period in CZK/MWh, excl. VAT. format: double nullable: true buyAveragePricePerMwhNt: type: number description: >- Achieved weighted-average NT buy price in CZK/MWh, excl. VAT. Null for single-tariff (D02d). format: double nullable: true buyTotalCzkNoVat: type: number description: >- Total the customer paid on the buy side (dodávka + distribuce + regulované) for the period, in CZK, excl. VAT. format: double nullable: true sellAveragePricePerMwh: type: number description: >- Achieved weighted-average sell (výkup) price in CZK/MWh, excl. VAT, as a positive value even if printed as a credit. format: double nullable: true sellTotalCzkNoVat: type: number description: >- Total the customer received on the sell side (výkup) for the period, in CZK, excl. VAT, as a positive value. format: double nullable: true balanceDueCzkWithVat: type: number description: >- Bottom-line balance including VAT, in CZK: positive = nedoplatek (to pay), negative = přeplatek (refund). format: double nullable: true additionalProperties: false description: >- Realized values printed on the invoice (typically page 1). Not calculator inputs — used for post-extraction sanity checks, UX display, and trend analysis. Each field null if not shown. ````