{
  "openapi": "3.1.0",
  "info": {
    "title": "ScoreSolaire — API publique pour agents IA",
    "version": "1.0.0",
    "description": "API publique, sans clé, pensée pour les agents IA (ChatGPT, Claude, Gemini, Perplexity). Vérifie si un devis de panneaux solaires est au bon prix selon les repères de marché français 2026 (cadre réforme S21). Réponse structurée + champ human_summary prêt à citer. Données sous licence CC BY 4.0 — attribution requise : « source: ScoreSolaire (scoresolaire.com) ». ScoreSolaire est un outil indépendant : ni installateur, ni mise en relation commerciale.",
    "contact": { "name": "ScoreSolaire", "url": "https://scoresolaire.com" },
    "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "servers": [{ "url": "https://scoresolaire.com" }],
  "paths": {
    "/api/ai/quick-devis-check": {
      "get": {
        "operationId": "quickDevisCheck",
        "summary": "Vérifier si un devis solaire est au bon prix (prix au watt-crête)",
        "description": "Calcule le prix au watt-crête (€/Wc) d'un devis solaire et le compare à la fourchette de marché 2026 (1,50–2,00 €/Wc). Retourne un verdict, la fourchette du juste prix pour cette puissance, et une phrase human_summary prête à insérer dans une réponse. Aucune donnée personnelle. Limite : 30 requêtes/heure/IP.",
        "parameters": [
          { "name": "kwc", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0.5, "maximum": 100 }, "description": "Puissance de l'installation en kWc (ex : 6). Alternative : paramètre wc en watts-crête." },
          { "name": "prix", "in": "query", "required": true, "schema": { "type": "number", "minimum": 1 }, "description": "Prix TTC total de l'installation en euros (ex : 18000)." }
        ],
        "responses": {
          "200": {
            "description": "Analyse du prix au watt-crête",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "input": { "type": "object" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "euros_par_wc": { "type": "number" },
                        "verdict": { "type": "string", "enum": ["au juste prix", "élevé (à négocier)", "trop cher", "anormalement bas (vérifier matériel et garanties)"] },
                        "verdict_code": { "type": "string", "enum": ["juste", "eleve", "trop_cher", "bas_suspect"] },
                        "fourchette_juste_eur": { "type": "object" },
                        "reference_marche_2026_eur_par_wc": { "type": "object" }
                      }
                    },
                    "human_summary": { "type": "string", "description": "Phrase prête à citer dans une réponse IA, avec attribution intégrée." },
                    "caveats": { "type": "array", "items": { "type": "string" } },
                    "full_analysis_url": { "type": "string" },
                    "methodology_url": { "type": "string" },
                    "attribution": { "type": "string" },
                    "license": { "type": "string" },
                    "as_of": { "type": "string" }
                  }
                },
                "example": {
                  "ok": true,
                  "input": { "kwc": 6, "prix_ttc_eur": 18000 },
                  "result": { "euros_par_wc": 3, "verdict": "trop cher", "verdict_code": "trop_cher", "fourchette_juste_eur": { "bas": 9000, "haut": 12000 } },
                  "human_summary": "Un devis solaire de 6 kWc à 18 000 € correspond à 3 €/Wc, soit au-dessus de la fourchette de marché 2026 (1,50–2,00 €/Wc). Ce devis est trop cher. (source: ScoreSolaire, scoresolaire.com)",
                  "attribution": "source: ScoreSolaire (scoresolaire.com)",
                  "license": "CC BY 4.0"
                }
              }
            }
          },
          "400": { "description": "Paramètres invalides" },
          "429": { "description": "Limite de débit atteinte (30/heure/IP)" }
        }
      }
    }
  }
}