Accesso diretto (SSO)
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
- L'utente clicca "Vai a Dokicasa" nel tuo sito.
- Il tuo server chiama Dokicasa con la tua API key e l'email dell'utente.
- 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.
- 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.
La chiamata
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"
}'{
"login_url": "https://app.dokicasa.it/redirect-sso?code=Xk2...",
"expires_in": 300,
"user_id": 48213,
"created": true
}| Campo | Obbligatorio | Descrizione |
|---|---|---|
email | sì | Email dell'utente. Se non c'è un external_user_id già collegato, è quella che identifica l'utente |
external_user_id | consigliato | L'id dell'utente nel tuo sistema. Lo colleghiamo all'utente Dokicasa: se poi l'email cambia, l'utente resta lo stesso |
external_group_id | no | L'id del gruppo, dell'agenzia o della sede nel tuo sistema. Lo salviamo per riconoscere gli utenti dello stesso gruppo |
first_name | no | Nome. Usato solo quando l'utente viene creato |
last_name | no | Cognome. Come sopra |
company_name | no | Ragione sociale. Come sopra |
vat_code | no | Partita IVA italiana (11 cifre). Se non è valida viene ignorata. Come sopra |
phone | no | Telefono. Come sopra |
professional_type | no | AZIENDA (predefinito), PROFESSIONISTA o PRIVATO. Come sopra |
redirect_path | no | Pagina di arrivo dopo l'accesso: un percorso di Dokicasa che inizia con /, per esempio /servizi/registrazione-contratto-locazione/richiedi. Predefinita: l'area riservata |
redirect_url | no | In 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.
// 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'));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.
In WordPress vai su Plugin → Aggiungi nuovo → Carica plugin, scegli lo zip e attivalo.
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.
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:
| Attributo | Predefinito | Descrizione |
|---|---|---|
testo | quello delle impostazioni | Il testo del pulsante |
pagina | quella delle impostazioni | La pagina di Dokicasa su cui arriva l'utente |
classe | button dokicasa-sso | Le 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.
Il link di accesso
- 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
| Stato | code | Cosa vuol dire |
|---|---|---|
401 | API key mancante o non valida | |
403 | Accesso diretto non abilitato sul tuo account, oppure chiamata da un IP non indicato | |
409 | EMAIL_NOT_YOURS | L'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 |
409 | USER_DISABLED | L'utente è stato disattivato |
422 | Dati non validi, per esempio un'email sbagliata o un redirect_path che non inizia con / |