API REST dell'archivio consensi
L'API REST dell'archivio consensi registra i consensi raccolti dai tuoi form. Il sito invia una richiesta POST per ogni consenso e l'archivio lo conserva come prova.
A chi serve
Serve a chi sviluppa un form o un'applicazione propria e vuole archiviare i consensi senza il plugin WordPress.
Prerequisiti
Prima di cominciare ti servono:
- un account Avacy con il piano Plus o superiore. Con un piano inferiore l'API risponde
403(vedi Errori); - uno spazio web già creato nella dashboard;
- il nome del team e l'id dello spazio web (vedi Dove trovare team e id);
- una Access Key dello spazio web (vedi Crea una Access Key).
Indirizzo dell'API
L'indirizzo base è https://api.avacy.eu/<team>/v4. L'endpoint di registrazione è il seguente.
POST https://api.avacy.eu/<team>/v4/webspaces/<id>/consents
<team> è il nome del team. <id> è l'id numerico dello spazio web.
Dove trovare team e id
- Apri lo spazio web nella dashboard.
- Apri Impostazioni spazio web.
- Apri Integrazione di Avacy sul tuo spazio web.
- Nella tab Integra Avacy apri la voce Google Tag Manager. Il campo Nome team contiene il valore di
<team>. - Leggi l'indirizzo della pagina nel browser. Ha la forma
.../banner-integration/<id>e il numero finale è l'id dello spazio web.
La dashboard non mostra l'id dello spazio web in un campo. Per questo si legge dall'indirizzo della pagina. Il campo Nome team contiene lo stesso valore che la dashboard usa nell'indirizzo delle sue chiamate all'API.
Crea una Access Key
- Apri Integrazione di Avacy sul tuo spazio web (step 1-3 sopra).
- Apri la tab Access Key.
- Premi Crea nuova Access Key.
- Scrivi un nome nel campo Nome della chiave (per esempio "Form contatti").
- Premi Crea Access Key.
- Copia la chiave mostrata e conservala.
La dashboard mostra la chiave una sola volta. Copiala subito.
Tieni la Access Key sul tuo server e chiama l'API da lì. Non scriverla nel JavaScript del sito: chiunque apre la pagina potrebbe leggerla e registrare consensi a nome tuo.
La chiave vale solo per lo spazio web per cui l'hai creata. Per ogni spazio web vale solo l'ultima chiave creata. Le chiavi precedenti ricevono 403.
Registra un consenso
Intestazioni
| Intestazione | Valore |
|---|---|
Authorization | Bearer <Access Key> |
Content-Type | application/json |
Accept | application/json |
Campi del corpo
Un consenso da form (consent_type uguale a form) richiede consent_type, optin, ip_address, consent_features e consent_data. Se invii un identifier, consent_data può mancare: il consenso viene salvato con una lista vuota.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
consent_type | stringa | Sì | form per i form propri. banner è riservato al banner di Avacy. |
optin | stringa | Sì | accepted o rejected. |
ip_address | stringa | Sì, per form | L'IP della persona che dà il consenso (vedi sotto). |
consent_features | array di stringhe | Sì, per form. Con optin uguale a rejected può essere vuoto ([]) | Le voci a cui la persona dà il consenso. Nei form di Avacy privacy_policy e cookie_policy ci sono sempre, perché senza non si invia il form. L'API però non le impone: in un form tuo scrivi solo le voci accettate davvero. Le altre, per esempio newsletter, sono facoltative e si possono revocare (vedi Revoca un consenso). Un form inviato senza nessuna voce accettata si registra con rejected e [], come fa il plugin WordPress dalla 1.5.0. |
consent_data | array di oggetti | Sì, per form senza identifier | Dati del consenso. Ogni voce ha label e value. |
identifier | stringa | No | Identificativo del soggetto, per esempio il suo id utente. |
source | stringa | No | Origine del consenso, per esempio website. |
html_form | stringa | No | Il codice HTML del form mostrato alla persona. |
uuid | stringa | No | UUID del consenso. Se manca, lo genera l'API. |
Per optin l'API accetta anche consent-all, reject-all, save-preferences e close-banner. Sono valori del banner. Nei tuoi form usa accepted o rejected.
ip_addressScrivi in ip_address l'IP della persona, non quello del tuo server. L'API salva il valore se è un indirizzo IPv4 o IPv6 valido. Se non lo è, l'API registra comunque il consenso, con l'IP da cui arriva la chiamata.
L'API accetta anche stringhe per consent_features ("privacy_policy,cookie_policy,newsletter") e per consent_data ("nome=Mario,email=mario@example.com"). La forma consigliata resta l'array JSON.
Esempio con curl
Sostituisci <team>, <id> e <Access Key> con i tuoi valori.
curl -i -X POST "https://api.avacy.eu/<team>/v4/webspaces/<id>/consents" \
-H "Authorization: Bearer <Access Key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"consent_type": "form",
"optin": "accepted",
"ip_address": "203.0.113.10",
"consent_features": ["privacy_policy", "cookie_policy", "newsletter"],
"consent_data": [
{ "label": "nome", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
],
"identifier": "utente-123",
"source": "website",
"html_form": "<form>Iscrizione alla newsletter</form>"
}'
Risposta
L'API risponde 201 Created con il consenso salvato. I valori di id, uuid, versions e delle date sono esempi.
{
"message": "Consent created successfully",
"data": {
"webspace_id": 1,
"ip_address": "203.0.113.10",
"versions": [
{
"slug": "privacy_policy",
"link": "https://assets.example.com/policies/...",
"date": "2026-10-27T10:30:00.000000Z"
}
],
"consent_type": "form",
"consent_features": ["privacy_policy", "cookie_policy", "newsletter"],
"optin": "accepted",
"consent_data": [
{ "label": "nome", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
],
"identifier": "utente-123",
"domain": null,
"source": "website",
"html_form": "<form>Iscrizione alla newsletter</form>",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"updated_at": "2026-10-27T10:30:00.000000Z",
"created_at": "2026-10-27T10:30:00.000000Z",
"id": 123
}
}
Il campo versions elenca la privacy policy e la cookie policy che Avacy genera per lo spazio web, solo se esistono. Il campo domain contiene l'intestazione Origin della richiesta o, se manca, Referer. Una chiamata dal server senza queste intestazioni lascia domain a null.
Errori
| Codice | Quando |
|---|---|
403 | La Access Key manca, non è valida, appartiene a un altro spazio web o è stata sostituita da una più recente. |
403 | Il piano non include l'archivio consensi. Il messaggio è Your plan does not include the consent archive feature. |
422 | Un campo obbligatorio manca o ha un valore non ammesso, per esempio un optin fuori elenco. |
429 | Lo stesso indirizzo IP ha inviato più di 60 richieste in un minuto per lo stesso spazio web. |
Il 403 per chiave non valida ha il corpo {"message":"Forbidden"}. Il corpo del 422 contiene message e, per ogni campo non valido, un elenco in errors.
{
"message": "The selected optin is invalid.",
"errors": {
"optin": ["The selected optin is invalid."]
}
}
La risposta 429 ha l'intestazione Retry-After, con i secondi da aspettare prima di riprovare. Se registri molti consensi insieme, per esempio con un import, distribuisci le richieste nel tempo.
I testi di message ed errors sono in inglese e possono cambiare. Nel codice usa il codice HTTP e i nomi dei campi in errors.
Revoca un consenso
Quando una persona ritira il consenso a una voce facoltativa, per esempio la newsletter, registra la nuova scelta con un altro POST. Non esiste un endpoint apposta per la revoca.
- Usa lo stesso
uuide lo stessoidentifierdel consenso da aggiornare. Conserva l'uuidche l'API restituisce alla prima registrazione. - In
consent_featuresscrivi le voci ancora valide, per esempioprivacy_policyecookie_policy. Togli quelle revocate. - Lascia
optinaaccepted: cosa è stato revocato lo diceconsent_features. - Invia anche gli altri campi del form (
ip_address,consent_data), come in una registrazione.
Questo esempio revoca la newsletter del consenso registrato nell'esempio precedente.
curl -i -X POST "https://api.avacy.eu/<team>/v4/webspaces/<id>/consents" \
-H "Authorization: Bearer <Access Key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"consent_type": "form",
"optin": "accepted",
"ip_address": "203.0.113.10",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"identifier": "utente-123",
"consent_features": ["privacy_policy", "cookie_policy"],
"consent_data": [
{ "label": "nome", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
]
}'
L'API risponde 201 e crea un nuovo record con lo stesso uuid. Il record precedente resta nell'archivio come prova della scelta di prima. La scelta attuale è quella del record con lo stesso uuid e il created_at più recente. A parità di created_at vale il record con l'id più alto, perché i record ravvicinati possono avere la stessa data. La data conta prima dell'id, perché un consenso importato da file può entrare nell'archivio dopo una sua versione più recente.
Non eliminare il consenso precedente per registrare una revoca. L'eliminazione cancella anche la prova della scelta di prima.
Elenco, export e import
L'API documentata serve a registrare i consensi. Elenco, ricerca, export e import si fanno dalla dashboard, nella voce Archivio consensi. Le istruzioni sono nella guida Archivio dei consensi.
Verifica
- Invia la richiesta
curldell'esempio. - Controlla che la risposta sia
201e contenga unuuid. - Apri la voce Archivio consensi del menu laterale della dashboard. Nella scheda Consensi da form, incolla l'
uuiddella risposta in Cerca per ID univoco.... - Compare la riga del consenso, con
utente-123come identificativo utente.
Problemi comuni
I problemi più frequenti:
403con messaggioForbidden: controlla che la chiave sia l'ultima creata per quello spazio web e che<id>sia lo spazio web della chiave;403con messaggio sul piano: il piano dell'account non include l'archivio consensi (dal piano Plus);422: controllaoptin,consent_features,consent_dataeip_address. Un consensoformli richiede tutti, tranneconsent_dataquando c'è unidentifier.- L'IP registrato è quello del server: controlla che
ip_addresscontenga un indirizzo IP valido.
Ultimo aggiornamento: 09/11/2026.