Documentazione

Indice dei contenuti

API docs: Come utilizzare l’API

Supponiamo di voler creare la privacy policy per un utente con le seguenti caratteristiche:

  • Sito web: www.sitowebutente.it
  • Email: pinco.pallino@gmail.com
  • Proprietario del sito web: Pinco Pallino, Via Roma, 18 – 20123 Milano (MI) – Italia
  • la chiave di autorizzazione di accesso all’API (API Key): c4f88fe3247f7df3f232025438596d54b59b76f8

Tutto quello che c’è da fare è effettuare una chiamata all’API di iubenda, indicando i parametri precedenti, che offrirà in risposta:

  • Il collegamento alla privacy policy generata
  • Il codice di inserimento per integrare la privacy policy in un sito web
  • Un link speciale, che non richiede login, per modificare la privacy policy
  • Un ID per richiamare queste informazioni in futuro

Esempio pratico

L’API è in formato JSON. Quello che segue è un esempio pratico di utilizzo

Creazione della privacy policy

POST

https://www.iubenda.com/api/transactions

POST Data

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email" => "pinco.pallino@gmail.com",
  },
  "privacy_policy" => {
    "url" => "www.sitowebutente.it",
    "owner" => {
      "info" => "Pinco Pallino, Via Roma, 18 - 20123 Milano (MI) - Italia",
      "email" => "owner.mail@iubenda.com"
      },
    "cookie_solution" => true

  }
}

RISPOSTA

"transaction_id" => 597127324 // ID della transazione
"output" => {
  "user" => {
    "id" => 20952, // ID dell'utente creato
    "email" => "user.name@gmail.com" // La mail dell'utente, inserita in precedenza
  }
  "privacy_policies" => [
    {
      "id" => 19276,
      "site_id" => 193712,
      "public_id" => 193847,
      "lang" => "en",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/services?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/edit?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "embed_code" => "<a href=\"https://www.iubenda.com/privacy-policy/193847\" class=\"iubenda-white no-brand iubenda-embed\" title=\"Privacy Policy\">Privacy Policy</a><script type=\"text/javascript\">(function (w,d) {var loader = function () {var s = d.createElement(\"script\"), tag = d.getElementsByTagName(\"script\")[0]; s.src = \"https://cdn.iubenda.com/iubenda.js\"; tag.parentNode.insertBefore(s,tag);}; w.addEventListener ? w.addEventListener(\"load\", loader, false) : w.attachEvent(\"onload\", loader);})(window, document);</script>"
    }
  ]
}
"errors" =>
"success" => true
"api_version" => "1.0"

Nella risposta, i dati da utili sono:

  • transaction_id: l’ID della transazione e serve a recuperare in qualunque momento i dati della privacy policy generata
  • output => privacy_policies => edit_url: l’indirizzo di modifica della privacy policy, da consegnare all’utente per la customizzazione e la gestione
  • output => privacy_policies => policy_url: l’indirizzo della privacy policy generata
  • output => privacy_policies => embed_code: il codice di inserimento che l’utente deve incollare nel codice del proprio sito web. Questo codice mostra un collegamento che apre la privacy policy. L’utente può anche scegliere di integrare la privacy policy direttamente inserendo il link al punto precedente.

È importante salvare il transaction_id nel database, in modo da poter recuperare in seguito i dati relativi alla privacy policy.

Generare la privacy policy in più lingue

È possibile specificare una lista di lingue in cui si vuole generare una privacy policy.

La lista delle lingue deve essere fornita come array di codici lingua per il parametro args.privacy_policy.langs come mostrato nell’esempio seguente. I codici lingua ammessi sono: “nl”, “en-GB”, “en”, “fr”, “de”, “it”, “pt-BR”, “ru” e “es”. Se nessuna lingua è fornita, la privacy policy verrà generata in inglese (si veda l’esempio precedente).

Le privacy policy generate (una per lingua) saranno ritornate nella proprietà output.privacy_policies della risposta JSON (si veda l’esempio seguente).

POST Data

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email" => "user.name@gmail.com",
  },
  "privacy_policy" => {
    "url" => "www.userwebsite.com",
    "langs" => ["it", "en"],
    "owner" => {
      "info" => "User Name, Via Roma, 18 - 20123 Milano (MI) - Italy",
      "email" => "owner.mail@iubenda.com"
      },
    "cookie_solution" => true
    
  }
}

RISPOSTA

"transaction_id" => 597198825 // ID della transazione
"output" => {
  "user" => {
    "id" => 20952, // ID dell'utente creato
    "email" => "user.name@gmail.com" // La mail dell'utente, inserita in precedenza
  }
  "privacy_policies" => [
    {
      "id" => 964529,
      "site_id" => 927554,
      "public_id" => 8239444,
      "lang" => "it",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/964529/services?l_email=user.name@gmail.com&l_tok=C1oy1Dt0xiRL3I0LHC",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/964529/edit?l_email=user.name@gmail.com&l_tok=C1oy1Dt0xiRL3I0LHC",
      "embed_code" => "<a href=\"https://www.iubenda.com/privacy-policy/8239444\" class=\"iubenda-white no-brand iubenda-embed\" title=\"Privacy Policy\">Privacy Policy</a><script type=\"text/javascript\">(function (w,d) {var loader = function () {var s = d.createElement(\"script\"), tag = d.getElementsByTagName(\"script\")[0]; s.src = \"https://cdn.iubenda.com/iubenda.js\"; tag.parentNode.insertBefore(s,tag);}; w.addEventListener ? w.addEventListener(\"load\", loader, false) : w.attachEvent(\"onload\", loader);})(window, document);</script>"
    },
    {
      "id" => 964530,
      "site_id" => 927554,
      "public_id" => 8239445,
      "lang" => "en",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/964530/services?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/964530/edit?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "embed_code" => "<a href=\"https://www.iubenda.com/privacy-policy/8239445\" class=\"iubenda-white no-brand iubenda-embed\" title=\"Privacy Policy\">Privacy Policy</a><script type=\"text/javascript\">(function (w,d) {var loader = function () {var s = d.createElement(\"script\"), tag = d.getElementsByTagName(\"script\")[0]; s.src = \"https://cdn.iubenda.com/iubenda.js\"; tag.parentNode.insertBefore(s,tag);}; w.addEventListener ? w.addEventListener(\"load\", loader, false) : w.attachEvent(\"onload\", loader);})(window, document);</script>"
    },
  ]
}
"errors" =>
"success" => true
"api_version" => "1.0"

