> ## 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.

# Best practice operative per le integrazioni Mattone

> Le 7 regole d'oro che si applicano a ogni integrazione Mattone: seguirle previene l'80% dei problemi e riduce il tempo di debug sul campo.

Queste 7 regole si applicano a ogni integrazione, indipendentemente dal pezzo che stai configurando. Non sono linee guida vaghe: derivano da errori reali accaduti sul campo. Seguirle previene l'80% dei problemi prima che si presentino e riduce il tempo di debug quando qualcosa va storto.

## 1. Segui l'ordine, non improvvisare

Ogni connessione ha un "prima" e un "dopo": l'ordine dei passi non è arbitrario ma riflette dipendenze reali tra i componenti. Saltare un passo, anche uno che sembra minore, rompe silenziosamente ciò che viene dopo.

Esempio classico: aggiungere un custom tool a Conduit senza configurare la skill corrispondente. L'agente ignora il tool o tenta un percorso nativo inaffidabile, e il problema non produce un errore visibile, il tool semplicemente non funziona.

<Tip>
  Prima di iniziare qualsiasi configurazione, apri la pagina **Integrazioni** corrispondente e leggi tutti i passi dall'inizio. Identifica le dipendenze prima di toccare qualsiasi impostazione.
</Tip>

## 2. Verifica SEMPRE i log dell'esito reale

Quello che mostra l'interfaccia di un'app è spesso una semplificazione, o peggio, un messaggio fuorviante. I log mostrano l'esito reale. Non fidarti di ciò che l'app ti dice: fidati di ciò che i log mostrano.

<Warning>
  **Caso reale, SwitchBot, 20 agosto:** l'app SwitchBot mostrava lo stato della batteria come "scarica". I Vercel runtime logs restituivano invece il codice `161`, che corrisponde a **device offline** (Hub Mini non raggiungibile). La diagnosi basata sull'app avrebbe portato a sostituire le batterie; quella basata sui log ha portato a ripristinare la connessione WiFi dell'Hub Mini. Due fix completamente diversi, uno corretto, l'altro inutile.
</Warning>

Controlla sempre: Vercel runtime logs, risposta grezza dell'API (spesso include il codice di errore), console del browser.

## 3. Ogni deploy/fix deve mostrare problema + soluzione

Un errore silenzioso o un messaggio generico come "qualcosa è andato storto" non è accettabile. Ogni scenario di errore deve:

* Mostrare all'utente (studente o operatore) **cosa è andato storto** in modo comprensibile
* Indicare **come risolverlo** o chi contattare
* Essere documentato nella pagina Troubleshooting corrispondente con il codice di errore e la soluzione

<Note>
  Se stai correggendo un bug e la soluzione non è ancora documentata, aggiungila alla pagina Troubleshooting prima di chiudere il ticket. Il prossimo a incontrare lo stesso problema potrebbe essere un account manager non tecnico.
</Note>

## 4. Ogni tool Conduit va SEMPRE con la sua skill

Un custom tool senza skill è inutile. L'agente Conduit non sa quando usarlo, quindi o lo ignora completamente o cade su un percorso nativo che non è stato pensato per quel caso d'uso.

La sequenza corretta è sempre:

1. Crea il tool
2. Crea la skill che specifica quando e come usarlo
3. Verifica che l'agente risponda correttamente a un input di test

<Warning>
  Non dichiarare "fatto" dopo aver creato il tool. Lo smoke test dell'agente (passo 3) è parte integrante della configurazione, non un'opzione.
</Warning>

## 5. Credenziali mai in chat né nei repo

Le chiavi API, i token e le password dei clienti non vanno mai in una chat (WhatsApp, Slack, email) né committate in un repository. Vanno sempre e solo nel **Vault**, il magazzino cifrato delle credenziali.

Se uno studente ti invia una credenziale in chat, fai due cose immediatamente:

1. Salvala nel Vault
2. Chiedi allo studente di **ruotare la chiave**, quella inviata in chat va considerata compromessa

<Warning>
  Una chiave inviata in chat è una chiave esposta. La policy è zero eccezioni.
</Warning>

Per le istruzioni su come salvare e recuperare le credenziali consulta la pagina [Credenziali e Vault](/riferimenti/credenziali).

## 6. Prima di dire "fatto", smoke test

L'onboarding non è completo finché non hai verificato personalmente che i tre elementi chiave funzionano:

* ✅ **Apertura porta**: il comando di apertura eseguito da Conduit aziona fisicamente la serratura
* ✅ **Knowledge Base**: l'agente risponde correttamente a una domanda sull'appartamento usando le informazioni della KB
* ✅ **Link di pagamento**: Stripe genera correttamente un link di pagamento per lo studente

<Tip>
  Esegui lo smoke test sempre dalla prospettiva dell'ospite finale, non dall'interfaccia di amministrazione. Usa un numero WhatsApp reale per testare il flusso completo.
</Tip>

Per la checklist completa vedi la pagina [Verifica finale](/onboarding/6-verifica-finale).

## 7. Conosci le pagine di riferimento prima di iniziare

Ogni integrazione ha una pagina dedicata in Mattone Docs con la lista degli endpoint attivi, i codici di errore noti e le soluzioni già documentate. Prima di improvvisare una soluzione o aprire un ticket, consulta la pagina di riferimento corrispondente: spesso il problema è già stato incontrato e risolto.

<Note>
  L'elenco completo delle integrazioni supportate con i relativi endpoint è in [Repo e API di riferimento](/riferimenti/repo-api). Aggiungila ai segnalibri insieme al [Catalogo MCP](/riferimenti/mcp-catalog) per avere tutto a portata di mano durante il debug.
</Note>