# bk-console API v1: полная документация

Один файл для модели и разработчика: правила, сценарии, все методы с примерами и тексты ошибок. Отдайте его модели целиком: по нему пишется рабочая интеграция. Раздел «Методы» собран из `/openapi.json` и совпадает с ним.

## Пример вызова

```sh
export BK_KEY='bk_…'          # ключ API с экрана «Профиль» панели

# Проверить ключ: аккаунт, баланс, цена клика
curl -H "X-Auth-Token: $BK_KEY" https://bk-console.com/api/v1/account

# Поставить разовое задание: найти example.com по запросу в Москве (регион 213) и кликнуть.
# Idempotency-Key — новый на каждое действие; повтор после таймаута — с тем же $IDEM
IDEM=$(uuidgen)
curl -X POST https://bk-console.com/api/v1/tasks \
  -H "X-Auth-Token: $BK_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $IDEM" \
  -d '{"items":[{"id":"a1","site":"example.com","key":"купить диван москва","region":213}]}'

# Итог задания: id — task.id из ответа POST /tasks
curl -H "X-Auth-Token: $BK_KEY" https://bk-console.com/api/v1/tasks/1042

# Завести проект простым списком: сайт, регион, бренды и клики общие, ключи — строками
curl -X POST https://bk-console.com/api/v1/projects \
  -H "X-Auth-Token: $BK_KEY" -H "Content-Type: application/json" \
  -d '{"domain":"https://example.com/catalog","region":213,"brands":["ikea"],"clicks":100,"keys":["купить диван","диван недорого"]}'

# Тот же проект со стартовым срезом позиций: итог — projects[].start_check, позиции — GET /projects/{id}/snapshots
curl -X POST https://bk-console.com/api/v1/projects \
  -H "X-Auth-Token: $BK_KEY" -H "Content-Type: application/json" \
  -d '{"domain":"https://example.com/catalog","region":213,"keys":["купить диван","диван недорого"],"start_check":true}'

# Разовый проклик ключа проекта 31: 3 клика впереди очереди
curl -X POST https://bk-console.com/api/v1/projects/31/oneoff \
  -H "X-Auth-Token: $BK_KEY" -H "Content-Type: application/json" \
  -d '{"keys":["купить диван"],"times":3}'
```

```python
import os
import time
import uuid

import requests

BASE = "https://bk-console.com/api/v1"
S = requests.Session()
S.headers["X-Auth-Token"] = os.environ["BK_KEY"]


def call(method, path, body=None, idem=None, **query):
    """Запрос к API → поле data (и next_cursor у списков). idem — Idempotency-Key: тот же при повторе после таймаута."""
    headers = {"Idempotency-Key": idem} if idem else {}
    while True:
        r = S.request(method, BASE + path, json=body, params=query or None, headers=headers, timeout=30)
        if r.status_code == 429:                      # лимит запросов в минуту: ждать столько, сколько сказано
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        if not r.headers.get("Content-Type", "").startswith("application/json"):
            raise RuntimeError(f"HTTP {r.status_code}: ответ nginx не JSON (413 — тело больше 2 МиБ; 502, 504 — повторите позже)")
        j = r.json()
        if not j["ok"]:
            raise RuntimeError(f"HTTP {r.status_code}: {j['error']}")   # текст ошибки дословно из таблиц методов
        return j


acc = call("GET", "/account")["data"]
print(acc["login"], acc["balance_kop"], acc["price_kop"])

idem = str(uuid.uuid4())                              # новый ключ на эту пачку; повтор после таймаута — с тем же idem
res = call("POST", "/tasks", {"items": [
    {"id": "a1", "site": "example.com", "key": "купить диван москва", "region": 213},
]}, idem=idem)["data"]
task_id = res["tasks"][0]["task"]["id"]

while True:                                           # без вебхука: опрос не чаще раза в минуту
    t = call("GET", f"/tasks/{task_id}")["data"]
    if t["status"] not in ("new", "running"):
        break
    time.sleep(60)
print(t["status"], t["result"])                      # done + {"outcome": "clicked", "position": 3, …}
```

## Что делает

Панель продаёт Целевые клики: ищет сайт клиента в мобильной выдаче Яндекса по поисковому запросу в заданном регионе и кликает по нему.

API открывает то же, что панель:

| Возможность | Что это |
|---|---|
| Проекты | Сайт и его ключи с лимитом кликов в сутки. Клики идут каждый день, пока проект включён и есть деньги. Списание — за клик |
| Разовые задания | Сайт + запрос + регион: сайт один раз ищется в выдаче, по нему делается клик. Итог — позиция и URL клика или «не найден», приходит вебхуком. Списание — за оба итога. Проверка позиции (`click: false`) — то же без клика: итог — позиция и URL результата выдачи или «не найден» |
| Источник | Панель сама забирает разовые задания с сервера клиента по протоколу API.md (`GET /task`) и возвращает итог (`POST /result`) |
| Статистика и деньги | Клики и позиции по суткам и ключам, баланс, операции, расход |
| Реселлер | Субаккаунты: перевод денег, своя цена клика, блок, ссылка входа без пароля |

## Термины

| Термин | Значение |
|---|---|
| Ключ API | Строка `bk_…` из 46 символов. Даёт права своего аккаунта. Выпускается на экране «Профиль» панели и показывается один раз |
| Проект | Сайт клиента и набор его ключей проекта. Один домен — один проект. Домен сравнивается целиком: `www.example.com` и `example.com` — два проекта |
| Ключ проекта | Поисковый запрос проекта: страница сайта, запрос, бренд-слова, кликов в сутки, раз в сколько суток, регион. `id` — 16 hex; меняется, если сменить страницу, запрос или регион |
| Смесь регионов | Доли регионов на ключ проекта: например Москва 50 %, города-миллионники 30 %, Екатеринбург 20 %. Задаётся полем `region_mix` ключа (KeyIn) или весами `*N` в `region`. Если в `region` есть `*` (`region_mix` пишет его всегда), доли держатся по факту кликов за сутки МСК: регион, набравший свою долю, дальше кликов не получает, пока не доберут остальные. Регион, где сайт плохо находится, поэтому ограничивает клики всего ключа, и за сутки ключ может набрать меньше `clicks`. Без `*` (`{213|2}`) доли — только веса выбора региона, фактическая доля может отличаться от весов |
| Разовое задание | Сайт + запрос + регион [+ бренд]. Исполняется один раз. Итог — `clicked` или `not_found`, у проверки позиции — `found` или `not_found` |
| Проверка позиции | Разовое задание с `click: false`: сайт ищется в выдаче, позиция снимается, клика нет. Цена — цена клика |
| Срез позиций | Проверка позиции по каждому включённому ключу проекта одним запросом (`POST /projects/{id}/snapshots`). Цена — цена среза позиций за проверку: одна для всех клиентов, по умолчанию 10 коп. |
| Старт | Первый срез позиций проекта: позиции до кликов. В панели — отдельная точка на графике позиций проекта и колонка «Старт» в таблице ключей |
| Разовый проклик | Разовые задания с кликом по выбранным ключам проекта, N раз каждый (`POST /projects/{id}/oneoff`). Идут впереди очереди разовых заданий |
| Итог | Финальный исход разового задания: `clicked` — сайт нашёлся и по нему кликнули; `found` — сайт нашёлся, клика не было (проверка позиции); `not_found` — сайта нет на просмотренных страницах выдачи |
| Срок | Время на итог разового задания: 60 мин от приёма. Задание в очереди (`new`) к сроку становится `expired`. Задание в исполнении (`running`) ждёт итога ещё запас срока 5 мин: итог в этот запас — `done` со списанием, позже — `expired` без списания |
| Позиция | Место сайта в органической выдаче, сквозное по просмотренным страницам, с 1. 0 — не найден |
| Бренд | Бренд-слово: ищется «запрос бренд», если по запросу сайт не нашёлся (`if_not_found`) или сразу (`always`) |
| Вебхук | POST панели на URL клиента, когда разовое задание стало финальным |
| Источник | Сервер клиента по протоколу API.md, с которого панель сама забирает разовые задания |
| Реселлер | Аккаунт, которому админ разрешил заводить субаккаунты |
| Субаккаунт | Аккаунт реселлера. Видит панель как обычный клиент, живёт на деньгах, которые реселлер ему перевёл. Логин реселлера, заметку к переводу, `peer_id` и метку `label` субаккаунт не видит: перевод у него — «пополнение от реселлера» или «возврат реселлеру» |
| Цена клика | `price_kop` аккаунта: списывается за клик проекта и за итог разового задания, кроме проверок среза позиций. Сейчас по умолчанию 10 коп. |
| Комиссия | Разница цены клика субаккаунта и цены реселлера: раз в минуту начисляется реселлеру строкой `commission` |
| Стоп | Проекты не крутятся: `blocked` — аккаунт заблокирован, `balance` — нет денег, `budget` — исчерпан бюджет проекта |
| Сутки | Сутки по Москве (МСК). По ним считаются лимиты кликов, статистика и даты `date_from`, `date_to` |
| Лимит | Сколько запросов в минуту принимает API: общий `all` и лимит метода (раздел «Лимиты») |

## Авторизация и права

Каждый запрос несёт заголовок `X-Auth-Token: bk_…`. Не в URL и не как Bearer. Тело — JSON с `Content-Type: application/json`. Заголовок `X-BK` нужен только экранам панели, по ключу — нет.

API вызывается с сервера. CORS закрыт: браузер со стороннего сайта запрос не выполнит (preflight `OPTIONS` — 405). Ключ API в код страницы не кладите.

Права ключа — права аккаунта на момент запроса. Аккаунт заблокирован — 403 и по ключу, ключи при этом не отзываются. Ключ отозван — 401 со следующего запроса.

| Кто | Что может |
|---|---|
| клиент | свои проекты, разовые задания, вебхук, Источник, баланс и операции |
| реселлер | всё, что клиент, и `/subaccounts*` |
| субаккаунт | как клиент; `/subaccounts*` — 403 `субаккаунт не может заводить субаккаунты` |

Ключами API управляют только из панели: `/account/keys*` по ключу отвечают 403 `метод доступен только из панели: войдите на сайт`.

## Формат ответа

```jsonc
{"ok": true, "data": {…}}                            // объект
{"ok": true, "data": […], "next_cursor": "1041"}     // список; next_cursor null — страниц больше нет
{"ok": false, "error": "текст ошибки"}               // HTTP 4xx или 5xx (кроме 413, 502, 504 от nginx: там HTML)
```

| Что | Как |
|---|---|
| Деньги | Целые копейки, поля `*_kop`. 10 коп. = 0,10 ₽ |
| Время | ISO 8601 UTC до секунд, без дробной части: `2026-11-20T07:15:00+00:00` |
| Даты периода | `date_from`, `date_to` — `ГГГГ-ММ-ДД` от 2000-01-01 до 2100-12-31, сутки МСК включительно |
| Страницы | `limit` 1–500, умолчание 100 (у отчётов 1–100). Следующая страница — тот же запрос с `cursor=<next_cursor>`. Курсор не разбирайте: передавайте как есть. `next_cursor` не null — следующая страница есть и не пуста |
| Ошибка | Текст `error` дословно из таблиц методов. `<…>` в таблице — подставляемое значение (число, домен, id) |
| Неизвестные поля тела | 400 `<поле>: неизвестное поле` (в элементе массива — `items[<i>].<поле>: неизвестное поле`) у `POST /projects`, `PATCH /projects/{id}`, `PATCH /projects/{id}/status`, `PUT`, `PATCH`, `DELETE /projects/{id}/keys`, `POST /projects/{id}/boost`, `POST /tasks`, `POST /tasks/cancel`, `PUT /webhook`, `PUT /source`. Из нескольких неизвестных называется первое по алфавиту. Остальные методы неизвестные поля пропускают молча: сверяйте имена полей с таблицами методов |
| Размер тела | До 2 МиБ (предел nginx). Больше — 413 с телом HTML |

## Общие ошибки

Эти ошибки бывают у любого метода и в таблицах методов не повторяются. Ответы 413, 502, 504 и 307 приходят не в формате `{"ok": false, "error"}`: проверяйте `Content-Type` до разбора JSON.

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 401 | `нужен вход` | нет заголовка `X-Auth-Token` | передайте ключ |
| 401 | `ключ API не найден или отозван` | ключ неверный, отозван или не начинается с `bk_` | выпустите новый на экране «Профиль» |
| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт ключа заблокирован | напишите админу |
| 403 | `метод доступен только из панели: войдите на сайт` | метод панели вызван по ключу | войдите в панель |
| 400 | `тело — не JSON` | тело не разобралось как JSON | исправьте тело и `Content-Type` |
| 400 | `тело — не объект JSON` | тело — массив или значение, а не объект | оберните поля в объект |
| 400 | `параметр <имя>: <текст FastAPI>` | параметр пути или query не того типа или вне пределов (`id=abc`, `id=0`). Текст после двоеточия — на английском | исправьте параметр |
| 404 | `не найдено` | нет такого пути | сверьте путь с `/openapi.json` |
| 405 | `метод не поддерживается: сверьте путь и метод с /openapi.json` | путь есть, HTTP-метод другой | сверьте метод |
| 429 | `слишком много запросов: лимит <N> в минуту (<лимит>), повторите через <S> с` | исчерпан лимит запросов в минуту | ждите `Retry-After` секунд |
| 500 | `внутренняя ошибка сервера: повторите позже` | необработанный сбой панели | повторите позже; изменяющий запрос без `Idempotency-Key` перед повтором проверьте: действие могло выполниться |
| 413 | тело HTML от nginx, не JSON | тело запроса больше 2 МиБ | разбейте запрос на части |
| 502, 504 | тело HTML от nginx, не JSON | панель перезапускается или не ответила за 60 с | повторите позже; действие могло выполниться: проверьте его перед повтором или шлите с `Idempotency-Key` |
| 307 | пустое тело, заголовок `Location` | путь с `/` на конце: панель перенаправляет на путь без `/` | пишите путь без `/` в конце |

## Когда какой метод

| Задача | Метод |
|---|---|
| проверить ключ и баланс | `GET /account`, `GET /balance` |
| завести сайт с ключами или заменить все ключи сайта | `POST /projects` (выключенный проект он включает, если не передать `enabled: false`) |
| завести сайт по списку ключей с общими регионом, брендами и кликами | `POST /projects` с `domain` и `keys` массивом строк (простой список) |
| добавить или обновить часть ключей, не трогая остальные | `PUT /projects/{id}/keys` (`items` — KeyIn или `keys` — строки с общими полями) |
| включить или выключить отдельные ключи | `PATCH /projects/{id}/keys` |
| удалить ключи | `DELETE /projects/{id}/keys` |
| включить или выключить проект | `PATCH /projects/{id}/status` |
| поднять или снизить лимиты всех ключей проекта на процент | `POST /projects/{id}/boost` |
| бюджет или заметка проекта | `PATCH /projects/{id}` |
| убрать проект | `DELETE /projects/{id}` (выключить и скрыть) |
| клики и позиции по суткам, по ключам | `GET /projects/{id}/stats`, `GET /projects/{id}/keys/stats` |
| позиции ключей проекта до кликов (Старт) или сейчас, без кликов | `start_check: true` в `POST /projects` или `POST /projects/{id}/snapshots`; итог — `GET /projects/{id}/snapshots`, `GET /projects/{id}/snapshots/{snapshot_id}` |
| кликнуть выбранные ключи проекта N раз сверх лимита, сразу | `POST /projects/{id}/oneoff` |
| какие ключи не находятся в выдаче: страница, регион, подсказка | `GET /projects/{id}/keys/stats?only=not_found&sort=not_found`; исправить ключ — `PUT /projects/{id}/keys` |
| план и факт за сегодня по всему аккаунту | `GET /performance` |
| найти позицию сайта и кликнуть один раз | `POST /tasks`, итог — вебхук или `GET /tasks/{id}` |
| получать итоги разовых заданий на свой сервер | `PUT /webhook`, `POST /webhook/secret`, `POST /webhook/test` |
| снять задания в очереди | `POST /tasks/cancel` (по id), `DELETE /queue` (все в очереди) |
| сколько заданий в работе | `GET /queue` |
| чтобы панель сама брала задания с вашего сервера по API.md | `PUT /source`, состояние — `GET /source` |
| операции по балансу | `GET /transactions` |
| реселлер: завести клиента и дать ему денег | `POST /subaccounts`, `POST /subaccounts/{id}/transfer` |
| реселлер: впустить клиента в панель без пароля | `POST /subaccounts/{id}/login-link` |
| реселлер: деньги субаккаунтов за период | `GET /subaccounts/report` |

## Методы

Справочник собран из `/openapi.json`. Общие ошибки (401, 403, 429, 500, тело не JSON) у методов не повторяются: они в разделе «Общие ошибки».

## Методы: Аккаунт, ключи API, показатели, баланс, операции

### GET /api/v1/account

Аккаунт ключа.

**Кто:** все.

Аккаунт, с правами которого выполняются запросы: роль, реселлер или субаккаунт, цена клика, баланс, стоп. Проверка ключа и связи — этим методом: он ничего не меняет.

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/account' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 7,
    "login": "client1",
    "role": "client",
    "parent_id": null,  // реселлер субаккаунта; null — обычный аккаунт
    "reseller": false,  // может заводить субаккаунты
    "verified": false,  // проверенный клиент: при нуле проекты идут ещё credit_days суток
    "price_kop": 10,  // цена клика и разового задания, копейки
    "balance_kop": 150000,  // баланс, копейки
    "negative_since": null,  // с какого момента баланс ≤ 0
    "credit_days": 5,  // суток кредита проверенного клиента
    "stop": null  // стоп аккаунта: blocked — заблокирован, balance — нет денег; null — работает
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### GET /api/v1/account/keys

Ключи API аккаунта.

**Кто:** все, только из панели.

Неотозванные ключи аккаунта, новые первыми. Ключ целиком не отдаётся: только `prefix`. По ключу API метод отвечает 403 `метод доступен только из панели: войдите на сайт`.

Метод вызывается только из панели (вход по cookie): по ключу API он отвечает 403, примера curl нет.

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 3,
      "prefix": "bk_Xq3v9Lm",  // первые 10 символов ключа для узнавания
      "name": "сервер интеграции",
      "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
      "last_used_at": "2026-11-20T09:02:11+00:00",  // не чаще раза в минуту
      "last_ip": "203.0.113.5"
    }
  ]
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### POST /api/v1/account/keys

Выпустить ключ API.

**Кто:** все, только из панели.

Ключ целиком — только в этом ответе: панель хранит его sha256. Неотозванных ключей у аккаунта — до 10. Тело можно не передавать. Неизвестные поля тела пропускаются молча.

Тело запроса:

| Поле | Значение |
|---|---|
| `name` | строка, до 64 символов |

Метод вызывается только из панели (вход по cookie): по ключу API он отвечает 403, примера curl нет.

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 3,
    "key": "bk_Xq3v9LmT2pR8sW4nY6bK1cD5fG7hJ0aZ9eQ3uI8oP2x",  // ключ целиком: показывается один раз, в панели хранится только sha256
    "prefix": "bk_Xq3v9Lm",
    "name": "сервер интеграции",
    "created_at": "2026-11-20T07:15:00+00:00"  // время ISO 8601 UTC
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `name: до 64 символов` | name не строка или длиннее 64 символов | сократите имя |
| 409 | `ключей уже 10: отзовите ненужный` | у аккаунта уже 10 неотозванных ключей | отзовите ненужный ключ: `DELETE /account/keys/{key_id}` |

### DELETE /api/v1/account/keys/{key_id}

Отозвать ключ API.

**Кто:** все, только из панели.

Ключ перестаёт работать со следующего запроса: тот отвечает 401.

Параметры:

| Параметр | Значение |
|---|---|
| `key_id` | в пути, целое, обязательно, 1–9223372036854775807 |

Метод вызывается только из панели (вход по cookie): по ключу API он отвечает 403, примера curl нет.

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "revoked": true
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `ключ не найден` | ключа нет, он чужой или уже отозван | проверьте id: `GET /account/keys` |

### GET /api/v1/performance

Показатели за сутки.

**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).

План и факт кликов проектов за сутки МСК, счётчики разовых заданий, расход и баланс. Клики приходят в статистику с отставанием около 10 мин. `clicked`, `not_found`, `other` — только по проектам: разовые задания — в `oneoff`.

Охват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/performance' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "date": "2026-11-20",  // сутки МСК
    "plan_clicks": 1200,  // сумма лимитов в сутки включённых проектов без стопа
    "clicked": 418,  // кликов за сутки МСК (отставание около 10 мин)
    "not_found": 37,  // «сайт не найден» за сутки
    "other": 12,  // прочие исходы за сутки: гео, капча, сбой
    "spent_kop": 4180,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
    "oneoff": {
      "new": 3,
      "running": 12,
      "done": 1,  // за сутки МСК
      "expired": 1  // за сутки МСК
    },
    "balance_kop": 150000,
    "days_left": 35.7  // баланс / средний расход в сутки за время с первого списания за 7 суток (не меньше часа, не больше 7 суток); расход — по времени клика; расхода не было — null
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### GET /api/v1/balance

Баланс.

**Кто:** все.

Баланс, цена клика, кредит проверенного клиента, стоп и расход за сутки МСК и за 7 суток.

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/balance' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "balance_kop": 150000,
    "price_kop": 10,
    "verified": false,
    "credit_days": 5,
    "credit_limit_kop": null,  // кредитный лимит; null — по умолчанию панели
    "negative_since": null,  // время ISO 8601 UTC
    "stop": null,
    "spent_today_kop": 3400,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
    "spent_7d_kop": 21000  // списано за 7 суток по времени клика; разовые задания — по времени списания
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### GET /api/v1/transactions

Операции по балансу.

**Кто:** все.

Строки бухгалтерии по id убыванием. Списание за клики проекта — строка на окно 5 мин и проект (`clicks` — кликов в строке). Разовое задание — строка на задание (`oneoff_id`). Даты — сутки МСК, до 93 суток; передана одна дата — вторая берётся по правилу: нет `date_to` — сегодня, нет `date_from` — 93 суток по `date_to`.

Параметры:

| Параметр | Значение |
|---|---|
| `kind` | в query, "deposit" \| "charge" \| "refund" \| "adjust" \| "transfer" \| "commission" |
| `date_from` | в query, строка — первые сутки МСК, ГГГГ-ММ-ДД, от 2000-01-01 до 2100-12-31 |
| `date_to` | в query, строка — последние сутки МСК включительно, от 2000-01-01 до 2100-12-31 |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/transactions?date_from=2026-11-01&date_to=2026-11-20' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 88123,
      "kind": "charge",  // deposit — пополнение, charge — списание за клики или разовое задание, refund — возврат, adjust — корректировка, transfer — перевод реселлер ↔ субаккаунт, commission — комиссия реселлера: из оплаченной части списания субаккаунта, списание в долг Комиссии не даёт (строка с 0)
      "amount_kop": -40,  // > 0 — зачисление, < 0 — списание
      "balance_after": 149960,  // баланс после строки
      "clicks": 4,  // charge и commission: списанных единиц — клики за окно 5 мин или 1 за разовое задание при любом итоге (фактический клик разового — outcome = clicked)
      "comment": "клики 07:10–07:15",  // у transfer субаккаунта — «пополнение от реселлера» или «возврат реселлеру»: логин и заметку реселлера субаккаунт не видит
      "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
      "project_id": 31,
      "domain": "example.com",  // домен проекта
      "hidden": false,  // проект удалён клиентом (скрыт); у нового проекта может быть тот же домен. Без проекта — null
      "oneoff_id": null,  // разовое задание
      "outcome": null,  // Итог разового задания (clicked, found, not_found); не разовое — null. clicks у разового 1 при любом итоге, кликом оно стало только при clicked
      "peer_id": null  // transfer, commission: другой аккаунт; субаккаунту — null
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `kind: deposit, charge, refund, adjust, transfer или commission` | kind не из списка | передайте одно из значений или уберите kind |
| 400 | `date_from: дата ГГГГ-ММ-ДД` | дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля) | передайте дату вида 2026-11-20 |
| 400 | `date_to: дата ГГГГ-ММ-ДД` | то же для date_to | передайте дату вида 2026-11-20 |
| 400 | `date_from: дата от 2000-01-01 до 2100-12-31` | date_from раньше 2000-01-01 или позже 2100-12-31 | передайте дату в этих пределах |
| 400 | `date_to: дата от 2000-01-01 до 2100-12-31` | то же для date_to | передайте дату в этих пределах |
| 400 | `date_to раньше date_from` | конец периода раньше начала | поменяйте даты местами |
| 400 | `период больше 93 суток` | между date_from и date_to больше 93 суток включительно | разбейте период на части |
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |

## Методы: Проекты (сайты) и их ключи, буст, срезы позиций, разовый проклик, статистика

### GET /api/v1/projects

Список проектов.

**Кто:** все.

Нескрытые проекты аккаунта по id убыванием.

Клики, «не найден» и позиции клиенту считаются только по домену проекта (с `www.` и без, без учёта регистра, IDN как punycode): ключи других сайтов в проекте не входят. История — с суток МСК подключения проекта.

Параметры:

