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