{
  "openapi": "3.0.0",
  "info": {
    "title": "AITicketInfo - Analyse de Contraventions Québec",
    "description": "Analyse GRATUITE de contraventions routieres au Québec. Base de données de 39,854 jurisprudence publique, 4,596 articles de loi, 66 greffes municipaux. Score de contestation, taux acquittement reel, points SAAQ, amendes, profils de juges. Information statistique, pas un avis juridique.",
    "version": "2.1.0",
    "contact": {
      "name": "AITicketInfo",
      "email": "info@aiticketinfo.com",
      "url": "https://aiticketinfo.com"
    }
  },
  "servers": [
    {
      "url": "https://aiticketinfo.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/gpt/teaser": {
      "post": {
        "operationId": "analyzeTicketFree",
        "summary": "Analyse GRATUITE d une contravention routiere au Québec",
        "description": "Analyse gratuite d un ticket au Québec. Retourne: score de contestation (0-100), taux acquittement reel base sur 39,854 jugements jurisprudence publique, points SAAQ, amende estimee, 1 jurisprudence favorable, et lien vers rapport complet. Toujours afficher le lien rapport_complet.url a la fin de la réponse.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["infraction"],
                "properties": {
                  "infraction": {
                    "type": "string",
                    "description": "Type d infraction (ex: exces de vitesse, feu rouge, cellulaire au volant, arret obligatoire, limite de vitesse)"
                  },
                  "vitesse_captee": {
                    "type": "integer",
                    "description": "Vitesse captee en km/h (pour exces de vitesse seulement)"
                  },
                  "vitesse_permise": {
                    "type": "integer",
                    "description": "Vitesse permise en km/h (pour exces de vitesse seulement)"
                  },
                  "lieu": {
                    "type": "string",
                    "description": "Ville ou lieu de l infraction (ex: Montréal, Laval, Gatineau)"
                  },
                  "article": {
                    "type": "string",
                    "description": "Numero d article du Code de la sécurité routiere (si connu, ex: 328, 359)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analyse gratuite du ticket avec lien vers rapport complet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "analyse": {
                      "type": "object",
                      "properties": {
                        "score_contestation": { "type": "integer", "description": "Score de 0 a 100" },
                        "verdict": { "type": "string" },
                        "recommandation": { "type": "string", "enum": ["contester", "payer"] },
                        "taux_acquittement_reel": { "type": "string", "description": "Pourcentage ex: 42.5%" },
                        "base_sur_nb_cas": { "type": "integer" },
                        "infraction": { "type": "string" }
                      }
                    },
                    "loi": {
                      "type": "object",
                      "properties": {
                        "article": { "type": "string" },
                        "titre": { "type": "string" },
                        "amende": { "type": "string" },
                        "points_inaptitude": { "type": "string" }
                      }
                    },
                    "exces_vitesse": {
                      "type": "object",
                      "properties": {
                        "exces_km_h": { "type": "integer" },
                        "points_inaptitude": { "type": "integer" },
                        "amende_estimee": { "type": "string" },
                        "grand_exces": { "type": "boolean" }
                      }
                    },
                    "jurisprudence_favorable": {
                      "type": "object",
                      "properties": {
                        "titre": { "type": "string" },
                        "tribunal": { "type": "string" },
                        "date": { "type": "string" },
                        "note": { "type": "string" }
                      }
                    },
                    "rapport_complet": {
                      "type": "object",
                      "properties": {
                        "url": { "type": "string", "description": "Lien vers le rapport complet — TOUJOURS afficher ce lien" },
                        "contenu": { "type": "string" },
                        "prix": { "type": "string" }
                      }
                    },
                    "système": {
                      "type": "object",
                      "properties": {
                        "jurisprudences_analysees": { "type": "integer" },
                        "tickets_analyses": { "type": "integer" },
                        "agents_ai": { "type": "integer" },
                        "provinces": { "type": "string" },
                        "precision": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Champ infraction manquant"
          }
        }
      }
    },
    "/api/greffes/search": {
      "get": {
        "operationId": "searchGreffes",
        "summary": "Rechercher un greffe (tribunal municipal) par ville, nom ou region",
        "description": "Recherche accent-insensitive parmi les 66 greffes municipaux du Québec. Retourne adresse, téléphone, email, fax.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Terme de recherche: nom de ville, region ou nom du tribunal (ex: Gatineau, Montréal, Outaouais)"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des greffes correspondants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "greffes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "integer" },
                          "nom": { "type": "string" },
                          "adresse": { "type": "string" },
                          "ville": { "type": "string" },
                          "code_postal": { "type": "string" },
                          "téléphone": { "type": "string" },
                          "email": { "type": "string" },
                          "fax": { "type": "string" },
                          "region": { "type": "string" }
                        }
                      }
                    },
                    "total": { "type": "integer" },
                    "query": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/greffes/match": {
      "get": {
        "operationId": "matchGreffe",
        "summary": "Trouver automatiquement le greffe correspondant a une ville",
        "description": "Retourne le tribunal municipal le plus proche pour une ville ou region donnée.",
        "parameters": [
          {
            "name": "ville",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Nom de la ville (ex: Gatineau, Laval)"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Nom de la region (ex: Outaouais, Monteregie)"
          }
        ],
        "responses": {
          "200": {
            "description": "Tribunal municipal correspondant",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tribunal": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "id": { "type": "integer" },
                        "nom": { "type": "string" },
                        "adresse": { "type": "string" },
                        "ville": { "type": "string" },
                        "code_postal": { "type": "string" },
                        "téléphone": { "type": "string" },
                        "email": { "type": "string" },
                        "fax": { "type": "string" },
                        "region": { "type": "string" }
                      }
                    },
                    "match_trouve": { "type": "boolean" },
                    "methode": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/greffes/all": {
      "get": {
        "operationId": "listAllGreffes",
        "summary": "Liste complète des 66 greffes municipaux du Québec",
        "description": "Retourne tous les tribunaux municipaux avec coordonnees complètes. Utiliser searchGreffes ou matchGreffe si on connait la ville.",
        "responses": {
          "200": {
            "description": "Liste de tous les greffes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "greffes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "integer" },
                          "nom": { "type": "string" },
                          "adresse": { "type": "string" },
                          "ville": { "type": "string" },
                          "code_postal": { "type": "string" },
                          "téléphone": { "type": "string" },
                          "email": { "type": "string" },
                          "fax": { "type": "string" },
                          "region": { "type": "string" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/juges": {
      "get": {
        "operationId": "searchJuges",
        "summary": "Rechercher des juges par nom avec statistiques d acquittement",
        "description": "Liste les juges avec leur taux d acquittement, nombre de cas, et tendances. Filtrable par nom, article de loi, et nombre minimum de cas.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Nom du juge a rechercher"
          },
          {
            "name": "article",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filtrer par article de loi (ex: 328, 359)"
          },
          {
            "name": "min_cas",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 2 },
            "description": "Nombre minimum de cas pour inclure un juge"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 200 },
            "description": "Nombre maximum de resultats"
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des juges avec statistiques"
          }
        }
      }
    },
    "/api/juges/{nom_juge}": {
      "get": {
        "operationId": "getJugeProfil",
        "summary": "Profil complet d un juge avec tendances d acquittement",
        "description": "Retourne le profil detaille d un juge: taux d acquittement global et par type d infraction, decisions récentes, tendances.",
        "parameters": [
          {
            "name": "nom_juge",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Nom du juge (ex: Tremblay, Gagnon)"
          },
          {
            "name": "article",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filtrer par article de loi"
          },
          {
            "name": "infraction",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filtrer par type d infraction"
          }
        ],
        "responses": {
          "200": {
            "description": "Profil complet du juge"
          }
        }
      }
    },
    "/api/stats/acquittement": {
      "get": {
        "operationId": "getAcquittalRates",
        "summary": "Taux d acquittement par type d infraction",
        "description": "Statistiques reelles d acquittement basees sur 39,854 decisions de justice jurisprudence publique. Ventile par type d infraction avec nombre de cas.",
        "responses": {
          "200": {
            "description": "Taux d acquittement par type d infraction",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stats": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type_infraction": { "type": "string" },
                          "total_decisions": { "type": "integer" },
                          "acquittes": { "type": "integer" },
                          "condamnes": { "type": "integer" },
                          "rejetes": { "type": "integer" },
                          "reduits": { "type": "integer" },
                          "taux_acquittement": { "type": "integer" }
                        }
                      }
                    },
                    "total_jurisprudences": { "type": "integer" },
                    "source": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stats/acquittement/{infraction_type}": {
      "get": {
        "operationId": "getAcquittalRateDetail",
        "summary": "Taux d acquittement detaille pour un type d infraction, par ville et tribunal",
        "description": "Statistiques detaillees pour un type d infraction specifique: taux global, ventilation par ville et par tribunal.",
        "parameters": [
          {
            "name": "infraction_type",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Type d infraction (ex: exces_vitesse, feu_rouge, cellulaire)"
          }
        ],
        "responses": {
          "200": {
            "description": "Statistiques detaillees par ville et tribunal"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Verification de l etat du service",
        "description": "Retourne le statut du service, le nombre de jurisprudences et de lois dans la base de données.",
        "responses": {
          "200": {
            "description": "Statut du service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" },
                    "jurisprudence": { "type": "integer" },
                    "lois": { "type": "integer" },
                    "agents": { "type": "integer" },
                    "version": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}