{
    "name": "GPA SERP Proxy — API platform",
    "description": "Micro-services de recherche/prix devant SerpApi (clé serveur, cache BDD, auth, rate limiting).",
    "base_url": "https://price.test.gpa07.com",
    "auth": {
        "type": "api_key",
        "required": true,
        "query_param": "key",
        "header": "X-Api-Key"
    },
    "rate_limit": {
        "limit": 60,
        "window_s": 60,
        "headers": [
            "X-RateLimit-Limit",
            "X-RateLimit-Remaining",
            "X-RateLimit-Reset"
        ]
    },
    "services": [
        {
            "id": "search",
            "method": "GET",
            "path": "/api/search",
            "auth": true,
            "summary": "Proxy SerpApi brut (passthrough) + cache BDD.",
            "params": [
                {
                    "name": "q",
                    "type": "string",
                    "required": true,
                    "desc": "Requête de recherche"
                },
                {
                    "name": "engine",
                    "type": "string",
                    "required": false,
                    "desc": "Moteur SerpApi (google, google_shopping, ebay, bing…)"
                },
                {
                    "name": "nocache",
                    "type": "0|1",
                    "required": false,
                    "desc": "Bypass cache (force un appel amont)"
                }
            ],
            "example": "/api/search?q=iphone+15&engine=google",
            "try": "/"
        },
        {
            "id": "shopping",
            "method": "GET",
            "path": "/api/shopping",
            "auth": true,
            "summary": "Pipeline multi-engine (Google Shopping + eBay) : dédoublonnage 3 niveaux + grouping par type de source + fourchette de prix.",
            "params": [
                {
                    "name": "q",
                    "type": "string",
                    "required": true,
                    "desc": "Requête produit (réf OEM + désignation + véhicule)"
                },
                {
                    "name": "gpa_price",
                    "type": "number",
                    "required": false,
                    "desc": "Prix GPA (€) → ajoute le positionnement + enregistre un instantané"
                },
                {
                    "name": "label",
                    "type": "string",
                    "required": false,
                    "desc": "Étiquette GPA associée (pour l'historique de positionnement)"
                },
                {
                    "name": "nocache",
                    "type": "0|1",
                    "required": false,
                    "desc": "Bypass cache"
                }
            ],
            "example": "/api/shopping?q=620905715R+pompe+ABS+Renault",
            "doc": "/docs/serpapi-algo-dedup-ebay.md",
            "try": "/etiquette"
        },
        {
            "id": "etiquette",
            "method": "GET",
            "path": "/api/etiquette",
            "auth": true,
            "summary": "Résout une étiquette GPA (ex. Z1-1937C) → désignation, réf OEM, véhicule (API GPA ou jeu local).",
            "params": [
                {
                    "name": "code",
                    "type": "string",
                    "required": true,
                    "desc": "Identifiant étiquette GPA"
                }
            ],
            "example": "/api/etiquette?code=Z1-1937C",
            "try": "/etiquette"
        },
        {
            "id": "recent",
            "method": "GET",
            "path": "/api/recent",
            "auth": true,
            "summary": "Liste des dernières recherches en cache (cliquables côté front).",
            "params": [
                {
                    "name": "mode",
                    "type": "string",
                    "required": false,
                    "desc": "all | shopping | search"
                },
                {
                    "name": "limit",
                    "type": "integer",
                    "required": false,
                    "desc": "Nb max d'entrées (déf. 20)"
                }
            ],
            "example": "/api/recent?mode=shopping&limit=15"
        },
        {
            "id": "snapshots",
            "method": "GET",
            "path": "/api/snapshots",
            "auth": true,
            "summary": "Historique des positionnements prix GPA enregistrés (price_snapshots).",
            "params": [
                {
                    "name": "limit",
                    "type": "integer",
                    "required": false,
                    "desc": "Nb max d'entrées (déf. 20)"
                }
            ],
            "example": "/api/snapshots?limit=20",
            "try": "/etiquette"
        },
        {
            "id": "health",
            "method": "GET",
            "path": "/health",
            "auth": false,
            "summary": "Healthcheck : statut DB, présence clé SerpApi, stats cache, config rate limit.",
            "params": [],
            "example": "/health"
        }
    ]
}