| Параметр | Значение |
|---|---|
| `q` | в query, строка — часть домена |
| `enabled` | в query, true или false |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 1042,
      "domain": "example.com",
      "note": "Диваны",  // заметка (название) проекта
      "enabled": true,  // желание клиента
      "stop_reason": null,  // стоп от панели; проект работает, только если enabled и stop_reason null
      "pending": false,  // вкл/выкл ещё не применён: применяется за секунды
      "limit_day": 1200,  // сумма лимитов включённых ключей в сутки, N@дни — как N/дни. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
      "keys": 25,  // включённых ключей. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
      "budget_kop": null,  // бюджет на весь срок; null — без бюджета
      "spent_kop": 4180,  // списано за всё время
      "today": {
        "clicked": 418,
        "not_found": 37,
        "other": 12  // geo_fail + captcha + error
      },
      "total_clicked": 15230,  // кликов за всё время в статистике
      "avg_position": 4.2,  // средняя Позиция без бренда
      "editable": true  // true — ключи правятся методами `/projects/{id}/keys`. false — проект настроен вручную: ключи через API не правятся
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `enabled: true или false` | enabled не true, false, 1 или 0 | передайте true или false |
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |

### POST /api/v1/projects

Создать проекты или заменить ключи.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Как загрузка файла на экране «Проекты». Строки группируются по домену, каждый домен — свой проект. Проект с таким доменом у аккаунта уже есть — его ключи заменяются целиком, скрытый проект снова показывается. Домен сравнивается целиком: `www.example.com` и `example.com` — два разных проекта (предел 1 000 000 в сутки у них общий). Чтобы заменить ключи, передавайте url с тем же хостом, что `domain` проекта. Если в проекте есть ключи другого сайта, ключи не заменяются: `projects[].error` с текстом «в проекте есть строки другого сайта: его правит админ».

Тело — `text` (строки `сайт;ключ|бренд1|бренд2;клики[@дни];&lr=регион`), `keys` (массив KeyIn, 1–50000) или простой список: `keys` — массив строк-ключей, а `domain`, `region` или `region_mix`, `brands`, `clicks` и `every_days` — общие на все ключи. `text` берётся, только если `keys` не передан. Ключ без `url` получает домен из поля `domain`; нет и его — строка считается в `bad` без текста ошибки. Регион ключа — `region` или смесь регионов `region_mix` (KeyIn); в `text` смесь пишется спинтаксом с весами `&lr={213*5|2|{54|65}*4}`.

Простой список — один проект: `domain` обязателен (адрес сайта или страницы, `https://example.com/catalog`), сервер подставляет его, регион, бренды и клики в строку каждого ключа. `clicks` без значения — 100 кликов в сутки на ключ. Общие поля разрешены только при `keys` строками: в прежних формах тела они — 400 `<поле>: неизвестное поле`. Ошибки общих полей — тексты KeyIn без префикса (`region: …`, `region_mix: …`), ошибка ключа — `keys[<i>]: …`.

`enabled` применяется и к проекту, который уже есть: без поля проект включается (умолчание true). Чтобы заменить ключи выключенного проекта и не включить его, передайте `enabled: false`. Новый проект начинает работу сразу, если `enabled` true и у аккаунта нет стопа. Предел — 1 000 000 кликов в сутки на сайт по всем проектам аккаунта. Ошибка одного домена не роняет запрос: она в `projects[].error`. Непринятые строки — в `projects[].error_rows`.

Тело — до 2 МиБ (предел nginx, больше — 413 с телом HTML): 50 000 ключей в него не помещаются. Ключ обычно занимает 100–300 байт; большую загрузку делите на части.

`limit_day` и `keys` проекта сразу после записи считают и выключенные ключи; в течение 10 мин в них остаются только включённые.

`start_check: true` — стартовый срез позиций: по Проверке позиции на каждый ключ записанного проекта, цена — цена среза позиций за проверку, как у `POST /projects/{id}/snapshots`. Итог — в `projects[].start_check`: `snapshot_id`, `tasks` или `error`. Отказ среза (Проверка позиции выключена, нет денег) проект не отменяет. Без поля ответ прежний. Повтор запроса с `start_check: true` в течение 24 ч второй срез не ставит и не оплачивает: в `projects[].start_check` — уже поставленный стартовый срез проекта, тот же `snapshot_id`.

Тело запроса:

| Поле | Значение |
|---|---|
| `domain` | строка — домен для keys без url; при keys строками — обязательный адрес сайта или страницы, без ; \| # и пробелов, до 500 символов |
| `keys` | массив (объект KeyIn или строка), 1–50000 элементов — массив KeyIn или массив строк-ключей (простой список); смешивать нельзя |
| `keys[].url` | строка или null — страница сайта (example.com/catalog, со схемой или без), без ; \| # и пробелов, до 500 символов: клик сначала по ней; null — домен проекта |
| `keys[].key` | строка, обязательно, длина 1–200 — поисковый запрос, 1–200 символов без ; и \| |
| `keys[].brands` | массив (строка), 0–20 элементов — бренд-слова: «ключ слово» ищется, если по ключу сайт не нашёлся |
| `keys[].clicks` | целое, обязательно, 1–100000 — кликов в сутки МСК |
| `keys[].every_days` | целое, 1–365, умолчание `1` — раз в сколько суток кликается ключ: в каждые сутки — с вероятностью 1/every_days |
| `keys[].region` | целое или строка или null — регион Яндекса lr (213) или спинтакс {213\|2}: число или строка; null — любой регион. Вес варианта — суффикс *N внутри {…}: {213*5\|2\|{54\|65}*4}, N от 1 до 10000, без суффикса вес 1; вес делится между регионами варианта поровну. Строка с * — доли регионов держатся по факту кликов за сутки МСК; регион, где сайт плохо находится, ограничивает клики всего ключа. Без * доли — только веса выбора региона. Строка с * — только при включённой смеси регионов, иначе прежний 400 `items[<i>].region: номер региона или спинтакс {…} из цифр, { } и \|` |
| `keys[].region_mix` | массив (объект) или null, 1–50 элементов — смесь регионов вместо region: строки «группа или регион — процент». Панель собирает из них спинтакс с весами (проценты, делённые на их НОД; *N у каждого варианта, *1 тоже, поэтому доли держатся по факту кликов; один вариант — без скобок) и пишет его в region ключа. Группы: msk — Москва (213), spb — Питер (2), mil — 14 городов от 1 млн без Москвы и Питера, rf — 94 центра регионов без Москвы, small — 264 города до 100 тыс.; группа — один вариант в своих скобках. Одинаковые варианты (msk и lr 213) складываются. pct — целое от 5 до 100, кратное 5, сумма ровно 100. Вместе с region — 400. Пока смесь регионов выключена — 400 `items[<i>].region_mix: смесь регионов пока выключена` |
| `keys[].host_brand` | строка или null, до 100 символов — Хост-бренд вручную, 1–100 символов; null — из домена |
| `text` | строка — строки файла загрузки |
| `note` | строка, до 200 символов |
| `enabled` | true или false, умолчание `true` — true — проект включается, в том числе существующий и скрытый; false — выключается |
| `region` | целое или строка или null — только при keys строками: регион всех ключей, как region у KeyIn |
| `region_mix` | массив (объект) или null, 1–50 элементов — только при keys строками: смесь регионов всех ключей, как region_mix у KeyIn; вместе с region нельзя |
| `brands` | массив (строка), 0–20 элементов — только при keys строками: бренд-запросы (подсказка) всех ключей, как brands у KeyIn |
| `clicks` | целое, 1–100000, умолчание `100` — только при keys строками: лимит в сутки каждого ключа |
| `every_days` | целое, 1–365, умолчание `1` — только при keys строками: раз в столько суток крутится каждый ключ |
| `start_check` | true или false, умолчание `false` — true — стартовый срез позиций по ключам каждого записанного проекта, как `POST /projects/{id}/snapshots`; итог — в `projects[].start_check`; повтор за 24 ч второй срез не ставит, отдаёт уже поставленный |

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/projects' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "https://example.com/catalog;купить диван|ikea;70;&lr=213\nexample.com;диван недорого;30@2;&lr=2", "note": "Диваны", "enabled": true}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "projects": [
      {
        "domain": "example.com",  // домен
        "project_id": 31,
        "existing": false,  // проект уже был: ключи заменены (`POST /projects`)
        "tasks": 25,  // ключей в проекте после записи
        "limit": 1200.0,  // сумма лимитов после записи
        "inserted": 25,
        "updated": 0,
        "deleted": 0,
        "dups": 0,  // повторы строк: пропущены
        "errors": 0,  // строк не принято
        "error_rows": [  // первые 5 непринятых строк
          {
            "n": 1,  // номер строки
            "text": "…"  // причина отказа дословно
          }
        ],
        "error": "…",  // только у домена, который не записан: тогда, кроме domain, других полей нет
        "start_check": {  // только при `start_check: true` в запросе: итог стартового среза позиций. Отказ среза проект не отменяет: тогда здесь только error
          "snapshot_id": 12,
          "tasks": 25,  // поставлено проверок позиции
          "skipped": 0,
          "error": "…"  // почему срез не поставлен: текст ошибки `POST /projects/{id}/snapshots`
        }
      }
    ],
    "bad": 0  // строк без домена (не попали ни в один проект)
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: domain, keys, text, note, enabled; при keys строками — ещё region, region_mix, brands, clicks, every_days. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `items[<i>].<поле>: неизвестное поле` | в элементе keys[<i>] (текст говорит items[<i>]) поле не из списка: url, key, brands, clicks, every_days, region, region_mix, host_brand | исправьте имя поля |
| 400 | `enabled: true или false` | enabled не булево | передайте true или false |
| 400 | `note: до 200 символов` | note не строка или длиннее 200 символов | сократите заметку |
| 400 | `start_check: true или false` | start_check не булево | передайте true или false |
| 400 | `keys: от 1 до 50000 ключей` | нет ни `keys`, ни `text` строкой, или в keys не 1–50000 элементов | передайте keys или text |
| 400 | `domain: адрес сайта без ; \| # и пробелов, до 500 символов — обязателен, когда keys — строки` | keys — строки, а domain нет, он пуст, длиннее 500 символов или содержит ; \| # пробел | передайте адрес сайта или страницы: https://example.com/catalog |
| 400 | `keys[<i>]: 1–200 символов без ; и \|` | в простом списке строка <i> пуста, длиннее 200 символов или содержит ; \| перевод строки | исправьте ключ <i> (номер с 0); бренды — полем brands |
| 400 | `clicks: целое 1–100000` | простой список: clicks не целое или вне 1–100000 | передайте лимит в сутки целым числом или уберите поле (умолчание 100) |
| 400 | `every_days: целое 1–365` | простой список: every_days не целое или вне 1–365 | передайте число суток или уберите поле (умолчание 1) |
| 400 | `region: номер региона или спинтакс {…} из цифр, { } и \|` | простой список: region не число до 8 цифр и не спинтакс; или в region есть *, а смесь регионов выключена | передайте номер региона Яндекса (213 — Москва) |
| 400 | `region: спинтакс с весами — {a*N\|b}, вес N от 1 до 10000 у варианта внутри {…}` | простой список: region с * при включённой смеси регионов не разбирается — вес вне скобок (213*5), 0, больше 10000 или без числа | исправьте вес: {213*5\|2} |
| 400 | `region: регион длиннее 2200 символов: уберите часть регионов из смеси` | простой список: region или собранная из region_mix строка длиннее 2200 символов | уберите часть регионов из смеси |
| 400 | `region_mix: <текст>` | простой список: общий region_mix не прошёл проверку. Тексты те же, что у items[<i>].region_mix…, без префикса items[<i>]. | исправьте по тексту |
| 400 | `brands: до 20 слов, каждое 1–100 символов без ; и \|` | простой список: brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; \| | исправьте массив бренд-слов |
| 400 | `items[<i>].key: 1–200 символов без ; и \|` | в элементе keys[<i>] (текст говорит items[<i>]): key пуст, длиннее 200 символов, содержит ; \| или перевод строки, или элемент — не объект | исправьте ключ <i> (номер с 0) |
| 400 | `items[<i>].clicks: целое 1–100000` | в элементе keys[<i>] (текст говорит items[<i>]): clicks нет, не целое или вне 1–100000 | передайте лимит в сутки целым числом |
| 400 | `items[<i>].every_days: целое 1–365` | в элементе keys[<i>] (текст говорит items[<i>]): every_days не целое или вне 1–365 | передайте число суток или уберите поле (умолчание 1) |
| 400 | `items[<i>].region: номер региона или спинтакс {…} из цифр, { } и \|` | в элементе keys[<i>] (текст говорит items[<i>]): region не число до 8 цифр и не спинтакс вида {213\|2}; или в region есть *, а смесь регионов выключена (ответ прежний) | передайте номер региона Яндекса (213 — Москва) |
| 400 | `items[<i>].region: спинтакс с весами — {a*N\|b}, вес N от 1 до 10000 у варианта внутри {…}` | в элементе keys[<i>] (текст говорит items[<i>]): region с * при включённой смеси регионов не разбирается — вес вне скобок (213*5), 0, больше 10000 или без числа | исправьте вес: {213*5\|2} |
| 400 | `items[<i>].region: регион длиннее 2200 символов: уберите часть регионов из смеси` | в элементе keys[<i>] (текст говорит items[<i>]): region или собранная из region_mix строка длиннее 2200 символов | уберите часть регионов из смеси |
| 400 | `items[<i>].region_mix: смесь регионов пока выключена` | в элементе keys[<i>] (текст говорит items[<i>]): region_mix | дождитесь включения или передайте region без весов |
| 400 | `items[<i>].region_mix: вместе с region нельзя, задайте одно` | в элементе keys[<i>] (текст говорит items[<i>]): переданы и region, и region_mix | оставьте одно поле |
| 400 | `items[<i>].region_mix: от 1 до 50 строк {group, pct} или {lr, pct}` | в элементе keys[<i>] (текст говорит items[<i>]): region_mix не массив, пустой или длиннее 50 строк | передайте 1–50 строк |
| 400 | `items[<i>].region_mix[<j>]: объект {group, pct} или {lr, pct}` | в элементе keys[<i>] (текст говорит items[<i>]): строка <j> смеси не объект, в ней лишнее поле, нет pct или есть и group, и lr | исправьте строку <j> (номер с 0) |
| 400 | `items[<i>].region_mix[<j>].group: msk, spb, mil, rf или small` | в элементе keys[<i>] (текст говорит items[<i>]): неизвестная группа в строке <j> | возьмите группу из списка |
| 400 | `items[<i>].region_mix[<j>].lr: номер региона Яндекса, целое от 1 до 99999999` | в элементе keys[<i>] (текст говорит items[<i>]): lr строки <j> не целое (строка "54" тоже) или вне 1–99999999 | передайте lr числом |
| 400 | `items[<i>].region_mix[<j>].pct: целое от 5 до 100, кратное 5` | в элементе keys[<i>] (текст говорит items[<i>]): pct строки <j> не целое, вне 5–100 или не кратно 5 | округлите процент до шага 5 |
| 400 | `items[<i>].region_mix: сумма pct <N>, нужно ровно 100` | в элементе keys[<i>] (текст говорит items[<i>]): сумма pct строк смеси N, а не 100 | поправьте проценты до суммы 100 |
| 400 | `смесь регионов пока выключена` | в строке `text` вес *N в поле региона. Не записывается ни один домен | уберите веса из поля региона или дождитесь включения |
| 400 | `регион длиннее 2200 символов: уберите часть регионов из смеси` | в строке `text` поле региона длиннее 2200 символов. Не записывается ни один домен | уберите часть регионов из смеси |
| 400 | `items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и \|` | в элементе keys[<i>] (текст говорит items[<i>]): brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; \| | исправьте массив бренд-слов |
| 400 | `items[<i>].host_brand: 1–100 символов без ; и \|` | в элементе keys[<i>] (текст говорит items[<i>]): host_brand длиннее 100 символов или содержит ; \| | исправьте или уберите host_brand |
| 400 | `items[<i>].url: адрес страницы сайта без ; \| # и пробелов, до 500 символов` | в элементе keys[<i>] (текст говорит items[<i>]): url длиннее 500 символов или содержит ; \| # пробел | передайте адрес страницы без этих символов |
| 400 | `ни одной строки с доменом: загрузите файл или вставьте строки вида https://сайт.ru;ключ;100;&lr=213` | ни в одной строке не нашёлся домен | добавьте сайт в строки или поле domain |
| 201, projects[].error | `лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт` | этот домен не записан: сумма лимитов сайта больше 1 000 000 | уменьшите лимиты ключей этого домена |
| 201, projects[].error | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не записан | повторите запрос: проект с тем же доменом заменит ключи |
| 201, projects[].error | `в проекте есть строки другого сайта: его правит админ` | проект с этим доменом уже есть. Ключи не заменены. | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 201, projects[].start_check.error | `проверка позиции выключена: напишите админу в Telegram` | — | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `разовые задания выключены: напишите админу в Telegram` | — | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `нет денег на балансе: пополните баланс` | у аккаунта стоп по деньгам | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `не хватает денег: <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | непроверенный клиент: баланса не хватит на срез | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | непроверенный клиент: баланса не хватит на срез и разовые задания в работе | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `не хватает денег: <S> проверок среза позиций × <SP> коп. + съём позиций в работе <R> ₽ = <X> ₽, на балансе <B> ₽` | то же, и в работе есть съём позиций: в сумму идёт его наибольшая цена (`reserved_kop` Партий `running`). Слагаемое «съём позиций» добавляется и к остальным вариантам этого текста | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |
| 201, projects[].start_check.error | `ключей больше 2000: срез позиций снимается не больше чем по 2000 ключам` | в проекте больше 2000 ключей | проект создан; срез снимите позже кнопкой или `POST /projects/{id}/snapshots` |

### GET /api/v1/projects/{id}

Проект.

**Кто:** все.

Проект — только свой и нескрытый.

Охват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 1042,
    "domain": "example.com",
    "note": "Диваны",  // заметка (название) проекта
    "enabled": true,  // желание клиента
    "stop_reason": null,  // стоп от панели; проект работает, только если enabled и stop_reason null
    "pending": false,  // вкл/выкл ещё не применён: применяется за секунды
    "limit_day": 1200,  // сумма лимитов включённых ключей в сутки, N@дни — как N/дни. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
    "keys": 25,  // включённых ключей. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
    "budget_kop": null,  // бюджет на весь срок; null — без бюджета
    "spent_kop": 4180,  // списано за всё время
    "today": {
      "clicked": 418,
      "not_found": 37,
      "other": 12  // geo_fail + captcha + error
    },
    "total_clicked": 15230,  // кликов за всё время в статистике
    "avg_position": 4.2,  // средняя Позиция без бренда
    "editable": true  // true — ключи правятся методами `/projects/{id}/keys`. false — проект настроен вручную: ключи через API не правятся
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

### PATCH /api/v1/projects/{id}

Изменить заметку или бюджет.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Меняются только переданные поля. Бюджет — на весь срок проекта: `spent_kop ≥ budget_kop` — стоп `budget`. `budget_kop: null` снимает бюджет. Запрос без тела или `{}` — ответ без изменений.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `note` | строка или null, до 200 символов — заметка; null или пустая строка — стереть |
| `budget_kop` | целое или null, ≥ 0 |

Пример запроса:

```sh
curl -X PATCH 'https://bk-console.com/api/v1/projects/1042' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Диваны, Москва", "budget_kop": 500000}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 1042,
    "domain": "example.com",
    "note": "Диваны",  // заметка (название) проекта
    "enabled": true,  // желание клиента
    "stop_reason": null,  // стоп от панели; проект работает, только если enabled и stop_reason null
    "pending": false,  // вкл/выкл ещё не применён: применяется за секунды
    "limit_day": 1200,  // сумма лимитов включённых ключей в сутки, N@дни — как N/дни. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
    "keys": 25,  // включённых ключей. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными
    "budget_kop": null,  // бюджет на весь срок; null — без бюджета
    "spent_kop": 4180,  // списано за всё время
    "today": {
      "clicked": 418,
      "not_found": 37,
      "other": 12  // geo_fail + captcha + error
    },
    "total_clicked": 15230,  // кликов за всё время в статистике
    "avg_position": 4.2,  // средняя Позиция без бренда
    "editable": true  // true — ключи правятся методами `/projects/{id}/keys`. false — проект настроен вручную: ключи через API не правятся
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: note, budget_kop. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `note: до 200 символов` | note не строка или длиннее 200 символов | сократите заметку |
| 400 | `budget_kop: целое ≥ 0 или null` | budget_kop не целое, отрицательное или больше 10^13 | передайте копейки целым числом или null |
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

### DELETE /api/v1/projects/{id}

Удалить проект.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Как «Удалить» в панели: проект выключается и скрывается, ключи и статистика сохраняются. Вернуть проект — `POST /projects` с тем же доменом.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl -X DELETE 'https://bk-console.com/api/v1/projects/1042' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "hidden": true
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

### PATCH /api/v1/projects/{id}/status

Включить или выключить проект.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Правка применяется за секунды; пока она не применена, `pending` у проекта true. Проект со стопом (`stop_reason`) стоит и включённым. `changed` — 1, если состояние поменялось, 0 — уже было таким.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `enabled` | true или false, обязательно |

Пример запроса:

