{
    "openapi": "3.0.3",
    "info": {
        "title": "GPA SERP Proxy — API platform",
        "description": "Micro-services de recherche/prix devant SerpApi (clé serveur, cache BDD, auth, rate limiting).",
        "version": "0.2.0"
    },
    "servers": [
        {
            "url": "https://price.test.gpa07.com"
        }
    ],
    "components": {
        "securitySchemes": {
            "ClientKeyQuery": {
                "type": "apiKey",
                "in": "query",
                "name": "key"
            },
            "ClientKeyHeader": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key"
            }
        }
    },
    "paths": {
        "/api/search": {
            "get": {
                "operationId": "search",
                "summary": "Proxy SerpApi brut (passthrough) + cache BDD.",
                "tags": [
                    "micro-services"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Clé client du proxy (alternative : en-tête X-Api-Key).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Requête de recherche",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "engine",
                        "in": "query",
                        "required": false,
                        "description": "Moteur SerpApi (google, google_shopping, ebay, bing…)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "nocache",
                        "in": "query",
                        "required": false,
                        "description": "Bypass cache (force un appel amont)",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "0",
                                "1"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    },
                    "401": {
                        "description": "Clé client manquante/invalide"
                    },
                    "429": {
                        "description": "Quota dépassé (Retry-After)"
                    },
                    "502": {
                        "description": "Échec amont SerpApi"
                    }
                },
                "security": [
                    {
                        "ClientKeyQuery": []
                    },
                    {
                        "ClientKeyHeader": []
                    }
                ]
            }
        },
        "/api/shopping": {
            "get": {
                "operationId": "shopping",
                "summary": "Pipeline multi-engine (Google Shopping + eBay) : dédoublonnage 3 niveaux + grouping par type de source + fourchette de prix.",
                "tags": [
                    "micro-services"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Clé client du proxy (alternative : en-tête X-Api-Key).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Requête produit (réf OEM + désignation + véhicule)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "gpa_price",
                        "in": "query",
                        "required": false,
                        "description": "Prix GPA (€) → ajoute le positionnement + enregistre un instantané",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "label",
                        "in": "query",
                        "required": false,
                        "description": "Étiquette GPA associée (pour l'historique de positionnement)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "nocache",
                        "in": "query",
                        "required": false,
                        "description": "Bypass cache",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "0",
                                "1"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    },
                    "401": {
                        "description": "Clé client manquante/invalide"
                    },
                    "429": {
                        "description": "Quota dépassé (Retry-After)"
                    },
                    "502": {
                        "description": "Échec amont SerpApi"
                    }
                },
                "security": [
                    {
                        "ClientKeyQuery": []
                    },
                    {
                        "ClientKeyHeader": []
                    }
                ]
            }
        },
        "/api/etiquette": {
            "get": {
                "operationId": "etiquette",
                "summary": "Résout une étiquette GPA (ex. Z1-1937C) → désignation, réf OEM, véhicule (API GPA ou jeu local).",
                "tags": [
                    "micro-services"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Clé client du proxy (alternative : en-tête X-Api-Key).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "required": true,
                        "description": "Identifiant étiquette GPA",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    },
                    "401": {
                        "description": "Clé client manquante/invalide"
                    },
                    "429": {
                        "description": "Quota dépassé (Retry-After)"
                    },
                    "502": {
                        "description": "Échec amont SerpApi"
                    }
                },
                "security": [
                    {
                        "ClientKeyQuery": []
                    },
                    {
                        "ClientKeyHeader": []
                    }
                ]
            }
        },
        "/api/recent": {
            "get": {
                "operationId": "recent",
                "summary": "Liste des dernières recherches en cache (cliquables côté front).",
                "tags": [
                    "micro-services"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Clé client du proxy (alternative : en-tête X-Api-Key).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "mode",
                        "in": "query",
                        "required": false,
                        "description": "all | shopping | search",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Nb max d'entrées (déf. 20)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    },
                    "401": {
                        "description": "Clé client manquante/invalide"
                    },
                    "429": {
                        "description": "Quota dépassé (Retry-After)"
                    },
                    "502": {
                        "description": "Échec amont SerpApi"
                    }
                },
                "security": [
                    {
                        "ClientKeyQuery": []
                    },
                    {
                        "ClientKeyHeader": []
                    }
                ]
            }
        },
        "/api/snapshots": {
            "get": {
                "operationId": "snapshots",
                "summary": "Historique des positionnements prix GPA enregistrés (price_snapshots).",
                "tags": [
                    "micro-services"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Clé client du proxy (alternative : en-tête X-Api-Key).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Nb max d'entrées (déf. 20)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    },
                    "401": {
                        "description": "Clé client manquante/invalide"
                    },
                    "429": {
                        "description": "Quota dépassé (Retry-After)"
                    },
                    "502": {
                        "description": "Échec amont SerpApi"
                    }
                },
                "security": [
                    {
                        "ClientKeyQuery": []
                    },
                    {
                        "ClientKeyHeader": []
                    }
                ]
            }
        },
        "/health": {
            "get": {
                "operationId": "health",
                "summary": "Healthcheck : statut DB, présence clé SerpApi, stats cache, config rate limit.",
                "tags": [
                    "micro-services"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK (champ cache_status: hit|miss)"
                    },
                    "400": {
                        "description": "Paramètre manquant"
                    },
                    "500": {
                        "description": "Erreur interne"
                    }
                }
            }
        }
    }
}