{
  "openapi": "3.1.0",
  "info": {
    "title": "HowMuchMe Preventivi API",
    "description": "Specifiche ufficiali deep-link per la generazione di richieste di preventivo precompilate su HowMuchMe per ristrutturazioni, impianti, casa e servizi in Italia. Endpoint di navigazione web frontend (GET) per interfaccia utente precompilata con conferma umana obbligatoria (Human-in-the-Loop); non supporta invii transazionali automatici senza revisione utente.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "https://app.howmuchme.com",
      "description": "Web App HowMuchMe"
    }
  ],
  "paths": {
    "/richiesta/nuova": {
      "get": {
        "operationId": "precompilaPreventivo",
        "summary": "Genera e apre l'interfaccia Web App precompilata per la richiesta di preventivo",
        "description": "Precompila i campi della richiesta di preventivo gratuito sulla Web App HowMuchMe (Step 3). L'endpoint non crea né invia preventivi transazionalmente in modo headless: apre l'interfaccia utente per consentire al committente di verificare, perfezionare i dati e confermare l'invio finale.",
        "parameters": [
          {
            "name": "categoriaId",
            "in": "query",
            "required": true,
            "description": "ID numerico della lavorazione dal catalogo ufficiale https://www.howmuchme.com/catalogo-lavorazioni.json (es. 201 per Rifacimento Bagno, 506 per Infissi PVC, 601 per Impianto Elettrico, 1002 per App Mobile, 1410 per Investigatore Privato).",
            "schema": {
              "type": "integer",
              "example": 201
            }
          },
          {
            "name": "citta",
            "in": "query",
            "required": false,
            "description": "Nome del comune o città italiana dove eseguire l'intervento.",
            "schema": {
              "type": "string",
              "example": "Roma"
            }
          },
          {
            "name": "cap",
            "in": "query",
            "required": false,
            "description": "Codice di avviamento postale (5 cifre numeriche coerente con la città). Se specificato dall'utente, mantenere il CAP esatto della zona/quartiere senza generalizzarlo a capoluogo.",
            "schema": {
              "type": "string",
              "example": "00185"
            }
          },
          {
            "name": "titolo",
            "in": "query",
            "required": true,
            "description": "Titolo sintetico dell'intervento (max 120 caratteri).",
            "schema": {
              "type": "string",
              "maxLength": 120,
              "example": "Rifacimento completo bagno"
            }
          },
          {
            "name": "descrizione",
            "in": "query",
            "required": true,
            "description": "Descrizione dettagliata delle opere richieste, materiali o particolarità (max 3000 caratteri).",
            "schema": {
              "type": "string",
              "maxLength": 3000,
              "example": "Sostituzione vasca con doccia, sanitari sospesi e nuove piastrelle"
            }
          },
          {
            "name": "metriQuadri",
            "in": "query",
            "required": false,
            "description": "Superficie stimata dell'intervento in mq.",
            "schema": {
              "type": "number",
              "example": 7
            }
          },
          {
            "name": "esecuzioneId",
            "in": "query",
            "required": false,
            "description": "Tempistica desiderata: 1=Urgente (48h), 2=Entro 1 settimana, 3=Entro 1 mese, 4=Entro 3 mesi, 5=Flessibile.",
            "schema": {
              "type": "integer",
              "enum": [1, 2, 3, 4, 5],
              "default": 5,
              "example": 3
            }
          },
          {
            "name": "preferenzaId",
            "in": "query",
            "required": false,
            "description": "Criterio di selezione del professionista: 1=Qualità prima del prezzo, 2=Miglior rapporto qualità/prezzo, 3=Prezzo più basso, 4=Esperienza/Referenze, 5=Prossimità.",
            "schema": {
              "type": "integer",
              "enum": [1, 2, 3, 4, 5],
              "default": 2,
              "example": 2
            }
          },
          {
            "name": "ai",
            "in": "query",
            "required": true,
            "description": "Indicatore che la richiesta è formulata tramite assistente AI.",
            "schema": {
              "type": "integer",
              "enum": [1],
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Interfaccia Web App precompilata (HTML/Frontend) aperta all'utente per revisione e invio finale con conferma umana."
          }
        }
      }
    }
  }
}