> ## 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. # Create a savings study > Generates the customer-facing savings-study PDF, stores it privately, e-mails it to the recipient (shareable link + the PDF attached), and returns the link. The link points at `GET /api/v1/studies/{id}/pdf`, which redirects to a short-lived SAS on each visit — the PDF is never a permanently-open public URL (GDPR: expiry + access logs + revocation on delete). ## OpenAPI ````yaml /api-reference/swagger-partner.json post /api/v1/studies 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/studies: post: tags: - Studies summary: Create a savings study description: >- Generates the customer-facing savings-study PDF, stores it privately, e-mails it to the recipient (shareable link + the PDF attached), and returns the link. The link points at `GET /api/v1/studies/{id}/pdf`, which redirects to a short-lived SAS on each visit — the PDF is never a permanently-open public URL (GDPR: expiry + access logs + revocation on delete). operationId: Create Study parameters: - name: X-Cubee-External-User in: header description: >- Optional id of the caller's own end-user this study belongs to. Tag studies with it to list them back later via `GET /api/v1/studies`. Opaque to Cubee — never send a name or e-mail. schema: type: string - name: X-Cubee-Cin in: header description: >- Cube IT only. Company identification number (IČO) of the company embedding the calculator, which brands the study (logo + contact) as that partner's instead of generic Cubee. Marks the call as an embed: any other token sending it gets 403, and a CIN matching no partner falls back to generic Cubee branding. schema: type: string requestBody: description: The study inputs plus the recipient's e-mail address. content: application/json: schema: $ref: '#/components/schemas/SavingsStudyEmailRequestModel' examples: existing-owner: summary: Existing FVE owner, e-mailed to the customer value: study: label: Novákovi — rodinný dům 10 kWp address: Slunečná 4, Olomouc extendedStudy: true periodType: 12M yearlyConsumptionKWh: 10000 totalKWp: 10 battery: batterySizeKwh: 10 reservedBatteryCapacityPercentage: 15 distribution: distributor: CEZ distributionRate: D57d lowTariffCommand: A1B4DP6 lowTariffRegion: STRED distributorFeeHighPerMWh: 2000 distributorFeeLowPerMWh: 721 renewableEnergyFeePerMWh: 0 systemServicesFeePerMWh: 212 circuitBreakerMonthlyFee: 236 electricityBuyingSettings: feeType: PerMWh fee: 250 spotPriceMinZero: true buyingType: SPOT monthlyFeeCzk: 100 vat: 21 electricitySellingSettings: feeType: PerMWh fee: 250 spotPriceMinZero: false sellingType: SPOT monthlyFeeCzk: 100 recipient: email: zakaznik@example.cz name: Jan Novák phone: '+420601123456' ownsPv: true wantsContact: true prospect: summary: Prospect without panels (FVE + Cubee offer) value: study: label: Dvořáková — novostavba, zájem o FVE address: Polní 12, Kolín periodType: '2025' yearlyConsumptionKWh: 4000 totalKWp: 7 battery: batterySizeKwh: 10 reservedBatteryCapacityPercentage: 15 distribution: distributor: CEZ distributionRate: D02d distributorFeeHighPerMWh: 2000 distributorFeeLowPerMWh: 0 renewableEnergyFeePerMWh: 0 systemServicesFeePerMWh: 212 circuitBreakerMonthlyFee: 236 electricityBuyingSettings: fixedBuyPriceCzkPerMWh: 3500 fixedBuyPriceCzkPerMwhInLowTariff: 3500 buyingType: FIX monthlyFeeCzk: 100 vat: 21 electricitySellingSettings: fixedSellPriceCzkPerMWh: 500 sellingType: FIX monthlyFeeCzk: 0 recipient: email: zakaznik@example.cz ownsPv: false wantsContact: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StudyCreatedResultModel' example: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 url: >- https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf emailSent: true '400': description: Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '401': description: Unauthorized content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '403': description: Forbidden content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProblemDetails' - $ref: '#/components/schemas/HttpValidationProblemDetails' '500': description: Internal Server Error security: - {} components: schemas: SavingsStudyEmailRequestModel: required: - battery - distribution - electricityBuyingSettings - recipient - totalKWp type: object properties: periodType: required: - 12M - '2024' - '2025' type: string description: >- Type of time period to evaluate — a specific year like "2024", "2025", or the rolling range "12M" (last 12 completed months). Accepted values come from `GET /api/v1/reference/periods`. Optional: leave it null and set `from` + `to` instead to evaluate an explicit date range. When both `from` and `to` are provided this field is ignored. Exactly one of { periodType } or { from + to } must be supplied. nullable: true from: type: string description: >- Optional explicit start of the evaluation period (date only, inclusive), e.g. "2025-01-01". Must be set together with `to`. When both are set, `periodType` is ignored — this lets you pin the exact window a study was computed over (e.g. a "last 12 months" run) so it can be reproduced later. The range must fall within the available data window (see the 400 response for the allowed bounds). format: date nullable: true to: type: string description: >- Optional explicit end of the evaluation period (date only, inclusive), e.g. "2025-12-31". Must be set together with `from`. The whole day is included. A full calendar year (from = Jan 1, to = Dec 31) yields the same result as the matching `periodType` year. format: date nullable: true yearlyConsumptionKWh: type: number description: >- Estimated total annual electricity consumption of the household in kilowatt-hours (kWh). format: float totalKWp: type: number description: >- Total installed PV power - kWp. Constraints: The system currently supports only a single PV array, so this represents the total capacity. If you need to create custom production profiles, use the CustomProductionConsumptionData property instead. format: float battery: $ref: '#/components/schemas/SavingCalculatorBatteryRequestModel' distribution: $ref: '#/components/schemas/SavingCaluclatorDistributionRequestModel' electricityBuyingSettings: oneOf: - $ref: '#/components/schemas/FixBuyingSettings' - $ref: '#/components/schemas/SpotBuyingSettings' description: >- Configuration for electricity purchasing strategy (either fixed or spot-based). electricitySellingSettings: oneOf: - $ref: '#/components/schemas/FixSellingSettings' - $ref: '#/components/schemas/SpotSellingSettings' description: >- Configuration for electricity selling strategy (if can't sell, set null). nullable: true customProductionConsumptionData: type: array items: $ref: '#/components/schemas/CustomProductionConsumptionDataModel' description: >- Optional custom production and consumption data for more accurate modeling. This is not required; if not provided, the model will use default estimations based on TotalKWp and YearlyConsumptionKWh. Model requires 1 hour granularity data for the entire period specified in PeriodType. nullable: true study: $ref: '#/components/schemas/StudySubjectModel' recipient: $ref: '#/components/schemas/StudyRecipientModel' additionalProperties: false description: >- The savings-study PDF request, delivered as an e-mail with the PDF attached. StudyCreatedResultModel: type: object properties: id: type: string description: The calculation id (also the blob name). format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 url: type: string description: >- Absolute URL of the public broker endpoint that redirects to a short-lived SAS. nullable: true example: >- https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf emailSent: type: boolean description: >- `true` if the e-mail was sent; `false` if e-mail is disabled or sending failed (PDF is still stored and reachable via Url). example: true additionalProperties: false description: >- Result of creating a study: the stored PDF's link plus whether the e-mail actually went out. 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: {} SavingCalculatorBatteryRequestModel: required: - batterySizeKwh - reservedBatteryCapacityPercentage type: object properties: batterySizeKwh: type: number description: Battery storage capacity in kilowatt-hours (kWh). format: float reservedBatteryCapacityPercentage: maximum: 100 minimum: 0 type: integer description: >- Percentage of battery capacity reserved and not used for optimization (0–100) %. format: int32 maximumBatteryChargingPowerWatt: type: integer description: Maximum power at which the battery can charge, in watts (W). format: int32 nullable: true maximumBatteryDischargingPowerWatt: type: integer description: Maximum power at which the battery can discharge, in watts (W). format: int32 nullable: true additionalProperties: false description: Configuration of the battery system used in the simulation. SavingCaluclatorDistributionRequestModel: required: - circuitBreakerMonthlyFee - distributionRate - distributor - distributorFeeHighPerMWh - renewableEnergyFeePerMWh - systemServicesFeePerMWh type: object properties: distributor: maxLength: 100 minLength: 1 type: string description: |- Key identifying the electricity distributor (e.g., CEZ, PRE, EGD). Valid keys come from `GET /api/v1/reference/distributors`. distributionRate: maxLength: 50 minLength: 1 type: string description: >- Distribution rate (sazba), e.g. "D02d", "D57d". The calculator resolves it to the correct TDD load-profile class. A raw "TDDx" value is also accepted for backward compatibility. Valid rates come from `GET /api/v1/reference/distribution-rates`. lowTariffCommand: maxLength: 100 type: string description: >- Distributor-defined code used to trigger low-tariff periods. Optional — leave null/empty for single-tariff rates (e.g. D01d, D02d, D61d) that have no HDO command. Valid commands come from `GET /api/v1/reference/distributors/{distributor}/commands`. nullable: true lowTariffRegion: maxLength: 100 type: string description: >- Optional distributor region key for the low-tariff command (e.g. ČEZ regions). Needed to resolve the correct HDO schedule when the same command exists in multiple regions. Valid region keys come from `GET /api/v1/reference/distributors/{distributor}/regions`. nullable: true distributorFeeHighPerMWh: type: number description: >- Fee for distribution during high-tariff periods, in CZK per MWh. Prefill from `GET /api/v1/reference/fees` (field `distributorFeeHighPerMWh`). format: double distributorFeeLowPerMWh: type: number description: >- Fee for distribution during low-tariff periods, in CZK per MWh. Prefill from `GET /api/v1/reference/fees` (field `distributorFeeLowPerMWh`). format: double renewableEnergyFeePerMWh: type: number description: >- Renewable energy fee applied per MWh, in CZK. Prefill from `GET /api/v1/reference/fees` (field `renewableEnergyFeePerMWh`). format: double systemServicesFeePerMWh: type: number description: >- System services fee applied per MWh, in CZK. Prefill from `GET /api/v1/reference/fees` (field `systemServicesFeePerMWh`). format: double circuitBreakerMonthlyFee: type: number description: >- Monthly fee for circuit breaker capacity, in CZK. Prefill from `GET /api/v1/reference/circuit-breakers` (field `monthlyFeeCzk` for the chosen breaker size). format: double additionalProperties: false description: Settings related to the electricity distributor and regulated fees. FixBuyingSettings: title: FixBuyingSettings required: - buyingType - monthlyFeeCzk allOf: - required: - fixedBuyPriceCzkPerMWh type: object properties: fixedBuyPriceCzkPerMWh: type: number description: Fixed electricity price in CZK/MWh during high-tariff periods. format: double fixedBuyPriceCzkPerMwhInLowTariff: type: number description: Fixed electricity price in CZK/MWh during low-tariff periods. format: double additionalProperties: false properties: buyingType: minLength: 1 required: - FIX - SPOT type: string description: Type of buying strategy — either "FIX" or "SPOT". monthlyFeeCzk: type: number description: Monthly fixed fee paid to the electricity supplier, in CZK. format: double vat: type: number description: >- Value-added tax (VAT) percentage applied to electricity prices. Defaults to 21%. format: double nullable: true description: >- Buying electricity at a fixed price, with different rates for high and low tariffs. SpotBuyingSettings: title: SpotBuyingSettings required: - buyingType - monthlyFeeCzk allOf: - required: - fee - feeType - spotPriceMinZero type: object properties: feeType: minLength: 1 required: - Percentage - PerMWh type: string description: >- Type of fee applied: "PerMWh" (fixed amount per energy unit) or "Percentage". fee: type: number description: >- Fee amount in CZK or percentage per MWh depending on FeeType. For PerMWh, it's amount in CZK/MWh. For Percentage, it's percentage of the power price of the electricity spot market (0.1 = 10% of power price) format: double spotPriceMinZero: type: boolean description: >- Indicates whether the electricity supplier sets the minimum spot price to 0 CZK if the market price drops below zero. additionalProperties: false properties: buyingType: minLength: 1 required: - FIX - SPOT type: string description: Type of buying strategy — either "FIX" or "SPOT". monthlyFeeCzk: type: number description: Monthly fixed fee paid to the electricity supplier, in CZK. format: double vat: type: number description: >- Value-added tax (VAT) percentage applied to electricity prices. Defaults to 21%. format: double nullable: true description: Buying electricity from the spot market with dynamic pricing and fees. FixSellingSettings: title: FixSellingSettings required: - monthlyFeeCzk - sellingType allOf: - required: - fixedSellPriceCzkPerMWh type: object properties: fixedSellPriceCzkPerMWh: type: number description: Fixed electricity selling price in CZK/MWh. format: double additionalProperties: false properties: sellingType: minLength: 1 required: - FIX - SPOT type: string description: Type of selling strategy — either "FIX" or "SPOT". monthlyFeeCzk: type: number description: Monthly fixed fee paid to the aggregator/seller, in CZK. format: double description: Selling electricity at a fixed price. SpotSellingSettings: title: SpotSellingSettings required: - monthlyFeeCzk - sellingType allOf: - required: - fee - feeType - spotPriceMinZero type: object properties: feeType: minLength: 1 required: - Percentage - PerMWh type: string description: >- Type of fee applied: "PerMWh" (fixed amount per energy unit) or "Percentage". fee: type: number description: >- Fee amount in CZK or percentage per MWh depending on FeeType. For PerMWh, it's amount in CZK/MWh. For Percentage, it's percentage of the power price of the electricity spot market (0.1 = 10% of power price) format: double spotPriceMinZero: type: boolean description: >- Indicates whether the electricity supplier sets the minimum spot price to 0 CZK if the market price drops below zero. additionalProperties: false properties: sellingType: minLength: 1 required: - FIX - SPOT type: string description: Type of selling strategy — either "FIX" or "SPOT". monthlyFeeCzk: type: number description: Monthly fixed fee paid to the aggregator/seller, in CZK. format: double description: Selling electricity on the spot market with dynamic pricing and fees. CustomProductionConsumptionDataModel: type: object properties: time: type: string description: Timestamp of the data point in ISO 8601 format. format: date-time productionWh: type: integer description: Production of energy from the PV system in watt-hours (Wh). format: int32 consumptionWh: type: integer description: Consumption of energy by the household in watt-hours (Wh). format: int32 additionalProperties: false StudySubjectModel: type: object properties: label: maxLength: 120 type: string description: >- Free-form label naming the study, printed on the cover (optional). Max 120 characters — enough for two cover lines; longer labels stop being a label. nullable: true address: maxLength: 200 type: string description: Site address printed on the cover (optional). Max 200 characters. nullable: true extendedStudy: type: boolean description: >- Whether to generate the EXTENDED study or a shortened one. `true` (default): the complete document. `false`: a shorter version that omits reference/methodology pages (currently the "Metodologie a omezení" page). The headline figures and the with-fees totals are identical either way. nullable: true additionalProperties: false description: Customer details shown on the study cover. StudyRecipientModel: required: - email type: object properties: email: maxLength: 254 minLength: 1 type: string description: Recipient e-mail address. format: email name: maxLength: 200 type: string description: >- The recipient's full name (optional). Used to name the customer in Cubee's CRM; when absent the e-mail address stands in. Not printed on the study — the cover uses `study.label`. nullable: true phone: maxLength: 30 type: string description: >- The recipient's phone number (optional). CRM contact detail only; never printed on the study. nullable: true ownsPv: type: boolean description: >- Whether the customer already owns the PV plant. `true` (the default when absent): the study compares Cubee against the customer's ordinary PV. `false`: the partner is offering PV + Cubee to a prospect with no panels — the study compares the whole offer against having no panels and omits payback. nullable: true wantsContact: type: boolean description: >- Whether the customer agreed to a follow-up contact (the wizard's optional consent step). Defaults to `true`; send `false` when the person declined — no CRM record is created then. Only studies from Cubee's own web/embed flow ever create Cubee CRM records; a partner's API studies never do, so for partners this field is informative. additionalProperties: false description: >- The customer the study is for — delivery address and CRM contact details. ````