API Cookies správně

2. Autentizace

Token vygenerujete v administraci v sekci Účet → API přístup a posíláte ho v hlavičce Authorization jako bearer token. Jeden účet má vždy nejvýše jeden token.

Jak token poslat

GET /api/v2/licenses HTTP/1.1
Host: cookies-spravne.cz
Authorization: Bearer cs_2f9Ktz...

Vlastnosti tokenu

Správa tokenu

• Vygenerovat token vytvoří nový token a jednorázově ho zobrazí.
• Vygenerovat nový token okamžitě nahradí ten stávající. Integrace používající starý token přestane fungovat.
• Zrušit token okamžitě uzavře přístup.

Chybný nebo chybějící token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="cookiesspravne", error="invalid_token"
Cache-Control: no-store
Content-Type: application/json

{"error":{"code":"invalid_token","message":"The API token is missing, malformed or no longer valid."}}

3. GET /api/v2/licenses

Vrací všechny licence, na které dosáhne váš token, seřazené podle id. Bez parametrů a bez stránkování. Odsud si vezmete id, které pak použijete jako license_id při exportu souhlasů.

Požadavek

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://cookies-spravne.cz/api/v2/licenses"

Odpověď

{
  "data": [
    { "id": 1, "domain": "example.cz", "is_active": true,  "created_at": "2025-04-01T09:12:00Z" },
    { "id": 7, "domain": "eshop.cz",   "is_active": false, "created_at": "2026-01-20T14:03:00Z" }
  ]
}

Pole záznamu

4. GET /api/v2/consents

Stránkovaný export souhlasů jedné licence. Povinný je jediný parametr license_id, zbytek má rozumné výchozí hodnoty.

Parametry

Jak se parametry validují

• license_id musí být číslo. Chybějící, prázdný nebo nečíselný vrací 400 invalid_request. Syntakticky platný, ale bez přístupu k licenci vrací 404 license_not_found. API nerozlišuje „neexistuje“ a „nemáte přístup“.
• limit nečíselný vrací 400. Číselný se ořízne do rozsahu 1 až 10000: limit=50000 vrátí 10000 řádků, limit=0 vrátí jeden. Použitá hodnota je vždy v odpovědi v poli meta.limit.
• order_by a order mimo povolené hodnoty, například order_by=id, vrací 400 invalid_request.
• from a to přijímají buď holé datum Y-m-d, nebo úplný ISO 8601 formát, který se použije přesně. from=2026-06-01 znamená 2026-06-01T00:00:00Z, to=2026-06-30 znamená 2026-06-30T23:59:59Z. Obě hranice jsou inkluzivní. Neexistující datum jako 2026-02-31 vrací 400 invalid_date. from větší než to vrátí prázdnou stránku.
• Rozsah dat se aplikuje na sloupec zvolený v order_by. S order_by=updated_at tedy from znamená „změněno od“, ne „vzniklo od“.

Odpověď

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=100"

{
  "data": [
    {
      "id": "9c1f7a2e-5b3d-4e18-9a6c-2f0d81b7e4aa",
      "uid": "aB3xY7kQ",
      "license_id": 1,
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-04T08:31:00Z",
      "necessary": true,
      "analytics": false,
      "marketing": false,
      "ad_user_data": false,
      "ad_personalization": false,
      "was_shown": true,
      "was_dismissed": false
    }
  ],
  "meta": {
    "count": 100,
    "limit": 100,
    "order": "asc",
    "order_by": "created_at",
    "has_more": true,
    "next_cursor": "v1.eyJ0IjoiMjAyNi0wNi0wMSAxMDowMDowMCJ9"
  },
  "links": {
    "next": "https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=100&cursor=v1.eyJ0IjoiMjAyNi0wNi0wMSAxMDowMDowMCJ9"
  }
}

Pole záznamu

Interní odkaz na verzi konfigurace, kterou návštěvník viděl, a příznak importu ze staršího systému se neexportují. Pokud je potřebujete, napište nám na podpora@cookies-spravne.cz.

Pole meta a links

links.next je sestavený z query stringu příchozího požadavku, do kterého se doplní cursor. Zachovává tedy i limit, order_by, from a to, se kterými stránkování začalo.

Datový model souhlasu

Lištu zajímá aktuální rozhodnutí návštěvníka, ne jeho historie. Zápis je proto upsert na dvojici license_id a uid: jeden řádek na návštěvníka, přepisovaný při každé změně volby.