```sh
curl -X PATCH 'https://bk-console.com/api/v1/projects/1042/status' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "changed": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: enabled. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `enabled: true или false` | enabled нет или не булево | передайте true или false |
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

### GET /api/v1/projects/{id}/keys

Ключи проекта.

**Кто:** все.

Ключи проекта со статистикой за сутки МСК. `cursor` — смещение (число строкой). `q` — часть ключа без учёта регистра: тогда панель читает все ключи проекта и отбирает сама (на больших проектах медленнее).

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `q` | в query, строка — часть ключа |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042/keys' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": "3f2a9c0d1e4b5a67",  // task_key: 16 hex. Меняется вместе с url, ключом без учёта регистра или регионом
      "url": "example.com/catalog",  // страница сайта; null — домен проекта
      "key": "купить диван москва",
      "brands": ["ikea"],
      "clicks": 4,
      "every_days": 1,
      "region": "213",  // регион lr или спинтакс строкой; null — любой регион
      "host_brand": null,
      "enabled": true,
      "today": {
        "clicked": 418,
        "not_found": 37,
        "other": 12  // geo_fail + captcha + error
      }
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не прочитан или не записан | повторите через минуту; не проходит — напишите админу |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | ключи такого проекта через API не правятся: напишите админу в Telegram |

### PUT /api/v1/projects/{id}/keys

Добавить и обновить ключи.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

До 500 ключей за вызов. Ключ, совпавший по `url`, ключу без учёта регистра и региону, обновляется (лимит, бренды, Хост-бренд) и сохраняет счётчики; новый добавляется; остальные ключи проекта не трогаются. `url` ключа должен быть на домене проекта; без `url` берётся домен проекта. url на `www.`-варианте домена проекта — другой домен: 400 `items[<i>].url: сайт другого домена …`. Предел 1 000 000 кликов в сутки на сайт проверяется до записи; в него входят и выключенные ключи проекта.

Простой список вместо `items`: `keys` — массив строк-ключей (1–500), `url`, `region` или `region_mix`, `brands`, `clicks` (умолчание 100) и `every_days` — общие на все ключи; сервер подставляет их в строку каждого ключа. `items` и `keys` вместе — 400. Ошибки общих полей — тексты KeyIn без префикса (`url: …`, `region: …`), ошибка ключа — `keys[<i>]: …`.

Поля вывода `GET /projects/{id}/keys` (`id`, `enabled`, `today`) в `items` не принимаются: 400 `items[<i>].<поле>: неизвестное поле`. Выключение ключей — `PATCH /projects/{id}/keys`.

После записи `limit_day` и `keys` проекта — по включённым ключам (N@дни считается как N/дни). Если пересчёт сразу после записи не удался, до 10 мин в них входят и выключенные ключи.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `items` | массив (объект KeyIn), 1–500 элементов — ключи KeyIn; без keys — обязательно |
| `items[].url` | строка или null — страница сайта (example.com/catalog, со схемой или без), без ; \| # и пробелов, до 500 символов: клик сначала по ней; null — домен проекта |
| `items[].key` | строка, обязательно, длина 1–200 — поисковый запрос, 1–200 символов без ; и \| |
| `items[].brands` | массив (строка), 0–20 элементов — бренд-слова: «ключ слово» ищется, если по ключу сайт не нашёлся |
| `items[].clicks` | целое, обязательно, 1–100000 — кликов в сутки МСК |
| `items[].every_days` | целое, 1–365, умолчание `1` — раз в сколько суток кликается ключ: в каждые сутки — с вероятностью 1/every_days |
| `items[].region` | целое или строка или null — регион Яндекса lr (213) или спинтакс {213\|2}: число или строка; null — любой регион. Вес варианта — суффикс *N внутри {…}: {213*5\|2\|{54\|65}*4}, N от 1 до 10000, без суффикса вес 1; вес делится между регионами варианта поровну. Строка с * — доли регионов держатся по факту кликов за сутки МСК; регион, где сайт плохо находится, ограничивает клики всего ключа. Без * доли — только веса выбора региона. Строка с * — только при включённой смеси регионов, иначе прежний 400 `items[<i>].region: номер региона или спинтакс {…} из цифр, { } и \|` |
| `items[].region_mix` | массив (объект) или null, 1–50 элементов — смесь регионов вместо region: строки «группа или регион — процент». Панель собирает из них спинтакс с весами (проценты, делённые на их НОД; *N у каждого варианта, *1 тоже, поэтому доли держатся по факту кликов; один вариант — без скобок) и пишет его в region ключа. Группы: msk — Москва (213), spb — Питер (2), mil — 14 городов от 1 млн без Москвы и Питера, rf — 94 центра регионов без Москвы, small — 264 города до 100 тыс.; группа — один вариант в своих скобках. Одинаковые варианты (msk и lr 213) складываются. pct — целое от 5 до 100, кратное 5, сумма ровно 100. Вместе с region — 400. Пока смесь регионов выключена — 400 `items[<i>].region_mix: смесь регионов пока выключена` |
| `items[].host_brand` | строка или null, до 100 символов — Хост-бренд вручную, 1–100 символов; null — из домена |
| `keys` | массив (строка), 1–500 элементов — простой список: ключевые фразы без ; и \|, вместо items |
| `url` | строка или null — только с keys: страница всех ключей на домене проекта, как url у KeyIn; без него — домен проекта |
| `region` | целое или строка или null — только с keys: регион всех ключей, как region у KeyIn |
| `region_mix` | массив (объект) или null, 1–50 элементов — только с keys: смесь регионов всех ключей, как region_mix у KeyIn; вместе с region нельзя |
| `brands` | массив (строка), 0–20 элементов — только с keys: бренд-запросы (подсказка) всех ключей, как brands у KeyIn |
| `clicks` | целое, 1–100000, умолчание `100` — только с keys: лимит в сутки каждого ключа |
| `every_days` | целое, 1–365, умолчание `1` — только с keys: раз в столько суток крутится каждый ключ |

Пример запроса:

```sh
curl -X PUT 'https://bk-console.com/api/v1/projects/1042/keys' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"url": "example.com/catalog", "key": "купить диван", "brands": ["ikea"], "clicks": 70, "region": "213"}, {"key": "диван недорого", "clicks": 30, "every_days": 2, "region": 2}]}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {  // Итог записи одного домена: либо поля итога записи, либо domain и error.
    "domain": "example.com",  // домен
    "project_id": 31,
    "existing": false,  // проект уже был: ключи заменены (`POST /projects`)
    "tasks": 25,  // ключей в проекте после записи
    "limit": 1200.0,  // сумма лимитов после записи
    "inserted": 25,
    "updated": 0,
    "deleted": 0,
    "dups": 0,  // повторы строк: пропущены
    "errors": 0,  // строк не принято
    "error_rows": [  // первые 5 непринятых строк
      {
        "n": 1,  // номер строки
        "text": "…"  // причина отказа дословно
      }
    ],
    "error": "…",  // только у домена, который не записан: тогда, кроме domain, других полей нет
    "start_check": {  // только при `start_check: true` в запросе: итог стартового среза позиций. Отказ среза проект не отменяет: тогда здесь только error
      "snapshot_id": 12,
      "tasks": 25,  // поставлено проверок позиции
      "skipped": 0,
      "error": "…"  // почему срез не поставлен: текст ошибки `POST /projects/{id}/snapshots`
    }
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: items; при keys — keys, url, region, region_mix, brands, clicks, every_days. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `items[<i>].<поле>: неизвестное поле` | в элементе ключа поле не из списка: url, key, brands, clicks, every_days, region, region_mix, host_brand; в том числе поля вывода GET /keys: id, enabled, today | уберите поле; выключение ключей — `PATCH /projects/{id}/keys` |
| 400 | `items: от 1 до 500 ключей` | items нет или в нём не 1–500 элементов | разбейте на части по 500 |
| 400 | `items: вместе с keys нельзя, задайте одно` | пришли и items, и keys | оставьте одно поле |
| 400 | `keys: от 1 до 500 ключей` | keys не массив или в нём не 1–500 элементов | разбейте на части по 500 |
| 400 | `keys: массив строк; объекты KeyIn передаются в items` | в keys есть не строка | передайте объекты в items, строки — в keys |
| 400 | `keys[<i>]: 1–200 символов без ; и \|` | строка <i> пуста, длиннее 200 символов или содержит ; \| перевод строки | исправьте ключ <i> (номер с 0); бренды — полем brands |
| 400 | `url: адрес страницы сайта без ; \| # и пробелов, до 500 символов` | простой список: url длиннее 500 символов или содержит ; \| # пробел | передайте адрес страницы без этих символов |
| 400 | `url: сайт другого домена <домен ключа>, у проекта <домен проекта>` | простой список: url на другом домене; `www.`-вариант домена проекта — тоже другой домен | другой сайт — отдельный проект: `POST /projects` |
| 400 | `clicks: целое 1–100000` | простой список: clicks не целое или вне 1–100000 | передайте лимит в сутки целым числом или уберите поле (умолчание 100) |
| 400 | `every_days: целое 1–365` | простой список: every_days не целое или вне 1–365 | передайте число суток или уберите поле (умолчание 1) |
| 400 | `region: номер региона или спинтакс {…} из цифр, { } и \|` | простой список: region не число до 8 цифр и не спинтакс; или в region есть *, а смесь регионов выключена | передайте номер региона Яндекса (213 — Москва) |
| 400 | `region: спинтакс с весами — {a*N\|b}, вес N от 1 до 10000 у варианта внутри {…}` | простой список: region с * при включённой смеси регионов не разбирается — вес вне скобок (213*5), 0, больше 10000 или без числа | исправьте вес: {213*5\|2} |
| 400 | `region: регион длиннее 2200 символов: уберите часть регионов из смеси` | простой список: region или собранная из region_mix строка длиннее 2200 символов | уберите часть регионов из смеси |
| 400 | `region_mix: <текст>` | простой список: общий region_mix не прошёл проверку. Тексты те же, что у items[<i>].region_mix…, без префикса items[<i>]. | исправьте по тексту |
| 400 | `brands: до 20 слов, каждое 1–100 символов без ; и \|` | простой список: brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; \| | исправьте массив бренд-слов |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 400 | `items[<i>].key: 1–200 символов без ; и \|` | в элементе ключа: key пуст, длиннее 200 символов, содержит ; \| или перевод строки, или элемент — не объект | исправьте ключ <i> (номер с 0) |
| 400 | `items[<i>].clicks: целое 1–100000` | в элементе ключа: clicks нет, не целое или вне 1–100000 | передайте лимит в сутки целым числом |
| 400 | `items[<i>].every_days: целое 1–365` | в элементе ключа: every_days не целое или вне 1–365 | передайте число суток или уберите поле (умолчание 1) |
| 400 | `items[<i>].region: номер региона или спинтакс {…} из цифр, { } и \|` | в элементе ключа: region не число до 8 цифр и не спинтакс вида {213\|2}; или в region есть *, а смесь регионов выключена (ответ прежний) | передайте номер региона Яндекса (213 — Москва) |
| 400 | `items[<i>].region: спинтакс с весами — {a*N\|b}, вес N от 1 до 10000 у варианта внутри {…}` | в элементе ключа: region с * при включённой смеси регионов не разбирается — вес вне скобок (213*5), 0, больше 10000 или без числа | исправьте вес: {213*5\|2} |
| 400 | `items[<i>].region: регион длиннее 2200 символов: уберите часть регионов из смеси` | в элементе ключа: region или собранная из region_mix строка длиннее 2200 символов | уберите часть регионов из смеси |
| 400 | `items[<i>].region_mix: смесь регионов пока выключена` | в элементе ключа: region_mix | дождитесь включения или передайте region без весов |
| 400 | `items[<i>].region_mix: вместе с region нельзя, задайте одно` | в элементе ключа: переданы и region, и region_mix | оставьте одно поле |
| 400 | `items[<i>].region_mix: от 1 до 50 строк {group, pct} или {lr, pct}` | в элементе ключа: region_mix не массив, пустой или длиннее 50 строк | передайте 1–50 строк |
| 400 | `items[<i>].region_mix[<j>]: объект {group, pct} или {lr, pct}` | в элементе ключа: строка <j> смеси не объект, в ней лишнее поле, нет pct или есть и group, и lr | исправьте строку <j> (номер с 0) |
| 400 | `items[<i>].region_mix[<j>].group: msk, spb, mil, rf или small` | в элементе ключа: неизвестная группа в строке <j> | возьмите группу из списка |
| 400 | `items[<i>].region_mix[<j>].lr: номер региона Яндекса, целое от 1 до 99999999` | в элементе ключа: lr строки <j> не целое (строка "54" тоже) или вне 1–99999999 | передайте lr числом |
| 400 | `items[<i>].region_mix[<j>].pct: целое от 5 до 100, кратное 5` | в элементе ключа: pct строки <j> не целое, вне 5–100 или не кратно 5 | округлите процент до шага 5 |
| 400 | `items[<i>].region_mix: сумма pct <N>, нужно ровно 100` | в элементе ключа: сумма pct строк смеси N, а не 100 | поправьте проценты до суммы 100 |
| 400 | `items[<i>].brands: до 20 слов, каждое 1–100 символов без ; и \|` | в элементе ключа: brands не массив строк, больше 20 слов, пустое или длинное слово, слово с ; \| | исправьте массив бренд-слов |
| 400 | `items[<i>].host_brand: 1–100 символов без ; и \|` | в элементе ключа: host_brand длиннее 100 символов или содержит ; \| | исправьте или уберите host_brand |
| 400 | `items[<i>].url: адрес страницы сайта без ; \| # и пробелов, до 500 символов` | в элементе ключа: url длиннее 500 символов или содержит ; \| # пробел | передайте адрес страницы без этих символов |
| 400 | `items[<i>].url: сайт другого домена <домен ключа>, у проекта <домен проекта>` | url ключа на другом домене; `www.`-вариант домена проекта — тоже другой домен | другой сайт — отдельный проект: `POST /projects` |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 400 | `лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт` | сумма лимитов в сутки этого проекта после записи (N, вместе с выключенными ключами) и `limit_day` других проектов аккаунта с тем же сайтом без `www.`, включая скрытые (M), больше 1 000 000 | уменьшите лимиты ключей. |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не прочитан или не записан | повторите через минуту; не проходит — напишите админу |

### PATCH /api/v1/projects/{id}/keys

Включить или выключить ключи.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Ключи по `id` (task_key) включаются или выключаются; счётчики сохраняются. Повтор id в списке считается один раз. `changed` — сколько ключей сменили состояние.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `ids` | массив (строка), обязательно, 1–500 элементов |
| `enabled` | true или false, обязательно |

Пример запроса:

```sh
curl -X PATCH 'https://bk-console.com/api/v1/projects/1042/keys' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["3f2a9c0d1e4b5a67"], "enabled": false}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "changed": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: ids, enabled. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `ids: от 1 до 500 id ключей` | ids не массив строк или в нём не 1–500 элементов | передайте id ключей из `GET /projects/{id}/keys` |
| 400 | `enabled: true или false` | enabled нет или не булево | передайте true или false |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не прочитан или не записан | повторите через минуту; не проходит — напишите админу |
| 404 | `ключ не найден: <id>` | ключа с таким id нет в проекте (показан первый из ненайденных) | перечитайте ключи: id меняется вместе с url, ключом и регионом |

### DELETE /api/v1/projects/{id}/keys

Удалить ключи.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Ключи удаляются из проекта. Тот же ключ, добавленный в этот проект снова, получит прежние счётчики (`id` тот же). Тело обязательно: `{"ids": […]}`.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `ids` | массив (строка), обязательно, 1–500 элементов |

Пример запроса:

```sh
curl -X DELETE 'https://bk-console.com/api/v1/projects/1042/keys' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["3f2a9c0d1e4b5a67", "0b1c2d3e4f5a6b7c"]}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "deleted": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: ids. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `ids: от 1 до 500 id ключей` | ids не массив строк или в нём не 1–500 элементов | передайте id ключей |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не прочитан или не записан | повторите через минуту; не проходит — напишите админу |
| 404 | `ключ не найден: <id>` | ключа с таким id нет в проекте | перечитайте ключи: `GET /projects/{id}/keys` |

### POST /api/v1/projects/{id}/boost

Буст: изменить лимиты ключей на процент.

**Кто:** все. **Лимит метода:** `boost` (плюс общий `all`).

Лимит каждого ключа × (1 + pct/100), округление, не меньше 1 и не больше 100 000. Предел сайта 1 000 000 в сутки проверяется до записи по включённым ключам, N@дни — как N/дни. Лимит метода — 1 запрос в минуту. `limit_before`, `limit_after` — суммы `clicks` всех ключей, включая выключенные.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `pct` | число, обязательно, -90–500 |

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/projects/1042/boost' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pct": 20}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "keys": 1,
    "changed": 1,
    "limit_before": 1,
    "limit_after": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: pct. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `pct: число от −90 до 500` | pct нет, не число или вне −90…500 | передайте процент числом |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects`; при `editable: false` ключи через API не правятся |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | ключи такого проекта через API не правятся: напишите админу в Telegram |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: проект не прочитан или не записан | повторите через минуту; не проходит — напишите админу |
| 400 | `лимит <N> в сутки и ещё <M> в других проектах этого сайта: вместе больше 1000000 на сайт` | сумма лимитов в сутки включённых ключей проекта после буста (N) и `limit_day` других проектов аккаунта с тем же сайтом без `www.`, включая скрытые (M), больше 1 000 000 | уменьшите лимиты ключей. |

### GET /api/v1/projects/{id}/snapshots

Срезы позиций проекта.

**Кто:** все.

До 50 срезов, новые первыми. Счётчики — на момент запроса: пока идут проверки, `pending` больше нуля. Первый срез проекта — «Старт».

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042/snapshots' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 12,
      "project_id": 31,
      "origin": "create",  // create — `start_check` при создании проекта; panel — кнопка «Снять срез позиций»; api — `POST /projects/{id}/snapshots` по ключу API
      "created_at": "2026-11-21T10:09:11+00:00",
      "tasks": 25,  // поставлено проверок позиции
      "skipped": 0,  // ключей, по которым проверку поставить нельзя (сайт или фраза не проходят проверку разового задания)
      "pending": 0,  // проверок ещё в работе (`new`, `running`)
      "found": 19,  // сайт найден, позиция снята
      "not_found": 6,  // сайт не найден на 5 страницах выдачи
      "failed": 0,  // без итога: Срок истёк, задание отклонено или снято
      "top10": 4,  // найденных с позицией 1–10
      "avg_position": 17.4,  // средняя позиция найденных, 1 знак; null — ни одного найденного
      "charged_kop": 250  // списано за проверки среза, коп.
    }
  ]
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `проект не найден` | проекта нет, он чужой или скрыт | проверьте id: `GET /projects` |

### POST /api/v1/projects/{id}/snapshots

Снять срез позиций проекта.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

Повтор с тем же `Idempotency-Key` и тем же телом отдаёт сохранённый ответ: задания не ставятся дважды.

По Проверке позиции (разовое задание `click: false`) на каждый включённый ключ проекта: сайт ищется в выдаче на 5 страницах, клика нет. Ключ с одной фразой, сайтом и регионом — одна проверка. Регион проверки — один из региона ключа, случайно по весам; ключ без региона — 213 (Москва). Бренды ключа не участвуют: позиция — по фразе без бренда.

Цена — цена среза позиций за проверку с итогом `found` или `not_found`: одна для всех клиентов, по умолчанию 10 коп.; цена клика к срезу не относится. Списывается цена на момент итога; Срок истёк — бесплатно. Деньги проверяются как у `POST /tasks`. Проверки — разовые задания аккаунта проекта с `project_id`: видны в `GET /tasks`, вебхук по ним не приходит.

Первый срез проекта — «Старт» на графике позиций экрана «Динамика» и колонка «Старт» в его таблице ключей. Итог появляется по мере проверок, обычно в пределах Срока задания (60 мин).

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

Тип: объект.

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/projects/1042/snapshots' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {  // Срез позиций проекта: по Проверке позиции (разовое задание `click: false`) на каждый включённый ключ. Первый срез проекта — «Старт» на графике позиций экрана «Динамика».
    "id": 12,
    "project_id": 31,
    "origin": "create",  // create — `start_check` при создании проекта; panel — кнопка «Снять срез позиций»; api — `POST /projects/{id}/snapshots` по ключу API
    "created_at": "2026-11-21T10:09:11+00:00",
    "tasks": 25,  // поставлено проверок позиции
    "skipped": 0,  // ключей, по которым проверку поставить нельзя (сайт или фраза не проходят проверку разового задания)
    "pending": 0,  // проверок ещё в работе (`new`, `running`)
    "found": 19,  // сайт найден, позиция снята
    "not_found": 6,  // сайт не найден на 5 страницах выдачи
    "failed": 0,  // без итога: Срок истёк, задание отклонено или снято
    "top10": 4,  // найденных с позицией 1–10
    "avg_position": 17.4,  // средняя позиция найденных, 1 знак; null — ни одного найденного
    "charged_kop": 250  // списано за проверки среза, коп.
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | тело — не пустой объект: полей у метода нет | передайте пустое тело или {} |
| 400 | `нет ключей проекта для разовых заданий: сохраните ключи и повторите` | у проекта нет включённых ключей его сайта, или все не проходят проверку разового задания | сохраните ключи проекта |
| 400 | `ключей больше 2000: срез позиций снимается не больше чем по 2000 ключам` | включённых ключей больше 2000 | выключите часть ключей |
| 503 | `разовые задания выключены: напишите админу в Telegram` | разовые задания выключены на всей панели | дождитесь включения или напишите админу |
| 503 | `проверка позиции выключена: напишите админу в Telegram` | — | дождитесь включения или напишите админу |
| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт проекта заблокирован | напишите админу |
| 402 | `нет денег на балансе: пополните баланс` | у аккаунта проекта стоп по деньгам | пополните баланс |
| 402 | `не хватает денег: <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | непроверенный клиент: баланса не хватит на проверки среза в работе и новые по цене среза | пополните баланс |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | непроверенный клиент: то же, и в работе есть разовые задания по цене клика | пополните баланс |
| 402 | `не хватает денег: <S> проверок среза позиций × <SP> коп. + съём позиций в работе <R> ₽ = <X> ₽, на балансе <B> ₽` | то же, и в работе есть съём позиций: в сумму идёт его наибольшая цена (`reserved_kop` Партий `running`). Слагаемое «съём позиций» добавляется и к остальным вариантам этого текста | пополните баланс |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects` |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | напишите админу |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | напишите админу |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: ключи проекта не прочитаны | повторите через минуту; не проходит — напишите админу |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок Idempotency-Key пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить) |

### GET /api/v1/projects/{id}/snapshots/{snapshot_id}

Срез позиций и проверки по ключам.

**Кто:** все.

Срез и его проверки в порядке постановки: позиция, страница и URL найденного сайта.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `snapshot_id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042/snapshots/{snapshot_id}' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {  // Срез позиций (Snapshot) и его проверки по ключам.
    "id": 12,
    "project_id": 31,
    "origin": "create",  // create — `start_check` при создании проекта; panel — кнопка «Снять срез позиций»; api — `POST /projects/{id}/snapshots` по ключу API
    "created_at": "2026-11-21T10:09:11+00:00",
    "tasks": 25,  // поставлено проверок позиции
    "skipped": 0,  // ключей, по которым проверку поставить нельзя (сайт или фраза не проходят проверку разового задания)
    "pending": 0,  // проверок ещё в работе (`new`, `running`)
    "found": 19,  // сайт найден, позиция снята
    "not_found": 6,  // сайт не найден на 5 страницах выдачи
    "failed": 0,  // без итога: Срок истёк, задание отклонено или снято
    "top10": 4,  // найденных с позицией 1–10
    "avg_position": 17.4,  // средняя позиция найденных, 1 знак; null — ни одного найденного
    "charged_kop": 250,  // списано за проверки среза, коп.
    "items": [  // проверки в порядке постановки
      {
        "task_id": 1042,  // id разового задания: `GET /tasks/{id}`
        "key": "купить диван",  // ключевая фраза без брендов
        "region": 213,  // регион проверки: один из региона ключа, случайно по весам; ключ без региона — 213
        "status": "done",
        "outcome": "found",
        "position": 7,  // позиция; null — не найден или ещё нет итога
        "page": 1,
        "found_url": "https://example.com/catalog"
      }
    ]
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `проект не найден` | проекта нет, он чужой или скрыт | проверьте id: `GET /projects` |
| 404 | `срез не найден` | среза с таким id у проекта нет | возьмите id из `GET /projects/{id}/snapshots` |

### POST /api/v1/projects/{id}/oneoff

Разовый проклик ключей проекта.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

Повтор с тем же `Idempotency-Key` и тем же телом отдаёт сохранённый ответ: задания не ставятся дважды.

`times` разовых заданий с кликом на каждый выбранный ключ проекта: `ids` — id ключей (`GET /projects/{id}/keys`), `keys` — фразы (все ключи с этой фразой, регистр не важен), без `ids` и `keys` — все включённые ключи. Ключ × `times` — не больше 2000 заданий за запрос.

Клики идут впереди очереди разовых заданий: в исполнение они уходят первыми, предел 5 заданий одного сайта в исполнении к ним не относится. Регион каждого задания — один из региона ключа, случайно по весам; ключ без региона — 213. Ключ с брендами — первый бренд в режиме `if_not_found`. 3 страницы выдачи.

Списание — как у разового задания: цена клика аккаунта за итог `clicked` или `not_found`. Деньги проверяются до приёма, и у проверенного клиента тоже: проклик — только в пределах баланса. Задания видны в `GET /tasks` с `project_id`, вебхук по ним не приходит.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

| Поле | Значение |
|---|---|
| `times` | целое, обязательно, 1–100 — сколько раз кликнуть каждый ключ |
| `ids` | массив (строка), 1–500 элементов — id ключей; вместе с keys нельзя |
| `keys` | массив (строка), 1–2000 элементов — ключевые фразы; вместе с ids нельзя |

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/projects/1042/oneoff' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["купить диван"], "times": 3}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "created": 3,  // поставлено разовых заданий
    "keys": 1,  // ключей, по которым поставлены задания
    "skipped": 0,  // ключей, не прошедших проверку разового задания
    "times": 3
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: ids, keys, times | исправьте имя поля или уберите его |
| 400 | `times: целое 1–100` | times нет, не целое или вне 1–100 | передайте, сколько раз кликнуть каждый ключ |
| 400 | `ids: вместе с keys нельзя, задайте одно` | в теле и ids, и keys | оставьте одно |
| 400 | `ids: от 1 до 500 id ключей` | ids не массив строк или длина вне 1–500 | передайте id ключей из `GET /projects/{id}/keys` |
| 400 | `keys: от 1 до 2000 фраз` | keys не массив непустых строк или длина вне 1–2000 | передайте ключевые фразы проекта |
| 400 | `заданий больше 2000: ключей × times — не больше 2000 за раз` | ключей × times больше 2000 | выберите меньше ключей или уменьшите times |
| 400 | `нет ключей проекта для разовых заданий: сохраните ключи и повторите` | у проекта нет включённых ключей его сайта, или все не проходят проверку разового задания | сохраните ключи проекта |
| 404 | `ключ не найден: <id или фраза>` | id или фразы нет среди включённых ключей проекта | сверьте с `GET /projects/{id}/keys`; ключ из редактора сначала сохраните |
| 503 | `разовые задания выключены: напишите админу в Telegram` | разовые задания выключены на всей панели | дождитесь включения или напишите админу |
| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт проекта заблокирован | напишите админу |
| 402 | `нет денег на балансе: пополните баланс` | у аккаунта проекта стоп по деньгам | пополните баланс |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽` | баланса не хватит на задания в работе и новые клики. У проклика и проверенный Только в пределах баланса | пополните баланс или уменьшите times |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | то же, и в работе есть проверки среза позиций: они считаются по цене среза | пополните баланс или уменьшите times |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. + съём позиций в работе <R> ₽ = <X> ₽, на балансе <B> ₽` | то же, и в работе есть съём позиций: в сумму идёт его наибольшая цена (`reserved_kop` Партий `running`). Слагаемое «съём позиций» добавляется и к остальным вариантам этого текста | пополните баланс или уменьшите times |
| 404 | `проект не найден или его правит только админ` | проекта нет, он чужой, скрыт или в нём ключи нескольких сайтов | проверьте id: `GET /projects` |
| 409 | `проект настроен вручную: его правит админ` | проект настроен вручную | напишите админу |
| 409 | `в проекте есть строки другого сайта: его правит админ` | в проекте есть ключи другого сайта | напишите админу |
| 502 | `не удалось обработать проект: повторите позже или напишите админу в Telegram` | временный сбой: ключи проекта не прочитаны | повторите через минуту; не проходит — напишите админу |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок Idempotency-Key пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить) |

### GET /api/v1/projects/{id}/stats

Статистика проекта по суткам.

**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).

Строка на каждые сутки МСК периода, сутки без данных — нулями. До 93 суток; без дат — 14 суток по сегодня. Клики — с отставанием около 10 мин.

Охват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `date_from` | в query, строка — первые сутки МСК, ГГГГ-ММ-ДД, от 2000-01-01 до 2100-12-31 |
| `date_to` | в query, строка — последние сутки МСК включительно, от 2000-01-01 до 2100-12-31 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042/stats?date_from=2026-11-01&date_to=2026-11-20' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "date": "2026-11-19",
      "sessions": 470,  // попыток найти сайт в выдаче
      "clicked": 418,
      "not_found": 37,
      "other": 12,
      "clicked_plain": 390,  // клик без бренда
      "clicked_brand": 28,  // клик после поиска с брендом
      "plain_tried": 460,  // Поисков без бренда
      "plain_top10": 401,  // из них сайт в первой десятке
      "avg_position": 4.2,  // средняя Позиция без бренда
      "spent_kop": 4180  // списано за сутки
    }
  ]
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `date_from: дата ГГГГ-ММ-ДД` | дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля) | передайте дату вида 2026-11-20 |
| 400 | `date_to: дата ГГГГ-ММ-ДД` | то же для date_to | передайте дату вида 2026-11-20 |
| 400 | `date_from: дата от 2000-01-01 до 2100-12-31` | date_from раньше 2000-01-01 или позже 2100-12-31 | передайте дату в этих пределах |
| 400 | `date_to: дата от 2000-01-01 до 2100-12-31` | то же для date_to | передайте дату в этих пределах |
| 400 | `date_to раньше date_from` | конец периода раньше начала | поменяйте даты местами |
| 400 | `период больше 93 суток` | между date_from и date_to больше 93 суток включительно | разбейте период на части |
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

