Skip to content

Accesso diretto (SSO) ​

Integra con un assistente AI
Scarica o copia il prompt di integrazione per Accesso diretto (SSO) e incollalo in Claude Code, Cursor o Copilot: contiene auth, esempi end-to-end e checklist.
Apri

Con l'accesso diretto i tuoi utenti entrano in Dokicasa dal tuo sito, senza password. Un pulsante "Vai a Dokicasa" nel tuo gestionale li porta già dentro la loro area riservata, o direttamente a una pratica.

Attivazione su richiesta

L'accesso diretto va abilitato da Dokicasa sul tuo account. Comunica anche gli IP pubblici dei tuoi server: non sono obbligatori, ma se li indichi le chiamate da altri IP vengono rifiutate.

Come funziona ​

  1. L'utente clicca "Vai a Dokicasa" nel tuo sito.
  2. Il tuo server chiama Dokicasa con la tua API key e l'email dell'utente.
  3. Dokicasa trova l'utente fra i tuoi, oppure lo crea, e ti restituisce un link di accesso valido 5 minuti e utilizzabile una sola volta.
  4. Il tuo server manda il browser dell'utente su quel link: l'utente è dentro.

L'utente diventa un utente collegato al tuo account, come quelli che registri tu: eredita le tue condizioni e vedi le sue pratiche.

Non chiamare l'endpoint dal browser

La chiamata usa la tua API key, che non deve mai arrivare nella pagina. Chiamala dal tuo server nel momento del clic, e poi fai il redirect.

bash
curl -X POST https://app.dokicasa.it/api/v3/sso/login-link \
  -H 'Authorization: Bearer LA_TUA_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "mario.rossi@example.com",
    "first_name": "Mario",
    "last_name": "Rossi",
    "redirect_path": "/app/area-personale/home"
  }'
json
{
  "login_url": "https://app.dokicasa.it/redirect-sso?code=Xk2...",
  "expires_in": 300,
  "user_id": 48213,
  "created": true
}
CampoObbligatorioDescrizione
emailsìEmail dell'utente. Se non c'è un external_user_id già collegato, è quella che identifica l'utente
external_user_idconsigliatoL'id dell'utente nel tuo sistema. Lo colleghiamo all'utente Dokicasa: se poi l'email cambia, l'utente resta lo stesso
external_group_idnoL'id del gruppo, dell'agenzia o della sede nel tuo sistema. Lo salviamo per riconoscere gli utenti dello stesso gruppo
first_namenoNome. Usato solo quando l'utente viene creato
last_namenoCognome. Come sopra
company_namenoRagione sociale. Come sopra
vat_codenoPartita IVA italiana (11 cifre). Se non è valida viene ignorata. Come sopra
phonenoTelefono. Come sopra
professional_typenoAZIENDA (predefinito), PROFESSIONISTA o PRIVATO. Come sopra
redirect_pathnoPagina di arrivo dopo l'accesso: un percorso di Dokicasa che inizia con /, per esempio /servizi/registrazione-contratto-locazione/richiedi. Predefinita: l'area riservata
redirect_urlnoIn alternativa a redirect_path: l'indirizzo completo, solo di app.dokicasa.it

I dati anagrafici servono solo alla creazione: per un utente che esiste già non li sovrascriviamo.

Nella risposta, created vale true quando l'utente è stato appena creato (risposta 201) e false quando esisteva già (risposta 200). Conserva user_id se vuoi collegarlo ai tuoi dati.

php
// Nel controller del pulsante "Vai a Dokicasa"
$res = Http::withToken(env('DOKICASA_API_KEY'))
    ->acceptJson()
    ->post('https://app.dokicasa.it/api/v3/sso/login-link', [
        'email'      => $user->email,
        'first_name' => $user->first_name,
        'last_name'  => $user->last_name,
    ]);

return redirect()->away($res->json('login_url'));
js
app.get('/vai-a-dokicasa', async (req, res) => {
  const r = await fetch('https://app.dokicasa.it/api/v3/sso/login-link', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DOKICASA_API_KEY}`,
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email: req.user.email, first_name: req.user.firstName }),
  })
  const { login_url } = await r.json()
  res.redirect(login_url)
})

Un pulsante sul tuo sito ​

Il pulsante "Vai a Dokicasa" o "Acquista qui" non può essere un link fisso: chiunque lo copiasse entrerebbe nell'account. Deve puntare a una pagina del tuo sito che, al clic, fa la chiamata qui sopra con l'utente collegato e poi manda il browser sul login_url.

Funziona quindi solo per gli utenti che hanno fatto l'accesso al tuo sito. Per i visitatori non registrati usa un normale link a https://app.dokicasa.it: si registrano o accedono lì.

Sito WordPress ​

Abbiamo preparato un plugin che fa tutto questo: scarica dokicasa-sso.zip.

  1. In WordPress vai su Plugin → Aggiungi nuovo → Carica plugin, scegli lo zip e attivalo.

  2. Vai su Impostazioni → Dokicasa, incolla la tua API key e salva. Lì scegli anche l'ambiente (produzione o prova), il testo del pulsante e la pagina di arrivo.

  3. Metti lo shortcode dove vuoi il pulsante, in una pagina, un widget o il menu:

    text
    [dokicasa_sso]
    [dokicasa_sso testo="Acquista qui" pagina="/servizi/registrazione-contratto-locazione/richiedi"]

Non serve scrivere codice. La chiave resta sul server di WordPress e non viene mai mostrata, nemmeno nelle impostazioni. Chi preferisce può metterla in wp-config.php con define('DOKICASA_API_KEY', '...');: in quel caso vale quella.

Gli attributi dello shortcode, tutti facoltativi, cambiano un singolo pulsante:

AttributoPredefinitoDescrizione
testoquello delle impostazioniIl testo del pulsante
paginaquella delle impostazioniLa pagina di Dokicasa su cui arriva l'utente
classebutton dokicasa-ssoLe classi CSS, per usare lo stile dei pulsanti del tuo tema

Il plugin manda a Dokicasa email, nome e cognome dell'utente WordPress e il suo id come external_user_id. Chi non ha fatto l'accesso a WordPress viene portato prima al login del tuo sito.

  • Vale 5 minuti e una sola volta: chiedine uno nuovo a ogni clic, non salvarlo e non mandarlo per email.
  • Aperto una seconda volta, o dopo la scadenza, risponde 410.
  • Dopo l'accesso l'utente resta collegato a Dokicasa come con un login normale.

Staging ​

Per provare senza toccare la produzione usa https://testing.dokicasa.it: stessa chiamata (/api/v3/sso/login-link), con la API key dello staging. Chiedi a Dokicasa di attivare la SSO anche lì.

Con il plugin WordPress scegli Prova (testing.dokicasa.it) in Impostazioni → Dokicasa e incolla la API key dello staging.

Errori ​

StatocodeCosa vuol dire
401API key mancante o non valida
403Accesso diretto non abilitato sul tuo account, oppure chiamata da un IP non indicato
409EMAIL_NOT_YOURSL'email è già registrata su Dokicasa ma non è un tuo utente. Per sicurezza non si entra negli account di altri: l'utente accede con le sue credenziali
409USER_DISABLEDL'utente è stato disattivato
422Dati non validi, per esempio un'email sbagliata o un redirect_path che non inizia con /