--- title: "Extract invoice data" method: POST path: "/api/v1/invoice-extraction" tags: ["InvoiceExtraction"] --- # Extract invoice data `POST /api/v1/invoice-extraction` ## Request - Base URL: `https://api.partner.cubee.cz` - URL: `https://api.partner.cubee.cz/api/v1/invoice-extraction` - Auth: none required 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. ## Request body `multipart/form-data` - object - `file` string, binary ## Response `200` OK - InvoiceExtractionResponseModel: 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). - `fileName` string, nullable: Original file name of the uploaded invoice. - `invoice` ExtractedInvoice: Structured data extracted from a single Czech energy invoice, consumed by the Cubee savings calculator. - `meta` InvoiceMeta: Invoice header and identity fields. - `supplierName` string, nullable: Supplier company name as printed. On "sell" invoices this is the buyer purchasing electricity from the customer. - `invoiceNumber` string, nullable: Invoice number / variabilní symbol. Null if not found. - `issueDate` string, nullable: Issue date, ISO format (YYYY-MM-DD). Null if not found. - `billingPeriodFrom` string, nullable: Start of the billing period, ISO format (YYYY-MM-DD). Null if not found. - `billingPeriodTo` string, nullable: End of the billing period, ISO format (YYYY-MM-DD). Null if not found. - `ean` string, nullable: 18-digit EAN of the supply point (odběrné místo). Null if not present. - `customerName` string, nullable: Customer full name or company name. On "sell" invoices this is the producer (výrobce). Null if not found. - `supplyPointAddress` string, nullable: Full address of the metered supply point. Null if not found. - `productName` string, nullable: Product/tariff name verbatim as printed (e.g. "elektřina Dynamik", "T-SPOT INDIVIDUAL"). Null if not found. - `contractEndDate` string, nullable: Contract end date / datum řádného ukončení závazku, ISO format (YYYY-MM-DD). Null if not found. - `energyType` string, nullable: Commodity billed: "electricity", "gas", or "both". - `invoiceDirection` string, nullable: "buy" (standard bill), "sell" (výkup/buyback by an FVE producer), or "both" (one invoice with buy and sell sides). - `currency` string, nullable: Currency the invoice is denominated in: "CZK" (default) or "EUR" (some innogy B2B industrial invoices). - `customerType` string, nullable: "residential" (fyzická osoba, default) or "business" (právnická osoba with IČO/DIČ printed). - `distribution` ExtractedDistribution: Regulated distribution terms parsed from the invoice. - `distributorKey` string, nullable: Distribution-grid operator: "CEZ", "EGD", or "PRE". Null if undetermined. Valid keys come from `GET /api/v1/reference/distributors`. - `distributorKeySource` string, nullable: 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". - `distributionRate` string, nullable: 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`. - `breakerSizeCode` string, nullable: 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`. - `breakerAmps` integer, nullable: Raw main-breaker amperage (amps) as printed (e.g. 25, 32, 63). Null if not found. - `breakerPhases` integer, nullable: Number of phases: 1 or 3. Null if not found. - `distributorFeeHighPerMWh` number, double, nullable: VT (high-tariff) distribution fee in CZK/MWh, excl. VAT. Null if not found. Prefill baseline: `GET /api/v1/reference/fees` (field `distributorFeeHighPerMWh`). - `distributorFeeLowPerMWh` number, double, nullable: NT (low-tariff) distribution fee in CZK/MWh, excl. VAT. Null for single-tariff sazby. Prefill baseline: `GET /api/v1/reference/fees` (field `distributorFeeLowPerMWh`). - `renewableEnergyFeePerMWh` number, double, nullable: 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`). - `systemServicesFeePerMWh` number, double, nullable: Systémové služby (ČEPS) fee in CZK/MWh, excl. VAT. Null if not found. Prefill baseline: `GET /api/v1/reference/fees` (field `systemServicesFeePerMWh`). - `circuitBreakerMonthlyFeeCzkInvoice` number, double, nullable: 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`). - `buying` ExtractedBuying: Buy-side (dodávka) contract terms and consumption. All fields null on pure "sell" invoices. - `buyingType` string, nullable: Supply pricing model: "FIX" (single fixed silová price) or "SPOT" (spot-linked). Null on pure sell invoices. - `monthlyFeeCzk` number, double, nullable: 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. - `fixedBuyPriceCzkPerMwh` number, double, nullable: FIX only: VT silová elektřina price in CZK/MWh, excl. VAT. Null for SPOT. - `fixedBuyPriceCzkPerMwhLowTariff` number, double, nullable: FIX only: NT silová elektřina price in CZK/MWh, excl. VAT. Null for SPOT or single-tariff. - `spotTraderFeePerMwh` number, double, nullable: 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. - `spotTraderFeeType` string, nullable: SPOT only: how SpotTraderFeePerMwh is denominated: "PerMWh" (usual) or "Percentage". Null when no separate trader fee. - `vtKwh` number, double, nullable: VT (vysoký tarif / T1) energy bought during the billing period, in kWh. Null if not found. - `ntKwh` number, double, nullable: NT (nízký tarif / T2) energy bought during the billing period, in kWh. Null for single-tariff sazby (D01d/D02d). - `totalKwh` number, double, nullable: Total energy bought from the grid during the billing period, in kWh. Null if not found. - `yearlyConsumptionKwhEstimated` number, double, nullable: Annualised consumption estimate in kWh, filled only when historic invoice data supports a reliable extrapolation. Null otherwise. - `selling` ExtractedSelling: 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). - `sellingType` string, nullable: Buyback pricing model: "FIX" (flat contract rate, rare) or "SPOT" (OTE spot weighted by production, common). Null on pure buy invoices. - `monthlyFeeCzk` number, double, nullable: Monthly admin/aggregator fee on the sell side in CZK/month, excl. VAT, recorded as a positive value. Null if not shown. - `fixedSellPriceCzkPerMwh` number, double, nullable: FIX selling only: fixed per-MWh buyback rate from the contract, in CZK/MWh, excl. VAT. Null for SPOT. - `spotTraderFeePerMwh` number, double, nullable: 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. - `spotTraderFeeType` string, nullable: SPOT selling only: how SpotTraderFeePerMwh is denominated: "PerMWh" or "Percentage". Null when no separate trader fee. - `soldKwh` number, double, nullable: Total energy sold to the grid (from FVE production) during the billing period, in kWh. Null if not found. - `observations` ExtractedObservations: 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. - `buyAveragePricePerMwhVt` number, double, nullable: Achieved weighted-average VT buy price for the period in CZK/MWh, excl. VAT. - `buyAveragePricePerMwhNt` number, double, nullable: Achieved weighted-average NT buy price in CZK/MWh, excl. VAT. Null for single-tariff (D02d). - `buyTotalCzkNoVat` number, double, nullable: Total the customer paid on the buy side (dodávka + distribuce + regulované) for the period, in CZK, excl. VAT. - `sellAveragePricePerMwh` number, double, nullable: Achieved weighted-average sell (výkup) price in CZK/MWh, excl. VAT, as a positive value even if printed as a credit. - `sellTotalCzkNoVat` number, double, nullable: Total the customer received on the sell side (výkup) for the period, in CZK, excl. VAT, as a positive value. - `balanceDueCzkWithVat` number, double, nullable: Bottom-line balance including VAT, in CZK: positive = nedoplatek (to pay), negative = přeplatek (refund). - `fieldConfidence` object, nullable: Model confidence per field, keyed by field name (e.g. "distributor_key"), each 0.0–1.0. - `warnings` ValidationWarning[], nullable: Non-fatal warnings flagged during extraction (e.g. arithmetic mismatch, missing EAN). Empty when none. - `field` string, nullable: Field path the warning concerns (e.g. "buying.nt_kwh", "observations.buy_total_czk_no_vat"); may be a wildcard like "selling.*". - `level` string, nullable: Severity: "warn" (worth reviewing) or "error" (likely wrong). - `reason` string, nullable: Human-readable explanation of the mismatch. - `extractedValue` number, double, nullable: The extracted value that triggered the warning, when numeric. Null when not applicable. - `expectedHint` string, nullable: Short hint at what was expected instead (e.g. "null", "non-null", "[500-10000]"). Null when not applicable. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `422`: Unprocessable Content - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-11-03** `50555858fb42`: 1 info - endpoint added [Operation history](https://skmtc.dev/cubee/apis/partner-api/changes/api/v1/invoice-extraction/post.md) --- [API](https://skmtc.dev/cubee/apis/partner-api.md) - [All operations](https://skmtc.dev/cubee/apis/partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cubee/apis/partner-api/revisions/50555858fb42?raw)