### GET /api/v1/projects/{id}/keys/stats

Статистика ключей проекта.

**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).

Суммы по ключам за период: до 31 суток, без дат — сегодня. Ключ без попыток в периоде не выводится. `sort=task_key` (умолчание) — порядок по `id` ключа (task_key) возрастанием, курсор — `id`. `sort=not_found` — по `not_found` убыванием, затем по `id`; курсор вида `<not_found>:<id>`. `only=not_found` — только ключи с `not_found` больше 0. Курсор `sort=not_found` держится на сумме `not_found`, а за сегодняшние сутки она растёт между запросами страниц: ключ, у которого `not_found` вырос выше курсора, на следующих страницах не придёт. Полный перебор без пропусков — с `date_to` раньше сегодня или `sort=task_key&only=not_found` с сортировкой у себя.

Какие ключи не находятся в выдаче: `?only=not_found&sort=not_found`. `id` ключа тот же, что у `GET`, `PUT`, `PATCH`, `DELETE /projects/{id}/keys`: найденный ключ правится сразу. Смена страницы, запроса или региона даёт новый ключ с новым `id`.

`url` и `region` — страница и регион ключа по попыткам за 40 суток. `null` — страница или регион не заданы, попыток не было или данные не получены за 15 с; остальные поля при этом приходят как обычно.

Подсказка `hint_code` и `hint` есть только у ключа с `not_found` больше 0, иначе обе `null`. Подсказка — возможная причина, а не факт:

| `hint_code` | Когда | Текст `hint` |
|---|---|---|
| `other_host` | За период в выдаче попыток с «не найден» был другой поддомен того же сайта, хотя бы в 1/5 таких попыток. Данные не получены — не определяется | `В выдаче был <хост> (в <n> из <nf> попыток с «не найден») — это ваш сайт на другом поддомене: заведите для него отдельный проект` |
| `seen` | Сегодня (сутки МСК) у ключа была позиция в поиске без бренда, независимо от `date_from`, `date_to` | `Сегодня сайт был в выдаче (лучшая позиция #<N>), в этих попытках не попал на просмотренные страницы` |
| `seen` | Сегодня позиции без бренда нет, но были клики: позиция снимается только при поиске без бренда, клик через поиск с брендом позиции не даёт | `Сегодня сайт находили по этой фразе (<n> клик, клика или кликов, позиции без бренда нет), в этих попытках не попал на просмотренные страницы` |
| `never` | Сегодня не было ни позиции, ни клика | `Сегодня сайт ни разу не найден по этой фразе в этом регионе: проверьте фразу, регион и страницу` |

Ветвитесь по `hint_code`: текст `hint` — для человека. `other_host`: ключ проекта не может вести на другой поддомен (`PUT /projects/{id}/keys` отвечает 400), поэтому заведите проект на этом поддомене (`POST /projects`), а старый ключ выключите или удалите (`PATCH`, `DELETE /projects/{id}/keys`).

Охват кликов и позиций — как у `GET /projects`: клиенту только домен проекта.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `date_from` | в query, строка — первые сутки МСК, ГГГГ-ММ-ДД, от 2000-01-01 до 2100-12-31 |
| `date_to` | в query, строка — последние сутки МСК включительно, от 2000-01-01 до 2100-12-31 |
| `sort` | в query, "task_key" \| "not_found", умолчание `"task_key"` — порядок строк: `task_key` — по `id` возрастанием; `not_found` — по `not_found` убыванием, затем по `id`; при `date_to` сегодня перебор страниц может пропустить ключ, чей `not_found` вырос между запросами |
| `only` | в query, "not_found" — `not_found` — только ключи с `not_found` больше 0; нет или пусто — все ключи |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/projects/1042/keys/stats?date_from=2026-11-01&date_to=2026-11-20&sort=not_found&only=not_found' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": "3f2a9c0d1e4b5a67",  // task_key
      "key": "купить диван москва",
      "url": "example.com/catalog",  // страница ключа по попыткам за 40 суток; null — страница не задана (домен проекта), попыток за 40 суток не было или данные не получены за 15 с
      "region": "213",  // регион ключа (lr) по попыткам за 40 суток; null — регион не задан, попыток за 40 суток не было или данные не получены за 15 с
      "sessions": 470,
      "clicked": 418,
      "not_found": 37,
      "other": 12,
      "not_found_pct": 7.9,  // доля not_found от clicked + not_found + other, %, один знак после запятой; исходов нет — 0
      "avg_position": 4.2,
      "best_position": 1,
      "hint_code": "seen",  // почему ключ мог не найтись (таблица в описании метода); null — not_found 0
      "hint": "Сегодня сайт был в выдаче (лучшая позиция #1), в этих попытках не попал на просмотренные страницы"  // текст подсказки для человека; null — not_found 0
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `date_from: дата ГГГГ-ММ-ДД` | дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля) | передайте дату вида 2026-11-20 |
| 400 | `date_to: дата ГГГГ-ММ-ДД` | то же для date_to | передайте дату вида 2026-11-20 |
| 400 | `date_from: дата от 2000-01-01 до 2100-12-31` | date_from раньше 2000-01-01 или позже 2100-12-31 | передайте дату в этих пределах |
| 400 | `date_to: дата от 2000-01-01 до 2100-12-31` | то же для date_to | передайте дату в этих пределах |
| 400 | `date_to раньше date_from` | конец периода раньше начала | поменяйте даты местами |
| 400 | `период больше 31 суток` | между date_from и date_to больше 31 суток включительно | разбейте период на части |
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `sort: task_key или not_found` | sort не task_key и не not_found | передайте task_key или not_found |
| 400 | `only: not_found или пусто` | only не not_found и не пусто | передайте not_found или уберите параметр |
| 400 | `cursor: неверный курсор` | cursor не того вида, что next_cursor при этом sort: 16 hex, при sort=not_found — <число>:<16 hex> | передайте next_cursor прошлого ответа с тем же sort |
| 404 | `проект не найден` | проекта нет, он чужой или скрытый | проверьте id: `GET /projects` |

## Методы: Разовые задания: сайт + ключ + регион, один клик или «не найден», вебхук

### GET /api/v1/tasks

Список разовых заданий.

**Кто:** все.

Задания аккаунта по id убыванием, с фильтрами. `created_from`, `created_to` — ISO 8601; без пояса — UTC; границы включительно.

Параметры:

| Параметр | Значение |
|---|---|
| `status` | в query, "new" \| "running" \| "done" \| "expired" \| "rejected" \| "canceled" |
| `origin` | в query, "api" \| "panel" \| "source" |
| `created_from` | в query, строка |
| `created_to` | в query, строка |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/tasks' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 1042,
      "client_id": "a1",  // свой id задания (items[].id, до 64 символов) или task_id Источника (до 500 символов); null — без id
      "origin": "api",  // api — POST /tasks, panel — экран «Разовые», source — Источник по API.md
      "status": "done",  // new — принято, ждёт исполнения; running — исполняется; done — итог clicked, found или not_found; expired — нет итога за срок; rejected — не принято к исполнению или (задание Источника) не прошло проверку; canceled — снято
      "success": true,  // true — done; false — expired, rejected, canceled; null — ещё в работе
      "site": "example.com",  // хост в нижнем регистре и путь без схемы, query, # и / по краям: так сайт сравнивается с выдачей. Сопоставляйте задания по client_id, не по site
      "key": "купить диван москва",
      "region": 213,
      "brand": "IKEA",
      "brand_mode": "if_not_found",
      "serp_pages": 2,
      "click": false,  // Есть только у проверки позиции и всегда равно false. Нет поля — задание с кликом
      "project_id": 31,  // Есть только у задания проекта: срез позиций или разовый проклик (`POST /projects/{id}/snapshots`, `POST /projects/{id}/oneoff`). Вебхук по такому заданию не приходит
      "result": {
        "outcome": "clicked",  // clicked — кликнули; not_found — сайта нет на serp_pages страницах; found — проверка позиции (`click: false`): сайт найден, клика не было
        "position": 3,  // сквозная Позиция клика по просмотренным страницам органики, с 1; 0 — не найден. У found — позиция найденного сайта
        "page": 1,  // страница выдачи клика; 0 — не найден. У found — страница найденного сайта
        "found_url": "https://example.com/catalog/divany",  // URL, по которому кликнули; null — not_found или URL клика не записан (тогда смотрите landed_url). У found — URL найденного результата выдачи
        "landed_url": "https://example.com/catalog/divany",  // адрес вкладки после клика; null — not_found и found (клика не было)
        "found_by": "url",  // url — совпала страница, domain — домен
        "brand_used": false,  // клик после поиска «ключ бренд». У found — сайт найден в поиске «ключ бренд»
        "plain_position": 3  // Позиция в поиске без бренда; null — не нашёлся или поиска не было
      },
      "attempts": 0,  // попыток с исходом error, captcha, geo_fail: не списываются, задание идёт снова
      "last_error": null,  // «<outcome>: <reason>» последней такой попытки
      "reject_reason": null,  // rejected: текст дословно
      "charged_kop": 10,  // списано за задание (цена клика на момент итога, у проверки среза позиций — цена среза на момент итога); 0 — не списывалось
      "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
      "started_at": "2026-11-20T07:15:30+00:00",  // начало исполнения
      "finished_at": "2026-11-20T07:21:04+00:00",  // время ISO 8601 UTC
      "expires_at": "2026-11-20T08:15:00+00:00"  // срок задания: new к нему — expired сразу; running — через запас срока 5 мин
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `status: new, running, done, expired, rejected или canceled` | status не из списка | передайте одно из значений |
| 400 | `origin: api, panel или source` | origin не из списка | передайте одно из значений |
| 400 | `created_from: время ISO 8601` | created_from не разобралось как время или выходит за края при переводе в UTC (0001-01-01T00:00+05:00) | передайте время вида 2026-11-20T07:00:00Z |
| 400 | `created_to: время ISO 8601` | то же для created_to | передайте время вида 2026-11-20T08:00:00Z |
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |

### POST /api/v1/tasks

Поставить разовые задания.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

До 500 заданий за вызов. Задание исполняется один раз: сайт ищется в выдаче Яндекса, по нему делается клик. Итог — `done` с `result.outcome` `clicked` (позиция и URL клика) или `not_found` (сайта нет на `serp_pages` страницах). Задание с `click: false` — проверка позиции: сайт ищется в выдаче без клика, итог `found` (позиция и URL результата выдачи) или `not_found`. Попытки с ошибкой (капча, сбой, неверный регион) итогом не считаются: задание идёт снова до срока.

Все задания проверяются до приёма: одна ошибка — 400, не принято ни одно. Порядок проверок: тело и задания (400) → `Idempotency-Key` (400, 409, сохранённый ответ) → разовые задания выключены (503) → проверка позиции выключена (503) → деньги (403, 402). Повтор принятого запроса с тем же `Idempotency-Key` получает сохранённый ответ и тогда, когда разовые задания уже выключены. Задание с `id`, который аккаунт уже присылал (через API или панель), не создаётся: в ответе прежнее с `duplicate: true`, деньги на него не проверяются.

Деньги: у непроверенного клиента баланс должен покрыть цену клика × (задания в работе + новые); проверки среза позиций в работе (`POST /projects/{id}/snapshots`) считаются по цене среза. Проверенный клиент ставит задания без этой проверки. Списание — цена клика аккаунта за `clicked`, `found` и `not_found`.

Срок — 60 мин от приёма. Задание в очереди (`new`) к сроку становится `expired`. Задание в исполнении (`running`) ждёт итога ещё запас срока 5 мин: итог в этот запас — `done` со списанием, позже — `expired` без списания. Финальный статус смотрите в `status`, а не по `expires_at`. Итог приходит вебхуком (`PUT /webhook`) и виден в `GET /tasks/{id}`.

Параметры:

| Параметр | Значение |
|---|---|
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

| Поле | Значение |
|---|---|
| `items` | массив (объект TaskIn), обязательно, 1–500 элементов |
| `items[].id` | строка, длина 1–64 — свой id задания, 1–64 символа. Уникален на аккаунт среди заданий api и panel: повтор id возвращает прежнее задание с duplicate true |
| `items[].site` | строка, обязательно, длина 3–300 — домен или URL сайта: example.com или https://example.com/catalog; query и # отбрасываются, сравнение с выдачей идёт по хосту в нижнем регистре и пути |
| `items[].key` | строка, обязательно, длина 1–200 — поисковый запрос, 1–200 символов без ; и \| |
| `items[].region` | целое или строка, обязательно — регион Яндекса lr, целое 1–10000000 или строка из цифр |
| `items[].brand` | строка или null, до 100 символов — бренд-слово или фраза до 100 символов без ; и \| |
| `items[].brand_mode` | "none" \| "if_not_found" \| "always" — none — Поиск только по ключу; if_not_found — по ключу, не нашёлся — «ключ бренд»; always — сразу «ключ бренд». Умолчание: if_not_found при brand, иначе none. if_not_found без brand исполняется как none; always без brand — 400 |
| `items[].serp_pages` | целое, 1–5, умолчание `3` — страниц выдачи в поиске |
| `items[].click` | true или false, умолчание `true` — true — сайт ищется в выдаче, по нему делается клик (итог `clicked` или `not_found`). false — проверка позиции: сайт ищется и позиция снимается без клика (итог `found` или `not_found`). Цена та же — цена клика. Предел 5 заданий одного сайта в исполнении на проверку не действует |

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/tasks' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"id": "a1", "site": "example.com", "key": "купить диван москва", "region": 213, "brand": "IKEA", "brand_mode": "if_not_found", "serp_pages": 2}, {"id": "a2", "site": "https://example.com/catalog", "key": "диван угловой", "region": "2"}]}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "tasks": [
      {
        "task": {
          "id": 1042,
          "client_id": "a1",  // свой id задания (items[].id, до 64 символов) или task_id Источника (до 500 символов); null — без id
          "origin": "api",  // api — POST /tasks, panel — экран «Разовые», source — Источник по API.md
          "status": "done",  // new — принято, ждёт исполнения; running — исполняется; done — итог clicked, found или not_found; expired — нет итога за срок; rejected — не принято к исполнению или (задание Источника) не прошло проверку; canceled — снято
          "success": true,  // true — done; false — expired, rejected, canceled; null — ещё в работе
          "site": "example.com",  // хост в нижнем регистре и путь без схемы, query, # и / по краям: так сайт сравнивается с выдачей. Сопоставляйте задания по client_id, не по site
          "key": "купить диван москва",
          "region": 213,
          "brand": "IKEA",
          "brand_mode": "if_not_found",
          "serp_pages": 2,
          "click": false,  // Есть только у проверки позиции и всегда равно false. Нет поля — задание с кликом
          "project_id": 31,  // Есть только у задания проекта: срез позиций или разовый проклик (`POST /projects/{id}/snapshots`, `POST /projects/{id}/oneoff`). Вебхук по такому заданию не приходит
          "result": {
            "outcome": "clicked",  // clicked — кликнули; not_found — сайта нет на serp_pages страницах; found — проверка позиции (`click: false`): сайт найден, клика не было
            "position": 3,  // сквозная Позиция клика по просмотренным страницам органики, с 1; 0 — не найден. У found — позиция найденного сайта
            "page": 1,  // страница выдачи клика; 0 — не найден. У found — страница найденного сайта
            "found_url": "https://example.com/catalog/divany",  // URL, по которому кликнули; null — not_found или URL клика не записан (тогда смотрите landed_url). У found — URL найденного результата выдачи
            "landed_url": "https://example.com/catalog/divany",  // адрес вкладки после клика; null — not_found и found (клика не было)
            "found_by": "url",  // url — совпала страница, domain — домен
            "brand_used": false,  // клик после поиска «ключ бренд». У found — сайт найден в поиске «ключ бренд»
            "plain_position": 3  // Позиция в поиске без бренда; null — не нашёлся или поиска не было
          },
          "attempts": 0,  // попыток с исходом error, captcha, geo_fail: не списываются, задание идёт снова
          "last_error": null,  // «<outcome>: <reason>» последней такой попытки
          "reject_reason": null,  // rejected: текст дословно
          "charged_kop": 10,  // списано за задание (цена клика на момент итога, у проверки среза позиций — цена среза на момент итога); 0 — не списывалось
          "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
          "started_at": "2026-11-20T07:15:30+00:00",  // начало исполнения
          "finished_at": "2026-11-20T07:21:04+00:00",  // время ISO 8601 UTC
          "expires_at": "2026-11-20T08:15:00+00:00"  // срок задания: new к нему — expired сразу; running — через запас срока 5 мин
        },
        "duplicate": false
      }
    ],
    "created": 1,
    "duplicates": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: items. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `items[<i>].<поле>: неизвестное поле` | в задании поле не из списка: id, site, key, region, brand, brand_mode, serp_pages, click | исправьте имя поля |
| 400 | `items: от 1 до 500 заданий` | items нет или в нём не 1–500 элементов | разбейте на части по 500 |
| 400 | `items[<i>].id: строка 1–64 символа` | id задания не строка или длина не 1–64 | передайте свой id строкой |
| 400 | `items: id «<id>» повторяется в запросе` | два задания в запросе с одним id | сделайте id уникальными |
| 400 | `items[<i>].site: домен или URL сайта, 3–300 символов` | site пуст, короче 3 или длиннее 300 символов, не домен, путь с ; \| или пробелом, или элемент — не объект | передайте example.com или https://example.com/catalog |
| 400 | `items[<i>].key: 1–200 символов без ; и \|` | key пуст, длиннее 200 символов или содержит ; \| перевод строки | исправьте запрос |
| 400 | `items[<i>].region: номер региона Яндекса, целое 1–10000000` | region нет, не целое (или строка цифр) или вне 1–10000000 | передайте номер региона (213 — Москва) |
| 400 | `items[<i>].brand: до 100 символов без ; и \|` | brand не строка, длиннее 100 символов или содержит ; \| | исправьте бренд |
| 400 | `items[<i>].brand_mode: none, if_not_found или always` | brand_mode не из списка | передайте одно из значений или уберите поле |
| 400 | `items[<i>].brand_mode always: нужен brand` | brand_mode always без бренда | добавьте brand или смените режим |
| 400 | `items[<i>].serp_pages: целое 1–5` | serp_pages не целое или вне 1–5 | передайте 1–5 или уберите поле (умолчание 3) |
| 400 | `items[<i>].click: true или false` | click не true и не false | передайте false для проверки позиции или уберите поле (умолчание true — клик) |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок Idempotency-Key пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить) |
| 503 | `разовые задания выключены: напишите админу в Telegram` | разовые задания выключены на всей панели | дождитесь включения или напишите админу |
| 503 | `проверка позиции выключена: напишите админу в Telegram` | в запросе есть задание с click: false | уберите click: false или напишите админу |
| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт заблокирован | напишите админу |
| 402 | `нет денег на балансе: пополните баланс` | у аккаунта стоп по деньгам | пополните баланс |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽` | непроверенный клиент: баланса не хватит на задания в работе и новые | пополните баланс или поставьте меньше заданий |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | то же, и в работе есть проверки среза позиций: они считаются по цене среза | пополните баланс или поставьте меньше заданий |
| 402 | `не хватает денег: <N> заданий в работе и новых × <P> коп. + съём позиций в работе <R> ₽ = <X> ₽, на балансе <B> ₽` | то же, и в работе есть съём позиций: в сумму идёт его наибольшая цена (`reserved_kop` Партий `running`). Слагаемое «съём позиций» добавляется и к остальным вариантам этого текста | пополните баланс или поставьте меньше заданий |

### GET /api/v1/tasks/{id}

Разовое задание.

**Кто:** все.

Задание по id панели (`id` из ответа `POST /tasks`, не свой `id`). Только свои. Опрашивайте не чаще раза в минуту: итог приходит и вебхуком.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/tasks/1042' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 1042,
    "client_id": "a1",  // свой id задания (items[].id, до 64 символов) или task_id Источника (до 500 символов); null — без id
    "origin": "api",  // api — POST /tasks, panel — экран «Разовые», source — Источник по API.md
    "status": "done",  // new — принято, ждёт исполнения; running — исполняется; done — итог clicked, found или not_found; expired — нет итога за срок; rejected — не принято к исполнению или (задание Источника) не прошло проверку; canceled — снято
    "success": true,  // true — done; false — expired, rejected, canceled; null — ещё в работе
    "site": "example.com",  // хост в нижнем регистре и путь без схемы, query, # и / по краям: так сайт сравнивается с выдачей. Сопоставляйте задания по client_id, не по site
    "key": "купить диван москва",
    "region": 213,
    "brand": "IKEA",
    "brand_mode": "if_not_found",
    "serp_pages": 2,
    "click": false,  // Есть только у проверки позиции и всегда равно false. Нет поля — задание с кликом
    "project_id": 31,  // Есть только у задания проекта: срез позиций или разовый проклик (`POST /projects/{id}/snapshots`, `POST /projects/{id}/oneoff`). Вебхук по такому заданию не приходит
    "result": {
      "outcome": "clicked",  // clicked — кликнули; not_found — сайта нет на serp_pages страницах; found — проверка позиции (`click: false`): сайт найден, клика не было
      "position": 3,  // сквозная Позиция клика по просмотренным страницам органики, с 1; 0 — не найден. У found — позиция найденного сайта
      "page": 1,  // страница выдачи клика; 0 — не найден. У found — страница найденного сайта
      "found_url": "https://example.com/catalog/divany",  // URL, по которому кликнули; null — not_found или URL клика не записан (тогда смотрите landed_url). У found — URL найденного результата выдачи
      "landed_url": "https://example.com/catalog/divany",  // адрес вкладки после клика; null — not_found и found (клика не было)
      "found_by": "url",  // url — совпала страница, domain — домен
      "brand_used": false,  // клик после поиска «ключ бренд». У found — сайт найден в поиске «ключ бренд»
      "plain_position": 3  // Позиция в поиске без бренда; null — не нашёлся или поиска не было
    },
    "attempts": 0,  // попыток с исходом error, captcha, geo_fail: не списываются, задание идёт снова
    "last_error": null,  // «<outcome>: <reason>» последней такой попытки
    "reject_reason": null,  // rejected: текст дословно
    "charged_kop": 10,  // списано за задание (цена клика на момент итога, у проверки среза позиций — цена среза на момент итога); 0 — не списывалось
    "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
    "started_at": "2026-11-20T07:15:30+00:00",  // начало исполнения
    "finished_at": "2026-11-20T07:21:04+00:00",  // время ISO 8601 UTC
    "expires_at": "2026-11-20T08:15:00+00:00"  // срок задания: new к нему — expired сразу; running — через запас срока 5 мин
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 404 | `задание не найдено` | задания нет или оно чужое | проверьте id: это `task.id` из ответа `POST /tasks` |

### POST /api/v1/tasks/cancel

Снять разовые задания.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

Задания в очереди (`new`) по id панели становятся `canceled`, без списания, и не исполняются. Задание в исполнении (`running`) не снимается: исполнение могло уже начаться, оно доходит до итога или срока и списывается как обычно. `new`, которое в эту секунду уходит в исполнение, тоже не снимается. Чужие, несуществующие, финальные и такие id пропускаются молча: `canceled` — сколько снято. Снятое задание уходит вебхуком.

Тело запроса:

| Поле | Значение |
|---|---|
| `ids` | массив (целое), обязательно, 1–500 элементов |

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/tasks/cancel' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1042, 1043]}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "canceled": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: ids. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `ids: от 1 до 500 номеров заданий` | ids не массив целых > 0 или в нём не 1–500 элементов | передайте id панели числами |

### GET /api/v1/queue

Очередь разовых заданий.

**Кто:** все. **Лимит метода:** `stats` (плюс общий `all`).

Счётчики аккаунта: в работе сейчас (`new`, `running`) и финальные за сутки МСК. `fleet_max` — сколько разовых заданий всех клиентов исполняется одновременно.

Параметры:

| Параметр | Значение |
|---|---|
| `origin` | в query, "api" \| "panel" \| "source" |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/queue' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "new": 3,
    "running": 12,
    "today": {  // за сутки МСК
      "done": 1,
      "expired": 1,
      "rejected": 1,
      "canceled": 1
    },
    "fleet_max": 2000  // разовых заданий в исполнении одновременно на всю панель
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `origin: api, panel или source` | origin не из списка | передайте одно из значений |

### DELETE /api/v1/queue

Очистить очередь.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

Снимает все задания аккаунта в очереди (`new`) с источником `origin` (без него — все), в том числе задания Источника. `status` — только `new`: задания в исполнении (`running`) не снимаются, как у `POST /tasks/cancel`. Снятые уходят вебхуком или в Источник с `success: false`.

Параметры:

| Параметр | Значение |
|---|---|
| `status` | в query, "new" |
| `origin` | в query, "api" \| "panel" \| "source" |

Пример запроса:

```sh
curl -X DELETE 'https://bk-console.com/api/v1/queue' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "canceled": 1
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `status: только new: начатое задание не снимается` | status не new: running снять нельзя | передайте new или уберите status |
| 400 | `origin: api, panel или source` | origin не из списка | передайте одно из значений |

