API·Ka

La donnée de l'écosystème, par API

API·Ka (www.api-ka.com) est la plateforme de données centrale de l'écosystème Groupe KA. Chaque jour, 9 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka, job-ka) sauvegardent les données des plateformes dans une base PostgreSQL unifiée (fetch → validation → checksum → insertion → backup → journal de run, retry 3× avec backoff 30 s → 2 min → 10 min), puis les exposent via une API FastAPI publique : données paginées, historiques par date, statistiques, rapports PDF.

Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku 4.5, SSE, boucle de 24 outils branchés sur les API publiques des plateformes) servi en widget (/ka-agent.js) aux 13 domaines de l'écosystème — et sert de superviseur des connecteurs (~3 270 connecteurs suivis au 2026-08-24 : historique des collectes /api/v1/runs, santé par service, alertes). L'accès à l'API produit exige une authentification : session KA ID ou jeton personnel (kapi_, généré sur groupe-ka.com/compte).

# Chiffres live (au 2026-08-24)

Instantané de GET /api/stats et GET /health — les pastilles dynamiques ci-dessus restent à jour en continu.

Métrique	Valeur
Collectes sur 7 jours	63 / 63 réussies (0 échec)
Enregistrements collectés sur 7 jours	4 158 204
Enregistrements de la collecte du jour (9 services)	663 770
Appels API sur 7 jours	6 196
Connecteurs supervisés (écosystème)	3 271 — 3 098 OK · 169 dégradés · 3 en panne · 1 périmé

Dernière collecte par service (2026-08-24) :

Service	Enregistrements	Service	Enregistrements
fabrika	385 061	autoka	48 446
immoka	67 702	jobka	21 492
foodka	50 936	sortika	17 147
louka	45 479	restoka	14 716
creaka	12 791	Total	663 770

# Visite guidée

