API pubblica

Documentazione completa dell'API REST di Consentio per sviluppatori

Panoramica

L'API pubblica di Consentio offre accesso programmatico ai tuoi dati sul consenso. Puoi usarla per:

Integrazione con i tuoi strumenti di analytics
Esportazione dati per i report
Automatizzare la gestione dei siti web
Creare dashboard personalizzate

Importante: l'API pubblica è disponibile solo con il piano Pro. Il piano Free non include l'accesso alle API.

Autenticazione

L'API utilizza l'autenticazione tramite chiave API. Inserisci la chiave nell'header Authorization:

Header HTTP

Authorization: ApiKey sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ottenere una chiave API

Accedi alla dashboard di Consentio
Vai su Impostazioni → Chiavi API
Clicca su Genera nuova chiave
Copia la chiave e conservala in modo sicuro

Sicurezza: non condividere mai la tua chiave API né salvarla in repository pubblici. La chiave garantisce l'accesso a tutti i dati del tuo account.

URL di base

Indirizza tutte le richieste API a:

URL

https://consentio.cz/api/v1

Limitazione delle richieste

L'API ha un limite sul numero di richieste all'ora:

Piano	Richieste/ora
Pro	1.000

La risposta include gli header con le informazioni sul rate limit:

Header di risposta

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067200

Formato della risposta

Tutte le risposte sono in formato JSON con una struttura coerente:

Risposta di successo

JSON

{
  "success": true,
  "data": { ... }
}

Risposta di errore

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrizione dell'errore"
  }
}

Endpoint

GET /websites

Restituisce un elenco di tutti i siti web associati al tuo account.

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/websites" \
  -H "Authorization: ApiKey sk_live_xxx"

Esempio di risposta

JSON