### GET /api/v1/webhook

Настройки вебхука.

**Кто:** все.

URL вебхука, есть ли секрет и последняя попытка Доставки. Секрет целиком не отдаётся: только первые 4 символа. Вебхук получает событие `task.finished`, когда задание `api` или `panel` стало `done`, `expired`, `rejected` или `canceled`, и событие `positions.finished`, когда закончилась Партия съёма позиций `api` или `panel`. Формат — объект WebhookEvent, подпись — раздел «Вебхук» в `/llms-full.md`.

Поле `error` (и `last_delivery.error` в `GET /webhook`):

| Текст | Что произошло | Что делать |
|---|---|---|
| `HTTP <код>` | ваш сервер ответил не 2xx | ответьте 2xx; тело ответа панель не читает |
| `нет ответа за 10 с` | ваш сервер не ответил за 10 с | отвечайте сразу, обработку делайте после ответа |
| `не удалось подключиться: <текст>` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |
| `адрес ведёт в частную сеть: <ip>` | адрес разрешается в частную сеть; такая Доставка сразу `failed` | укажите публичный адрес |
| `неверный адрес вебхука` | адрес не разбирается как URL (сохранён до нынешних проверок адреса); такая Доставка сразу `failed` | задайте адрес заново: `PUT /webhook` |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/webhook' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "url": "https://example.com/bk-hook",
    "secret_set": true,
    "secret_hint": "9f3a",  // первые 4 символа секрета
    "last_delivery": {
      "at": "…",  // время ISO 8601 UTC
      "http_status": 1,
      "error": "…"
    }
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### PUT /api/v1/webhook

Задать URL вебхука.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

`url: null` выключает вебхук, секрет остаётся. Первый URL создаёт секрет, но не показывает его: получите его `POST /webhook/secret`. Адрес, имя которого пока не разрешается, принимается: ошибку покажут попытки Доставки. Доставка идёт на URL, который был задан в момент итога задания.

Тело запроса:

| Поле | Значение |
|---|---|
| `url` | строка или null, обязательно, до 500 символов |

Пример запроса:

```sh
curl -X PUT 'https://bk-console.com/api/v1/webhook' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/bk-hook"}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "url": "https://example.com/bk-hook",
    "secret_set": true,
    "secret_hint": "9f3a",  // первые 4 символа секрета
    "last_delivery": {
      "at": "…",  // время ISO 8601 UTC
      "http_status": 1,
      "error": "…"
    }
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: url. Из нескольких называется первое по алфавиту | исправьте имя поля или уберите его |
| 400 | `url: адрес http или https до 500 символов` | url нет в теле, не строка, не http(s), без хоста, с логином и паролем, с пробелом или управляющим символом, с портом вне 1–65535, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов | передайте https://ваш-сервер/путь |
| 400 | `url: адрес ведёт в частную сеть` | хост разрешается в частную сеть или loopback | укажите публичный адрес |

### POST /api/v1/webhook/secret

Сменить секрет вебхука.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Новый секрет — 64 hex. Действует сразу, прежний — нет: Доставки после ответа подписываются новым. Секрет показывается только в этом ответе: сохраните его. Тело не нужно.

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/webhook/secret' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "secret": "…"
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 409 | `вебхук не задан: PUT /webhook` | у аккаунта нет URL вебхука | сначала задайте URL: `PUT /webhook` |

### POST /api/v1/webhook/test

Проверить вебхук.

**Кто:** все. **Лимит метода:** `tasks` (плюс общий `all`).

Одна попытка события `ping` (`task: null`) с подписью, без повторов. Ответ — итог попытки; она же видна в `last_delivery`. Тело не нужно. Из панели (вход по cookie) проверка тоже считается в лимит `tasks`: 15 в минуту; превышение — 429.

Поле `error` (и `last_delivery.error` в `GET /webhook`):

| Текст | Что произошло | Что делать |
|---|---|---|
| `HTTP <код>` | ваш сервер ответил не 2xx | ответьте 2xx; тело ответа панель не читает |
| `нет ответа за 10 с` | ваш сервер не ответил за 10 с | отвечайте сразу, обработку делайте после ответа |
| `не удалось подключиться: <текст>` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |
| `адрес ведёт в частную сеть: <ip>` | адрес разрешается в частную сеть; такая Доставка сразу `failed` | укажите публичный адрес |
| `неверный адрес вебхука` | адрес не разбирается как URL (сохранён до нынешних проверок адреса); такая Доставка сразу `failed` | задайте адрес заново: `PUT /webhook` |

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/webhook/test' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "ok": false,  // ответ 2xx
    "http_status": 1,
    "error": "…"
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 409 | `вебхук не задан: PUT /webhook` | у аккаунта нет URL вебхука | сначала задайте URL: `PUT /webhook` |

## Методы: Съём позиций живой выдачи Яндекса: позиция домена, топ N, выдача, Ответ Алисы

### GET /api/v1/positions

Список Партий съёма.

**Кто:** все.

Партии съёма аккаунта по id убыванием.

Параметры:

| Параметр | Значение |
|---|---|
| `status` | в query, "running" \| "done" |
| `project_id` | в query, целое, 1–9223372036854775807 |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/positions' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 41,
      "account_id": 7,
      "origin": "api",  // api — по ключу API, panel — из панели, project — съём ключей проекта
      "project_id": 1,  // проект при `origin: project`
      "status": "running",  // `done` — итоги всех строк записаны и списание проведено
      "items_total": 3,
      "counts": {  // строк по статусу
        "new": 1,
        "running": 1,
        "done": 1,
        "failed": 1,
        "expired": 1
      },
      "has_serp": false,  // есть строки с Выдачей или Ответом Алисы: читать их `GET /positions/{id}/serp`
      "reserved_kop": 1,  // цена всех строк Партии: на неё проверялся баланс при приёме
      "charged_kop": 1,  // списано после конца Партии: строки с итогом × цена строки, округлено до копейки; 0 — пока `running`
      "created_at": "…",
      "expires_at": "…",  // строка, не начатая до этого времени, станет `expired`
      "finished_at": "…"
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `status: running или done` | status не из списка | передайте одно из значений |
| 400 | `project_id: целое 1–9223372036854775807` | project_id не целое | передайте id проекта |
| 400 | `limit: целое 1–500` | limit вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor | передайте next_cursor прошлого ответа как есть |

### POST /api/v1/positions

Снять позиции.

**Кто:** все. **Лимит метода:** `positions` (плюс общий `all`).

Съём позиций живой выдачи Яндекса. До 2000 строк за вызов. Строка поиска домена `{key, lr, domain, depth}` ищет домен в первых `depth` позициях и отдаёт его позицию; строка топа `{key, lr, mode: "top", top}` снимает топ N органики. К любой строке можно попросить Выдачу (`serp`) и Ответ Алисы (`alice`): их отдаёт `GET /positions/{id}/serp`.

Строки с одинаковыми ключом и регионом снимаются за один проход, поэтому все домены по одному ключу выгодно слать одной Партией. Обычно Партия кончается за 1–3 минуты; капча и повторы растягивают её до 15 минут (`expires_at`).

Цена — 5 ₽ за 1000 строк (0,5 коп. за строку, `GET /positions/prices`), одна при любой `depth`, `top`, `serp` и `alice`. Глубина влияет только на скорость: чем меньше `depth`, тем быстрее и надёжнее итог, строка получает его, как только позиция в пределах `depth` найдена или эти позиции пролистаны. У строки поиска глубину задаёт `depth` (10, 20, …, 100, умолчание 100); домен глубже `depth` даёт `not_found` без позиции. У строки топа глубина — её `top`.

Списание — одной операцией после конца Партии, только за строки с итогом `found`, `not_found`, `top_done`; строки `failed` и `expired` бесплатны. Сумма — число таких строк × 0,5 коп., округлённая до копейки по Партии (0,5 — вверх): 1 строка — 1 коп., 727 строк — 364 коп.

Деньги: у непроверенного клиента баланс должен покрыть цену Партии (`reserved_kop`: все её строки) вместе с Партиями и разовыми заданиями в работе. Проверенный клиент — без этой проверки.

Конец Партии шлёт вебхук `positions.finished` (`PUT /webhook`), если вебхук задан.

Порядок проверок: тело и строки (400) → `Idempotency-Key` (400, 409, сохранённый ответ) → съём выключен (503) → деньги (403, 402) → приём съёмом (400, 503).

Параметры:

| Параметр | Значение |
|---|---|
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

| Поле | Значение |
|---|---|
| `items` | массив (объект PosItemIn), обязательно, 1–2000 элементов |
| `items[].key` | строка, обязательно, длина 1–400 — ключевая фраза; пробелы схлопываются, съём переводит в нижний регистр |
| `items[].lr` | целое, обязательно, ≥ 1 — регион Яндекса |
| `items[].domain` | строка, до 300 символов — цель поиска: домен (`divan.ru`, `www.` не важен, поддомен — другой сайт) или адрес с путём (`t.me/канал`, `vk.com/club1`) |
| `items[].depth` | 10 \| 20 \| 30 \| 40 \| 50 \| 60 \| 70 \| 80 \| 90 \| 100, умолчание `100` — только у строки с `domain`: глубина поиска. Позиция глубже — итог `not_found` без позиции. На цену не влияет. **Умолчание 100** — самый долгий поиск |
| `items[].mode` | "top" — `top` — снять топ N органики вместо поиска домена |
| `items[].top` | целое, 1–100, умолчание `100` — только у `mode: top`: сколько позиций органики снять |
| `items[].serp` | "none" \| "sites" \| "full" — что сохранить из выдачи для `GET /positions/{id}/serp`: `sites` — органика (позиция, домен, URL, заголовок), `full` — все блоки со сниппетами, рекламой, колдунщиками. Умолчание: у поиска домена `none`, у топа `sites` |
| `items[].alice` | true или false, умолчание `false` — снять Ответ Алисы с 1-й страницы |

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/positions' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"key": "купить диван", "lr": 213, "domain": "divan.ru", "depth": 30}, {"key": "купить диван", "lr": 213, "domain": "hoff.ru"}, {"key": "купить диван", "lr": 213, "mode": "top", "top": 30, "serp": "full", "alice": true}]}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {  // Партия съёма позиций: строки одного запроса `POST /positions`.
    "id": 41,
    "account_id": 7,
    "origin": "api",  // api — по ключу API, panel — из панели, project — съём ключей проекта
    "project_id": 1,  // проект при `origin: project`
    "status": "running",  // `done` — итоги всех строк записаны и списание проведено
    "items_total": 3,
    "counts": {  // строк по статусу
      "new": 1,
      "running": 1,
      "done": 1,
      "failed": 1,
      "expired": 1
    },
    "has_serp": false,  // есть строки с Выдачей или Ответом Алисы: читать их `GET /positions/{id}/serp`
    "reserved_kop": 1,  // цена всех строк Партии: на неё проверялся баланс при приёме
    "charged_kop": 1,  // списано после конца Партии: строки с итогом × цена строки, округлено до копейки; 0 — пока `running`
    "created_at": "…",
    "expires_at": "…",  // строка, не начатая до этого времени, станет `expired`
    "finished_at": "…"
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: items | исправьте имя поля |
| 400 | `items: от 1 до 2000 строк` | items нет или в нём не 1–2000 элементов | разбейте на Партии по 2000 |
| 400 | `items[<i>]: объект {key, lr, domain} или {key, lr, mode: top, top}` | строка не объект | исправьте строку |
| 400 | `items[<i>].<поле>: неизвестное поле` | в строке поле не из списка: key, lr, domain, depth, mode, top, serp, alice | исправьте имя поля |
| 400 | `items[<i>].key: непустая строка до 400 знаков` | ключ пуст, не строка или длиннее 400 знаков | исправьте ключ |
| 400 | `items[<i>].lr: номер региона Яндекса, целое больше 0` | регион не целое или не больше 0 | передайте номер региона, Москва — 213 |
| 400 | `items[<i>].alice: true или false` | alice не логическое | передайте true или false |
| 400 | `items[<i>]: нужно одно из domain или mode` | нет ни domain, ни mode, или есть оба | оставьте одно |
| 400 | `items[<i>].mode: только top` | mode не top | передайте "mode": "top" |
| 400 | `items[<i>].top: целое 1–100` | top вне 1–100 или не целое | исправьте top |
| 400 | `items[<i>].top: только у строки с mode top` | у строки поиска домена есть top | уберите top или передайте mode: top вместо domain |
| 400 | `items[<i>].depth: 10, 20, 30, 40, 50, 60, 70, 80, 90 или 100` | depth не из списка | передайте глубину, кратную 10 |
| 400 | `items[<i>].depth: только у строки с domain, у топа глубина — top` | у строки топа есть depth | уберите depth, глубину задаёт top |
| 400 | `items[<i>].serp: у строки топа sites или full` | у строки топа serp не sites и не full | исправьте serp |
| 400 | `items[<i>].serp: none, sites или full` | у строки поиска serp не из списка | исправьте serp |
| 400 | `items[<i>].domain: домен или адрес сайта до 300 знаков` | domain не строка, пуст или длиннее 300 знаков | исправьте цель |
| 400 | `items[<i>].domain 'X' — не домен и не адрес сайта (до 300 знаков)` | съём не разобрал цель | исправьте цель |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ |
| 503 | `съём позиций выключен: напишите админу в Telegram` | съём позиций временно выключен | дождитесь включения или напишите админу |
| 503 | `съём позиций недоступен: повторите позже` | сервис съёма не ответил или отказал; Партия не создана, деньги не тронуты | повторите запрос через минуту с тем же Idempotency-Key |
| 403 | `аккаунт заблокирован: напишите админу в Telegram` | аккаунт заблокирован | напишите админу |
| 402 | `нет денег на балансе: пополните баланс` | у аккаунта стоп по деньгам | пополните баланс |
| 402 | `не хватает денег: съём позиций в работе и новый <X> ₽ = <N> ₽, на балансе <B> ₽` | непроверенный клиент: баланса не хватит на цену Партий в работе и новой | пополните баланс или пошлите меньше строк |
| 402 | `не хватает денег: съём позиций в работе и новый <X> ₽ + разовые задания в работе <O> ₽ = <N> ₽, на балансе <B> ₽` | то же, и в работе есть разовые задания | пополните баланс или пошлите меньше строк |

### GET /api/v1/positions/prices

Цены съёма позиций.

**Кто:** все.

Цена съёма: `per_1000_kop` — 1000 строк с итогом, `row_kop` — одна строка. Цена одна при любой глубине, `serp` и `alice`. Списание идёт по цене на момент конца Партии.

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/positions/prices' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "per_1000_kop": 500,  // цена 1000 строк с итогом, коп.
    "row_kop": 0.5  // цена одной строки, коп. (доля копейки); списание Партии округляется до копейки
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### GET /api/v1/positions/{id}

Партия съёма и итоги строк.

**Кто:** все.

Партия и её строки `offset`…`offset+limit` с итогами, без Выдачи. Опрашивайте раз в 15–30 с, пока `status` не станет `done`: итоги строк появляются по мере съёма, `charged_kop` и `price_kop` — после конца Партии. Только свои Партии.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `offset` | в query, целое, 0–2000, умолчание `0` — номер первой строки, 0–2000, умолчание 0 |
| `limit` | в query, целое, 0–2000, умолчание `2000` — сколько строк отдать, 0–2000, умолчание 2000; 0 — только Партия |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/positions/1042' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {}
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `offset: целое 0–2000` | offset вне 0–2000 | исправьте offset |
| 400 | `limit: целое 0–2000` | limit вне 0–2000 | исправьте limit |
| 404 | `съём позиций не найден` | Партии нет или она чужая | проверьте id: это `id` из ответа `POST /positions` |

### GET /api/v1/positions/{id}/serp

Выдача и Ответ Алисы строк Партии.

**Кто:** все. **Лимит метода:** `positions` (плюс общий `all`).

Выдача строк `offset`…`offset+limit` (до 50 за раз), которые её просили (`serp` не `none`, строка топа или `alice: true`). Выдача хранится 7 суток после съёма. Строки без Выдачи в ответ не входят. `serp_status: pending` — повторите запрос через 15–30 с.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `offset` | в query, целое, 0–2000, умолчание `0` — номер первой строки, 0–2000, умолчание 0 |
| `limit` | в query, целое, 1–50, умолчание `50` — строк, 1–50, умолчание 50 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/positions/1042/serp' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 1,
    "offset": 1,
    "limit": 1,
    "serp_error": "…",  // текст сбоя хранилища выдачи; null — выдача прочитана
    "items": [
      {
        "idx": 1,  // номер строки в запросе
        "serp_status": "none",  // `pending` — строка ещё идёт или выдача доезжает (до 120 с после итога), повторите запрос; `ready` — целиком; `partial` — неполная; `error` — хранилище не ответило, повторите
        "serp": [{}]
      }
    ]
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `offset: целое 0–2000` | offset вне 0–2000 | исправьте offset |
| 400 | `limit: целое 1–50` | limit вне 1–50 | читайте частями по 50 |
| 404 | `съём позиций не найден` | Партии нет или она чужая | проверьте id: это `id` из ответа `POST /positions` |
| 404 | `выдача этой Партии уже удалена: она хранится 7 суток` | Партия старше 7 суток | итоги строк остаются в `GET /positions/{id}` |
| 503 | `съём позиций недоступен: повторите позже` | хранилище выдачи не ответило | повторите запрос |

## Методы: Источник заданий: сервер клиента по API.md (GET на адрес забора, POST на адрес результатов)

### GET /api/v1/source

Источник заданий.

**Кто:** все.

Источник — сервер клиента по протоколу API.md. Панель сама берёт с него задания запросом `GET` ровно на `task_url` и шлёт итог `POST` ровно на `result_url`: к адресам ничего не дописывается. `GET /task` и `POST /result` в текстах ниже — названия методов API.md, а не путь запроса. `data: null` — Источник не задан.

Итог задания на адрес в частной сети или на неверный адрес не повторяется: сразу попадает в `results_failed`.

Поле `last_error` Источника. Текст остаётся и после восстановления: сравнивайте `last_error_at` с `last_ok_at`.

| Текст | `state` | Что произошло | Что делать |
|---|---|---|---|
| `сервер клиента отказал в доступе: HTTP <401 или 403> на GET /task — проверьте заголовок авторизации` | `auth` | сервер отказал; забор выключен (`enabled: false`) | исправьте `auth_header`, `auth_value` и включите: `PUT /source` с `enabled: true` |
| `HTTP 404 на GET /task: проверьте адрес` | `error` | по адресу `task_url` ничего нет | исправьте `task_url`: запрос идёт ровно на него |
| `HTTP <код> на GET /task` | `error` | сервер ответил не 200 и не 204 | исправьте сервер; повтор — с паузой 15, 30, 60 … до 600 с |
| `ответ GET /task — не JSON-объект` | `error` | тело не JSON-объект или длиннее 64 КБ | отдавайте одно задание объектом JSON |
| `ответ GET /task без task_id: задание пропущено` | `error` | в ответе нет `task_id` строкой или целым | добавьте `task_id` |
| `ответ GET /task: task_id длиннее 500 символов, задание пропущено` | `error` | `task_id` строкой длиннее 500 символов: задание не берётся | давайте `task_id` до 64 символов |
| `нет ответа за 10 с на GET /task` | `error` | сервер не ответил за 10 с | ускорьте ответ |
| `не удалось подключиться: <текст>` | `error` | имя не разрешилось, порт закрыт, ошибка TLS | проверьте адрес и сертификат |
| `адрес ведёт в частную сеть: <ip>` | `error` | адрес разрешается в частную сеть; забор выключен | укажите публичный адрес и включите забор |
| `неверный адрес` | `error` | адрес Источника не разбирается как URL (сохранён до нынешних проверок адреса); забор выключен | задайте адрес заново и включите: `PUT /source` |
| `разовые задания выключены админом` | `paused` | запросов нет, проверка раз в 60 с | Норма: забор продолжится сам |
| `нет денег на балансе: забор на паузе` | `paused` | у аккаунта стоп: нет денег или аккаунт заблокирован | пополните баланс: забор продолжится сам |
| `не хватает денег: <N> заданий в работе и новых × <P> коп. = <X> ₽, на балансе <B> ₽` | `paused` | непроверенный клиент: баланса не хватит ещё на одно задание | пополните баланс |
| `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` | `paused` | то же, и в работе есть проверки среза позиций: они считаются по цене среза | пополните баланс |
| `суточный потолок <N> заданий: забор продолжится в 00:00 МСК` | `paused` | за сутки МСК взято столько, сколько разрешает потолок | Норма. Поднять — свой `day_limit` или потолок панели |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/source' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 5,
    "account_id": 7,
    "login": "client1",
    "url": "https://tasks.example.com/api",  // для старых клиентов: основа, если адреса ровно `<url>/task` и `<url>/result` (основа без `?`, `#` и `/` в конце); иначе null. Запросы идут на `task_url` и `result_url`
    "task_url": "https://tasks.example.com/api/task",  // полный адрес забора: GET ровно на него
    "result_url": "https://tasks.example.com/api/result",  // полный адрес результатов: POST ровно на него
    "auth_header": "X-Api-Key",  // имя заголовка авторизации
    "auth_value_set": true,  // значение задано; не отдаётся
    "enabled": true,
    "state": "ok",  // off — выключен; ok — задания идут; idle — у сервера нет заданий (204), запрос раз в 15 с; error — ошибка, повтор с паузой 15…600 с; auth — сервер отказал (401, 403), забор выключен; paused — пауза без запросов (деньги, потолок суток, разовые выключены)
    "last_error": null,  // последняя ошибка забора дословно (таблица в описании GET /source); не стирается при успехе — сравнивайте last_error_at с last_ok_at
    "last_error_at": null,  // время ISO 8601 UTC
    "last_ok_at": "2026-11-20T09:01:58+00:00",  // время ISO 8601 UTC
    "inflight": 140,  // заданий Источника в работе
    "inflight_max": 200,  // потолок «в работе»; NULL у Источника — умолчание панели
    "today": 3180,  // взято за сутки МСК
    "day_max": 100000,  // суточный потолок панели; NULL у Источника — умолчание панели
    "day_limit": 5000,  // свой суточный потолок клиента
    "results_pending": 0,  // результатов ждут отправки
    "results_failed": 0  // результатов не доставлено
  }
}
```

Своих ошибок нет: только общие (раздел «Общие ошибки»).

### PUT /api/v1/source

Задать Источник заданий.

**Кто:** все. **Лимит метода:** `write` (плюс общий `all`).

Создаёт или меняет свой Источник.

Адреса — два полных: `task_url` (забор, `GET`) и `result_url` (итог, `POST`). Панель шлёт запрос ровно на них, ничего не дописывая; адреса могут быть на разных хостах, параметры после `?` разрешены. Оба обязательны.

Прежнее поле `url` (база сервера) принимается вместо двух адресов: панель запишет `task_url` = `<url>/task`, `result_url` = `<url>/result`. `url` вместе с `task_url` или `result_url` — 400. В ответе `url` — основа, если адреса ровно `<основа>/task` и `<основа>/result`, иначе `null`.

`auth_header`, `auth_value`, `day_limit` не переданы — остаются прежними; `null` — очищает. Включение, смена любого из двух адресов или авторизации сбрасывают ошибки: забор начинается сразу.

Задания Источника исполняются как разовые задания аккаунта и списываются так же. В работе одновременно — не больше `inflight_max` (старт 200), за сутки МСК — не больше меньшего из `day_max` и своего `day_limit`. Задание с `task_id`, который Источник уже отдавал, заново не исполняется: прежний итог уходит на `result_url` ещё раз.

Тело запроса:

| Поле | Значение |
|---|---|
| `task_url` | строка, до 500 символов — полный адрес забора: запрос GET идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url` |
| `result_url` | строка, до 500 символов — полный адрес результатов: запрос POST идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url` |
| `url` | строка, до 500 символов — прежнее поле вместо двух адресов: база https://host[:port][/путь], панель запишет `<url>/task` и `<url>/result`. Без `?`, `#`, логина и пароля; без `/` в конце — до 493 символов, `/` в конце снимается. Вместе с `task_url` или `result_url` — 400 |
| `auth_header` | строка или null, шаблон `^[A-Za-z0-9-]{1,64}$` — имя заголовка: латиница, цифры, -; не передано — прежнее, null — без авторизации |
| `auth_value` | строка или null, до 1000 символов — значение заголовка: до 1000 печатных символов ASCII; не передано — прежнее |
| `enabled` | true или false, обязательно |
| `day_limit` | целое или null, ≥ 0 — свой суточный потолок; null — потолок панели; не передано — прежнее |

Пример запроса:

```sh
curl -X PUT 'https://bk-console.com/api/v1/source' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_url": "https://tasks.example.com/api/task", "result_url": "https://results.example.com/api/result?token=abc", "auth_header": "X-Api-Key", "auth_value": "secret-value", "day_limit": 5000, "enabled": true}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 5,
    "account_id": 7,
    "login": "client1",
    "url": "https://tasks.example.com/api",  // для старых клиентов: основа, если адреса ровно `<url>/task` и `<url>/result` (основа без `?`, `#` и `/` в конце); иначе null. Запросы идут на `task_url` и `result_url`
    "task_url": "https://tasks.example.com/api/task",  // полный адрес забора: GET ровно на него
    "result_url": "https://tasks.example.com/api/result",  // полный адрес результатов: POST ровно на него
    "auth_header": "X-Api-Key",  // имя заголовка авторизации
    "auth_value_set": true,  // значение задано; не отдаётся
    "enabled": true,
    "state": "ok",  // off — выключен; ok — задания идут; idle — у сервера нет заданий (204), запрос раз в 15 с; error — ошибка, повтор с паузой 15…600 с; auth — сервер отказал (401, 403), забор выключен; paused — пауза без запросов (деньги, потолок суток, разовые выключены)
    "last_error": null,  // последняя ошибка забора дословно (таблица в описании GET /source); не стирается при успехе — сравнивайте last_error_at с last_ok_at
    "last_error_at": null,  // время ISO 8601 UTC
    "last_ok_at": "2026-11-20T09:01:58+00:00",  // время ISO 8601 UTC
    "inflight": 140,  // заданий Источника в работе
    "inflight_max": 200,  // потолок «в работе»; NULL у Источника — умолчание панели
    "today": 3180,  // взято за сутки МСК
    "day_max": 100000,  // суточный потолок панели; NULL у Источника — умолчание панели
    "day_limit": 5000,  // свой суточный потолок клиента
    "results_pending": 0,  // результатов ждут отправки
    "results_failed": 0  // результатов не доставлено
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 400 | `<поле>: неизвестное поле` | в теле поле не из списка: url, task_url, result_url, auth_header, auth_value, day_limit, enabled. Из нескольких называется первое по алфавиту | исправьте имя поля: опечатка в day_limit иначе оставила бы забор без своего потолка |
| 400 | `url: нельзя вместе с task_url и result_url` | в теле `url` и хотя бы один из `task_url`, `result_url` не null: неясно, какой адрес имелся в виду | передайте либо `task_url` и `result_url`, либо только `url` |
| 400 | `task_url: обязательно` | нет ни `url`, ни `task_url` (или он null) | передайте оба адреса: `task_url` и `result_url` |
| 400 | `result_url: обязательно` | нет ни `url`, ни `result_url` (или он null) | передайте оба адреса: `task_url` и `result_url` |
| 400 | `task_url: адрес http или https до 500 символов, без логина и пароля и без #` | task_url не строка, не http(s), без хоста, с логином или паролем, с `#`, с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов. Параметры после `?` разрешены | передайте полный адрес забора: https://host[:порт]/путь[?параметры] |
| 400 | `result_url: адрес http или https до 500 символов, без логина и пароля и без #` | result_url не строка, не http(s), без хоста, с логином или паролем, с `#`, с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов. Параметры после `?` разрешены | передайте полный адрес результатов: https://host[:порт]/путь[?параметры] |
| 400 | `url: адрес http или https до 493 символов, без логина и пароля` | url не строка, не http(s), без хоста, с логином или паролем, с `?` или `#` (даже пустыми в конце), с пробелом или управляющим символом, с портом 0 или неверным, с пустой меткой хоста или меткой длиннее 63 символов (`a..b.com`), длиннее 500 символов или длиннее 493 без `/` в конце (493 = 500 − длина `/result`) | передайте базу сервера https://host[:порт][/путь] или перейдите на `task_url` и `result_url` |
| 400 | `auth_header: латиница, цифры и -, до 64 символов` | имя заголовка с другими символами или длиннее 64 | передайте имя вида X-Api-Key |
| 400 | `auth_value: до 1000 символов` | auth_value не строка или длиннее 1000 символов | сократите значение |
| 400 | `auth_value: только печатные символы ASCII` | в значении перевод строки или не-ASCII | передайте значение из печатных ASCII |
| 400 | `day_limit: целое ≥ 0 или null` | day_limit не целое, отрицательное или больше 2147483647 | передайте число или null |
| 400 | `enabled: true или false` | enabled нет или не булево | передайте true или false |
| 503 | `разовые задания выключены: напишите админу в Telegram` | разовые задания выключены на всей панели | дождитесь включения или напишите админу |
| 400 | `task_url: адрес ведёт в частную сеть` | хост `task_url` разрешается в частную сеть или loopback | укажите публичный адрес |
| 400 | `result_url: адрес ведёт в частную сеть` | хост `result_url` разрешается в частную сеть или loopback | укажите публичный адрес |
| 400 | `url: адрес ведёт в частную сеть` | передан `url`: хост разрешается в частную сеть или loopback | укажите публичный адрес |

## Методы: Субаккаунты реселлера: переводы, цена клика, ссылка входа

### GET /api/v1/subaccounts

Субаккаунты.

**Кто:** реселлер.

Субаккаунты по id возрастанием. Реселлер видит своих. `q` — часть логина, Telegram или метки (до 100 символов).

Параметры:

| Параметр | Значение |
|---|---|
| `q` | в query, строка |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–500, умолчание `100` — строк на странице, 1–500, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/subaccounts' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "id": 58,
      "login": "client1",
      "telegram": "client1_tg",  // логин Telegram без @
      "label": "Иванов, мебель",
      "status": "active",
      "price_kop": 10,  // цена клика субаккаунта
      "balance_kop": 150000,
      "negative_since": null,  // время ISO 8601 UTC
      "projects": 3,  // проектов, в том числе скрытых
      "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
      "spent_today_kop": 3400,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
      "clicked_today": 340,  // фактических кликов за сутки МСК: клики проектов и разовые с итогом clicked
      "parent_id": 7,  // реселлер субаккаунта
      "admin_blocked": false  // Блок поставил админ: снять его может только админ
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 400 | `limit: целое 1–500` | limit не целое или вне 1–500 | передайте limit от 1 до 500 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |

### POST /api/v1/subaccounts

Создать субаккаунт.

**Кто:** реселлер. **Лимит метода:** `write` (плюс общий `all`).

Субаккаунт входит в панель своим логином и видит её как обычный клиент. Пароль не передан — генерируется и возвращается один раз в `password`. Баланс нового субаккаунта — 0: переведите ему деньги (`POST /subaccounts/{id}/transfer`). Цена клика не передана — цена реселлера. Неизвестные поля тела пропускаются молча.

Параметры:

| Параметр | Значение |
|---|---|
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

| Поле | Значение |
|---|---|
| `login` | строка, обязательно, шаблон `^[A-Za-z0-9_.-]{3,32}$` — 3–32 символа: латиница, цифры, _ . - |
| `password` | строка, длина 8–128 — от 8 символов; не передан — сгенерируется и вернётся в ответе |
| `telegram` | строка — @name; не передан — пусто (Telegram реселлера не копируется) |
| `price_kop` | целое, 0–100000 — цена клика; не ниже цены реселлера; умолчание — цена реселлера |
| `label` | строка, до 100 символов |

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/subaccounts' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"login": "client1", "price_kop": 15, "label": "Иванов, мебель"}'
```

Ответ HTTP 201 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "subaccount": {
      "id": 58,
      "login": "client1",
      "telegram": "client1_tg",  // логин Telegram без @
      "label": "Иванов, мебель",
      "status": "active",
      "price_kop": 10,  // цена клика субаккаунта
      "balance_kop": 150000,
      "negative_since": null,  // время ISO 8601 UTC
      "projects": 3,  // проектов, в том числе скрытых
      "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
      "spent_today_kop": 3400,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
      "clicked_today": 340,  // фактических кликов за сутки МСК: клики проектов и разовые с итогом clicked
      "parent_id": 7,  // реселлер субаккаунта
      "admin_blocked": false  // Блок поставил админ: снять его может только админ
    },
    "password": "…"
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 400 | `логин: 3–32 символа, латиница, цифры, _ . -` | login не подходит | исправьте логин |
| 400 | `пароль: от 8 символов` | password не строка или длина не 8–128 | передайте 8–128 символов или не передавайте |
| 400 | `Telegram: логин вида @name, 5–32 символа` | telegram не похож на логин Telegram | передайте @name или уберите поле |
| 400 | `price_kop: целое <P>–100000: не ниже вашей цены клика` | цена клика не целое, ниже вашей цены P или больше 100000 | передайте цену не ниже своей |
| 400 | `label: до 100 символов` | label не строка или длиннее 100 символов | сократите метку |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок Idempotency-Key пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить) |
| 409 | `такой логин уже есть` | логин занят (без учёта регистра) | выберите другой логин |

### GET /api/v1/subaccounts/{id}

Субаккаунт.

**Кто:** реселлер.

Реселлер — только свой субаккаунт.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/subaccounts/1042' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 58,
    "login": "client1",
    "telegram": "client1_tg",  // логин Telegram без @
    "label": "Иванов, мебель",
    "status": "active",
    "price_kop": 10,  // цена клика субаккаунта
    "balance_kop": 150000,
    "negative_since": null,  // время ISO 8601 UTC
    "projects": 3,  // проектов, в том числе скрытых
    "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
    "spent_today_kop": 3400,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
    "clicked_today": 340,  // фактических кликов за сутки МСК: клики проектов и разовые с итогом clicked
    "parent_id": 7,  // реселлер субаккаунта
    "admin_blocked": false  // Блок поставил админ: снять его может только админ
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 404 | `субаккаунт не найден` | субаккаунта нет или он чужой | проверьте id: `GET /subaccounts` |

### PATCH /api/v1/subaccounts/{id}

Изменить субаккаунт.

**Кто:** реселлер. **Лимит метода:** `write` (плюс общий `all`).

Цена клика, метка, блок; меняются только переданные поля, пустой объект `{}` — ответ без изменений (запрос совсем без тела — 400 `тело — не JSON`). Неизвестные поля тела пропускаются молча. Блок закрывает входы субаккаунта и непогашенные ссылки входа, проекты встают на стоп `blocked`. Реселлер ставит цену не ниже своей.

Блок, поставленный админом (`admin_blocked: true`), реселлер не снимает: `status: active` даёт 403.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Тело запроса:

| Поле | Значение |
|---|---|
| `price_kop` | целое, 0–100000 |
| `label` | строка или null, до 100 символов |
| `status` | "active" \| "blocked" |

Пример запроса:

```sh
curl -X PATCH 'https://bk-console.com/api/v1/subaccounts/1042' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price_kop": 20, "status": "blocked"}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "id": 58,
    "login": "client1",
    "telegram": "client1_tg",  // логин Telegram без @
    "label": "Иванов, мебель",
    "status": "active",
    "price_kop": 10,  // цена клика субаккаунта
    "balance_kop": 150000,
    "negative_since": null,  // время ISO 8601 UTC
    "projects": 3,  // проектов, в том числе скрытых
    "created_at": "2026-11-20T07:15:00+00:00",  // время ISO 8601 UTC
    "spent_today_kop": 3400,  // списано за сутки МСК по времени клика; разовые задания — по времени списания
    "clicked_today": 340,  // фактических кликов за сутки МСК: клики проектов и разовые с итогом clicked
    "parent_id": 7,  // реселлер субаккаунта
    "admin_blocked": false  // Блок поставил админ: снять его может только админ
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 400 | `price_kop: целое <P>–100000: не ниже вашей цены клика` | реселлер: цена ниже его цены P, не целое или больше 100000 | передайте цену не ниже своей |
| 400 | `label: до 100 символов` | label не строка или длиннее 100 символов | сократите метку |
| 400 | `status: active или blocked` | status не из списка | передайте active или blocked |
| 404 | `субаккаунт не найден` | субаккаунта нет или он чужой | проверьте id: `GET /subaccounts` |
| 403 | `субаккаунт заблокирован админом: снять блок может только админ` | реселлер передал status active, а блок поставил админ (admin_blocked: true) | напишите админу в Telegram |

### POST /api/v1/subaccounts/{id}/transfer

Перевести деньги субаккаунту или вернуть.

**Кто:** реселлер. **Лимит метода:** `money` (плюс общий `all`).

`to_sub` — с баланса реселлера на баланс субаккаунта, `from_sub` — обратно. В минус перевод не уводит: кредит проверенного клиента на переводы не действует. У непроверенного субаккаунта `from_sub` не забирает резерв под его разовые задания в работе: (`new` + `running`) × его цена клика. У непроверенного реселлера `to_sub` так же не переводит резерв под его собственные разовые задания в работе. Две строки `transfer` (у отправителя и получателя) в одной транзакции. `comment` длиннее 500 символов обрезается. Шлите с `Idempotency-Key`. Неизвестные поля тела пропускаются молча.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |
| `Idempotency-Key` | заголовок, строка, длина 1–64 — ключ повтора запроса. Тот же ключ и то же тело — сохранённый ответ без повтора действия; другое тело — 409 |

Тело запроса:

| Поле | Значение |
|---|---|
| `amount_kop` | целое, обязательно, 1–10000000000 |
| `direction` | "to_sub" \| "from_sub", обязательно |
| `comment` | строка, до 500 символов — заметка: попадает только в строку реселлера, субаккаунт её не видит |

Пример запроса:

```sh
IDEM=$(uuidgen)    # новый ключ на каждое действие; повтор после таймаута — с тем же $IDEM
curl -X POST 'https://bk-console.com/api/v1/subaccounts/1042/transfer' \
  -H "X-Auth-Token: $BK_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"amount_kop": 100000, "direction": "to_sub", "comment": "аванс за ноябрь"}'
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "parent_balance_kop": 1,
    "sub_balance_kop": 1,
    "transaction_ids": [1]
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 400 | `amount_kop: целое 1–10000000000` | сумма не целое или вне 1…10^10 копеек | передайте копейки целым числом |
| 400 | `direction: to_sub или from_sub` | direction не из списка | передайте to_sub или from_sub |
| 400 | `Idempotency-Key: 1–64 символа` | заголовок Idempotency-Key пуст или длиннее 64 символов | передайте ключ 1–64 символа |
| 409 | `Idempotency-Key уже использован другим методом` | тот же Idempotency-Key уже был на другом пути или методе | для нового действия — новый ключ |
| 409 | `Idempotency-Key уже использован с другим телом запроса` | тот же Idempotency-Key пришёл с другим телом | для нового действия — новый ключ; повтор шлите с тем же телом байт в байт по смыслу (ключи JSON можно переставить) |
| 404 | `субаккаунт не найден` | субаккаунта нет или он чужой | проверьте id: `GET /subaccounts` |
| 402 | `недостаточно денег на балансе: <B> ₽` | to_sub: у реселлера меньше суммы перевода (B — его баланс) | пополните баланс или переведите меньше |
| 402 | `недостаточно денег на балансе: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе` | to_sub у непроверенного реселлера: баланс минус резерв R под его разовые задания в работе меньше суммы | переведите не больше F или дождитесь итога заданий |
| 402 | `недостаточно денег у субаккаунта: <B> ₽` | from_sub: у субаккаунта меньше суммы | верните не больше B |
| 402 | `недостаточно денег у субаккаунта: свободно <F> ₽, <R> ₽ в резерве под разовые задания в работе` | from_sub у непроверенного субаккаунта: баланс минус резерв R меньше суммы | верните не больше F или дождитесь итога заданий |

### POST /api/v1/subaccounts/{id}/login-link

Ссылка входа в субаккаунт.

**Кто:** реселлер. **Лимит метода:** `login_link` (плюс общий `all`).

Одноразовая ссылка входа без пароля, живёт 5 минут. Открытая один раз — гаснет. Отдайте её клиенту, сами не открывайте и не пишите в журналы. Ссылка ведёт на домен, с которого пришёл запрос. Тело не нужно.

Параметры:

| Параметр | Значение |
|---|---|
| `id` | в пути, целое, обязательно, 1–9223372036854775807 |

Пример запроса:

```sh
curl -X POST 'https://bk-console.com/api/v1/subaccounts/1042/login-link' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": {
    "url": "…",
    "expires_in": 300
  }
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 404 | `субаккаунт не найден` | субаккаунта нет или он чужой | проверьте id: `GET /subaccounts` |
| 409 | `субаккаунт заблокирован` | субаккаунт в статусе blocked | снимите блок: `PATCH /subaccounts/{id}` |

### GET /api/v1/subaccounts/report

Отчёт по субаккаунтам.

**Кто:** реселлер. **Лимит метода:** `stats` (плюс общий `all`).

Строка на субаккаунт за период: сутки МСК, до 93. Без `date_from` — 30 суток по `date_to`, без `date_to` — по сегодня. Субаккаунт без движения денег в периоде и с нулём на начало не выводится. Возвраты (`refund`) отдельной колонкой не показаны: при них `closing_kop − opening_kop` не равно сумме колонок.

Параметры:

| Параметр | Значение |
|---|---|
| `date_from` | в query, строка — первые сутки МСК, ГГГГ-ММ-ДД, от 2000-01-01 до 2100-12-31 |
| `date_to` | в query, строка — последние сутки МСК включительно, от 2000-01-01 до 2100-12-31 |
| `cursor` | в query, строка — next_cursor прошлой страницы |
| `limit` | в query, целое, 1–100, умолчание `100` — строк на странице, 1–100, умолчание 100 |

Пример запроса:

```sh
curl 'https://bk-console.com/api/v1/subaccounts/report?date_from=2026-11-01&date_to=2026-11-20' \
  -H "X-Auth-Token: $BK_KEY"
```

Ответ HTTP 200 (комментарии `//` — пояснения, в ответе их нет):

```jsonc
{
  "ok": true,
  "data": [
    {
      "account_id": 58,
      "login": "client1",
      "parent_id": 7,
      "opening_kop": 100000,  // баланс на начало периода: balance_after последней строки до него; 0 — строк не было
      "deposits_kop": 0,
      "adjust_kop": 0,
      "transfer_in_kop": 50000,
      "transfer_out_kop": 0,  // по модулю
      "commission_kop": 0,
      "charged_kop": 21000,  // списано, по модулю
      "clicks": 2100,  // списанных единиц: клики проектов и разовые задания с любым итогом, по 1. Фактические клики — clicks − oneoff_not_found − oneoff_found
      "oneoff_clicked": 120,
      "oneoff_not_found": 14,
      "oneoff_found": 5,  // Списаний за проверки позиции с итогом found. Есть только когда больше 0
      "closing_kop": 129000  // баланс на конец периода
    }
  ],
  "next_cursor": "…"  // курсор следующей страницы; null — страниц больше нет
}
```

Ошибки метода (кроме общих), текст дословно, `<…>` — подставляемое значение:

| HTTP | Текст | Что произошло | Что делать |
|---|---|---|---|
| 403 | `субаккаунт не может заводить субаккаунты` | метод вызвал субаккаунт | методы субаккаунтов — только у реселлера |
| 403 | `субаккаунты выключены: напишите админу в Telegram` | аккаунт не реселлер | попросите админа включить субаккаунты |
| 400 | `date_from: дата ГГГГ-ММ-ДД` | дата не в формате ГГГГ-ММ-ДД или такой даты нет (30 февраля) | передайте дату вида 2026-11-20 |
| 400 | `date_to: дата ГГГГ-ММ-ДД` | то же для date_to | передайте дату вида 2026-11-20 |
| 400 | `date_from: дата от 2000-01-01 до 2100-12-31` | date_from раньше 2000-01-01 или позже 2100-12-31 | передайте дату в этих пределах |
| 400 | `date_to: дата от 2000-01-01 до 2100-12-31` | то же для date_to | передайте дату в этих пределах |
| 400 | `date_to раньше date_from` | конец периода раньше начала | поменяйте даты местами |
| 400 | `период больше 93 суток` | между date_from и date_to больше 93 суток включительно | разбейте период на части |
| 400 | `limit: целое 1–100` | limit не целое или вне 1–100 | передайте limit от 1 до 100 |
| 400 | `cursor: неверный курсор` | cursor не из next_cursor прошлой страницы | передайте next_cursor прошлого ответа как есть |

## Объекты

Поля объектов, на которые ссылаются методы.

### Error

| Поле | Значение |
|---|---|
| `ok` | false, обязательно |
| `error` | строка, обязательно — текст ошибки дословно: по нему ветвится вызывающий код |

### Account

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `login` | строка, обязательно |
| `role` | "client", обязательно |
| `parent_id` | целое или null, обязательно — реселлер субаккаунта; null — обычный аккаунт |
| `reseller` | true или false, обязательно — может заводить субаккаунты |
| `verified` | true или false, обязательно — проверенный клиент: при нуле проекты идут ещё credit_days суток |
| `price_kop` | целое, обязательно — цена клика и разового задания, копейки |
| `balance_kop` | целое, обязательно — баланс, копейки |
| `negative_since` | строка или null, обязательно — с какого момента баланс ≤ 0 |
| `credit_days` | целое, обязательно — суток кредита проверенного клиента |
| `stop` | "blocked" \| "balance" \| null, обязательно — стоп аккаунта: blocked — заблокирован, balance — нет денег; null — работает |

### ApiKey

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `prefix` | строка, обязательно — первые 10 символов ключа для узнавания |
| `name` | строка, обязательно |
| `created_at` | строка, обязательно — время ISO 8601 UTC |
| `last_used_at` | строка или null, обязательно — не чаще раза в минуту |
| `last_ip` | строка или null, обязательно |

### ApiKeyCreated

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `key` | строка, обязательно — ключ целиком: показывается один раз, в панели хранится только sha256 |
| `prefix` | строка, обязательно |
| `name` | строка, обязательно |
| `created_at` | строка, обязательно — время ISO 8601 UTC |

### Performance

| Поле | Значение |
|---|---|
| `date` | строка, обязательно — сутки МСК |
| `plan_clicks` | целое, обязательно — сумма лимитов в сутки включённых проектов без стопа |
| `clicked` | целое, обязательно — кликов за сутки МСК (отставание около 10 мин) |
| `not_found` | целое, обязательно — «сайт не найден» за сутки |
| `other` | целое, обязательно — прочие исходы за сутки: гео, капча, сбой |
| `spent_kop` | целое, обязательно — списано за сутки МСК по времени клика; разовые задания — по времени списания |
| `oneoff` | объект, обязательно |
| `balance_kop` | целое, обязательно |
| `days_left` | число или null, обязательно — баланс / средний расход в сутки за время с первого списания за 7 суток (не меньше часа, не больше 7 суток); расход — по времени клика; расхода не было — null |

### Balance

| Поле | Значение |
|---|---|
| `balance_kop` | целое, обязательно |
| `price_kop` | целое, обязательно |
| `verified` | true или false, обязательно |
| `credit_days` | целое, обязательно |
| `credit_limit_kop` | целое или null, обязательно — кредитный лимит; null — по умолчанию панели |
| `negative_since` | строка или null, обязательно — время ISO 8601 UTC |
| `stop` | "blocked" \| "balance" \| null, обязательно |
| `spent_today_kop` | целое, обязательно — списано за сутки МСК по времени клика; разовые задания — по времени списания |
| `spent_7d_kop` | целое, обязательно — списано за 7 суток по времени клика; разовые задания — по времени списания |

### Transaction

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `kind` | "deposit" \| "charge" \| "refund" \| "adjust" \| "transfer" \| "commission", обязательно — deposit — пополнение, charge — списание за клики или разовое задание, refund — возврат, adjust — корректировка, transfer — перевод реселлер ↔ субаккаунт, commission — комиссия реселлера: из оплаченной части списания субаккаунта, списание в долг Комиссии не даёт (строка с 0) |
| `amount_kop` | целое, обязательно — > 0 — зачисление, < 0 — списание |
| `balance_after` | целое, обязательно — баланс после строки |
| `clicks` | целое или null, обязательно — charge и commission: списанных единиц — клики за окно 5 мин или 1 за разовое задание при любом итоге (фактический клик разового — outcome = clicked) |
| `comment` | строка или null, обязательно — у transfer субаккаунта — «пополнение от реселлера» или «возврат реселлеру»: логин и заметку реселлера субаккаунт не видит |
| `created_at` | строка, обязательно — время ISO 8601 UTC |
| `project_id` | целое или null, обязательно |
| `domain` | строка или null, обязательно — домен проекта |
| `hidden` | true или false или null — проект удалён клиентом (скрыт); у нового проекта может быть тот же домен. Без проекта — null |
| `oneoff_id` | целое или null, обязательно — разовое задание |
| `outcome` | строка или null — Итог разового задания (clicked, found, not_found); не разовое — null. clicks у разового 1 при любом итоге, кликом оно стало только при clicked |
| `peer_id` | целое или null, обязательно — transfer, commission: другой аккаунт; субаккаунту — null |

### Project

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `domain` | строка, обязательно |
| `note` | строка, обязательно — заметка (название) проекта |
| `enabled` | true или false, обязательно — желание клиента |
| `stop_reason` | "blocked" \| "budget" \| "balance" \| null, обязательно — стоп от панели; проект работает, только если enabled и stop_reason null |
| `pending` | true или false, обязательно — вкл/выкл ещё не применён: применяется за секунды |
| `limit_day` | целое, обязательно — сумма лимитов включённых ключей в сутки, N@дни — как N/дни. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными |
| `keys` | целое, обязательно — включённых ключей. Сразу после `POST /projects` (до 10 мин) — вместе с выключенными |
| `budget_kop` | целое или null, обязательно — бюджет на весь срок; null — без бюджета |
| `spent_kop` | целое, обязательно — списано за всё время |
| `today` | объект, обязательно |
| `total_clicked` | целое, обязательно — кликов за всё время в статистике |
| `avg_position` | число или null, обязательно — средняя Позиция без бренда |
| `editable` | true или false, обязательно — true — ключи правятся методами `/projects/{id}/keys`. false — проект настроен вручную: ключи через API не правятся |

### KeyIn

Ключ проекта в запросе. Поля вывода `GET /projects/{id}/keys` (`id`, `enabled`, `today`) не принимаются: 400 `items[<i>].<поле>: неизвестное поле`.

