Documentazione

Consent Solution – Documentazione API HTTP

Le API HTTP della Consent Solution ti permettono di salvare e recuperare le azioni di consenso portate a termine dai tuoi utenti, che di seguito verranno definiti soggetti.

Headers

Autenticazione

Al fine di poter scrivere tramite le nostre API, forniamo due tipologie di chiavi:

  • Chiave pubblica, comunemente utilizzata dalla libreria Javascript
  • Chiave privata, comunemente utilizzata dall’API HTTP

Tutte le chiamate API, sia tramite HTTP che tramite JS, specificano se sono state autenticate tramite chiave pubblica o privata. Le chiamate effettuate mediante chiave privata sono più affidabili in quanto forniscono maggiore certezza quando è necessario verificare che i dati siano stati realmente inviati dall’utente.

Per le API HTTP, la chiave privata va inviata tramite l’header ApiKey. Le chiavi pubbliche sono accettate solo sull’endpoint POST /public/consent.

Content-Type

Per inviare dati alla nostra API HTTP, è necessario impostare un header content-type uguale ad application/json o x-www-form-urlencoded.

Limiti al numero di chiamate

Il numero massimo di chiamate è di 5 per secondo e 10800 per ora. Lato server, se questi limiti vengono oltrepassati riceverai un messaggio 429 Too Many Requests.

Dimensione massima delle chiamate

Per ogni chiamata, è stato impostato un limite massimo pari a 350kb. Lato server, se questi limiti sono oltrepassati riceverai un messaggio 413 Request Entity Too Large.

Consent

CREATE consent

POST https://consent.iubenda.com/consent
{
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "verified": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof form"
    }
  ],
  "preferences": {
    "newsletter": false,
    "privacy_policy": true
  }
}

Questa chiamata creerà un nuovo evento di consenso.

La risposta è la seguente:

200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "subject_id": "J02eZvKYlo2ClwuJ1"
}

Il metodo consent ammette i seguenti campi. Tutti i campi sono opzionali. Alcuni campi verrano compilati automaticamente se non viene fornito alcun valore.

timestamp compilato automaticamente (se non fornito) stringa ISO 8601 timestamp del momento in cui è avvenuto il consenso
subject object
id compilato automaticamente (se non fornito) stringa
email opzionale stringa
first_name opzionale stringa
last_name opzionale stringa
full_name opzionale stringa
verified opzionale boolean campo che segnala se un soggetto è verificato o meno, ad esempio attraverso double opt-in
custom_attributes opzionale object un set di coppie chiave-valore contenenti attributi personalizzati
legal_notices richiesto array array di oggetti contenenti dati sulle note legali
identifier stringa privacy_policy, cookie_policy, terms o un identificativo personalizzato
version stringa
proofs richiesto array array di oggetti contenente dati sulle prove di consenso
content richiesto testo
form opzionale testo
preferences richiesto oggetto insieme di coppie chiave-valore relative alle preferenze dell’utente per ogni azione di consenso

GET consent

GET https://consent.iubenda.com/consent/:id
200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "owner": "1234",
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "subject@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe"
    "verified": false
  },
  "preferences": {
    "privacy_policy": true,
    "newsletter": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof form"
    }
  ]
}

In aggiunta alle proprietà descritte in precedenza:

id identificativo univoco dello specifico evento di consenso
owner identificativo univoco del proprietario dell’API
source private_key public_key chiarisce se il consenso è stato inviato con chiave API pubblica o privata

Subjects

CREATE subject

POST https://consent.iubenda.com/subjects
{
  "id": "J02eZvKYlo2ClwuJ1",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "verified": false
}

Questo metodo crea un nuovo soggetto e può essere usato anche da consent. Controlla la documentazione riferita al metodo consent per ulteriori dettagli.

id compilato automaticamente (se non fornito) stringa
email opzionale stringa
first_name opzionale stringa
last_name opzionale stringa
full_name opzionale stringa
verified opzionale boolean campo che segnala se un soggetto è verificato o meno, ad esempio attraverso double opt-in
in arrivo a breve
custom_attributes opzionale oggetto insieme di coppie chiave-valore contenenti attributi custom

La risposta è la seguente:

200 OK
{
  "id": "J02eZvKYlo2ClwuJ1",
  "timestamp": "2018-05-04T14:52:26Z"
}

GET subject

GET https://consent.iubenda.com/subjects/:id
200 OK
{
  "id": "J02eZvKYlo2ClwuJ1",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "verified": false,
  "timestamp": "2018-05-04T14:52:26Z"
  "preferences": {
    "privacy_policy": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    },
    "newsletter": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    }
  },
}

UPDATE subject

PATCH https://consent.iubenda.com/subjects/:id
{
  "first_name": "Mary",
  "verified": true
}

Questa chiamata aggiorna un soggetto pre-esistente.

La risposta è la seguente:

200 OK
{
  "id": "testsubject",
  "created_at": "2018-05-04T14:52:26Z"
}