Integrazione dell'archivio consensi tramite REST API

In questa sezione è mostrata l'integrazione e consultazione dell'archivio consensi, necessario per poter memorizzare delle prove del consenso al trattamento dei dati personali che gli utenti possono aver prestato consapevolmente navigando sul tuo sito web.

Questa documentazione descrive gli endpoint per la gestione dei consensi all'interno dei webspace. L'URL base dell'API è

https://api.avacy.eu/:team/v4

Crea un nuovo consenso per uno specifico spazio web

POST /webspaces/:id/consents

Parametri di route

Nome	Tipo	Obbligatorio	Descrizione
`id`	integer	Sì	L'identificativo dello spazio web su cui viene creato il consenso

Autenticazione

La richiesta richiede una Access Key, inviata nell'header Authorization: Bearer <token>.

Come ottenere la Access Key

Accedi ad Avacy e apri lo spazio web su cui vuoi registrare i consensi.
In alto a destra clicca su impostazioni spazio web e poi su Integrazione di Avacy sul tuo spazio web.
Apri la tab Access Key e crea una nuova Access Key, assegna un nome per riconoscerla (es. "Plugin WordPress") e copia il codice mostrato.

warning

Il codice viene mostrato una sola volta: le chiavi già create non sono più visibili. Vale solo l'ultima chiave creata per lo spazio web: le chiavi precedenti vengono rifiutate con 403. Se ne generi una nuova, aggiornala ovunque sia usata. Se elimini l'ultima chiave creata, torna valida quella precedente ancora presente.

Una chiave è valida solo per lo spazio web per cui è stata generata e non ha una scadenza.

La registrazione dei consensi è disponibile solo se il piano dell'account include l'archivio consensi: in caso contrario la richiesta viene rifiutata con 403, sia per form sia per banner.

Headers richiesti

Nome	Tipo	Obbligatorio	Descrizione
`Authorization`	string	Sì	`Bearer <token>`, dove `<token>` è la Access Key dello spazio web (vedi Autenticazione)
`Accept`	string	Sì	Specifica il formato di risposta desiderato (`application/json`)
`Content-Type`	string	Sì	Specifica il formato del contenuto della richiesta (`application/json`)

Parametri nella richiesta (formato JSON)

Nome	Tipo	Obbligatorio	Descrizione
`consent_type`	string	Sì	Il tipo di consenso: `form` o `banner`
`optin`	string	Sì	Stato del consenso: `accepted`, `rejected` o `partially_accepted`
`identifier`	string	No	Identificativo univoco del soggetto che fornisce il consenso
`ip_address`	string	Sì per `form`	Obbligatorio per i form. L'IP registrato è quello da cui parte la chiamata: se chiami dal tuo server, riporta l'IP del contatto in `consent_data`
`consent_features`	array, oggetto o string	Sì per `form`	Finalità del consenso. Come array elenca le finalità per cui è stato dato il consenso. Come oggetto associa a ogni finalità il suo stato, `true` (accettata) o `false` (rifiutata o revocata): `{"telefono": true, "whatsapp": false}`. Accetta anche una stringa separata da virgole (`"a,b"`)
`consent_data`	array o string	Sì per `form`	Dati del consenso con struttura label/value. Accetta anche una stringa (`"nome=Mario,email=x"`)
`uuid`	string	No	Identificativo del consenso in formato UUID. Se omesso viene generato da Avacy. Conservalo se ti serve revocare il consenso (vedi Revoca del consenso)
`source`	string	No	Sorgente del consenso (es. "website", "app")
`html_form`	string	No	Rappresentazione HTML del form di consenso mostrato all'utente
`versions`	array	No	Non utilizzato

note

Le versioni registrate sono quelle delle policy (privacy e cookie) generate da Avacy sullo spazio web. Se usi un'informativa esterna, indicane gli estremi in consent_data.
Con consent_type: banner la Access Key non serve: la richiesta viene verificata controllando che Origin o Referer corrispondano a un dominio dello spazio web. Se mancano entrambi la risposta è 400, se non corrispondono è 403. Il controllo è attivo solo in produzione. Il Bearer token è richiesto per form.
Il banner Avacy invia anche altri valori di optin (consent-all, reject-all, save-preferences, close-banner): sono interni al banner e non vanno usati nelle integrazioni.

Esempio:

