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.

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

# Visite guidée

Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900).

www.api-ka.com/doc — le guide public de l'API (desktop)	Guide — version mobile
/docs — l'API interactive (OpenAPI)

# Nouveautés (2026-08-25)

• KA Agent v3.2 — 33 outils (recherche fédérée, annuaires déménageurs/inspecteurs, historique/coût réel/TAL logement, ValoPlex, KA Scores) ; cartes d'annonces construites côté serveur (afficher_cartes), lien public lien_fiche sur chaque résultat, reprise automatique après coupure max_tokens.
• Widget ka-agent v4 servi aux 13 domaines — cartes cliquables (ka-card) et choix en boutons (ka-choix).
• Monitoring des connecteurs — statut retired pour les sources désactivées ou disparues.
• Nav mobile v2 sur les pages web.

🗄️ Les captures d'époque sont conservées dans docs/archive/.

# 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.

# 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 :

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

# Démarrage rapide

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) :

# 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

/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

# 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).

pm2 restart apika-api                            # après un changement en production

# Déploiement

• Nœud : M3U96b (Mac Studio, cluster MacLustr) — répertoire /opt/api-ka (hostname vérifié au démarrage)
• Port : 8000 (API liée à 127.0.0.1, exposée uniquement via le tunnel)
• Processus PM2 : apika-api (API) + apika-scheduler (collectes) + apika-ngrok (tunnel)
• Domaine : https://www.api-ka.com (tunnel ngrok)

# Écosystème Groupe KA

# Contact

Simon-Pierre Boucher — fondateur, Groupe KA 📧 contact@spboucher.ai

© Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai Ce repo vit sur spbgit (git.spboucher.ai).