| Поле | Значение |
|---|---|
| `url` | строка или null — страница сайта (example.com/catalog, со схемой или без), без ; \| # и пробелов, до 500 символов: клик сначала по ней; null — домен проекта |
| `key` | строка, обязательно, длина 1–200 — поисковый запрос, 1–200 символов без ; и \| |
| `brands` | массив (строка), 0–20 элементов — бренд-слова: «ключ слово» ищется, если по ключу сайт не нашёлся |
| `clicks` | целое, обязательно, 1–100000 — кликов в сутки МСК |
| `every_days` | целое, 1–365, умолчание `1` — раз в сколько суток кликается ключ: в каждые сутки — с вероятностью 1/every_days |
| `region` | целое или строка или null — регион Яндекса lr (213) или спинтакс {213\|2}: число или строка; null — любой регион. Вес варианта — суффикс *N внутри {…}: {213*5\|2\|{54\|65}*4}, N от 1 до 10000, без суффикса вес 1; вес делится между регионами варианта поровну. Строка с * — доли регионов держатся по факту кликов за сутки МСК; регион, где сайт плохо находится, ограничивает клики всего ключа. Без * доли — только веса выбора региона. Строка с * — только при включённой смеси регионов, иначе прежний 400 `items[<i>].region: номер региона или спинтакс {…} из цифр, { } и \|` |
| `region_mix` | массив (объект) или null, 1–50 элементов — смесь регионов вместо region: строки «группа или регион — процент». Панель собирает из них спинтакс с весами (проценты, делённые на их НОД; *N у каждого варианта, *1 тоже, поэтому доли держатся по факту кликов; один вариант — без скобок) и пишет его в region ключа. Группы: msk — Москва (213), spb — Питер (2), mil — 14 городов от 1 млн без Москвы и Питера, rf — 94 центра регионов без Москвы, small — 264 города до 100 тыс.; группа — один вариант в своих скобках. Одинаковые варианты (msk и lr 213) складываются. pct — целое от 5 до 100, кратное 5, сумма ровно 100. Вместе с region — 400. Пока смесь регионов выключена — 400 `items[<i>].region_mix: смесь регионов пока выключена` |
| `host_brand` | строка или null, до 100 символов — Хост-бренд вручную, 1–100 символов; null — из домена |

### Key

| Поле | Значение |
|---|---|
| `id` | строка, обязательно — task_key: 16 hex. Меняется вместе с url, ключом без учёта регистра или регионом |
| `url` | строка или null, обязательно — страница сайта; null — домен проекта |
| `key` | строка, обязательно |
| `brands` | массив (строка), обязательно |
| `clicks` | целое, обязательно |
| `every_days` | целое, обязательно |
| `region` | строка или null, обязательно — регион lr или спинтакс строкой; null — любой регион |
| `host_brand` | строка или null, обязательно |
| `enabled` | true или false, обязательно |
| `today` | объект, обязательно |

### ImportResult

Итог записи одного домена: либо поля итога записи, либо domain и error.

| Поле | Значение |
|---|---|
| `domain` | строка, обязательно — домен |
| `project_id` | целое или null |
| `existing` | true или false — проект уже был: ключи заменены (`POST /projects`) |
| `tasks` | целое или null — ключей в проекте после записи |
| `limit` | число или null — сумма лимитов после записи |
| `inserted` | целое или null |
| `updated` | целое или null |
| `deleted` | целое или null |
| `dups` | целое — повторы строк: пропущены |
| `errors` | целое — строк не принято |
| `error_rows` | массив (объект) — первые 5 непринятых строк |
| `error` | строка — только у домена, который не записан: тогда, кроме domain, других полей нет |
| `start_check` | объект — только при `start_check: true` в запросе: итог стартового среза позиций. Отказ среза проект не отменяет: тогда здесь только error |

### DayStat

| Поле | Значение |
|---|---|
| `date` | строка, обязательно |
| `sessions` | целое, обязательно — попыток найти сайт в выдаче |
| `clicked` | целое, обязательно |
| `not_found` | целое, обязательно |
| `other` | целое, обязательно |
| `clicked_plain` | целое, обязательно — клик без бренда |
| `clicked_brand` | целое, обязательно — клик после поиска с брендом |
| `plain_tried` | целое, обязательно — Поисков без бренда |
| `plain_top10` | целое, обязательно — из них сайт в первой десятке |
| `avg_position` | число или null, обязательно — средняя Позиция без бренда |
| `spent_kop` | целое, обязательно — списано за сутки |

### KeyStat

| Поле | Значение |
|---|---|
| `id` | строка, обязательно — task_key |
| `key` | строка, обязательно |
| `url` | строка или null, обязательно — страница ключа по попыткам за 40 суток; null — страница не задана (домен проекта), попыток за 40 суток не было или данные не получены за 15 с |
| `region` | строка или null, обязательно — регион ключа (lr) по попыткам за 40 суток; null — регион не задан, попыток за 40 суток не было или данные не получены за 15 с |
| `sessions` | целое, обязательно |
| `clicked` | целое, обязательно |
| `not_found` | целое, обязательно |
| `other` | целое, обязательно |
| `not_found_pct` | число, обязательно — доля not_found от clicked + not_found + other, %, один знак после запятой; исходов нет — 0 |
| `avg_position` | число или null, обязательно |
| `best_position` | целое или null, обязательно |
| `hint_code` | "other_host" \| "seen" \| "never" \| null, обязательно — почему ключ мог не найтись (таблица в описании метода); null — not_found 0 |
| `hint` | строка или null, обязательно — текст подсказки для человека; null — not_found 0 |

### TaskIn

| Поле | Значение |
|---|---|
| `id` | строка, длина 1–64 — свой id задания, 1–64 символа. Уникален на аккаунт среди заданий api и panel: повтор id возвращает прежнее задание с duplicate true |
| `site` | строка, обязательно, длина 3–300 — домен или URL сайта: example.com или https://example.com/catalog; query и # отбрасываются, сравнение с выдачей идёт по хосту в нижнем регистре и пути |
| `key` | строка, обязательно, длина 1–200 — поисковый запрос, 1–200 символов без ; и \| |
| `region` | целое или строка, обязательно — регион Яндекса lr, целое 1–10000000 или строка из цифр |
| `brand` | строка или null, до 100 символов — бренд-слово или фраза до 100 символов без ; и \| |
| `brand_mode` | "none" \| "if_not_found" \| "always" — none — Поиск только по ключу; if_not_found — по ключу, не нашёлся — «ключ бренд»; always — сразу «ключ бренд». Умолчание: if_not_found при brand, иначе none. if_not_found без brand исполняется как none; always без brand — 400 |
| `serp_pages` | целое, 1–5, умолчание `3` — страниц выдачи в поиске |
| `click` | true или false, умолчание `true` — true — сайт ищется в выдаче, по нему делается клик (итог `clicked` или `not_found`). false — проверка позиции: сайт ищется и позиция снимается без клика (итог `found` или `not_found`). Цена та же — цена клика. Предел 5 заданий одного сайта в исполнении на проверку не действует |

### TaskResult

| Поле | Значение |
|---|---|
| `outcome` | "clicked" \| "found" \| "not_found", обязательно — clicked — кликнули; not_found — сайта нет на serp_pages страницах; found — проверка позиции (`click: false`): сайт найден, клика не было |
| `position` | целое, обязательно — сквозная Позиция клика по просмотренным страницам органики, с 1; 0 — не найден. У found — позиция найденного сайта |
| `page` | целое, обязательно — страница выдачи клика; 0 — не найден. У found — страница найденного сайта |
| `found_url` | строка или null, обязательно — URL, по которому кликнули; null — not_found или URL клика не записан (тогда смотрите landed_url). У found — URL найденного результата выдачи |
| `landed_url` | строка или null, обязательно — адрес вкладки после клика; null — not_found и found (клика не было) |
| `found_by` | "url" \| "domain" \| null, обязательно — url — совпала страница, domain — домен |
| `brand_used` | true или false, обязательно — клик после поиска «ключ бренд». У found — сайт найден в поиске «ключ бренд» |
| `plain_position` | целое или null, обязательно — Позиция в поиске без бренда; null — не нашёлся или поиска не было |

### Task

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `client_id` | строка или null, обязательно — свой id задания (items[].id, до 64 символов) или task_id Источника (до 500 символов); null — без id |
| `origin` | "api" \| "panel" \| "source", обязательно — api — POST /tasks, panel — экран «Разовые», source — Источник по API.md |
| `status` | "new" \| "running" \| "done" \| "expired" \| "rejected" \| "canceled", обязательно — new — принято, ждёт исполнения; running — исполняется; done — итог clicked, found или not_found; expired — нет итога за срок; rejected — не принято к исполнению или (задание Источника) не прошло проверку; canceled — снято |
| `success` | true или false или null, обязательно — true — done; false — expired, rejected, canceled; null — ещё в работе |
| `site` | строка, обязательно — хост в нижнем регистре и путь без схемы, query, # и / по краям: так сайт сравнивается с выдачей. Сопоставляйте задания по client_id, не по site |
| `key` | строка, обязательно |
| `region` | целое, обязательно |
| `brand` | строка или null, обязательно |
| `brand_mode` | "none" \| "if_not_found" \| "always", обязательно |
| `serp_pages` | целое, обязательно |
| `click` | false — Есть только у проверки позиции и всегда равно false. Нет поля — задание с кликом |
| `project_id` | целое — Есть только у задания проекта: срез позиций или разовый проклик (`POST /projects/{id}/snapshots`, `POST /projects/{id}/oneoff`). Вебхук по такому заданию не приходит |
| `result` | объект TaskResult или null, обязательно |
| `attempts` | целое, обязательно — попыток с исходом error, captcha, geo_fail: не списываются, задание идёт снова |
| `last_error` | строка или null, обязательно — «<outcome>: <reason>» последней такой попытки |
| `reject_reason` | строка или null, обязательно — rejected: текст дословно |
| `charged_kop` | целое, обязательно — списано за задание (цена клика на момент итога, у проверки среза позиций — цена среза на момент итога); 0 — не списывалось |
| `created_at` | строка, обязательно — время ISO 8601 UTC |
| `started_at` | строка или null, обязательно — начало исполнения |
| `finished_at` | строка или null, обязательно — время ISO 8601 UTC |
| `expires_at` | строка, обязательно — срок задания: new к нему — expired сразу; running — через запас срока 5 мин |

### Queue

| Поле | Значение |
|---|---|
| `new` | целое, обязательно |
| `running` | целое, обязательно |
| `today` | объект, обязательно — за сутки МСК |
| `fleet_max` | целое, обязательно — разовых заданий в исполнении одновременно на всю панель |

### Webhook

| Поле | Значение |
|---|---|
| `url` | строка или null, обязательно |
| `secret_set` | true или false, обязательно |
| `secret_hint` | строка или null, обязательно — первые 4 символа секрета |
| `last_delivery` | объект или null, обязательно |

### WebhookEvent

Тело вебхука. `task.finished` — `task` = объект Task; `positions.finished` — `task` = null, `positions` = объект PosBatch; `ping` — `task` = null. Заголовки: X-BK-Event, X-BK-Delivery, X-BK-Timestamp, X-BK-Signature = sha256=<hex HMAC-SHA256(секрет, «<X-BK-Timestamp>.» + сырое тело)>

| Поле | Значение |
|---|---|
| `event` | "task.finished" \| "positions.finished" \| "ping", обязательно |
| `task` | объект Task или null, обязательно |
| `positions` | объект PosBatch — только у `positions.finished`: Партия съёма, `status` `done`. Строки и цены — `GET /positions/{id}` |
| `sent_at` | строка, обязательно — время ISO 8601 UTC |

### Source

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `account_id` | целое, обязательно |
| `login` | строка, обязательно |
| `url` | строка или null, обязательно — для старых клиентов: основа, если адреса ровно `<url>/task` и `<url>/result` (основа без `?`, `#` и `/` в конце); иначе null. Запросы идут на `task_url` и `result_url` |
| `task_url` | строка, обязательно — полный адрес забора: GET ровно на него |
| `result_url` | строка, обязательно — полный адрес результатов: POST ровно на него |
| `auth_header` | строка или null, обязательно — имя заголовка авторизации |
| `auth_value_set` | true или false, обязательно — значение задано; не отдаётся |
| `enabled` | true или false, обязательно |
| `state` | "off" \| "ok" \| "idle" \| "error" \| "auth" \| "paused", обязательно — off — выключен; ok — задания идут; idle — у сервера нет заданий (204), запрос раз в 15 с; error — ошибка, повтор с паузой 15…600 с; auth — сервер отказал (401, 403), забор выключен; paused — пауза без запросов (деньги, потолок суток, разовые выключены) |
| `last_error` | строка или null, обязательно — последняя ошибка забора дословно (таблица в описании GET /source); не стирается при успехе — сравнивайте last_error_at с last_ok_at |
| `last_error_at` | строка или null, обязательно — время ISO 8601 UTC |
| `last_ok_at` | строка или null, обязательно — время ISO 8601 UTC |
| `inflight` | целое, обязательно — заданий Источника в работе |
| `inflight_max` | целое, обязательно — потолок «в работе»; NULL у Источника — умолчание панели |
| `today` | целое, обязательно — взято за сутки МСК |
| `day_max` | целое, обязательно — суточный потолок панели; NULL у Источника — умолчание панели |
| `day_limit` | целое или null, обязательно — свой суточный потолок клиента |
| `results_pending` | целое, обязательно — результатов ждут отправки |
| `results_failed` | целое, обязательно — результатов не доставлено |

### SourceIn

| Поле | Значение |
|---|---|
| `task_url` | строка, до 500 символов — полный адрес забора: запрос GET идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url` |
| `result_url` | строка, до 500 символов — полный адрес результатов: запрос POST идёт ровно на него. http или https, без логина, пароля и `#`, параметры после `?` разрешены, до 500 символов, адрес из публичного интернета. Обязателен, если нет `url` |
| `url` | строка, до 500 символов — прежнее поле вместо двух адресов: база https://host[:port][/путь], панель запишет `<url>/task` и `<url>/result`. Без `?`, `#`, логина и пароля; без `/` в конце — до 493 символов, `/` в конце снимается. Вместе с `task_url` или `result_url` — 400 |
| `auth_header` | строка или null, шаблон `^[A-Za-z0-9-]{1,64}$` — имя заголовка: латиница, цифры, -; не передано — прежнее, null — без авторизации |
| `auth_value` | строка или null, до 1000 символов — значение заголовка: до 1000 печатных символов ASCII; не передано — прежнее |
| `enabled` | true или false, обязательно |
| `day_limit` | целое или null, ≥ 0 — свой суточный потолок; null — потолок панели; не передано — прежнее |

### Subaccount

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `login` | строка, обязательно |
| `telegram` | строка, обязательно — логин Telegram без @ |
| `label` | строка или null, обязательно |
| `status` | "active" \| "blocked", обязательно |
| `price_kop` | целое, обязательно — цена клика субаккаунта |
| `balance_kop` | целое, обязательно |
| `negative_since` | строка или null, обязательно — время ISO 8601 UTC |
| `projects` | целое, обязательно — проектов, в том числе скрытых |
| `created_at` | строка, обязательно — время ISO 8601 UTC |
| `spent_today_kop` | целое, обязательно — списано за сутки МСК по времени клика; разовые задания — по времени списания |
| `clicked_today` | целое, обязательно — фактических кликов за сутки МСК: клики проектов и разовые с итогом clicked |
| `parent_id` | целое, обязательно — реселлер субаккаунта |
| `admin_blocked` | true или false, обязательно — Блок поставил админ: снять его может только админ |

### SubaccountIn

| Поле | Значение |
|---|---|
| `login` | строка, обязательно, шаблон `^[A-Za-z0-9_.-]{3,32}$` — 3–32 символа: латиница, цифры, _ . - |
| `password` | строка, длина 8–128 — от 8 символов; не передан — сгенерируется и вернётся в ответе |
| `telegram` | строка — @name; не передан — пусто (Telegram реселлера не копируется) |
| `price_kop` | целое, 0–100000 — цена клика; не ниже цены реселлера; умолчание — цена реселлера |
| `label` | строка, до 100 символов |

### SummaryRow

| Поле | Значение |
|---|---|
| `account_id` | целое, обязательно |
| `login` | строка, обязательно |
| `parent_id` | целое или null, обязательно |
| `opening_kop` | целое, обязательно — баланс на начало периода: balance_after последней строки до него; 0 — строк не было |
| `deposits_kop` | целое, обязательно |
| `adjust_kop` | целое, обязательно |
| `transfer_in_kop` | целое, обязательно |
| `transfer_out_kop` | целое, обязательно — по модулю |
| `commission_kop` | целое, обязательно |
| `charged_kop` | целое, обязательно — списано, по модулю |
| `clicks` | целое, обязательно — списанных единиц: клики проектов и разовые задания с любым итогом, по 1. Фактические клики — clicks − oneoff_not_found − oneoff_found |
| `oneoff_clicked` | целое, обязательно |
| `oneoff_not_found` | целое, обязательно |
| `oneoff_found` | целое — Списаний за проверки позиции с итогом found. Есть только когда больше 0 |
| `closing_kop` | целое, обязательно — баланс на конец периода |

### Snapshot

Срез позиций проекта: по Проверке позиции (разовое задание `click: false`) на каждый включённый ключ. Первый срез проекта — «Старт» на графике позиций экрана «Динамика».

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `project_id` | целое, обязательно |
| `origin` | "create" \| "panel" \| "api", обязательно — create — `start_check` при создании проекта; panel — кнопка «Снять срез позиций»; api — `POST /projects/{id}/snapshots` по ключу API |
| `created_at` | строка, обязательно |
| `tasks` | целое, обязательно — поставлено проверок позиции |
| `skipped` | целое, обязательно — ключей, по которым проверку поставить нельзя (сайт или фраза не проходят проверку разового задания) |
| `pending` | целое, обязательно — проверок ещё в работе (`new`, `running`) |
| `found` | целое, обязательно — сайт найден, позиция снята |
| `not_found` | целое, обязательно — сайт не найден на 5 страницах выдачи |
| `failed` | целое, обязательно — без итога: Срок истёк, задание отклонено или снято |
| `top10` | целое, обязательно — найденных с позицией 1–10 |
| `avg_position` | число или null, обязательно — средняя позиция найденных, 1 знак; null — ни одного найденного |
| `charged_kop` | целое, обязательно — списано за проверки среза, коп. |

### SnapshotItem

Проверка позиции одного ключа в срезе.

| Поле | Значение |
|---|---|
| `task_id` | целое, обязательно — id разового задания: `GET /tasks/{id}` |
| `key` | строка, обязательно — ключевая фраза без брендов |
| `region` | целое, обязательно — регион проверки: один из региона ключа, случайно по весам; ключ без региона — 213 |
| `status` | "new" \| "running" \| "done" \| "expired" \| "rejected" \| "canceled", обязательно |
| `outcome` | "found" \| "not_found" \| null, обязательно |
| `position` | целое или null, обязательно — позиция; null — не найден или ещё нет итога |
| `page` | целое или null, обязательно |
| `found_url` | строка или null, обязательно |

### SnapshotDetail

Срез позиций (Snapshot) и его проверки по ключам.

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `project_id` | целое, обязательно |
| `origin` | "create" \| "panel" \| "api", обязательно — create — `start_check` при создании проекта; panel — кнопка «Снять срез позиций»; api — `POST /projects/{id}/snapshots` по ключу API |
| `created_at` | строка, обязательно |
| `tasks` | целое, обязательно — поставлено проверок позиции |
| `skipped` | целое, обязательно — ключей, по которым проверку поставить нельзя (сайт или фраза не проходят проверку разового задания) |
| `pending` | целое, обязательно — проверок ещё в работе (`new`, `running`) |
| `found` | целое, обязательно — сайт найден, позиция снята |
| `not_found` | целое, обязательно — сайт не найден на 5 страницах выдачи |
| `failed` | целое, обязательно — без итога: Срок истёк, задание отклонено или снято |
| `top10` | целое, обязательно — найденных с позицией 1–10 |
| `avg_position` | число или null, обязательно — средняя позиция найденных, 1 знак; null — ни одного найденного |
| `charged_kop` | целое, обязательно — списано за проверки среза, коп. |
| `items` | массив (объект SnapshotItem), обязательно — проверки в порядке постановки |

### PosItemIn

Строка съёма: поиск домена `{key, lr, domain}` или топ `{key, lr, mode: "top", top}`. Одно из `domain` и `mode` обязательно.

| Поле | Значение |
|---|---|
| `key` | строка, обязательно, длина 1–400 — ключевая фраза; пробелы схлопываются, съём переводит в нижний регистр |
| `lr` | целое, обязательно, ≥ 1 — регион Яндекса |
| `domain` | строка, до 300 символов — цель поиска: домен (`divan.ru`, `www.` не важен, поддомен — другой сайт) или адрес с путём (`t.me/канал`, `vk.com/club1`) |
| `depth` | 10 \| 20 \| 30 \| 40 \| 50 \| 60 \| 70 \| 80 \| 90 \| 100, умолчание `100` — только у строки с `domain`: глубина поиска. Позиция глубже — итог `not_found` без позиции. На цену не влияет. **Умолчание 100** — самый долгий поиск |
| `mode` | "top" — `top` — снять топ N органики вместо поиска домена |
| `top` | целое, 1–100, умолчание `100` — только у `mode: top`: сколько позиций органики снять |
| `serp` | "none" \| "sites" \| "full" — что сохранить из выдачи для `GET /positions/{id}/serp`: `sites` — органика (позиция, домен, URL, заголовок), `full` — все блоки со сниппетами, рекламой, колдунщиками. Умолчание: у поиска домена `none`, у топа `sites` |
| `alice` | true или false, умолчание `false` — снять Ответ Алисы с 1-й страницы |

### PosBatch

Партия съёма позиций: строки одного запроса `POST /positions`.

| Поле | Значение |
|---|---|
| `id` | целое, обязательно |
| `account_id` | целое, обязательно |
| `origin` | "api" \| "panel" \| "project", обязательно — api — по ключу API, panel — из панели, project — съём ключей проекта |
| `project_id` | целое или null, обязательно — проект при `origin: project` |
| `status` | "running" \| "done", обязательно — `done` — итоги всех строк записаны и списание проведено |
| `items_total` | целое, обязательно |
| `counts` | объект, обязательно — строк по статусу |
| `has_serp` | true или false, обязательно — есть строки с Выдачей или Ответом Алисы: читать их `GET /positions/{id}/serp` |
| `reserved_kop` | целое, обязательно — цена всех строк Партии: на неё проверялся баланс при приёме |
| `charged_kop` | целое, обязательно — списано после конца Партии: строки с итогом × цена строки, округлено до копейки; 0 — пока `running` |
| `created_at` | строка, обязательно |
| `expires_at` | строка, обязательно — строка, не начатая до этого времени, станет `expired` |
| `finished_at` | строка или null, обязательно |

### PosItem

Строка Партии с итогом. У строки поиска есть `domain`, у строки топа — `mode`, `top`, `top_n`.

| Поле | Значение |
|---|---|
| `idx` | целое, обязательно — номер строки в запросе, с 0 |
| `key` | строка, обязательно |
| `lr` | целое, обязательно |
| `domain` | строка — цель после нормализации (без схемы, `www.`, в нижнем регистре, кириллица — в punycode) |
| `depth` | целое — у строки поиска: выбранная глубина |
| `mode` | "top" |
| `top` | целое |
| `serp` | "none" \| "sites" \| "full", обязательно |
| `alice` | true или false, обязательно |
| `status` | "new" \| "running" \| "done" \| "failed" \| "expired", обязательно — `done` — итог есть; `failed` — 2 попытки без итога (капча, не тот регион, сбой); `expired` — строка не начата до `expires_at` |
| `outcome` | "found" \| "not_found" \| "top_done" \| "captcha" \| "geo_fail" \| "cut" \| "error" \| "no_report" \| "lost" \| "expired" \| null, обязательно — `found` — домен найден не глубже `depth`; `not_found` — домена нет в первых `depth` позициях (норма); `top_done` — топ снят; остальные — без итога, повторите строку новой Партией |
| `rank` | целое или null, обязательно — позиция в органике; null — не найден |
| `page` | целое или null, обязательно — страница выдачи с найденным доменом |
| `url` | строка или null, обязательно — адрес найденного результата |
| `title` | строка или null, обязательно — заголовок найденного результата |
| `lr_serp` | целое или null, обязательно — регион, который показала выдача |
| `pages` | целое или null, обязательно — страниц пролистано |
| `captchas` | целое или null, обязательно — капч в последней попытке |
| `top_n` | целое или null — только у строки топа: сколько позиций собрано |
| `alice_found` | целое или null — только при `alice: true`: 1 — Ответ Алисы есть, 0 — нет |
| `done_at` | строка или null, обязательно |
| `price_kop` | число или null, обязательно — цена строки, коп.: 0,5 при цене 5 ₽ за 1000 (доля копейки; сумма Партии — `charged_kop`, округлена до копейки); null — без списания или Партия ещё идёт |

### PosSerpRow

Выдача строки Партии. Блок: `idx` (порядок блока в выдаче), `page`, `kind` (`organic`, `direct_top`, `direct_bottom`, `rsya`, `promo`, `gallery`, `wizard`, `alice`, `related`), `rank` (позиция органики, у остальных 0), `pos`, `domain`, `url`, `title`; при `serp: full` — ещё `wizard`, `snippet`, `text`, `links`, `sitelinks`, `ad_label`, `ad_path`, `via_yabs`, `filled`, `offers`, `cards`.