{
  "consent_type": "form",
  "optin": "accepted",
  "ip_address": "192.168.1.20",
  "consent_data": [
    {
      "label": "nome",
      "value": "Mario"
    },
    {
      "label": "cognome",
      "value": "Rossi"
    }
  ],
  "identifier": "user-123",
  "source": "website",
  "consent_features": [
    "privacy_policy",
    "cookie_policy"
  ],
  "html_form": "<p>Usiamo cookie e altre tecnologie...</p>",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Per registrare anche le finalità rifiutate, passa consent_features come oggetto, con una voce per ogni finalità:

"consent_features": {
  "telefono": true,
  "whatsapp": false,
  "email": true
}

Risposta di Successo

Codice: 201 Created

{
  "message": "Consent created successfully",
  "data": {
    "id": 123,
    "webspace_id": 1,
    "ip_address": "192.168.1.20",
    "consent_type": "form",
    "optin": "accepted",
    "consent_data": [
      {
        "label": "nome",
        "value": "Mario"
      },
      {
        "label": "cognome",
        "value": "Rossi"
      }
    ],
    "versions": [
      {
        "slug": "privacy_policy",
        "link": "https://assets.example.com/policies/.../privacy_policy.html",
        "date": "2025-05-15"
      }
    ],
    "identifier": "user-123",
    "domain": null,
    "source": "website",
    "consent_features": [
      "privacy_policy",
      "cookie_policy"
    ],
    "html_form": "<p>Usiamo cookie e altre tecnologie...</p>",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-11-12T10:30:00.000000Z",
    "updated_at": "2025-11-12T10:30:00.000000Z"
  }
}

domain riporta l'Origin (o, in mancanza, il Referer) della richiesta: è null se chiami dal tuo server senza questi header. In versions, date è la data e ora in cui il consenso è stato registrato.

Risposta di Errore

Codice	Quando
`400 Bad Request`	Solo `banner`: mancano sia `Origin` sia `Referer`
`403 Forbidden`	Access Key mancante o non valida (inclusa una chiave sostituita da una più recente, o di un altro spazio web), dominio non riconosciuto per `banner`, oppure piano senza archivio consensi
`404 Not Found`	Il webspace con l'ID specificato non esiste. Con `form` non è raggiungibile: un `id` diverso da quello della chiave dà prima `403`
`422 Unprocessable Entity`	Campi obbligatori mancanti o non validi

Consultazione, esportazione, importazione ed eliminazione

Questi endpoint operano sullo stesso spazio web (/webspaces/:id/consents) e richiedono l'autenticazione dell'area riservata: la Access Key non è accettata.

Elenco dei consensi

GET /webspaces/:id/consents

Risposta paginata, ordinata per data di creazione decrescente. Filtri disponibili come query string:

Parametro	Descrizione
`identifier`	Ricerca parziale sull'identificativo
`uuid`	Ricerca parziale sull'UUID
`type`	`form` o `banner`
`optin`	`accepted`, `rejected` o `partially_accepted`
`start`, `end`	Intervallo di date di creazione (`YYYY-MM-DD`)
`consent_features`	Ricerca parziale sulle finalità, senza distinzione tra maiuscole e minuscole
`domain`	Ricerca parziale sul dominio di provenienza
`limit`	Risultati per pagina (default 15)

Esportazione

GET /webspaces/:id/consents/export

Restituisce un file .tsv. Accetta gli stessi filtri dell'elenco (tranne domain) e il parametro ids con gli ID dei consensi separati da virgola. La colonna Optin vale Yes per accepted e No per tutti gli altri valori, quindi partially_accepted non è distinguibile da rejected.

Importazione

POST /webspaces/:id/consents/import

Invia un file csv, tsv o txt (max 10 MB) nel campo file in multipart/form-data. Colonne obbligatorie: Identifier, Consent Type, IP Address, Created At, più Optin. Le righe non valide vengono scartate e riportate nel campo errors della risposta.

IP Address accetta solo indirizzi IPv4: le righe con un IPv6 vengono scartate.
Optin vale accepted solo per yes, true, 1, accepted, sì o si: qualsiasi altro valore, compreso partially_accepted, viene importato come rejected.
Se almeno una riga è importata la risposta è 200, altrimenti 422.

Eliminazione

Endpoint	Descrizione
`DELETE /webspaces/:id/consents/:consent_id`	Elimina un consenso
`DELETE /webspaces/:id/consents/delete`	Elimina i consensi indicati in `consent_ids` (array nel body). Risponde `400` se è vuoto e `404` se nessun ID corrisponde
`DELETE /webspaces/:id/consents`	Elimina in blocco i consensi che corrispondono ai filtri indicati in query string

I filtri dell'eliminazione in blocco sono identifier, uuid, type, optin, start, end e consent_features. Il filtro domain non è disponibile e consent_features distingue tra maiuscole e minuscole, a differenza dell'elenco.

attenzione

DELETE /webspaces/:id/consents senza filtri elimina tutti i consensi dello spazio web.

Revoca del consenso

Non esiste un endpoint dedicato alla revoca. Il consenso si revoca registrando un nuovo consenso con POST /webspaces/:id/consents, come fa il banner Avacy:

Conserva l'uuid che ricevi nella risposta alla creazione del consenso.
Per revocare, invia un nuovo POST con lo stesso uuid e lo stesso identifier, e metti a false le finalità revocate in consent_features (come oggetto). Gli altri campi obbligatori per i form (optin, ip_address, consent_data) vanno inviati come in una creazione.

Le parti che cambiano rispetto al consenso originale:

{
  "consent_type": "form",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "identifier": "user-123",
  "consent_features": {
    "telefono": false,
    "whatsapp": false,
    "email": true
  }
}

Vale l'ultimo record registrato: i precedenti restano nell'archivio come storico e prova.

attenzione

Non usare gli endpoint di eliminazione per revocare un consenso: eliminano il record, e con esso la prova.

Crea un nuovo consenso per uno specifico spazio web​

Parametri di route​

Autenticazione​

Headers richiesti​

Parametri nella richiesta (formato JSON)​

Risposta di Successo​

Risposta di Errore​

Consultazione, esportazione, importazione ed eliminazione​

Elenco dei consensi​

Esportazione​

Importazione​

Eliminazione​

Revoca del consenso​