API Riferimento

Integra con la Piattaforma di Gestione del Consenso Conzent. Questi endpoint alimentano il banner di consenso, targeting geolocalizzato, registrazione dell'audit del consenso e scansione dei cookie.

Tutti gli endpoint sono relativi alla tua istanza Conzent auto-ospitata. Sostituisci l'URL di base con il tuo dominio reale.

Autenticazione

La maggior parte degli endpoint sono pubblici — vengono chiamati dallo script del banner di consenso in esecuzione sui browser dei tuoi visitatori.

Gli endpoint che accettano dati utilizzano una Chiave del Sito per identificare a quale sito appartiene la richiesta. Trova la tua chiave del sito nel dashboard di Conzent sotto Siti.

Formato della Risposta

Le risposte API utilizzano due formati a seconda dell'endpoint:

Risposta Standard

Utilizzato da Controllo Salute e Webhook di Scansione.

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

Risposta Leggera

Utilizzato dagli endpoint beacon (Visualizzazione Pagina, Consenso, Dati di Scansione) per un sovraccarico minimo.

{
  "status": "ok"
}

Controllo Salute

Restituisce lo stato di salute dell'applicazione e dei servizi di supporto. Utilizzato per monitoraggio, controlli del bilanciatore di carico e probe di salute Docker.

Risposta

{
  "success": true,
  "data": {
    "status": "ok",
    "services": {
      "database": true,
      "redis": true
    },
    "environment": "production",
    "timestamp": "2026-03-16T12:00:00+00:00"
  }
}

{
  "success": true,
  "data": {
    "status": "degradato",
    "services": {
      "database": true,
      "redis": false
    }
  }
}

Esempio

curl https://your-instance.example.com/health

Geolocalizzazione

Restituisce il codice paese del visitatore e lo stato di appartenenza all'UE. Utilizzato dallo script di consenso per applicare regolamenti geo-targetizzati (GDPR, CCPA).

Campi della Risposta

Risposta

{
  "country": "dk",
  "in_eu": true
}

Esempio

curl https://your-instance.example.com/api/v1/geo_ip

Beacon di Visualizzazione Pagina

Registra eventi di visualizzazione pagina e caricamento banner. Inviato tramite navigator.sendBeacon() come multipart/form-data. Incrementa il contatore di visualizzazioni giornaliere e memorizza le osservazioni dei cookie per l'elaborazione asincrona.

Corpo della Richiesta multipart/form-data

Risposta

{
  "status": "ok"
}

Esempio

curl -X POST https://your-instance.example.com/api/v1/log \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "request_type=banner_load" \
  -F "log_time=$(date +%s)"

Registro Consenso

Registra la traccia di audit del consenso GDPR quando un visitatore accetta, rifiuta o personalizza il consenso. Questo è l'endpoint principale per la conformità.

Corpo della Richiesta multipart/form-data

Risposta

{
  "status": "ok"
}

Esempio

curl -X POST https://your-instance.example.com/api/v1/consent \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "conzent_id=a1b2c3d4e5f6..." \
  -F 'log=[{"category":"analytics","consented":true}]' \
  -F "consented_domain=example.com" \
  -F "language=en" \
  -F "country=dk"

Beacon di Dati di Scansione

Riceve dati di scansione dei cookie lato client. Lo script di consenso rileva i cookie nel browser del visitatore e li riporta per la categorizzazione automatica. I dati vengono memorizzati in Redis e elaborati in modo asincrono.

Corpo della Richiesta multipart/form-data

Struttura del Payload

{
  "scan_id": 123,
  "action": "runscan",
  "scan_url": "https://example.com/",
  "consent_phase": "pre_consent",
  "data": {
    "cookies": [
      { "name": "_ga", "domain": ".example.com" }
    ]
  }
}

Risposta

{
  "status": "ok"
}

Esempio

curl -X POST https://your-instance.example.com/api/v1/scan_data \
  -F "key=YOUR_WEBSITE_KEY" \
  -F 'payload={"scan_id":123,"action":"runscan","scan_url":"https://example.com/"}'

Webhook di Scansione

Riceve i risultati della scansione dai server di scansione esterni quando una scansione dei cookie è completata. Autenticato tramite l'intestazione X-Api-Key che corrisponde alla variabile ambientale SCANNER_WEBHOOK_SECRET.

Intestazioni

Corpo della Richiesta application/json

Risposta

{
  "success": true,
  "data": {
    "status": "processed"
  }
}

Errore

{
  "success": false,
  "error": "Non autorizzato"
}

Esempio

curl -X POST https://your-instance.example.com/api/v1/scan-webhook \
  -H "X-Api-Key: YOUR_SCANNER_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "webhook",
    "scan_id": 456,
    "scan_url": "https://example.com/",
    "data": {
      "cookies": [
        {"name": "_ga", "domain": ".example.com", "category": "analytics"}
      ]
    }
  }'