Parametri avanzati

Di seguito la lista di tutti i parametri accettati

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email"  => "pinco.pallino@gmail.com",
    "pwd"    => "password",  // obbligatorio in caso l'utente sia già registrato/creato
    "lang"   => "it",        // facoltativo, in caso di creazione utente, disponibili 'en' e 'it', default 'en'
    "c_code" => "DE",        // facoltativo, in caso di creazione utente, il codice ISO Alpha-2 della info nazione
                             //              dell'utente; se non fornito, nessuna info nazione sarà settata
  },
  "privacy_policy" => {
    "type" => "web_site",              // facoltativo, disponibili 'web_site' e 'mobile_app', default 'web_site'
    "url"  => "www.sitowebutente.it",  // obbligatorio se 'type' non è fornito o è 'web_site'
    "app_name" => "testApp",           // obbligatorio se 'type' è 'mobile_app'
    "langs" => ['it', 'en'],           // facoltativo, default ['en'] (si veda la sezione precedente sulle lingue)
    "owner" => {                       // facoltativo
      "info"  => "Pinco Pallino, Via Roma, 18 - 20123 Milano (MI) - Italia",
      "email" => "owner.mail@iubenda.com"
    },
    "pro" => true,  // facoltativo, default 'false'; se fornito 'true' la privacy policy sarà creata Pro 
                        //              e una licenza di 1 anno sarà associata alla privacy policy
                      // NOTA: l'api account deve essere abilitato a creare privacy policy Pro, in caso contrario 
                      //       un errore sarà ritornato
                      // NOTA: nel caso in cui l'utente di destinazione ha attivo un piano multi licenza, la privacy 
                      //       policy sarà creata Pro indipendentemente da questo parametro
    "cookie_solution" => true,  // opzionale, default 'false'; 
                      // se impostato a 'true' viene creata una cookie solution, 
                      // attivando un piano gratuito fino a 25k pageview al mese,  
                      // se l'utente non ne ha già uno attivo.
    "skip_configuration_mail" => true,  // facoltativo, default 'false'; se fornito 'true' non verrà inviata
                                          //              alcuna mail di configurazione della Privacy Policy appena
                                          //              creata all'indirizzo mail dell'utente di destinazione
  }
}

Richiamare una privacy policy dopo averla generata

Per richiamare una privacy policy si esegue una chiamata GET verso l’API, offrendo come input l’API Key e il transaction_id ottenuto in sede di creazione

GET

https://www.iubenda.com/api/transactions/transaction_id?api_key=api_key_value

Esempio:

https://www.iubenda.com/api/transactions/193847?api_key=c4f88fe3247f7df3f232025438596d54b59b76f8

RISPOSTA

=> {
  "id" => 193847,
  "transaction" => {
    "success" => true,
    "type" => "create_privacy_policy",
    "input" => {
      "user" => {
        "email" => "pinco.pallino@gmail.com",
        "lang" => "it",
        "c_code" => "IT"
      },
      "privacy_policy" => {
        "url" => "http://www.sitowebutente.com",
        "langs" => ["en"],
        "owner" => {
          "info" => "Pinco Pallino, Via Roma, 18 - 20123 Milano (MI) - Italia",
          "email" => "pinco.pallino@gmail.com"
        }
      }
    },
    "output" => {
      "user" => {
        "id" => 6269,
        "email" => "pinco.pallino@gmail.com"
      },
      "privacy_policies" => [
        {
          "id" => 19276,
          "lang" => "it",
          "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/services?l_email=pinco.pallino@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
          "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/edit?l_email=pinco.pallino@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
          "policy_url" => "https://www.iubenda.com/privacy-policy/193847",
          "embed_code" => "<a href=\"https://www.iubenda.com/privacy-policy/193847\" class=\"iubenda-white no-brand iubenda-embed\" title=\"Privacy Policy\">Privacy Policy</a><script type=\"text/javascript\">(function (w,d) {var loader = function () {var s = d.createElement(\"script\"), tag = d.getElementsByTagName(\"script\")[0]; s.src = \"https://cdn.iubenda.com/iubenda.js\"; tag.parentNode.insertBefore(s,tag);}; w.addEventListener ? w.addEventListener(\"load\", loader, false) : w.attachEvent(\"onload\", loader);})(window, document);</script>"
        }
      ]
    }
  },
  "errors" => [],
  "success" => true,
  "api_version" => "1.0",
  "test" => false
}

Da questa risposta si possono estrarre tutti i valori di output => privacy_policies. Notare che privacy_policies è un array che, in questo scenario, è sempre composto da un solo elemento.

Hai ancora domande?

Partecipa a uno dei nostri webinar gratuiti Scrivici via email Live chat