{
  "success": true,
  "data": [
    {
      "id": "clx1234567890",
      "name": "My e-shop",
      "domain": "my-eshop.com",
      "description": "Main e-shop",
      "status": "active",
      "cookieCount": 15,
      "consentCount": 1250,
      "consentRate": 78,
      "viewsThisMonth": 450,
      "lastScanAt": "2025-01-15T10:30:00.000Z",
      "createdAt": "2024-06-01T08:00:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /websites/:id

Restituisce i dettagli di un sito web specifico, incluse le impostazioni.

Parametri

Parametro	Tipo	Descrizione
`id`	string	ID del sito web (nell'URL)

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/websites/clx1234567890" \
  -H "Authorization: ApiKey sk_live_xxx"

GET /websites/:id/cookies

Restituisce un elenco dei cookie rilevati sul sito web.

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/websites/clx1234567890/cookies" \
  -H "Authorization: ApiKey sk_live_xxx"

GET /analytics

Restituisce i dati di analytics per un sito web - statistiche sul consenso, geografia, dispositivi e tendenze.

Parametri della query

Parametro	Tipo	Obbligatorio	Descrizione
`websiteId`	string	Sì	ID del sito web
`period`	string	No	Periodo: 7d, 30d, 90d, all (predefinito: 30d)

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/analytics?websiteId=clx123&period=30d" \
  -H "Authorization: ApiKey sk_live_xxx"

Esempio di risposta

JSON

{
  "success": true,
  "data": {
    "summary": {
      "totalViews": 1250,
      "consentRate": 78.5,
      "acceptedCount": 850,
      "rejectedCount": 275,
      "customCount": 125,
      "uniqueVisitors": 980,
      "totalImpressions": 2500
    },
    "consentBreakdown": {
      "acceptAll": 68,
      "rejectAll": 22,
      "custom": 10
    },
    "categoryConsent": {
      "necessary": 100,
      "analytics": 72,
      "marketing": 45,
      "functionality": 58
    },
    "geographic": [
      {
        "country": "Czechia",
        "countryCode": "CZ",
        "flag": "🇨🇿",
        "count": 850,
        "percentage": 68
      }
    ],
    "devices": {
      "desktop": 55,
      "mobile": 40,
      "tablet": 5
    },
    "trend": [
      {
        "date": "2025-01-01",
        "views": 45,
        "accepted": 35,
        "rejected": 10
      }
    ],
    "utmBreakdown": {
      "sources": [...],
      "mediums": [...],
      "campaigns": [...]
    }
  }
}

GET /consents

Restituisce un elenco dei singoli consensi con paginazione.

Parametri della query

Parametro	Tipo	Obbligatorio	Descrizione
`websiteId`	string	Sì	ID del sito web
`startDate`	ISO 8601	No	Data di inizio (es. 2025-01-01)
`endDate`	ISO 8601	No	Data di fine
`limit`	number	No	Numero di record (predefinito: 100, massimo: 1000)
`offset`	number	No	Record da saltare (predefinito: 0)

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/consents?websiteId=clx123&limit=50&offset=0" \
  -H "Authorization: ApiKey sk_live_xxx"

Esempio di risposta

JSON

{
  "success": true,
  "data": [
    {
      "id": "consent_abc123",
      "visitorId": "v_xyz789",
      "action": "ACCEPT_ALL",
      "categories": {
        "necessary": true,
        "analytics": true,
        "marketing": true,
        "functionality": true
      },
      "ipCountry": "CZ",
      "device": "desktop",
      "utmSource": "google",
      "utmMedium": "cpc",
      "utmCampaign": "brand",
      "createdAt": "2025-01-15T14:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "hasMore": true
  }
}

POST /consents/export

Esporta i consensi in un file CSV o JSON.

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`websiteId`	string	Sì	ID del sito web
`startDate`	ISO 8601	No	Data di inizio
`endDate`	ISO 8601	No	Data di fine
`format`	string	No	"csv" o "json" (predefinito: json)

Esempio di richiesta

curl

curl -X POST "https://consentio.cz/api/v1/consents/export" \
  -H "Authorization: ApiKey sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": "clx1234567890",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "format": "csv"
  }' \
  -o consents.csv

GET /account/usage

Restituisce l'utilizzo attuale dell'account rispetto ai limiti del piano.

Esempio di richiesta

curl

curl -X GET "https://consentio.cz/api/v1/account/usage" \
  -H "Authorization: ApiKey sk_live_xxx"

Esempio di risposta

JSON

{
  "success": true,
  "data": {
    "plan": "PRO",
    "websites": {
      "used": 3,
      "limit": 15
    },
    "pageviews": {
      "used": 45000,
      "limit": 250000,
      "periodStart": "2025-01-01T00:00:00.000Z",
      "periodEnd": "2025-01-31T23:59:59.999Z"
    },
    "analyticsRetention": "unlimited",
    "scanInterval": "1 day",
    "apiRequests": {
      "used": 150,
      "limit": 1000,
      "resetAt": "2025-01-15T15:00:00.000Z"
    }
  }
}

Codici di errore

Stato HTTP	Codice	Descrizione
400	`MISSING_WEBSITE_ID`	Il parametro obbligatorio websiteId è mancante
400	`INVALID_FORMAT`	Formato di esportazione non valido
401	`UNAUTHORIZED`	Chiave API mancante o non valida
403	`API_ACCESS_DENIED`	Il tuo piano non include l'accesso alle API
404	`WEBSITE_NOT_FOUND`	Sito web non trovato o accesso negato
429	`RATE_LIMIT_EXCEEDED`	Limite di richieste superato
500	`INTERNAL_ERROR`	Errore interno del server

SDK e librerie

Stiamo preparando SDK ufficiali per i linguaggi più diffusi:

JavaScript/TypeScript (npm)
Python (pip)
PHP (composer)

Suggerimento: vuoi essere avvisato quando gli SDK saranno rilasciati? Segui le nostre novità o contattaci all'indirizzo [email protected].

Lingue