REST API

REST API позволяет автоматизировать всё, что можно сделать в панели управления: добавлять домены, запускать сканирования, искать и экспортировать записи о согласии и получать вебхуки при изменениях. API доступен на тарифах Pro и Enterprise.

Аутентификация

Создайте API-ключ в разделе Settings → API keys. Ключ действует в пределах одного рабочего пространства и дает доступ только на чтение или на чтение и запись. Передавайте ключ как bearer-токен:

curl https://api.cookiesh.eu/v1/domains \
  -H "Authorization: Bearer ck_sk_live_..."

Секретные ключи начинаются с ck_sk_. Никогда не используйте их в браузерном коде. Тегу script нужен только ваш публичный ID сайта.

Все запросы выполняются по HTTPS в формате JSON. Базовый URL — https://api.cookiesh.eu/v1. Отметки времени передаются строками ISO 8601 в UTC.

Эндпоинты

Метод	Путь	Описание
GET	/domains	Список доменов в рабочем пространстве
POST	/domains	Добавить домен
GET	/domains/{id}	Получить домен и его настройки
DELETE	/domains/{id}	Удалить домен
POST	/domains/{id}/scans	Запустить сканирование cookie
GET	/domains/{id}/scans/{scan_id}	Получить статус и результаты сканирования
GET	/domains/{id}/cookies	Список классифицированных файлов cookie и трекеров
GET	/consents	Поиск записей о согласии
GET	/consents/{consent_id}	Получить одну запись о согласии с подтверждением по хеш-цепочке
POST	/exports	Запустить экспорт записей о согласии в CSV или JSON
GET	/exports/{id}	Получить статус экспорта и URL для скачивания
DELETE	/subjects/{user_id}	Удалить все записи о согласии, связанные с ID пользователя

Пример: найти записи о согласии одного посетителя.

curl "https://api.cookiesh.eu/v1/consents?domain_id=dom_29xk&consent_id=cns_8Hq2Lw" \
  -H "Authorization: Bearer ck_sk_live_..."

{
  "data": [
    {
      "id": "cns_8Hq2Lw",
      "domain_id": "dom_29xk",
      "created_at": "2026-10-12T09:41:07Z",
      "region": "DE",
      "method": "banner",
      "banner_version": "v14",
      "categories": { "necessary": true, "preferences": false, "analytics": true, "marketing": false },
      "hash": "9f2c…e71a"
    }
  ],
  "next_cursor": null
}

Пагинация

Эндпоинты со списками возвращают до 100 элементов. Чтобы получить меньше, передайте limit. Если результатов больше, ответ содержит next_cursor. Передайте его обратно в параметре cursor, чтобы получить следующую страницу. Курсоры действительны 24 часа.

Ошибки

Ошибки возвращаются со стандартными кодами состояния HTTP и единообразным телом:

{
  "error": {
    "type": "invalid_request",
    "message": "domain_id is required",
    "request_id": "req_4Kd92"
  }
}

Статус	Значение
400	Некорректный запрос. Причина указана в сообщении.
401	API-ключ отсутствует или недействителен.
403	Ключ дает доступ только на чтение, или ваш тариф не включает эту функцию.
404	Ресурс не существует в этом рабочем пространстве.
429	Превышен лимит запросов. Повторите запрос через количество секунд, указанное в Retry-After.
5xx	Ошибка на нашей стороне. Повторите запрос с экспоненциальной задержкой.

Обращаясь в поддержку, указывайте request_id.

Лимиты запросов

Рабочие пространства на тарифе Pro могут выполнять 600 запросов в минуту, на тарифе Enterprise — 3000. Каждый ответ содержит заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. Выполняющиеся экспорты не учитываются в лимите.

Вебхуки

Добавьте эндпоинт в разделе Settings → Webhooks и выберите события, которые хотите получать:

Событие	Когда отправляется
consent.created	Посетитель сохраняет новый выбор
consent.updated	Посетитель меняет ранее сделанный выбор
scan.completed	Сканирование cookie завершено
scan.new_items	Сканирование нашло файлы cookie или трекеры, которые нужно проверить
usage.threshold	Рабочее пространство достигло 80 % или 100 % месячного лимита записей о согласии

Каждая доставка — это запрос POST с телом в формате JSON и заголовком Cookiesh-Signature. Заголовок содержит отметку времени и подпись HMAC-SHA256 строки timestamp.body, созданную с помощью секрета подписи вашего эндпоинта. Проверяйте подпись, прежде чем доверять содержимому:

import crypto from 'node:crypto';

export function verify(rawBody: string, header: string, secret: string): boolean {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // отклоняем старые доставки
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Ответьте статусом 2xx в течение 10 секунд. Неудачные доставки повторяются с экспоненциальной задержкой в течение 24 часов. События могут приходить повторно, поэтому используйте id события, чтобы отбрасывать дубликаты.