# Sincronizzazione della cartella dello studio (Windows)

Lo script `allega-sync.ps1` scarica in una cartella del PC i file caricati dai clienti, già ordinati con la regola di nomi e cartelle impostata in Allega (Impostazioni > Personalizzazione). Non è un programma: è un solo script PowerShell, nessuna installazione.

## Cosa serve

- Windows con PowerShell 5.1 (già presente) o successivo.
- Una chiave API con permesso `read:files` (Impostazioni > Integrazioni > Chiavi API).

## Preparazione

1. Scarica `allega-sync.ps1` da https://allega.it/download/allega-sync.ps1 e copialo in una cartella, ad esempio `C:\Allega\sync`.
2. Nella stessa cartella crea `allega-sync.config.json`:

```json
{
  "apiKey": "ak_live_...",
  "destinationFolder": "D:\\Studio\\Allega",
  "baseUrl": "https://app.allega.it"
}
```

`baseUrl` è facoltativo. Il file contiene la chiave: tienilo leggibile solo dall'utente che esegue lo script.

3. Prova a mano da PowerShell: `powershell -ExecutionPolicy Bypass -File C:\Allega\sync\allega-sync.ps1`

Al primo giro scarica tutto ciò che è già presente; nei giri successivi solo i file nuovi.

## Come si comporta

- Scarica solo file con antivirus concluso e pulito (niente file in analisi o in quarantena).
- Sincronizza i file **caricati** dai clienti, non solo quelli approvati.
- Non sovrascrive mai: se il file esiste già aggiunge ` (2)`, ` (3)` al nome.
- Se il file ha un checksum, lo verifica dopo il download.
- Se un file fallisce si ferma e al giro successivo riparte da lì.
- Cancellare o spostare un file dalla cartella non lo fa riscaricare. Per ripartire da zero cancella `allega-sync.state.json`.
- Se cambi la regola di nomi in Allega, valgono solo i file nuovi; quelli già scaricati restano dove sono.

File creati accanto allo script: `allega-sync.state.json` (avanzamento) e `allega-sync.log` (registro: un rigo per file scaricato ed eventuali errori).

## Pianificazione ogni 15 minuti (Utilità di pianificazione)

1. Apri **Utilità di pianificazione** > **Crea attività** (non "attività di base").
2. Scheda **Generale**: nome `Allega sync`; scegli "Esegui indipendentemente dalla connessione dell'utente" se il PC resta acceso senza accesso.
3. Scheda **Trigger** > Nuovo: "Su base giornaliera", poi spunta **Ripeti attività ogni** `15 minuti` per la durata `Indefinitamente`.
4. Scheda **Azioni** > Nuova: programma `powershell.exe`, argomenti
   `-NoProfile -ExecutionPolicy Bypass -File "C:\Allega\sync\allega-sync.ps1"`, "Inizia in" `C:\Allega\sync`.
5. Scheda **Impostazioni**: "Non avviare una nuova istanza" se l'attività è già in esecuzione.

Oppure, da un prompt dei comandi come amministratore:

```
schtasks /Create /TN "Allega sync" /SC MINUTE /MO 15 /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Allega\sync\allega-sync.ps1"
```

## Problemi frequenti

- `401` nel log: chiave sbagliata, revocata o scaduta.
- `403 insufficient_scope`: la chiave non ha `read:files`.
- `429`: troppe richieste, il giro successivo riprova.
- Percorsi oltre 260 caratteri: accorcia la cartella di destinazione o i modelli di nome.