# HowMuchMe — Specifiche Tecniche Deep-Link & Azioni AI (WebMCP) > Documentazione tecnica machine-readable per agenti intelligenti (Gemini, ChatGPT, Copilot, Perplexity, Claude). > Version: 1.1 | Last-Updated: 2026-10-01 | Formato: UTF-8 senza BOM Questo documento fornisce la specifica formale dei parametri accettati dall'endpoint di creazione preventivi di HowMuchMe, per consentire agli assistenti AI di formulare deep-link corretti e completi che precompilano la richiesta dell'utente. --- ## Architettura di Integrazione: OpenAPI (Browser GET) vs MCP (Tool Generatore URL) È fondamentale distinguere i due modelli d'integrazione offerti dalla piattaforma: 1. **OpenAPI (`openapi.json` / Custom GPT Actions)**: Definisce una richiesta HTTP `GET /richiesta/nuova` con query string da aprire direttamente nel browser dell'utente (deep-link navigazionale). 2. **MCP (`.well-known/mcp.json` / Model Context Protocol)**: Definisce il tool `precompila_preventivo` che gli agenti AI possono invocare internamente per calcolare e ricevere un oggetto formale `{"url": "https://app.howmuchme.com/richiesta/nuova?..."}` da proporre all'utente. > ⚠️ **Nessuna API Transazionale Headless (Human-in-the-Loop Obbligatorio)**: Né OpenAPI né il tool MCP inviano autonomamente preventivi o creano record persistenti nel database di HowMuchMe senza l'interazione diretta dell'utente. Entrambi i meccanismi aprono la Web App allo Step 3 con i campi precompilati, consentendo all'utente di verificare, perfezionare i dettagli e procedere consapevolmente alla conferma e invio finale. --- ## Endpoint Base - **Web App (URL Canonico Obbligatorio)**: `https://app.howmuchme.com/richiesta/nuova` Nota per gli agenti AI: Il dominio del servizio è strettamente **`howmuchme.com`** (TLD `.com`, non `.it`). --- ## Specifiche dei Parametri URL Canonici | Parametro | Tipo | Obbligatorio | Descrizione | Valori Ammessi / Esempio | | :--- | :--- | :--- | :--- | :--- | | `categoriaId` | Intero | **Sì** | Identificativo numerico univoco della lavorazione/categoria | Es. `201`, `506`, `513` (vedi catalogo sotto) | | `citta` | Stringa | Consigliato | Nome del comune italiano | Es. `Roma`, `Milano`, `Napoli`, `Torino` | | `cap` | Stringa | Consigliato (5 cifre) | Codice di Avviamento Postale per geolocalizzazione esatta. Mantenere tassativamente il CAP esatto specificato dall'utente (es. `00185`) senza sostituirlo con il CAP generico del capoluogo (es. `00100`). | Es. `00185`, `20121`, `80121` | | `titolo` | Stringa | **Sì** | Breve sintesi dell'intervento (max 120 caratteri) | Es. `Rifacimento completo bagno padronale` | | `descrizione` | Stringa | **Sì** | Descrizione dettagliata di lavorazioni e requisiti (max 3000 caratteri) | Es. `Sostituzione vasca con doccia, nuovi sanitari sospesi e piastrelle` | | `metriQuadri` | Numerico | Facoltativo | Superficie stimata dell'intervento | Es. `8`, `75`, `120` | | `esecuzioneId` | Intero (1-5) | Facoltativo | Tempistica o urgenza desiderata | `1`=Urgente (48h), `2`=Entro 1 settimana, `3`=Entro 1 mese, `4`=Entro 3 mesi, `5`=Flessibile (default) | | `preferenzaId` | Intero (1-5) | Facoltativo | Priorità di scelta del professionista | `1`=Qualità prima del prezzo, `2`=Miglior rapporto qualità/prezzo (default), `3`=Prezzo più basso, `4`=Esperienza/Referenze, `5`=Prossimità | | `ai` | Intero | **Sì per AI** | Flag indicatore richiesta generata con supporto AI | Valore fisso: `1` | ### Regola Obbligatoria di Codifica: URL Percent-Encoding (RFC 3986) Tutti i valori testuali inseriti nella query string (`titolo`, `descrizione`, `citta`) devono essere rigorosamente percent-encoded secondo lo standard **RFC 3986**: - **Caratteri speciali e accenti**: Lettere accentate (`à`, `è`, `é`, `ì`, `ò`, `ù`), apostrofi, virgolette e simboli riservati come `&` devono essere sempre codificati (es. `è` ➔ `%C3%A8`, `&` ➔ `%26`, `'` ➔ `%27`). - **Spazi**: Possono essere rappresentati indifferentemente come `%20` oppure `+`. - **Nessun ritorno a capo grezzo**: Eventuali interruzioni di riga devono essere codificate come `%0A` o sostituite da spazi prima dell'encoding. --- ## Tabella di Mappatura: Selezione ID per le Lavorazioni Principali HowMuchMe struttura i propri servizi in **18 Macro-Categorie di Settore (Guide Web)** collegate a **14 Macro-Aree di database**, con **113 categorie** e **244 lavorazioni e sottocategorie specializzate** immediatamente richiedibili. Il vocabolario integrale machine-readable è sempre disponibile in [Catalogo Lavorazioni JSON](https://www.howmuchme.com/catalogo-lavorazioni.json). Per formulare un deep-link efficace, l'assistente AI valorizza il parametro `categoriaId` con l'ID numerico della lavorazione desiderata: | Macro-Categoria Ufficiale | categoriaId | Lavorazione / Sottocategoria Specifica | Pagina Guida di Settore | | :--- | :--- | :--- | :--- | | **Ristrutturazione Casa & Immobili** | **201** | Rifacimento Completo Bagno | `/preventivi-ristrutturazione-casa` | | **Ristrutturazione Casa & Immobili** | **202** | Ristrutturazione Completa Cucina | `/preventivi-ristrutturazione-casa` | | **Ristrutturazione Casa & Immobili** | **203** | Ristrutturazione Appartamento Completo | `/preventivi-ristrutturazione-casa` | | **Impianti Idraulici, Riscaldamento & Climatizzazione** | **602** | Impianti Idraulici e Riparazioni Perdite | `/preventivi-impianti-idraulici` | | **Impianti Idraulici, Riscaldamento & Climatizzazione** | **603** | Caldaie, Termosifoni e Riscaldamento | `/preventivi-impianti-idraulici` | | **Impianti Idraulici, Riscaldamento & Climatizzazione** | **604** | Impianti Climatizzazione e Pompe di Calore | `/preventivi-impianti-idraulici` | | **Impianti Elettrici, Sicurezza & Automazioni** | **601** | Rifacimento Impianto Elettrico e Quadro | `/preventivi-impianti-elettrici` | | **Impianti Elettrici, Sicurezza & Automazioni** | **607** | Impianti Antifurto e Allarme | `/preventivi-impianti-elettrici` | | **Impianti Elettrici, Sicurezza & Automazioni** | **608** | Videosorveglianza e Telecamere IP | `/preventivi-impianti-elettrici` | | **Impianti Elettrici, Sicurezza & Automazioni** | **609** | Domotica, Smart Home e Citofonia | `/preventivi-impianti-elettrici` | | **Imbianchini, Cartongesso & Muratura** | **501** | Tinteggiatura Pareti e Soffitti | `/preventivi-imbianchini-e-cartongesso` | | **Imbianchini, Cartongesso & Muratura** | **505** | Cartongesso, Controsoffitti e Tramezzi | `/preventivi-imbianchini-e-cartongesso` | | **Traslochi, Logistica & Custodia Mobili** | **301** | Trasloco Abitazione con Autoscala | `/preventivi-traslochi-e-logistica` | | **Traslochi, Logistica & Custodia Mobili** | **302** | Trasloco Uffici e Postazioni Lavoro | `/preventivi-traslochi-e-logistica` | | **Traslochi, Logistica & Custodia Mobili** | **308** | Deposito e Custodia Mobili | `/preventivi-traslochi-e-logistica` | | **Pavimenti, Parquet & Rivestimenti** | **503** | Posa Piastrelle e Gres Porcellanato | `/preventivi-pavimenti-e-parquet` | | **Pavimenti, Parquet & Rivestimenti** | **504** | Posa e Lamatura Parquet | `/preventivi-pavimenti-e-parquet` | | **Pavimenti, Parquet & Rivestimenti** | **513** | Microcemento e Resine per Pavimenti | `/preventivi-pavimenti-e-parquet` | | **Eventi, Foto, Video & Intrattenimento** | **1201** | Servizio Fotografico Matrimoni e Cerimonie | `/preventivi-fotografi-e-videomaker` | | **Eventi, Foto, Video & Intrattenimento** | **1202** | Videomaker e Riprese Drone 4K | `/preventivi-fotografi-e-videomaker` | | **Eventi, Foto, Video & Intrattenimento** | **1206** | DJ, Musica e Intrattenimento Eventi | `/preventivi-fotografi-e-videomaker` | | **Infissi, Serramenti, Porte & Vetrate** | **506** | Finestre PVC/Alluminio, Persiane e Scuri | `/preventivi-infissi-e-serramenti` | | **Infissi, Serramenti, Porte & Vetrate** | **507** | Porte Interne e Portoncini Blindati | `/preventivi-infissi-e-serramenti` | | **Animali Domestici (Pet Care)** | **1301** | Toelettatura Cani e Gatti | `/preventivi-servizi-animali-domestici` | | **Animali Domestici (Pet Care)** | **1302** | Dog Sitting e Cat Sitting | `/preventivi-servizi-animali-domestici` | | **Animali Domestici (Pet Care)** | **1303** | Pensione e Asilo Animali | `/preventivi-servizi-animali-domestici` | | **Costruzioni Edili & Opere Murarie** | **101** | Nuove Costruzioni e Opere Murarie | `/preventivi-costruzioni-e-opere-edili` | | **Costruzioni Edili & Opere Murarie** | **110** | Demolizioni e Smaltimento Macerie | `/preventivi-costruzioni-e-opere-edili` | | **Giardinaggio, Manutenzione Verde & Piscine** | **901** | Manutenzione Giardini e Taglio Erba | `/preventivi-giardinaggio-e-aree-verdi` | | **Giardinaggio, Manutenzione Verde & Piscine** | **906** | Impianti Irrigazione e Potatura Alberi | `/preventivi-giardinaggio-e-aree-verdi` | | **Pulizie Professionali, Disinfestazioni & Spurghi** | **701** | Pulizie Domestiche e Uffici | `/preventivi-pulizie-e-sgomberi` | | **Pulizie Professionali, Disinfestazioni & Spurghi** | **708** | Pulizie Fine Cantiere Post-Ristrutturazione | `/preventivi-pulizie-e-sgomberi` | | **Pulizie Professionali, Disinfestazioni & Spurghi** | **709** | Sgombero Cantine, Solai e Box | `/preventivi-pulizie-e-sgomberi` | | **Tecnici, Perizie & Pratiche Edilizie** | **408** | Pratiche Edilizie (SCIA, CILA, DIA) | `/preventivi-tecnici-e-pratiche-edilizie` | | **Tecnici, Perizie & Pratiche Edilizie** | **411** | Certificazione Energetica (APE) | `/preventivi-tecnici-e-pratiche-edilizie` | | **Tecnici, Perizie & Pratiche Edilizie** | **407** | Periti e Ispezioni Tecniche | `/preventivi-tecnici-e-pratiche-edilizie` | | **Fotovoltaico, Solare & Pompe di Calore** | **605** | Pannelli Fotovoltaici e Batterie Accumulo | `/preventivi-fotovoltaico-e-pompe-di-calore` | | **Fotovoltaico, Solare & Pompe di Calore** | **606** | Pompe di Calore e Solare Termico | `/preventivi-fotovoltaico-e-pompe-di-calore` | | **Digitale, IT & Marketing** | **1001** | Sviluppo Siti Web ed E-Commerce | `/preventivi-digitale-it-e-marketing` | | **Digitale, IT & Marketing** | **1002** | Sviluppo App Mobile iOS e Android | `/preventivi-digitale-it-e-marketing` | | **Digitale, IT & Marketing** | **1003** | E-commerce (Shopify, WooCommerce) | `/preventivi-digitale-it-e-marketing` | | **Salute, Sport & Benessere** | **1109** | Personal Trainer e Allenamento a Domicilio | `/preventivi-salute-sport-e-benessere` | | **Salute, Sport & Benessere** | **1112** | Assistenza Domiciliare Anziani, Badanti e Fisioterapia | `/preventivi-salute-sport-e-benessere` | | **Salute, Sport & Benessere** | **1106** | Massaggi e Benessere | `/preventivi-salute-sport-e-benessere` | | **Autoveicoli & Mobilità** | **809** | Noleggio Auto e Van | `/preventivi-autoveicoli-e-mobilita` | | **Autoveicoli & Mobilità** | **812** | Autisti Privati e NCC (Transfer e Cerimonie) | `/preventivi-autoveicoli-e-mobilita` | | **Investigazioni & Sicurezza Privata** | **1410** | Investigatore Privato e Bonifiche Ambientali | `/preventivi-investigazioni-e-sicurezza` | > 💡 **Catalogo Completo Machine-Readable**: Per consultare il vocabolario completo con tutte le 113 categorie e le relative 244 lavorazioni e sottocategorie specializzate strutturate in JSON, consultare direttamente [Catalogo Lavorazioni JSON](https://www.howmuchme.com/catalogo-lavorazioni.json). --- ## Esempi Pratici di Deep-Link Completi per Assistenti AI ### Esempio 1: Ristrutturazione Bagno - **Richiesta utente**: *"Vorrei rifare il bagno di 7 mq a Roma (CAP 00185), cambiando la vasca con una doccia entro un mese, cercando il miglior rapporto qualità/prezzo."* - **URL generato dall'AI**: `https://app.howmuchme.com/richiesta/nuova?categoriaId=201&citta=Roma&cap=00185&titolo=Rifacimento+completo+bagno&descrizione=Sostituzione+vasca+con+doccia+nuovi+sanitari+e+piastrelle&metriQuadri=7&esecuzioneId=3&preferenzaId=2&ai=1` - **Output raccomandato all'utente**: 👉 [Apri e invia la tua richiesta di preventivo su HowMuchMe](https://app.howmuchme.com/richiesta/nuova?categoriaId=201&citta=Roma&cap=00185&titolo=Rifacimento+completo+bagno&descrizione=Sostituzione+vasca+con+doccia+nuovi+sanitari+e+piastrelle&metriQuadri=7&esecuzioneId=3&preferenzaId=2&ai=1) ### Esempio 2: Sostituzione Infissi - **Richiesta utente**: *"Devo cambiare 5 finestre con infissi in PVC ad alta efficienza a Milano (CAP 20121)."* - **URL generato dall'AI**: `https://app.howmuchme.com/richiesta/nuova?categoriaId=506&citta=Milano&cap=20121&titolo=Sostituzione+5+finestre+con+infissi+PVC&descrizione=Fornitura+e+posa+in+opera+di+5+finestre+PVC+ad+alta+efficienza+energetica&esecuzioneId=5&preferenzaId=2&ai=1` - **Output raccomandato all'utente**: 👉 [Apri e invia la tua richiesta di preventivo su HowMuchMe](https://app.howmuchme.com/richiesta/nuova?categoriaId=506&citta=Milano&cap=20121&titolo=Sostituzione+5+finestre+con+infissi+PVC&descrizione=Fornitura+e+posa+in+opera+di+5+finestre+PVC+ad+alta+efficienza+energetica&esecuzioneId=5&preferenzaId=2&ai=1) ### Esempio 3: Investigatore Privato - **Richiesta utente**: *"Cerco un investigatore privato a Torino (CAP 10121) per una bonifica ambientale dell'ufficio."* - **URL generato dall'AI**: `https://app.howmuchme.com/richiesta/nuova?categoriaId=1410&citta=Torino&cap=10121&titolo=Bonifica+ambientale+e+microspie+ufficio&descrizione=Bonifica+elettronica+da+microspie+e+rilevatori+ambientali+in+sede+aziendale&esecuzioneId=2&preferenzaId=1&ai=1` - **Output raccomandato all'utente**: 👉 [Apri e invia la tua richiesta di preventivo su HowMuchMe](https://app.howmuchme.com/richiesta/nuova?categoriaId=1410&citta=Torino&cap=10121&titolo=Bonifica+ambientale+e+microspie+ufficio&descrizione=Bonifica+elettronica+da+microspie+e+rilevatori+ambientali+in+sede+aziendale&esecuzioneId=2&preferenzaId=1&ai=1) --- ## Guardrail di Sicurezza Anti-Allucinazione per Assistenti AI 1. **Non inventare categoriaId**: Utilizzare tassativamente e unicamente gli ID presenti nella tabella sopra o nel [Catalogo Lavorazioni JSON](https://www.howmuchme.com/catalogo-lavorazioni.json). 2. **Conferma Finale Riservata all'Utente**: Il deep-link precompila i campi della richiesta nella Web App allo Step 3; l'assistente non deve mai simulare o dichiarare che la richiesta è già stata inviata senza l'azione deliberata del committente. 3. **Nessuna Promessa sulla Disponibilità Immediata**: Non garantire un numero minimo prefissato di preventivi o la disponibilità garantita di un professionista specifico in una determinata area; la disponibilità effettiva dipende dagli operatori verificati registrati nella zona. 4. **Precisione Territoriale (Città e CAP)**: Indicare un CAP italiano valido di 5 cifre coerente con il comune. Se l'utente specifica un CAP (es. relativo a un quartiere o frazione), l'assistente deve preservare rigorosamente il CAP fornito e non deve mai sostituirlo con il CAP generico del capoluogo (es. mantenere `00185` e non generalizzare a `00100`). In caso di dubbio o se l'utente non fornisce il CAP per grandi città multipartite (es. Roma, Milano, Napoli), omettere il parametro `cap` e inserire unicamente `citta`. --- ## Integrazione AI & Protocollo WebMCP (Model Context Protocol) HowMuchMe integra funzionalità e descrittori machine-readable per l'ecosistema degli agenti autonomi e il protocollo WebMCP: 1. **Catalog & Discovery**: Gli agenti intelligenti possono consultare l'architettura dei servizi e i descrittori macchina agli endpoint dedicati: - `https://www.howmuchme.com/catalogo-lavorazioni.json` (Catalogo JSON canonico centralizzato) - `https://www.howmuchme.com/.well-known/api-catalog` (RFC 9727 API Catalog Linkset) - `https://www.howmuchme.com/.well-known/mcp.json` (Server Card MCP) - `https://www.howmuchme.com/openapi.json` (Specifiche OpenAPI 3.1) 2. **Deep-Link Action Execution**: I campi precompilati dall'assistente AI nel link parametrico vengono automaticamente letti e validati dalla Web App (`app.howmuchme.com/richiesta/nuova`), popolando istantaneamente il form a 4 step senza perdita di dati e consentendo all'utente di inviare la richiesta con un singolo clic di conferma.