JiriUhlir
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
# 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). |
|
|
|
|
### 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.
|
|
|
|
## 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`.
|