_{Accueil — le site de documentation de l'API (desktop)}	_{Accueil — version mobile}
_{Étape 1 · Explorez le site de documentation}	_{Étape 2 · Parcourez l'API dans Swagger (/docs)}
_{Étape 3 · Surveillez les collectes sur /stats}

# Fonctionnalités

9 collecteurs quotidiens — un par plateforme Ka (Job-Ka intégré le 2026-08-18), avec validation, checksum, retry 3× (backoff exponentiel) et journal de run ; tout échec après 3 tentatives est loggé (collection_runs, logs/alerts.log).
Scheduler APScheduler — job quotidien à 02:00 (collecteurs en parallèle et indépendants) + backfill automatique des dates manquées (7 derniers jours).
API publique de données — GET /api/v1/{service} (pagination, limit max 500), /latest, /date/{YYYY-MM-DD}, /stats, /api/v1/runs (historique des collectes), pour {service} ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka.
Authentification obligatoire sur l'API produit — session KA ID ou jeton Bearer kapi_ ; monitoring, stats et agent restent ouverts.
KA Agent (IA) — POST /api/agent/chat en SSE (Claude Haiku 4.5, boucle de 24 outils sur les données live des plateformes : logements, propriétés, véhicules, emplois, épicerie, produits, restos, plats, menus, inspections MAPAQ, sorties, créateurs, juste prix, estimateur Vrai-Prix, boutiques, suggestions, facettes, stats, état des services) + recherche floue en cascade + widget embarquable GET /ka-agent.js (v3 : bulle déplaçable, position mémorisée par site), CORS ouvert aux 13 domaines.
SSO KA ID — GET /api/auth/ka/{login,callback}, session /api/auth/me, et échange de jeton pour les apps natives (POST /api/ios/auth/exchange, vérification HS256, aud ∈ ka-ios, ka-android).
Stats & rapports — tableau de bord /stats, GET /api/stats (KPI compact JSON), GET /api/stats/report (PDF de la plateforme) et GET /api/stats/ecosystem-report (rapport PDF consolidé de l'écosystème, liste dynamique via ecosystem.json) + rapports PDF personnalisés (catalogue + constructeur).
Recherche transversale — GET /api/v1/search + GET /api/v1/suggest (proxy du moteur Trouve-Ka, pivot moteur de recherche Groupe KA).
Backups quotidiens horodatés par service (data/backups/YYYY-MM-DD/, rétention 90 jours).
Santé & supervision — GET /health (nœud, état DB, dernière collecte par service) ; chaque service vérifie le hostname au démarrage et refuse de tourner en production ailleurs que sur m3u96b.
SEO du site de doc — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.

# API (endpoints principaux)

Référence interactive complète : Swagger sur /docs. 🔒 = session KA ID ou jeton Bearer kapi_ requis.

Méthode & endpoint	Description
`GET /health`	santé : nœud, état DB, dernière collecte par service
`GET /api/stats`	KPI compact JSON : collectes 7 j, enregistrements, appels API, connecteurs (alimente les pastilles ci-dessus)
🔒 `GET /api/v1/{service}`	données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka
🔒 `GET /api/v1/{service}/latest`	dernière collecte du service
🔒 `GET /api/v1/{service}/date/{YYYY-MM-DD}`	collecte d'une date précise
🔒 `GET /api/v1/{service}/stats`	statistiques du service
🔒 `GET /api/v1/louka/fairvalue/{uid}`	juste prix d'une annonce Lou·Ka (proxy live, utilisé par l'app iOS KA)
`GET /api/v1/runs`	historique des runs de collecte (supervision)
`GET /api/v1/monitoring/connectors` · `/connectors/{service}`	santé des connecteurs de l'écosystème (~3 270 suivis)
`GET /api/stats/dashboard` · `/report` · `/catalog` · `POST /api/stats/report/custom`	tableau de bord + rapports PDF (catalogue, personnalisés)
`GET /api/stats/ecosystem-report`	rapport PDF consolidé des 13 plateformes
`POST /api/agent/chat` (SSE) · `GET /ka-agent.js`	KA Agent (Claude Haiku 4.5 + 24 outils live) et son widget embarquable
`GET /api/v1/search` · `GET /api/v1/suggest`	recherche transversale (incl. recherche floue) et suggestions — proxy Trouve-Ka
`GET /api/auth/config` · `/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout`	SSO KA ID
`POST /api/ios/auth/exchange`	échange de jeton pour les apps natives (`aud` ka-ios / ka-android)

# Architecture

FastAPI + Uvicorn (src/api/) : 9 routeurs (health, auth, runs, monitoring, stats, search, services, agent, iosauth) + pages web et PDF (fpdf2).
PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, psycopg2) : une table de données par service ({service}_data) + journal collection_runs.
Collecteurs (src/collectors/) : classe abstraite base_collector (fetch, validate, save, retry) + 9 collecteurs concrets, httpx.
Scheduler (src/scheduler/) : daily_job.py (02:00) + backfill.py.
Utils (src/utils/) : backups quotidiens, rétention 90 jours ; src/monitoring/ pour la supervision.
anthropic SDK pour le KA Agent.

Collecteurs et cadence :

Collecteur	Source	Cadence
`louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` · `jobka`	API publique de chaque plateforme Ka (`{SERVICE}_SOURCE_URL`)	quotidien 02:00 (parallèle, indépendants)
backfill	dates manquées des 7 derniers jours	au démarrage du job quotidien
backups	dump horodaté par service (`data/backups/YYYY-MM-DD/`)	quotidien, rétention 90 jours

Processus PM2 sur le nœud (commandes de start réelles) :

Processus	Commande	Rôle
`apika-api`	`venv/bin/uvicorn src.api.main:app --host 127.0.0.1 --port 8000`	l'API FastAPI/Uvicorn sur le port 8000 (liée à 127.0.0.1)
`apika-scheduler`	`venv/bin/python -m src.scheduler.daily_job`	le job quotidien 02:00 + backfill
`apika-ngrok`	`ngrok http --domain=www.api-ka.com 8000 --log stdout`	tunnel vers www.api-ka.com

# Démarrage rapide

bash

git clone gitsrv:api-ka.git && cd api-ka
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                             # puis remplir les valeurs

python -m src.database.db --init                 # initialiser la base PostgreSQL
uvicorn src.api.main:app --reload --port 8000    # API en dev → http://127.0.0.1:8000
python -m src.scheduler.daily_job --now          # collecte manuelle immédiate
python -m src.scheduler.backfill --date 2026-08-15
pytest tests/ -v                                 # 8 modules de tests (api, collectors, retry, backfill, search, stats, connector_health)

# Variables d'environnement

Déclarées dans .env.example (copier vers .env, jamais commité — aucun secret dans le repo) :

Variable	Rôle
`APP_ENV` · `NODE_NAME`	environnement + garde-fou de hostname (`m3u96b` en prod)
`DATABASE_URL`	connexion PostgreSQL (SQLAlchemy)
`API_PORT` · `RATE_LIMIT_PER_MINUTE`	port de l'API (8000) et rate-limit
`DAILY_RUN_HOUR` · `BACKUP_RETENTION_DAYS`	heure du job quotidien (02) et rétention des backups (90)
`NGROK_AUTHTOKEN` · `NGROK_DOMAIN`	tunnel ngrok (www.api-ka.com)
`LOUKA_SOURCE_URL` … `JOBKA_SOURCE_URL` (×9)	URL source de chaque collecteur
`TROUVEKA_SEARCH_URL` · `TROUVEKA_SUGGEST_URL`	proxy du moteur de recherche Trouve-Ka
`KA_HUB_URL` · `KA_SSO_SECRET` · `KA_IOS_SSO_SECRET` · `SESSION_SECRET`	SSO KA ID (hub groupe-ka.com) + sessions
`ANTHROPIC_API_KEY`	clé du KA Agent (lue par le SDK anthropic)
`APIKA_BASE_URL`	base URL publique de l'API

# Données & conformité

Provenance : les données proviennent exclusivement des API publiques des 9 plateformes Ka (aucun scraping tiers dans ce repo) ; chaque enregistrement passe par validation + checksum avant insertion.
Cadence : resynchronisation quotidienne à 02:00 (collecteurs parallèles) + backfill automatique des 7 derniers jours ; backups quotidiens horodatés, rétention 90 jours.
Accès : l'API produit exige une authentification (session KA ID ou jeton kapi_ révocable sur groupe-ka.com/compte) ; monitoring, stats et agent restent publics ; rate-limit 120 req/min.
Traçabilité : chaque run de collecte est journalisé (collection_runs, exposé via /api/v1/runs) ; alertes dans logs/alerts.log.

# Structure du repo

text

/opt/api-ka
├── src/          # api/ (routes, web, PDF), collectors/ (9), scheduler/, database/, monitoring/, utils/, config.py
├── scripts/      # deploy_m3u96b.sh, healthcheck.sh, run_daily_backup.sh, start_ngrok.sh…
├── systemd/      # unités historiques (le déploiement actuel utilise PM2)
├── tests/        # pytest (8 modules)
├── data/         # backups/YYYY-MM-DD/ (rétention 90 jours)
├── logs/         # logs centralisés + alerts.log
├── docs/         # captures d'écran
└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md

# Documentation

Guide en ligne : www.api-ka.com/doc/ — à quoi sert la plateforme, le parcours en 3 étapes (site de doc → Swagger /docs → supervision /stats), d'où viennent les données, FAQ.
Guide PDF : api-ka-documentation.pdf — la même documentation, téléchargeable.
Swagger interactif : www.api-ka.com/docs — tous les endpoints, schémas et essais en direct.
Les captures du guide sont versionnées dans src/api/web/doc/img/ (etape1 → etape3).

# Historique

Date	Jalon
2026-08-17	naissance de la plateforme : collecte quotidienne des 8 services KA + API publique (`d8b3b82`), design Groupe KA + SSO KA ID, page `/stats`, rapport écosystème PDF, KA Agent v1 (Claude Haiku, SSE, 12 outils, CORS 13 domaines)
2026-08-18	Job-Ka devient le 9ᵉ service (collecteur + supervision, `609d6bb`) ; supervision centralisée des connecteurs de l'écosystème ; auth mobile ka-ios/ka-android
2026-08-19	KA Agent v2 : 24 outils + recherche floue en cascade + widget v2 (`e548e0d`) ; socle mobile (anti-zoom 16 px)
2026-08-22	ka-agent v3 : bulle déplaçable, position mémorisée par site ; standard header KA
2026-08-23	authentification obligatoire sur l'API produit (KA ID / jeton `kapi_`, `99ebb9e`) ; stats v3 (rapports PDF personnalisés) ; recherche `/api/v1/search` (proxy Trouve-Ka) ; SEO complet ; monitoring affiné (fenêtre 6 h, sources vides ≠ pannes)
2026-08-24	page documentation `/doc` + guide PDF ; README v2 puis v3 (chiffres live, pastilles dynamiques)

# Développement (remote-first)

La source de vérité est le repo git sur le nœud M3U96b (/opt/api-ka) — on n'édite jamais les copies laptop. Toute modification se fait sur le nœud via SSH : édition, tests, pm2 restart, puis commit/push depuis le nœud.

Remote origin = spbgit (git perso git.spboucher.ai, bare repos sur M3U96a). Pas GitHub.
L'agent forwarding SSH est actif : le git push origin main fonctionne pendant une session SSH depuis le laptop.
Chaque fichier du dépôt porte l'en-tête d'auteur obligatoire (voir CLAUDE.md).