navod

app/main.py

@@ -24,13 +24,76 @@ ROOT_PATH = os.getenv("ROOT_PATH", "")
 DESCRIPTION = """
 Stateless proxy exposing **Google Analytics 4** and **Sklik** (Seznam) APIs.
 
-All credentials are passed per request as `X-` headers (never stored):
+Veškeré přihlašovací údaje se posílají v každém requestu jako `X-` hlavičky –
+služba si nic neukládá. Vyplníte je v Swaggeru po kliknutí na **Try it out**.
 
-* **Google Analytics** — `X-GA-Access-Token` (preferred) or `X-GA-Credentials`
-  (base64 service-account JSON). Optional `X-GA-Quota-Project`.
-* **Sklik** — `X-Sklik-Token`. Optional `X-Sklik-User-Id` for managed accounts.
+| Služba | Hlavička | Povinné |
+| --- | --- | --- |
+| Google Analytics | `X-GA-Access-Token` **nebo** `X-GA-Credentials` | jedna z nich |
+| Google Analytics | `X-GA-Quota-Project` | ne |
+| Sklik | `X-Sklik-Token` | ano |
+| Sklik | `X-Sklik-User-Id` | ne (jen pro agenturní/MCC přístup) |
 
-See `documentation/` in the repository for details.
+---
+
+## Kde vzít přihlašovací údaje
+
+### 🔹 Google Analytics 4
+
+Potřebujete dvě věci: **přístup k API** a **ID property** (číslo, na které se
+ptáte).
+
+**ID property** (`property_id` v URL): v GA4 vpravo dole **Administrace →
+Nastavení property** – nahoře je *ID property*, např. `123456789`.
+
+Pro přístup máte dvě možnosti (stačí jedna):
+
+**A) Service account – doporučeno pro automatizaci (`X-GA-Credentials`)**
+
+1. [Google Cloud Console](https://console.cloud.google.com/) → vytvořte nebo
+   vyberte projekt.
+2. **APIs & Services → Library** → povolte **Google Analytics Data API**
+   a **Google Analytics Admin API**.
+3. **IAM & Admin → Service Accounts → Create service account**.
+4. U vytvořeného účtu **Keys → Add key → Create new key → JSON** – stáhne se
+   soubor s klíčem.
+5. Z JSON souboru zkopírujte `client_email` a v GA4 ho přidejte k property:
+   **Administrace → Správa přístupu k property → +** , role **Viewer**
+   (Čtenář).
+6. Celý JSON soubor zakódujte do **base64** a vložte do hlavičky
+   `X-GA-Credentials`:
+   - Windows PowerShell:
+     `[Convert]::ToBase64String([IO.File]::ReadAllBytes("klic.json"))`
+   - Linux/macOS: `base64 -w0 klic.json`
+
+**B) Hotový OAuth2 token – pro rychlý test (`X-GA-Access-Token`)**
+
+1. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).
+2. Vlevo zadejte scope `https://www.googleapis.com/auth/analytics.readonly`
+   a klikněte **Authorize APIs** (přihlaste se Google účtem, který má přístup
+   k property).
+3. **Exchange authorization code for tokens** → zkopírujte *Access token* do
+   hlavičky `X-GA-Access-Token`. Pozor: platí jen ~1 hodinu.
+
+### 🔹 Sklik
+
+Potřebujete **API token (klíč)** z účtu, jehož data chcete číst.
+
+1. Přihlaste se na [sklik.cz](https://www.sklik.cz/).
+2. Vpravo nahoře klikněte na **své uživatelské jméno → Nastavení**.
+3. V nastavení účtu otevřete sekci **Přístup k API Drak**.
+4. Klikněte na **Zobrazit token** a token zkopírujte do hlavičky
+   `X-Sklik-Token`.
+
+> ⚠️ Každé vygenerování nového tokenu **zneplatní ten předchozí**. Token je
+> vázaný na účet, pod kterým jste přihlášeni.
+>
+> Spravujete-li cizí účty (agentura/MCC), vložte cílové `userId` do hlavičky
+> `X-Sklik-User-Id`.
+
+---
+
+Podrobnosti k jednotlivým endpointům jsou v `documentation/` v repozitáři.
 """.strip()
 
 app = FastAPI(

documentation/google-analytics.md

@@ -23,6 +23,30 @@ The service account (or token) must have access to the GA4 property — add its
 > `[Convert]::ToBase64String([IO.File]::ReadAllBytes("service-account.json"))`
 > (PowerShell).
 
+## Kde získat údaje (návod pro klienta)
+
+**ID property** (`property_id` v URL): GA4 → **Administrace → Nastavení
+property** → *ID property* (např. `123456789`).
+
+**A) Service account – doporučeno (`X-GA-Credentials`)**
+
+1. [Google Cloud Console](https://console.cloud.google.com/) → projekt.
+2. **APIs & Services → Library** → povolit **Google Analytics Data API** a
+   **Google Analytics Admin API**.
+3. **IAM & Admin → Service Accounts → Create service account**.
+4. U účtu **Keys → Add key → JSON** → stáhne se klíč.
+5. `client_email` z JSON přidat v GA4 **Administrace → Správa přístupu k
+   property** jako **Viewer**.
+6. JSON zakódovat do base64 (viz výše) → hlavička `X-GA-Credentials`.
+
+**B) Hotový OAuth2 token – rychlý test (`X-GA-Access-Token`)**
+
+1. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).
+2. Scope `https://www.googleapis.com/auth/analytics.readonly` → **Authorize
+   APIs** (Google účet s přístupem k property).
+3. **Exchange authorization code for tokens** → *Access token* → hlavička
+   `X-GA-Access-Token` (platí ~1 h).
+
 ## Data API endpoints
 
 `property_id` may be the bare number (`123456789`) or `properties/123456789`.

documentation/sklik.md

@@ -25,6 +25,16 @@ injects the session — callers never handle the session.
 | `X-Sklik-Token` | yes | API token from Sklik → account settings → API. |
 | `X-Sklik-User-Id` | no | Managed account `userId` (agency/MCC access). |
 
+### Kde získat token (návod pro klienta)
+
+1. Přihlaste se na [sklik.cz](https://www.sklik.cz/).
+2. Vpravo nahoře **uživatelské jméno → Nastavení**.
+3. Sekce **Přístup k API Drak** → **Zobrazit token**.
+4. Token → hlavička `X-Sklik-Token`.
+
+> Nový token zneplatní ten předchozí. Token je vázaný na účet, pod kterým jste
+> přihlášeni. Pro správu cizích účtů (agentura/MCC) použijte `X-Sklik-User-Id`.
+
 Missing token → `401 missing_credentials`. Sklik business errors (invalid token,
 access denied, bad arguments) are surfaced as `upstream_error` with the Sklik
 `status` and full body.