API REST

L’API REST ti permette di automatizzare tutto ciò che puoi fare nella dashboard: aggiungere domini, avviare scansioni, cercare ed esportare record di consenso e ricevere webhook quando qualcosa cambia. È disponibile con i piani Pro ed Enterprise.

Autenticazione

Crea una chiave API in Settings → API keys. Le chiavi valgono per un solo workspace e sono di sola lettura oppure di lettura e scrittura. Invia la chiave come bearer token:

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

Le chiavi segrete iniziano con ck_sk_. Non usarle mai nel codice eseguito nel browser. Al tag script basta il tuo Site ID pubblico.

Tutte le richieste usano HTTPS e JSON. L’URL di base è https://api.cookiesh.eu/v1. Le marche temporali sono stringhe ISO 8601 in UTC.

Endpoint

Metodo	Percorso	Descrizione
GET	/domains	Elenca i domini del workspace
POST	/domains	Aggiunge un dominio
GET	/domains/{id}	Restituisce un dominio e le sue impostazioni
DELETE	/domains/{id}	Rimuove un dominio
POST	/domains/{id}/scans	Avvia una scansione dei cookie
GET	/domains/{id}/scans/{scan_id}	Restituisce stato e risultati di una scansione
GET	/domains/{id}/cookies	Elenca i cookie e i tracker classificati
GET	/consents	Cerca i record di consenso
GET	/consents/{consent_id}	Restituisce un record di consenso con la prova della catena di hash
POST	/exports	Avvia un’esportazione in CSV o JSON dei record di consenso
GET	/exports/{id}	Restituisce lo stato di un’esportazione e l’URL di download
DELETE	/subjects/{user_id}	Elimina tutti i record di consenso collegati a un ID utente

Esempio: trovare i record di consenso di un visitatore.

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
}

Paginazione

Gli endpoint di elenco restituiscono fino a 100 elementi. Passa limit per riceverne di meno. Se ci sono altri risultati, la risposta include un next_cursor. Rimandalo come cursor per ottenere la pagina successiva. I cursori restano validi per 24 ore.

Errori

Gli errori usano i codici di stato HTTP standard e un corpo sempre uguale:

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

Stato	Significato
400	La richiesta non è valida. Il messaggio spiega il motivo.
401	La chiave API manca o non è valida.
403	La chiave è di sola lettura, oppure il tuo piano non include questa funzionalità.
404	La risorsa non esiste in questo workspace.
429	Hai raggiunto il limite di richieste. Riprova dopo il numero di secondi indicato in Retry-After.
5xx	Qualcosa non ha funzionato da parte nostra. Riprova con un backoff esponenziale.

Indica il request_id quando contatti il supporto.

Limiti di richieste

I workspace Pro possono effettuare 600 richieste al minuto, quelli Enterprise 3.000. Ogni risposta include le intestazioni RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Le esportazioni in corso non vengono conteggiate nel limite.

Webhook

Aggiungi un endpoint in Settings → Webhooks e scegli gli eventi da ricevere:

Evento	Inviato quando
consent.created	Un visitatore salva una nuova scelta
consent.updated	Un visitatore modifica una scelta precedente
scan.completed	Una scansione dei cookie termina
scan.new_items	Una scansione trova cookie o tracker da verificare
usage.threshold	Il workspace raggiunge l’80% o il 100% dei log di consenso mensili

Ogni consegna è una richiesta POST con un corpo JSON e un’intestazione Cookiesh-Signature. L’intestazione contiene una marca temporale e una firma HMAC-SHA256 di timestamp.body, generata con il segreto di firma del tuo endpoint. Verificala prima di fidarti del payload:

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; // rifiuta le consegne vecchie
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Rispondi con uno stato 2xx entro 10 secondi. Le consegne non riuscite vengono ritentate con backoff esponenziale per un massimo di 24 ore. Gli eventi possono arrivare più di una volta, quindi usa l’id dell’evento per ignorare i duplicati.