first

2026-06-18 11:58:23 +02:00
parent 284e013753
commit 6934f22253
18 changed files with 1367 additions and 17 deletions
@@ -0,0 +1,84 @@
+# Sklik (Seznam)
+
+Proxy over the Sklik **Drak JSON API**
+(`https://api.sklik.cz/drak/json/v5/{method}`).
+
+## Protocol (verified against seznam/api-examples)
+
+- HTTP `POST` to the base URL with the **method name appended** to the path.
+- Body is a **JSON array** of positional arguments.
+- `client.loginByToken` takes the API token and returns
+  `{"status":200,"session":"...","statusMessage":"OK"}`.
+- Every authenticated method takes the user struct `{"session": ...}` (optionally
+  `"userId"`) as its **first** argument, followed by the method's own arguments.
+- Every response is an object with `status` (HTTP-style), `statusMessage`, a
+  refreshed `session`, and method-specific data. `200`, `206` and `301` are
+  treated as success.
+
+The proxy performs `client.loginByToken` per request from `X-Sklik-Token` and
+injects the session — callers never handle the session.
+
+## Credentials
+
+| Header | Required | Meaning |
+| --- | --- | --- |
+| `X-Sklik-Token` | yes | API token from Sklik → account settings → API. |
+| `X-Sklik-User-Id` | no | Managed account `userId` (agency/MCC access). |
+
+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.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| POST | `/sklik/login` | Verify the token. Returns `{valid, status, statusMessage}` (no session). |
+| GET | `/sklik/limits` | `api.limits` — quotas and the `statsDataLimit`. |
+| POST | `/sklik/report/{entity}` | `createReport` + paged `readReport` for an entity. |
+| POST | `/sklik/rpc/{method}` | Generic authenticated call to any method. |
+
+### Report helper
+
+`entity` ∈ `campaigns, groups, ads, keywords, queries, sitelinks, productSets,
+banners`. Body = the arguments for `{entity}.createReport` (restriction filter +
+optional display options). The proxy creates the report then pages through
+`{entity}.readReport` (100 rows/page) and returns:
+
+```json
+{ "reportId": "...", "totalCount": 1234, "returnedCount": 1234, "truncated": false, "report": [ ... ] }
+```
+
+Example body for `POST /sklik/report/campaigns`:
+
+```json
+[
+  { "dateFrom": "2026-06-01", "dateTo": "2026-06-18", "statGranularity": "daily" },
+  { "statGranularity": "daily" }
+]
+```
+
+### Generic RPC
+
+`POST /sklik/rpc/{method}` with a JSON-array body of the arguments **after** the
+session struct (which the proxy injects). Examples:
+
+```bash
+# List campaigns
+curl -X POST ".../apps/analytics/sklik/rpc/campaigns.list" \
+  -H "X-Sklik-Token: <TOKEN>" -H "Content-Type: application/json" \
+  -d '[{"statuses":["active"]}, {"displayColumns":["id","name","status"]}]'
+
+# Account info
+curl -X POST ".../apps/analytics/sklik/rpc/client.get" \
+  -H "X-Sklik-Token: <TOKEN>" -H "Content-Type: application/json" -d '[]'
+```
+
+`client.loginByToken` cannot be called via `/sklik/rpc` — the proxy manages the
+session (returns `400`).
+
+## Method reference
+
+Full method list: <https://api.sklik.cz/drak/>. Common ones: `client.get`,
+`api.limits`, `campaigns.list`, `groups.list`, `ads.list`, `keywords.list`,
+`*.createReport` / `*.readReport`.