> ## 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.

# Uložené studie zákazníka

> Historie vygenerovaných studií — celá, na uživatele, nebo podle data

Každá vygenerovaná **studie úspor (PDF)** se ukládá do historie vašeho partnerského účtu — kdykoli si ji vylistujete zpět přes `GET /api/v1/studies`, celou nebo filtrovanou. A když studii při vytváření označíte vlastním ID koncového uživatele, ukážete třeba zákazníkovi v e-shopu jen jeho výpočty.

<Info>
  Funguje pro **libovolný partnerský API klíč**. Nemusíte o nic žádat.
</Info>

## Jak to funguje

<Steps>
  <Step title="Označte studii při vytváření">
    Ke `POST /api/v1/studies` přidejte hlavičku `X-Cubee-External-User` s ID uživatele z vašeho systému.

    ```bash Vytvoření označené studie theme={null}
    curl -X POST https://api.partner.cubee.cz/api/v1/studies \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -H "X-Cubee-External-User: eshop-user-8421" \
      -d @studie.json
    ```
  </Step>

  <Step title="Vylistujte si je zpět">
    Bez parametrů dostanete celou historii svého účtu; `externalUserId` ji zúží na jednoho uživatele, `from`/`to` (datum, včetně) na období. Studie chodí od nejnovější, každá s odkazem na své PDF.

    ```bash Výpis studií jednoho uživatele theme={null}
    curl https://api.partner.cubee.cz/api/v1/studies?externalUserId=eshop-user-8421 \
      -H "Authorization: Bearer $TOKEN"
    ```

    ```bash Celá historie za srpen theme={null}
    curl "https://api.partner.cubee.cz/api/v1/studies?from=2026-08-01&to=2026-08-31" \
      -H "Authorization: Bearer $TOKEN"
    ```

    Výpis je stránkovaný (`page`, `pageSize`, výchozích 50 na stránku):

    ```json Odpověď theme={null}
    {
      "totalCount": 128,
      "page": 1,
      "pageSize": 50,
      "items": [
        {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "createdAt": "2026-02-13T09:41:00+00:00",
        "annualSaving": 12095,
        "currency": "CZK",
        "paybackYears": 1.7,
        "url": "https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf",
        "studyLabel": "Novákovi — rodinný dům 10 kWp",
        "externalUserId": "eshop-user-8421",
        "recipientEmail": "novakovi@example.cz",
        "recipientName": "Jan Novák",
        "recipientPhone": "+420601123456",
        "wantsContact": true,
        "origin": null,
        "redactedAt": null,
        "userId": null,
          "partnerId": "8d2f6f0a-4c3b-4a6e-9f2d-1b7c9e5a3d10"
        }
      ]
    }
    ```

    `studyLabel` je označení z `study.label`; `recipientEmail`, `recipientName` a `recipientPhone` jsou kontakt z objektu `recipient` požadavku a `wantsContact` jeho souhlas s kontaktováním; `origin` je web embedované kalkulačky, `userId` uživatel partnerské konzole (u API studií `null`) a `partnerId` vždy váš vlastní účet.

    Detail jedné studie vrátí `GET /api/v1/studies/{id}` — kromě polí z výpisu nese i celé uložené zadání (`input`) a spočítaný model studie (`result`) přesně tak, jak byly zaznamenány. Samotné PDF je na `GET /api/v1/studies/{id}/pdf`.
  </Step>

  <Step title="Na požádání smažte osobní údaje">
    Když zákazník uplatní právo na výmaz, zavolejte `POST /api/v1/studies/{id}/redact`. Smazat můžete kteroukoli svou studii — i bez štítku; `externalUserId` je volitelná pojistka (studie pak musí nést stejné ID, takže integrace jednající za jednoho uživatele nesmaže cizí studii). Z uložených dat se vymažou osobní hodnoty (označení a adresa, e-mail, jméno a telefon příjemce, replikační data) a uložené PDF se smaže (odkaz začne vracet 404); ve výpisu řádek zůstane s vyplněným `redactedAt` a odosobněným výpočtem pro statistiku.
  </Step>
</Steps>

## Co je to za ID

Je to **vaše** ID, Cubee ho nijak neinterpretuje — může to být ID zákazníka v e-shopu, ID uživatelského účtu nebo ID relace. Stačí, aby bylo u téhož uživatele pokaždé stejné.

<Warning>
  Posílejte jen neprůhledný identifikátor. **Nikdy ne jméno, e-mail, telefon ani jiný osobní údaj** — hodnota se ukládá do auditního záznamu a při výmazu se nemaže.
</Warning>

## Kdo co uvidí

Výpis je vždy omezený na **API klíč volajícího** — vidíte jen studie, které jste vytvořili vy svým klíčem.

* Bez parametrů dostanete **celou historii svého partnerského účtu**; každá položka nese `studyLabel` a `externalUserId`, ať se v ní vyznáte.
* S `externalUserId` výpis zúžíte na jednoho svého koncového uživatele. ID si volíte sami, takže se napříč partnery mohou opakovat — právě proto je vždy kombinováno s vaším účtem: stejné `eshop-user-8421` u jiného partnera je jiný uživatel a jeho studie neuvidíte.
* `from`/`to` (datum, včetně) omezí výpis podle data vygenerování — jdou kombinovat s `externalUserId` i použít samostatně.
* Anonymizované studie ve výpisu zůstávají s vyplněným `redactedAt` — osobní údaje mají vynulované a `url` je `null` (PDF je smazané).

<Info>
  Studie bez hlavičky `X-Cubee-External-User` se vytvoří normálně a v celé historii účtu ji uvidíte také — jen ji nepůjde filtrovat na konkrétního uživatele (`externalUserId` bude `null`).
</Info>