API docs: Creare e recuperare una privacy policy

Questa è la documentazione per utilizzare la API JSON di iubenda, che permette di generare una privacy policy tramite un’unica chiamata e di recuperarne i dati in qualsiasi momento, tramite l’ID della transazione.

Requisiti

API Key

La chiave unica di cui ogni soggetto autorizzato all’uso dell’API è in possesso.

Creare una Privacy Policy

POST

api/transactions, type create_privacy_policy

URL

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

Parametri

"api_key" => // una API Key valida (required)
"type" => "create_privacy_policy" // (required)
"test" => // "true" | "false" (optional, default: false)
"args" => {
  "user" => {
    "email" => // email dell'utente (required)
    "lang" => // "it" o "en" , (optional, default: "it")
  } // "user"
  "privacy_policy" => {
    "url" => // URL del sito web di cui generare la policy (required)
    "langs" => // Lingue in cui generare la privacy policy "it" o "en" (optional, default: "it")
    "owner" => {
      "info" => // Intestazione del Titolare del Trattamento (required)
      "email" => // email di contatto da inserire nella privacy policy (optional, default: email dell'utente)
    } // "owner"
  } // "privacy_policy"
} // "args"

Gestione utente

Se l’utente di cui viene fornita l’email non è presente nel sistema, viene creato.

Se l’utente di cui viene fornita l’email è già presente nel sistema, le privacy policy gli vengono aggiunte in ogni caso.

Inoltre, in caso di utente già presente nel sistema, la password corrente dell’utente deve essere provvista insieme alla sua email.
In riferimento all’esempio precedente, l’input diviene:

...
"args" => {
  "user" => {
    "email" => // email dell'utente (required)
    "pwd" =>   // password corrente dell'utente 
  } // "user"
...

Output

"transaction_id" => // id della transazione creata (nullo se la transazione è di test (test => true) )
"output" => { // campo presente se la transazione viene eseguita correttamente (success => true)
  "user" => {
    "id" => // ID dell'utente creato (o a cui la privacy policy viene aggiunta se l'utente è già registrato)
    "email" => // l'email dell'utente creato o modificato
  } // "user"
  "privacy_policies" => [ // array di hash, uno per ciascuna privacy policy aggiunta, ciascun hash avente la struttura:
    {
      "id" => // ID della privacy policy aggiunta
      "lang" => // lingua della privacy policy aggiunta ("it" o "en")
      "setup_url" => // url per accedere al setup della privacy policy aggiunta
      "edit_url" => // url per accedere al pannello di modifica della privacy policy
      "policy_url" => // link diretto alla privacy policy
      "embed_code" => // codice d'inserimento della privacy policy
    }
  ] // "privacy_policies"
} // "output"
"errors" => // array di messaggi di errore (vuoto se la transazione è eseguita con successo)
"success" => // true o false
"api_version" => "1.0"
"test" => // true o false (in base al parametro test passato in input)

Note sugli output

I valori “setup_url” e “edit_url” sono configurati per fornire dei link che effettuano il login automatico dell’utente, dunque non necessitano di autenticazione.

Quando l’utente utilizza per la prima volta uno di questi due link (e non era in precedenza registrato) gli viene chiesto di settare la sua password prima di poter procedere.

Esempio

POST

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

POST Data

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email" => "test.mail@iubenda.com",
  },
  "privacy_policy" => {
    "url" => "http://www.example.com",
    "owner" => {
      "info" => "Iubenda Srl, Via Monti, 52 - Milano (MI) - Italia",
      "email" => "owner.mail@iubenda.com"
    }
  }
}

RESPONSE (JSON)

=> {
  "success" => true, 
  "transaction_id" => 1,
  "output" => {
    "user" => {
      "id"=> 6269, 
      "email" => "test.mail@iubenda.com"
    }, 
    "privacy_policies" => [
      {
        "id" => 19276, 
        "lang" => "it", 
        "setup_url" => "https://www.iubenda.com/p/it/privacy-policy-generator/19276/services?l_email=test.mail@iubenda.com&l_tok=enL39d1xhk1RPPRuW8U5",
        "edit_url" => "https://www.iubenda.com/p/it/privacy-policy-generator/19276/edit?l_email=test.mail@iubenda.com&l_tok=enL39d1xhk1RPPRuW8U5", 
        "policy_url" => "https://www.iubenda.com/p/privacy-policy/193847"
        "embed_code" => "<a href=\"https://www.iubenda.com/p/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" => [], 
  "api_version" => "1.0",
  "test" => false
}