Příznaky was_shown a was_dismissed jsou v exportu proto, že bez nich mají tři různé situace stejný tvar, tedy všechny kategorie na false:

5. Řazení a stránkování

Pro pravidelný import dat vždy řaďte podle updated_at. Stránkuje se kurzorem, který si pamatuje filtry původního dotazu a neexpiruje.

Řazení a aktuálnost dat

Důvod je v datovém modelu: souhlas je stav, ne událost. Když si návštěvník volbu rozmyslí, jeho řádek se přepíše, ale created_at zůstane staré. Při řazení podle created_at takový záznam leží dál na starém místě a váš přírůstkový import ho mine.

Stránkování

Jedna stránka vrátí nejvýše 10 000 záznamů. Další stránky se čtou parametrem cursor, jehož hodnotu najdete v odpovědi v meta.next_cursor. V links.next máte rovnou celou adresu další stránky i se všemi původními parametry.

GET /api/v2/consents?license_id=1&limit=2

{ "data": [ … 2 řádky … ],
  "meta": { "count": 2, "limit": 2, "has_more": true, "next_cursor": "v1.eyJ0IjoiMjAyNi0w…" },
  "links": { "next": "…&cursor=v1.eyJ0IjoiMjAyNi0w…" } }

GET /api/v2/consents?license_id=1&limit=2&cursor=v1.eyJ0IjoiMjAyNi0w…

{ "data": [ … 2 řádky … ],
  "meta": { "count": 2, "limit": 2, "has_more": true, "next_cursor": "v1.eyJ0IjoiMjAyNi0x…" },
  "links": { "next": "…&cursor=v1.eyJ0IjoiMjAyNi0x…" } }

GET /api/v2/consents?license_id=1&limit=2&cursor=v1.eyJ0IjoiMjAyNi0x…

{ "data": [ … 1 řádek … ],
  "meta": { "count": 1, "limit": 2, "has_more": false, "next_cursor": null },
  "links": { "next": null } }

Další stránka existuje, dokud platí has_more === true a zároveň links.next !== null. Hodnota has_more je odvozená z toho, že se načte o řádek víc, než kolik se vrátí.

Vlastnosti kurzoru

• Zachovává filtry původního dotazu. Použití s jiným license_id, order, order_by, from nebo to vrací 400 cursor_mismatch.
• Nevalidní kurzor vrací 400 invalid_cursor.
• Neexpiruje. Ukazuje na pozici v pořadí, ne na výsledek dotazu.

6. Limity a chyby

S platným tokenem máte 120 požadavků za minutu. Každá chybová odpověď má stejný tvar: objekt error s poli code a message.

Limity

S platným tokenem se limit klíčuje na účet, nikoli na IP. Servery za jednou NAT adresou si tedy rozpočet nedělí, zato dva stroje téhož účtu ano. Při limit=10000 strop odpovídá 1 200 000 řádkům za minutu.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error":{"code":"rate_limited","message":"Too many requests."}}

Odpověď 429 nenese hlavičku Retry-After ani hlavičky X-RateLimit-*. Okno je pevná minuta, stačí tedy počkat a zopakovat požadavek.

Tvar chybové odpovědi

Stejný tvar mají všechny chyby včetně 500:

{
  "error": {
    "code": "invalid_token",
    "message": "The API token is missing, malformed or no longer valid."
  }
}

Chybové kódy

Příklad

GET /api/v2/consents?license_id=abc

HTTP/1.1 400 Bad Request

{"error":{"code":"invalid_request","message":"A numeric license_id is required."}}

7. Příklady volání

Tři ukázky k rovnou použití: plný export do JSONL, přírůstkové čtení změn a načtení jedné stránky.

Plný export do JSONL

Bash s curl a jq. Prochází všechny stránky přes links.next, dokud nějaká další existuje.

#!/usr/bin/env bash
set -euo pipefail

TOKEN="cs_…"
URL="https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=1000"

while [ -n "$URL" ]; do
  BODY=$(curl -sS -H "Authorization: Bearer $TOKEN" "$URL")
  echo "$BODY" | jq -c '.data[]' >> souhlasy.jsonl
  URL=$(echo "$BODY" | jq -r '.links.next // ""')
done

Přírůstkové čtení změn

JavaScript. Čte záznamy změněné od zadaného okamžiku, řadí podle updated_at a umí počkat při překročení limitu.

