> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Collegare un device Shelly alla piattaforma Mattone

> Come registrare un device Shelly nella piattaforma Mattone usando il token Shelly Cloud per abilitare l'apertura remota della porta.

Per abilitare l'apertura remota della porta tramite Shelly, devi registrare il device nella piattaforma Mattone usando il token Shelly Cloud generato dallo studente. Il token è la chiave di accesso alle API Shelly Cloud: viene conservato in modo cifrato nel Vault e non deve mai circolare fuori da quel contesto.

## Prerequisiti

Prima di iniziare, assicurati che siano tutti soddisfatti:

* Device Shelly **fisicamente installato** sulla porta o citofono dell'immobile
* Account Shelly Cloud **creato dallo studente** e associato al device
* Device **visibile come online** nell'app o nel portale Shelly Cloud

## Collegamento

<Steps>
  <Step title="Genera il token Shelly Cloud">
    Lo studente accede al portale Shelly Cloud (o all'app Shelly Smart Control), va in **Account → Impostazioni → API token** e clicca su **Genera nuovo token**. Copia il token generato, sarà visibile una sola volta.
  </Step>

  <Step title="Invia il token in modo sicuro al team Mattone">
    Lo studente invia il token al team Mattone tramite il canale sicuro concordato (mai via chat ordinaria, email non cifrata o documenti condivisi). Il team riceve anche il **Device ID** del device Shelly, visibile nelle impostazioni del device in Shelly Cloud.
  </Step>

  <Step title="Salva il token nel Vault">
    Il team Mattone salva il token cifrato nel Vault, associandolo alla proprietà dello studente. Nessun membro del team deve conservare il token in locale o in strumenti non approvati.
  </Step>

  <Step title="Aggiungi il device in piattaforma">
    Nella piattaforma Mattone, vai su **Devices → Aggiungi Shelly**. Inserisci il token Shelly Cloud e il Device ID del device, quindi salva la configurazione.
  </Step>

  <Step title="Verifica la connessione">
    La piattaforma testa la connessione al device. Il device deve risultare **online** nel pannello Devices. Se appare offline, verifica che il device sia connesso al WiFi e che il token sia corretto.
  </Step>

  <Step title="Test di apertura reale">
    Esegui un'apertura di test dalla piattaforma e verifica nei log che il relay si sia attivato correttamente. Il log deve mostrare una risposta di successo (non un errore). Idealmente, esegui il primo test con qualcuno fisicamente presente all'immobile.
  </Step>
</Steps>

<Warning>
  Salva le credenziali Shelly **solo nel Vault**, mai in messaggi, email, fogli di calcolo o documenti condivisi. Credenziali esposte consentono il controllo remoto del device a chiunque le possieda.
</Warning>

<Note>
  **In parole semplici:** il **Server** dice *dove* sta l'account Shelly e la **Auth Key** *autorizza* ad aprire il relè (l'interruttore che apre porta/citofono) di quell'account. Senza, l'apertura è negata.

  **Come è fatto davvero.** Shelly Cloud lavora **per account**: ogni account ha un **Server** (`shelly-<NN>-eu.shelly.cloud`) + una **Auth Key**. Per gli **studenti** questi dati vanno nel Vault come `shelly_config_<token>` = `{ server, auth_key, devices }` e il nostro ponte li usa quando l'assistente lavora; per **Cosmica** i device stanno nel registro codice `SHELLY_DEVICES` (`src/lib/shelly.ts`), 1 riga per device (slug, deviceId 12-hex, tipo citofono/porta, account). L'apertura è un **impulso al relè**: `POST /device/relay/control` con `timer=3` (acceso 3 sec poi si spegne). Stato: `POST /device/status`. Limite: **1 richiesta/sec per account**.
</Note>

## Verifica

Dopo il collegamento, controlla che tutto funzioni correttamente:

* Il device appare come **online** nel pannello Devices della piattaforma
* Il test di apertura **attiva fisicamente il relay** (la porta o il citofono risponde)
* I log mostrano una **risposta di successo**, senza codici di errore

<Tip>
  Verifica che il relay Shelly attivi il circuito corretto, alcuni edifici hanno più relay sullo stesso citofono o più porte controllabili. Esegui sempre il primo test con una persona fisicamente presente all'immobile per confermare quale porta si apre.
</Tip>

<Tip>
  **▷ Prompt Claude Code: Aggiungi un device Shelly**  ·  incolla in Claude Code:
</Tip>

```text theme={null}
Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri il repo di check-in giusto, `~/Projects/cosmica-booking`
(baseline Cosmica: `src/lib/shelly.ts` + guest portal `/access/<slug>`) o il
repo di check-in dello studente, e LEGGI la pagina mattone-docs
/integrazioni/shelly/collegamento. Poi procedi:

Aggiungi un device Shelly per la proprietà [NOME/SLUG] seguendo mattone-docs
/integrazioni/shelly/collegamento. Chiedimi deviceId (12 hex), type
(citofono/porta) e account (cosmica/verdi o nuovo). Verifica prima i
prerequisiti (env dell'account su Vercel, proprietà nel PMS). Aggiungi UNA riga
a SHELLY_DEVICES in src/lib/shelly.ts, fai commit+push, poi verifica:
list_properties mostra lo slug, il guest portal /access/<slug> carica, e
fammi fare un'apertura REALE leggendo i log. Le Auth Key stanno nel Vault, non
metterle nel repo.
```

<CardGroup cols={2}>
  <Card title="Shelly Cloud" icon="arrow-up-right-from-square" href="https://control.shelly.cloud">Device → Settings → Device Information (deviceId)</Card>
  <Card title="Troubleshooting Shelly" icon="arrow-up-right-from-square" href="/integrazioni/shelly/troubleshooting">Relay offline / non apre</Card>
</CardGroup>