# Dokicasa SSO: istruzioni di integrazione per assistenti AI

Da consegnare a un assistente AI per far entrare gli utenti di un partner in
Dokicasa senza password. Guida completa: https://docs.dokicasa.it/sso

Se manca un dato (API key, pagina di arrivo, come si legge l'utente collegato), chiedilo all'utente. Non inventarlo.

## Come funziona

1. L'utente, gia' collegato al sito del partner, clicca un pulsante ("Vai a Dokicasa", "Acquista qui").
2. Il SERVER del partner chiama `POST https://app.dokicasa.it/api/v3/sso/login-link`
   con `Authorization: Bearer <API key del partner>` e i dati dell'utente.
3. La risposta contiene `login_url`: valido 5 minuti, una sola volta.
4. Il server fa il redirect del browser su `login_url`. L'utente entra in Dokicasa.

L'utente diventa figlio dell'account del partner. Un'email gia' registrata su
Dokicasa per un altro account non entra (409 `EMAIL_NOT_YOURS`): e' voluto.

## Regole

1. La API key non deve MAI finire nel browser, in un bundle o nel codice versionato.
   L'endpoint si chiama solo dal server, nel momento del clic.
2. Il pulsante NON puo' essere un link fisso a `login_url`: va chiesto un link nuovo a
   ogni clic. Non salvarlo e non mandarlo per email.
3. Funziona solo per utenti collegati al sito del partner. Per i visitatori anonimi
   usa un link normale a https://app.dokicasa.it.
4. La SSO va attivata da Dokicasa sull'account. Se il partner comunica gli IP dei
   server, le chiamate da altri IP ricevono 403.
5. Non esistono `access_token` da passare in URL, endpoint `/api/v1/sso/...` per i
   partner nuovi, o chiavi diverse dalla API key. Se li trovi in vecchi esempi, ignorali.

## Campi (JSON)

| Campo | Obbligatorio | Note |
|---|---|---|
| `email` | si' | identifica l'utente se non c'e' un `external_user_id` gia' collegato |
| `external_user_id` | consigliato | id dell'utente nel sistema del partner; resta valido anche se l'email cambia |
| `external_group_id` | no | id di gruppo/agenzia/sede nel sistema del partner |
| `first_name`, `last_name`, `company_name`, `vat_code`, `phone` | no | usati solo alla creazione; P.IVA non valida ignorata |
| `professional_type` | no | `AZIENDA` (predefinito), `PROFESSIONISTA`, `PRIVATO` |
| `redirect_path` | no | percorso Dokicasa che inizia con `/` (es. `/servizi/registrazione-contratto-locazione/richiedi`) |
| `redirect_url` | no | in alternativa: URL completo, solo `app.dokicasa.it` |

Risposta: `{ "login_url", "expires_in": 300, "user_id", "created" }`, 201 se creato, 200 se esisteva.

## Errori

- 401: API key mancante o sbagliata.
- 403: SSO non attiva sull'account, oppure IP non in elenco.
- 409 `EMAIL_NOT_YOURS`: email di un altro account Dokicasa. Mostra un messaggio:
  "accedi da app.dokicasa.it con le tue credenziali".
- 409 `USER_DISABLED`: utente disattivato.
- 422: dati non validi (email, `redirect_path` che non inizia con `/`, dominio di `redirect_url`).
- Aprendo `login_url` una seconda volta o dopo 5 minuti: 410.

## Esempio (PHP / Laravel)

```php
$res = Http::withToken(env('DOKICASA_API_KEY'))->acceptJson()
    ->post('https://app.dokicasa.it/api/v3/sso/login-link', [
        'email'            => $user->email,
        'external_user_id' => (string) $user->id,
        'first_name'       => $user->first_name,
        'last_name'        => $user->last_name,
        'redirect_path'    => '/app/area-personale/home',
    ]);

if ($res->status() === 409) {
    return back()->withErrors('Email gia\' registrata su Dokicasa: accedi con le tue credenziali.');
}

return redirect()->away($res->throw()->json('login_url'));
```

## WordPress

Esiste un plugin pronto, senza codice: https://docs.dokicasa.it/downloads/dokicasa-sso.zip
(Plugin > Carica plugin). Poi Impostazioni > Dokicasa: API key, ambiente (produzione/prova),
testo e pagina predefiniti. Shortcode: `[dokicasa_sso testo="Acquista qui" pagina="/servizi/.../richiedi" classe="button"]`.
In alternativa la chiave puo' stare in `wp-config.php` (`define('DOKICASA_API_KEY', '...');`).

## Staging

Base URL `https://testing.dokicasa.it`, stessa chiamata, API key dello staging
(chiedila a Dokicasa insieme all'attivazione della SSO sullo staging).