const TOKEN = process.env.COOKIES_SPRAVNE_TOKEN;
const BASE = 'https://cookies-spravne.cz/api/v2/consents';

async function* changes(licenseId, since) {
  let url = `${BASE}?license_id=${licenseId}&order_by=updated_at&order=asc&limit=1000`
    + (since ? `&from=${encodeURIComponent(since)}` : '');

  while (url) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });

    if (res.status === 429) {
      await new Promise(resolve => setTimeout(resolve, 60_000));
      continue;
    }

    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${res.status} ${error.code}: ${error.message}`);
    }

    const { data, links } = await res.json();

    yield* data;

    url = links.next;
  }
}

Jedna stránka v PHP

<?php

$token = getenv('COOKIES_SPRAVNE_TOKEN');

$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer {$token}\r\n",
    ],
]);

$url = 'https://cookies-spravne.cz/api/v2/consents?' . http_build_query([
    'license_id' => 1,
    'order_by' => 'updated_at',
    'order' => 'asc',
    'limit' => 1000,
]);

$page = json_decode(file_get_contents($url, false, $context), true);

8. Starší API (v1)

Endpointy původního systému zůstávají dostupné na stejných adresách a vrací data ve stejném formátu, aby stávající integrace fungovaly beze změny.

Autentizace staršího API

Starší API se neautentizuje API tokenem, ale klíčem pro starší API, který jste dostali při aktivaci přístupu v původním systému. Pokud ho u účtu evidujeme, najdete ho v administraci v části Účet → API přístup. Pokud ho tam nevidíte, napište nám na podpora@cookies-spravne.cz.

Klíč se posílá v hlavičce Authorization. Kvůli zpětné kompatibilitě se přijímá i hlavička Authentication, kterou uváděla původní dokumentace:

Authorization: Bearer xxxxxxxxx
Authentication: Bearer xxxxxxxxx

Odpovědi jsou vždy application/json. Chyby mají stejný tvar i kódy jako v2 a platí pro ně i stejné limity.

GET /api/consent-report

Vrací souhlasy uživatelů. Podporuje stránkování a filtrování.

Spojením from a to vznikne interval, který zahrnuje from a nezahrnuje to. Například ?from=2022-01-01&to=2022-02-01 vrátí celý leden 2022. Filtruje se podle data prvního udělení souhlasu, tedy date_of_consent, a záznamy jsou podle něj vzestupně seřazené.

Hlavičky odpovědi

Příklad

curl -sS -H "Authorization: Bearer $LEGACY_KEY" \
  "https://cookies-spravne.cz/api/consent-report?key=bstl7sn95ns7sno97s1q&from=2022-01-01&to=2022-02-01&page=1"

[
  {
    "_id": { "$oid": "9c1f7a2e-5b3d-4e18-9a6c-2f0d81b7e4aa" },
    "uid": "CxQ25iVbozc2o82J4RcuX1Lv5DoXpO",
    "key": "bstl7sn95ns7sno97s1q",
    "necessary": "1",
    "analytics": "0",
    "marketing": "1",
    "config": { "$oid": "4812" },
    "date_of_consent": "1644842294"
  }
]

GET /api/consent-configs

Vrací všechny verze nastavení lišty a jejích textů, které se návštěvníkům zobrazily. Souhlasy mohou být vázané k jinému znění lišty, proto má každý souhlas v poli config odkaz na konkrétní verzi. Jediný parametr je povinný key se stejným významem jako výše.

[
  {
    "_id": { "$oid": "4812" },
    "modified": 1644236417,
    "texts": {
      "cs": {
        "reject_all": "Odmítnout",
        "cookie_policy": "Více o cookies",
        "iframe_no_cookies": "Pro zobrazení tohoto obsahu povolte prosím ukládání cookies."
      }
    }
  }
]

_id.$oid odpovídá hodnotě config.$oid ve výpisu souhlasů, modified je unixový timestamp, kdy se tato verze poprvé zobrazila, a texts obsahuje texty lišty podle jazyka.

Rozdíly oproti původnímu systému

• Souhlas je jeden záznam na návštěvníka. Když návštěvník volbu změní, záznam se přepíše a date_of_consent zůstává datem prvního souhlasu. Pro sledování změn použijte API v2 s order_by=updated_at.
• Chyby vrací JSON s objektem error. Například chybějící key vrací 400 invalid_request.