REST API

REST API võimaldab automatiseerida kõike, mida saad teha töölaual: lisada domeene, käivitada skannimisi, otsida ja eksportida nõusolekukirjeid ning saada webhook’e, kui midagi muutub. See on saadaval Pro- ja Enterprise-paketis.

Autentimine

Loo API-võti jaotises Settings → API keys. Võtmed kehtivad ühes tööruumis ning on kas ainult lugemiseks või lugemiseks ja kirjutamiseks. Saada võti bearer-tokenina:

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

Salajased võtmed algavad eesliitega ck_sk_. Ära kasuta neid kunagi brauseri koodis. Skriptimärgend vajab ainult sinu avalikku saidi ID-d.

Kõik päringud kasutavad HTTPS-i ja JSON-it. Baas-URL on https://api.cookiesh.eu/v1. Ajatemplid on ISO 8601 stringid UTC ajas.

Lõpp-punktid

Meetod	Tee	Kirjeldus
GET	/domains	Loetle tööruumi domeenid
POST	/domains	Lisa domeen
GET	/domains/{id}	Hangi domeen ja selle seaded
DELETE	/domains/{id}	Eemalda domeen
POST	/domains/{id}/scans	Käivita küpsiste skannimine
GET	/domains/{id}/scans/{scan_id}	Hangi skannimise olek ja tulemused
GET	/domains/{id}/cookies	Loetle liigitatud küpsised ja jälgijad
GET	/consents	Otsi nõusolekukirjeid
GET	/consents/{consent_id}	Hangi üks nõusolekukirje koos räsiahela tõendiga
POST	/exports	Käivita nõusolekukirjete eksport CSV- või JSON-vormingus
GET	/exports/{id}	Hangi ekspordi olek ja allalaadimise URL
DELETE	/subjects/{user_id}	Kustuta kõik kasutaja ID-ga seotud nõusolekukirjed

Näide: leia ühe külastaja nõusolekukirjed.

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
}

Lehitsemine

Loendi lõpp-punktid tagastavad kuni 100 kirjet. Väiksema arvu küsimiseks anna parameeter limit. Kui tulemusi on rohkem, sisaldab vastus väärtust next_cursor. Anna see tagasi parameetrina cursor, et saada järgmine lehekülg. Kursorid kehtivad 24 tundi.

Vead

Vead kasutavad standardseid HTTP olekukoode ja ühtset kehavormingut:

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

Olek	Tähendus
400	Päring on vigane. Teade selgitab põhjust.
401	API-võti puudub või on kehtetu.
403	Võti on ainult lugemiseks või sinu pakett ei sisalda seda funktsiooni.
404	Ressurssi selles tööruumis ei ole.
429	Jõudsid päringute piirmäärani. Proovi uuesti päises Retry-After toodud sekundite möödudes.
5xx	Meie poolel läks midagi valesti. Proovi uuesti eksponentsiaalselt kasvava ooteajaga.

Toega ühendust võttes lisa väärtus request_id.

Päringute piirmäärad

Pro-paketi tööruumid saavad teha 600 päringut minutis ja Enterprise-paketi tööruumid 3000. Iga vastus sisaldab päiseid RateLimit-Limit, RateLimit-Remaining ja RateLimit-Reset. Ekspordid ei lähe töötamise ajal piirmäära arvesse.

Webhook’id

Lisa lõpp-punkt jaotises Settings → Webhooks ja vali sündmused, mida soovid saada:

Sündmus	Saadetakse, kui
consent.created	Külastaja salvestab uue valiku
consent.updated	Külastaja muudab varasemat valikut
scan.completed	Küpsiste skannimine lõpeb
scan.new_items	Skannimine leiab küpsiseid või jälgijaid, mis vajavad ülevaatust
usage.threshold	Tööruum jõuab 80% või 100%-ni oma igakuistest nõusolekulogidest

Iga edastus on POST-päring JSON-kehaga ja päisega Cookiesh-Signature. Päis sisaldab ajatemplit ja väärtuse timestamp.body HMAC-SHA256 allkirja, mis on loodud sinu lõpp-punkti allkirjastamissaladusega. Kontrolli seda, enne kui andmeid usaldad:

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; // lükka vanad edastused tagasi
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Vasta 10 sekundi jooksul olekuga 2xx. Ebaõnnestunud edastusi proovitakse uuesti eksponentsiaalselt kasvava ooteajaga kuni 24 tundi. Sündmused võivad saabuda rohkem kui üks kord, seega kasuta duplikaatide eiramiseks sündmuse väärtust id.