| Поле | Значение |
|---|---|
| `idx` | целое, обязательно — номер строки в запросе |
| `serp_status` | "none" \| "pending" \| "ready" \| "partial" \| "error", обязательно — `pending` — строка ещё идёт или выдача доезжает (до 120 с после итога), повторите запрос; `ready` — целиком; `partial` — неполная; `error` — хранилище не ответило, повторите |
| `serp` | массив (объект) или null, обязательно |

## Вебхук и проверка подписи

Когда разовое задание (`origin` `api` или `panel`) становится финальным (`done`, `expired`, `rejected`, `canceled`), панель шлёт POST на URL вебхука аккаунта с событием `task.finished`. Когда заканчивается Партия съёма позиций (`origin` `api` или `panel`), панель шлёт событие `positions.finished`.

Заголовки:

| Заголовок | Значение |
|---|---|
| `Content-Type` | `application/json` (UTF-8) |
| `User-Agent` | `bk-console-webhook/1` |
| `X-BK-Event` | `task.finished`, `positions.finished` или `ping` (`POST /webhook/test`) |
| `X-BK-Delivery` | номер Доставки. Повтор той же Доставки — тот же номер |
| `X-BK-Timestamp` | unix-время отправки этой попытки, секунды |
| `X-BK-Signature` | `sha256=<hex HMAC-SHA256(секрет, "<X-BK-Timestamp>." + сырое тело)>` |

Тело — объект WebhookEvent:

```jsonc
{
  "event": "task.finished",                 // ping — проверка, task тогда null
  "task": { "id": 1042, "client_id": "a1", "status": "done", "success": true, "result": {…}, … },  // объект Task целиком
  "sent_at": "2026-11-20T07:21:05+00:00"    // время отправки попытки, UTC
}
```

Конец Партии съёма позиций:

```jsonc
{
  "event": "positions.finished",
  "task": null,
  "positions": { "id": 17, "status": "done", "items_total": 40, "reserved_kop": 2240, "charged_kop": 412, … },  // объект PosBatch
  "sent_at": "2026-11-22T07:21:05+00:00"
}
```

Строки и цены Партии — `GET /positions/{id}`.

| Правило | Как |
|---|---|
| Ответ | 2xx за 10 с. Тело ответа панель не читает. Редиректы не выполняются |
| Повторы | ответ не 2xx или нет ответа: попытки через 1 мин, 5 мин, 15 мин, 1 ч, 6 ч; после 6-й — Доставка `failed` |
| Первая попытка | в течение 5 с после итога |
| Адрес | URL, заданный на момент итога. Вебхука не было в момент итога — Доставки этого задания не будет. Адрес в частной сети или неверный адрес (`неверный адрес вебхука`) — Доставка сразу `failed` |
| Секрет | 64 hex. Ключ HMAC — сама строка секрета в UTF-8, не байты из hex. Подпись — текущим секретом на момент попытки |
| Порядок | не гарантирован: Доставки идут параллельно |
| Повтор события | одно задание или Партия может прийти дважды (ваш ответ не дошёл): определяйте по `task.id` или `positions.id` |

Проверка подписи на Python (тело — сырые байты запроса, до разбора JSON):

```python
import hashlib
import hmac
import time


def webhook_ok(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers.get("X-BK-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:   # старая попытка: чужой повтор запроса
        return False
    want = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, headers.get("X-BK-Signature", ""))


# Flask:
# @app.post("/bk-hook")
# def hook():
#     if not webhook_ok(SECRET, request.headers, request.get_data()):
#         return "", 401
#     event = request.get_json()
#     if event["event"] == "task.finished":
#         save_result(event["task"])            # идемпотентно по event["task"]["id"]
#     return "", 204
```

Проверка подписи на Node.js (Express: тело читается сырым `express.raw`):

```js
const crypto = require("crypto");
const express = require("express");

function webhookOk(secret, headers, rawBody) {
  const ts = headers["x-bk-timestamp"] || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  const got = headers["x-bk-signature"] || "";
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}

const app = express();
app.post("/bk-hook", express.raw({ type: "application/json" }), (req, res) => {
  if (!webhookOk(process.env.BK_SECRET, req.headers, req.body)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "task.finished") saveResult(event.task);   // идемпотентно по event.task.id
  res.sendStatus(204);
});
```

Порядок подключения:

1. `PUT /webhook {"url": "https://ваш-сервер/bk-hook"}`.
2. `POST /webhook/secret` — сохраните `secret`: он показывается один раз.
3. `POST /webhook/test` — ваш сервер получит `ping`; в ответе `ok: true` и `http_status` 2xx.

## Забор заданий по API.md (Источник)

Источник — ваш сервер с двумя адресами по протоколу API.md: адрес забора (`task_url`, запрос `GET`) отдаёт одно задание, адрес результатов (`result_url`, запрос `POST`) принимает итог. Панель сама забирает задания, исполняет их как разовые задания вашего аккаунта и возвращает итог. В API.md эти методы называются `GET /task` и `POST /result`: так они названы и в текстах ошибок, но запрос идёт ровно на ваши адреса, они могут быть любыми и на разных серверах.

### Что вы настраиваете

На экране «Источник» панели или методом `PUT /source`:

| Поле | Значение |
|---|---|
| `task_url` | полный адрес забора: `https://tasks.example.com/api/task`. Панель шлёт `GET` ровно на него, ничего не дописывая. http или https, без логина, пароля и `#`, параметры после `?` разрешены (токен в адресе), до 500 символов, адрес из публичного интернета. Обязателен |
| `result_url` | полный адрес результатов: `https://tasks.example.com/api/result`. Панель шлёт `POST` ровно на него. Правила — как у `task_url`. Обязателен |
| `url` | прежнее поле, вместо двух адресов: база `https://tasks.example.com/api`, панель запишет `<url>/task` и `<url>/result`. Без `?` и `#`, до 493 символов. Вместе с `task_url` или `result_url` — 400 `url: нельзя вместе с task_url и result_url`. В ответе `url` — основа, если адреса ровно `<основа>/task` и `<основа>/result`, иначе `null` |
| `auth_header` | имя заголовка, которым ваш сервер проверяет панель: `X-Api-Key`, `Authorization`. Пусто — без заголовка |
| `auth_value` | значение заголовка: `secret-value` или `Bearer abc`. Печатные символы ASCII, до 1000. Не отдаётся обратно: в ответе только `auth_value_set` |
| `day_limit` | свой суточный потолок заданий (сутки МСК). `null` — только потолок панели |
| `enabled` | забор включён |

```sh
curl -X PUT https://bk-console.com/api/v1/source \
  -H "X-Auth-Token: $BK_KEY" -H "Content-Type: application/json" \
  -d '{"task_url":"https://tasks.example.com/api/task","result_url":"https://results.example.com/bk/result?token=abc",
       "auth_header":"X-Api-Key","auth_value":"secret-value","day_limit":5000,"enabled":true}'
```

Без `url` нужны оба адреса: только `task_url` — 400 `result_url: обязательно`. Адрес, который разрешается в частную сеть, — 400 `task_url: адрес ведёт в частную сеть` (или `result_url: …`).

### Что панель шлёт

`GET <task_url>` с заголовками `User-Agent: bk-console-source/1`, `Accept: application/json`, `<auth_header>: <auth_value>`. Ожидаемый ответ:

| Ответ сервера | Что делает панель |
|---|---|
| 200 и JSON-объект с `task_id` | ставит задание и сразу просит следующее, пока есть место (до 50 за проход, проход раз в 2 с) |
| 204 | заданий нет (`state: idle`): следующий запрос через 15 с |
| 401 или 403 | забор выключается (`state: auth`): исправьте авторизацию и включите заново |
| другой код, не JSON, нет `task_id`, `task_id` длиннее 500 символов, нет ответа за 10 с | `state: error`, повтор с паузой 15, 30, 60 … 600 с |
| адрес разрешается в частную сеть или не разбирается как URL | `state: error`, забор выключается (`enabled: false`) |

Поля задания:

| Поле API.md | Как переводится |
|---|---|
| `task_id` | строка или целое; вернётся в `POST /result` как строка, целиком. До 64 символов. 65–500 символов — задание не исполняется: в `POST /result` придёт тот же `task_id` и `success: false`, `reject_reason` — `id: строка 1–64 символа`. Строка длиннее 500 символов — задание не берётся: `state: error`, `last_error` `ответ GET /task: task_id длиннее 500 символов, задание пропущено` |
| `site` | домен или URL сайта |
| `key` | поисковый запрос |
| `region` | номер региона Яндекса: строка из цифр или целое |
| `brand` | бренд-слово; пустая строка — бренда нет |
| `brand_mode` | `none`, `if_not_found`, `always`. Нет — `if_not_found` при бренде, иначе `none` |
| `serp_pages` | страниц выдачи, приводится к 1–5. Нет — 3 |
| `click` | `false` (или `0`, `"false"`, `"0"`) — проверка позиции без клика, итог `found` или `not_found`. Нет поля — клик. Другое значение — задание не исполняется, `reject_reason` — `click: true или false` |

Задание, которое не прошло проверку (нет `site`, `region` не число, `always` без бренда), не исполняется: итог `success: false` уходит сразу. Текст причины виден в `GET /tasks?origin=source` в поле `reject_reason`.

`POST <result_url>` с теми же заголовками и `Content-Type: application/json`:

| Итог задания | Тело |
|---|---|
| `clicked` | `{"task_id": "20848693", "success": true, "position": 2, "found_url": "https://example.com/catalog"}` |
| `found` | `{"task_id": "20848693", "success": true, "position": 2, "found_url": "https://example.com/catalog"}` — как у `clicked`, клика не было |
| `not_found` | `{"task_id": "20848693", "success": true, "position": 0, "found_url": false}` |
| `expired`, `rejected`, `canceled` | `{"task_id": "20848693", "success": false, "position": 0, "found_url": false}` |

`success: true` значит «выдача получена», как в API.md: у `not_found` тоже true. `found_url` — URL, по которому был клик (у `found` — URL найденного результата выдачи); если он не записан — адрес страницы после клика, а без него — `https://<site>`. Ответ 2xx — итог доставлен; иначе повторы через 1 мин, 5 мин, 15 мин, 1 ч, 6 ч. Адрес в частной сети или неверный адрес — без повторов, итог сразу в `results_failed`. Тело ответа панель не читает.

### Сколько и когда

| Правило | Значение |
|---|---|
| В работе одновременно | не больше `inflight_max` Источника (умолчание 200) |
| За сутки МСК | не больше меньшего из `day_max` (умолчание 100 000) и своего `day_limit`. Считаются все взятые задания, в том числе отклонённые |
| Деньги | как у разовых заданий: цена клика за `clicked`, `found` и `not_found`. Нет денег — забор на паузе (`state: paused`), запросов к вашему серверу нет |
| Повтор `task_id` | задание с `task_id`, который этот Источник уже отдавал, не исполняется заново. Прежнее в работе — ничего; прежнее финальное — его итог уходит в `POST /result` ещё раз. `task_id` должен быть уникальным всегда |
| Состояние | `GET /source`: `state`, `last_error`, `inflight`, `today`, `results_pending`, `results_failed`. Тексты `last_error` — в описании метода `GET /source` |

## Лимиты

Лимит — запросов в календарную минуту на аккаунт, по всем его ключам вместе. Каждый запрос по ключу считается в `all`; у метода с лимитом метода — ещё и в нём. Запрос считается и тогда, когда потом отвечает ошибкой. Запросы экранов панели не считаются. Исключение — `POST /webhook/test`: проверка вебхука из панели тоже считается в `tasks` (15 в минуту), превышение — та же 429.

| Лимит | Клиент | Методы |
|---|---|---|
| `all` | 60 | все запросы по ключу |
| `write` | 20 | `POST /projects`, `PATCH`, `DELETE /projects/{id}`, `PATCH /projects/{id}/status`, `PUT`, `PATCH`, `DELETE /projects/{id}/keys`, `PUT /webhook`, `POST /webhook/secret`, `PUT /source`, `POST /subaccounts`, `PATCH /subaccounts/{id}` |
| `boost` | 1 | `POST /projects/{id}/boost` |
| `stats` | 12 | `GET /performance`, `GET /queue`, `GET /projects/{id}/stats`, `GET /projects/{id}/keys/stats`, `GET /subaccounts/report` |
| `tasks` | 15 | `POST /tasks`, `POST /tasks/cancel`, `DELETE /queue`, `POST /webhook/test` |
| `money` | 30 | `POST /subaccounts/{id}/transfer` |
| `login_link` | 30 | `POST /subaccounts/{id}/login-link` |

Превышение — 429 и заголовок `Retry-After` с секундами до конца минуты. Ждите их и повторяйте. `POST /tasks` принимает до 500 заданий за вызов: 15 вызовов в минуту — до 7 500 заданий.

## Повтор запроса (Idempotency-Key)

Заголовок `Idempotency-Key` (1–64 символа) принимают `POST /tasks`, `POST /projects/{id}/snapshots`, `POST /projects/{id}/oneoff`, `POST /subaccounts`, `POST /subaccounts/{id}/transfer`. Ставьте его всегда: без него повтор после сетевого сбоя выполнит действие дважды.

| Случай | Ответ |
|---|---|
| ключ новый | действие выполняется, ответ хранится 24 ч |
| тот же ключ позже 24 ч | новое действие, как с новым ключом |
| тот же ключ, то же тело, тот же путь | сохранённый ответ с тем же HTTP-кодом, действие не повторяется |
| тот же ключ, другое тело | 409 `Idempotency-Key уже использован с другим телом запроса` |
| тот же ключ, другой путь | 409 `Idempotency-Key уже использован другим методом` |
| ключ пуст или длиннее 64 | 400 `Idempotency-Key: 1–64 символа` |
| первый запрос с этим ключом ещё идёт | второй ждёт его и получает его ответ |

Ключ действует на весь аккаунт: один постоянный ключ на разные действия даёт 409. Тело сравнивается как JSON: порядок полей не важен. Ответ с ошибкой не сохраняется: после исправления тела можно повторить с тем же ключом. У `POST /tasks` сохранённый ответ отдаётся раньше проверки «разовые задания выключены» (503): повтор принятого запроса получает его ответ и при выключенных заданиях.

## Нюансы

| Тема | Как пользоваться правильно |
|---|---|
| Статистика | Клики приходят в статистику и списание с отставанием около 10 мин. Проект списывается строкой на окно 5 мин |
| Ключ проекта | `id` ключа меняется при смене страницы, запроса или региона: это новый ключ с новыми счётчиками. Лимит и бренды меняйте `PUT /projects/{id}/keys`: `id` сохранится |
| Смесь регионов | `region_mix` — массив строк `{"group": "msk", "pct": 50}` или `{"lr": 54, "pct": 20}`, `pct` кратно 5, сумма ровно 100. Группы: `msk` — Москва (213), `spb` — Питер (2), `mil` — 14 городов от 1 млн без Москвы и Питера, `rf` — 94 центра регионов без Москвы, `small` — 264 города до 100 тыс. Панель собирает из строк `region` с весами: `[{"group":"msk","pct":50},{"group":"spb","pct":10},{"lr":54,"pct":40}]` → `{213*5\|2*1\|54*4}` (проценты, делённые на их НОД; `*N` у каждого варианта, `*1` тоже; один регион — без скобок). Вес группы делится между её городами поровну. `GET /projects/{id}/keys` отдаёт этот `region`, `region_mix` не отдаёт. Смена смеси — смена региона: у ключа новый `id` и новые счётчики. |
| Простой список | `keys` массивом строк в `POST /projects` и `PUT /projects/{id}/keys`: каждая строка — ключевая фраза без `;` и `\|`, а страница (`domain` в `POST`, `url` в `PUT`), `region` или `region_mix`, `brands`, `clicks` (умолчание 100) и `every_days` — общие на все ключи. Сервер подставляет их в строку каждого ключа, ответ тот же, что у KeyIn. Ошибки общих полей — без префикса (`region: …`), ошибка ключа — `keys[<i>]: …`, номер с 0. Массив KeyIn и строки в одном `keys` смешивать нельзя |
| Срез позиций | `POST /projects/{id}/snapshots` ставит по Проверке позиции на каждый включённый ключ проекта, не больше 2000 ключей. Ключ с одной фразой, страницей и регионом — одна проверка. Регион проверки — один регион из `region` ключа, случайно по весам смеси; ключ без региона — 213. Бренды не участвуют. 5 страниц выдачи: `not_found` — сайта нет в первых 50. Цена — цена среза позиций за проверку с итогом `found` или `not_found` (одна для всех клиентов, по умолчанию 10 коп.), не цена клика; списывается цена на момент итога. Непроверенный клиент должен иметь на балансе цену клика × разовые задания в работе + цену среза × (проверки среза в работе + новые), иначе 402 `не хватает денег: <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` (есть разовые задания в работе — перед `<S>` стоит `<N> заданий в работе и новых × <P> коп. + `). Первый срез проекта — «Старт». Счётчики среза (`pending`, `found`, `avg_position`) растут по мере итогов, обычно в пределах срока (60 мин). Повтор `POST /projects` с `start_check: true` в течение 24 ч (например, после 504) второй срез не ставит и не оплачивает: в `projects[].start_check` — уже поставленный стартовый срез, тот же `snapshot_id` |
| Разовый проклик | `POST /projects/{id}/oneoff`: `times` (1–100) разовых заданий с кликом на каждый ключ из `ids` или `keys` (без них — все включённые), всего не больше 2000. В исполнение они уходят первыми, предел 5 заданий одного сайта к ним не относится. Регион — свой у каждого задания, случайно по весам смеси ключа; ключ без региона — 213; ключ с брендами — первый бренд, `if_not_found`. Деньги проверяются до приёма у всех клиентов, и у проверенного тоже: на балансе — цена клика × (задания в работе + новые). Фраза из `keys`, которой нет среди включённых ключей проекта, — 404 `ключ не найден: <фраза>`: новый ключ сначала сохраните |
| Задания проекта в `GET /tasks` | Проверки среза и разовый проклик — разовые задания аккаунта проекта: у них есть поле `project_id`, у прочих заданий его нет. Вебхук по ним не приходит. Снимаются, как все, пока в очереди (`POST /tasks/cancel`) |
| Длина региона | `region` ключа (и собранный из `region_mix`) — до 2200 символов, иначе 400 `items[<i>].region: регион длиннее 2200 символов: уберите часть регионов из смеси` (в простом списке — `region: …`, в строке `text` — без префикса). |
| Удаление проекта | `DELETE /projects/{id}` выключает и скрывает проект. Тот же домен в `POST /projects` вернёт его с новыми ключами |
| `POST /projects` и `enabled` | `enabled` применяется и к проекту, который уже есть: без поля проект включается. Чтобы заменить ключи выключенного проекта и не включить его, передайте `enabled: false` |
| Счётчики проекта | `limit_day` и `keys` — по включённым ключам, N@дни считается как N/дни. Сразу после `POST /projects` (до 10 мин) в них входят и выключенные ключи |
| Предел сайта | 1 000 000 кликов в сутки на сайт по всем проектам аккаунта, включая скрытые; сайт — домен без `www.`. В `PUT /projects/{id}/keys` в предел входят и выключенные ключи проекта, в бусте — только включённые |
| Блок админа | Субаккаунт, заблокированный админом, реселлер разблокировать не может: `admin_blocked: true`, `PATCH /subaccounts/{id}` со `status: active` даёт 403. Свой блок реселлер снимает сам |
| Сайт и поддомен | Сайт совпадает с результатом выдачи только целиком: при поиске в выдаче `www.` не важен, другой поддомен — другой сайт. Для проектов `www.` важен: `www.example.com` и `example.com` — два проекта, url на `www.` в `PUT /projects/{id}/keys` проекта `example.com` — 400. Пример: в мобильной выдаче Википедия ведёт на `ru.m.wikipedia.org`, поэтому сайт `ru.wikipedia.org` будет `not_found`, хотя стоит первым. Указывайте хост, на который ведёт ссылка в мобильной выдаче Яндекса |
| Ключи «не найден» | `GET /projects/{id}/keys/stats?only=not_found&sort=not_found` отдаёт ключи, по которым сайт не нашёлся, с наибольшим `not_found` первыми. `hint_code` — возможная причина, а не факт. `other_host` — сайт в выдаче на другом поддомене. Ключ проекта не может вести на другой поддомен (`PUT /projects/{id}/keys` отвечает 400): заведите проект на этом поддомене (`POST /projects`), а старый ключ выключите или удалите (`PATCH`, `DELETE /projects/{id}/keys`). Курсор `sort=not_found` держится на сумме `not_found`, а за сегодняшние сутки она растёт между запросами страниц: ключ, у которого `not_found` вырос выше курсора, на следующих страницах не придёт. Полный перебор без пропусков — с `date_to` раньше сегодня или `sort=task_key&only=not_found` с сортировкой у себя. `url` и `region` равны `null`, если страница или регион не заданы, попыток за 40 суток не было или данные не получены за 15 с: счётчики ключа при этом верны |
| Проект с `editable: false` | Проект настроен вручную: его ключи через API не правятся. Изменить их — напишите админу в Telegram |
| Разовые: свой id | `id` задания уникален на аккаунт среди заданий `api` и `panel` навсегда. Повтор возвращает прежнее задание с `duplicate: true`, а не новое |
| Разовые: два id | `id` панели (`task.id`, число) — для `GET /tasks/{id}` и `POST /tasks/cancel`. Свой `id` (`client_id`) — для сопоставления у себя |
| Разовые: `site` в ответе | Хост в нижнем регистре и путь без схемы, query, `#` и `/` по краям: так сайт сравнивается с выдачей. Сопоставляйте задания по `client_id`, не по `site` |
| Разовые: очередь | Один сайт аккаунта исполняется не больше чем 5 заданиями с кликом одновременно (проверки позиции этот предел не занимают), вся панель — не больше `fleet_max` (`GET /queue`). Остальные ждут в `new`, и срок у них идёт. Много заданий на один сайт за раз — часть станет `expired` |
| Разовые: задержки | Принятое задание уходит в исполнение не позже чем через 30 с (`new` → `running`). Итоги панель получает раз в 10 с |
| Разовые: попытки | Капча, сбой и неверный регион итогом не считаются: растёт `attempts`, задание идёт снова до срока, деньги не списываются |
| Разовые: бренд | `if_not_found` без бренда исполняется как `none`. `always` без бренда — 400 |
| Разовые: проверка позиции | `click: false` в задании. В ответе у такого задания есть поле `click: false`; у задания с кликом поля `click` нет. Итог `found`: `position`, `page`, `found_url` заполнены, `landed_url` — `null`. |
| Разовые: снятие | Снимается только задание в очереди (`new`). Задание в исполнении (`running`) не снимается: исполнение могло уже начаться. Оно доходит до итога или срока и списывается как обычно |
| Разовые: деньги | Списание — по цене клика на момент итога, у проверки позиции тоже; проверка среза позиций — по цене среза (строка «Срез позиций»). Итог задания в исполнении (`running`), пришедший до `expires_at` + 5 мин, — `done` со списанием; позже — `expired` без списания. Финальный статус смотрите в `status`, а не по `expires_at`. Непроверенный клиент должен иметь на балансе цену клика × (задания в работе + новые); проверки среза в работе считаются по цене среза, текст отказа тогда — `не хватает денег: <N> заданий в работе и новых × <P> коп. + <S> проверок среза позиций × <SP> коп. = <X> ₽, на балансе <B> ₽` |
| Разовые: стоп | У аккаунта со стопом задания ждут в `new` и не исполняются; срок при этом идёт |
| Вебхук | Отвечайте 2xx сразу, обработку делайте после ответа. Проверяйте подпись и время `X-BK-Timestamp` |
| Субаккаунт | Цена клика субаккаунта — не ниже цены реселлера. Клик субаккаунта списывается с него по его цене; разница — Комиссия реселлера раз в минуту (`GET /transactions?kind=commission`). Цена реселлера выше цены субаккаунта — Комиссия отрицательная и списывается с реселлера. Комиссия идёт только из оплаченной части: клик, списанный субаккаунту в минус, Комиссии не даёт (строка `commission` с 0) |
| Субаккаунт: возврат денег | `from_sub` у непроверенного субаккаунта не забирает резерв под его разовые задания в работе: (`new` + `running`) × его цена клика. `to_sub` у непроверенного реселлера так же не переводит резерв под его собственные разовые задания |
| Ссылка входа | Живёт 5 минут, открывается один раз. Ведёт на домен, с которого пришёл запрос. Не открывайте её сами и не пишите в журналы |
| Блок | Блок аккаунта не отзывает ключи: они отвечают 403 до снятия блока |
| Источник: перезапуск панели | Подтверждения выдачи в API.md нет. При остановке панель не шлёт новых `GET /task` и до 15 с ждёт начатые, чтобы выданное задание успело записаться. При аварийном падении панели задание, которое ваш сервер уже отдал, может потеряться: `POST /result` по нему не придёт. Задание без итога дольше 2 ч отдавайте снова с тем же `task_id`: панель исполнит его, если не видела, или пришлёт прежний итог |
| Адрес вебхука и Источника | Адрес проверяется при каждом соединении: имя, которое разрешается в частную сеть или loopback, отвергается, даже если при сохранении оно было публичным |
| Безопасные действия | Изменяющие запросы шлите, только когда пользователь поручил именно это действие. Связь проверяйте `GET /account`. Ключ API, секрет вебхука, пароль субаккаунта и ссылку входа не пишите в журналы и примеры. Не обходите лимиты другим ключом и перебором id |
