[](https://www.api-ka.com)
[](https://www.api-ka.com/doc/)
[](https://www.api-ka.com/doc/api-ka-documentation.pdf)
[](https://www.api-ka.com/docs)
[](https://www.api-ka.com/api/stats)
[](https://www.api-ka.com/api/stats)
[](https://www.api-ka.com/api/stats)
[](https://www.api-ka.com/stats)
[](https://www.api-ka.com/stats)
[](https://www.api-ka.com/health)
[](https://www.api-ka.com/health)
**API·Ka** ([www.api-ka.com](https://www.api-ka.com)) est la **plateforme de données centrale de l'écosystème Groupe KA**. Chaque jour, **11 collecteurs** (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka, job-ka, house-ka, rent-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 **34 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** (~4 460 connecteurs suivis au 2026-08-28 : 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-28)
Instantané de `GET /api/stats` et `GET /health` — les pastilles dynamiques ci-dessus restent à jour en continu.
| Métrique | Valeur |
|---|---|
| Collectes sur 7 jours | **70 / 74 réussies** (4 échecs, rattrapées par le backfill) |
| Enregistrements collectés sur 7 jours | **4 522 761** |
| Appels API sur 7 jours | **5 680** |
| Services collectés | **11** (house-ka et rent-ka intégrés les 2026-08-27/28) |
| Connecteurs supervisés (écosystème) | **4 458** — 4 179 OK · 133 dégradés · 3 en panne · 85 périmés · 58 retirés |
Dernière collecte par service (2026-08-28) :
| Service | Enregistrements | | Service | Enregistrements |
|---|---|---|---|---|
| fabrika | 384 574 | | jobka | 2 297 |
| rentka | 55 241 | | immoka | 36 |
| sortika | 17 168 | | autres* | 0 |
| louka | 7 365 | | **Total du jour** | **466 681** |
Accueil — « Toutes les données KA, centralisées chaque jour »
Le héros de www.api-ka.com : badge « API opérationnelle · M3U96B », réponse live de GET /health (nœud, base, dernières collectes) et compteurs en direct. |
Accueil · 01 — Sources
Les services collectés en cartes : vocation, route /api/v1/{service}, enregistrements historisés et lien vers chaque plateforme Ka. |
Accueil · 02 — Référence des endpoints
Chaque endpoint documenté en place : description, paramètres, extraits curl / Python / JavaScript copiables et bouton « Essayer ». |
Accueil — les endpoints d'historique
/api/v1/{service}/latest et /api/v1/{service}/date/{YYYY-MM-DD} : paramètres requis/optionnels, pagination (limit max 500). |
/stats — la supervision de la plateforme
Appels API, latences moyenne et p95, taux d'erreur, collectes réussies/échouées, enregistrements — filtres de période et rapports PDF (complet, personnalisés). |
/docs — l'API interactive (Swagger, OpenAPI 3.1)
Tous les routeurs (health, auth, runs, monitoring, stats, services, agent…) avec schémas et essais en direct. |
/doc — « Comment fonctionne API·Ka »
Le guide public : vue d'ensemble (collecteurs quotidiens, retry 3× + backfill, backups 90 jours, KA Agent), téléchargeable en PDF. |
/doc — la même page servie sur la route sans barre oblique finale
Le guide reste accessible aux deux chemins (/doc et /doc/). |
/contact — « Nous joindre »
Les trois courriels officiels du Groupe KA (projets/partenariats, médias, légal & Loi 25) et le rappel que la connexion « Se connecter avec KA » est déléguée au hub KA ID. |
Accueil — version mobile (390×844)
Le même héros et le statut /health live, en colonne unique avec la nav mobile v2. |
> 🗄️ Les captures du guide et du Swagger en WebP restent dans [`docs/screenshots/desktop/`](docs/screenshots/desktop/) et [`docs/screenshots/mobile/`](docs/screenshots/mobile/) ; les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
### Nouveautés
- **2026-08-28 — Rent-Ka devient le 11ᵉ service** : collecteur `rentka` (pagination offset/2000 comme lou-ka), table `rentka_data`, supervision des ~680 sources du connecteur au premier run (`6c64acd`).
- **2026-08-27 — House-Ka devient le 10ᵉ service** : collecteur + modèle + CORS + supervision (17 sources) (`eb543c9`).
- **KA Agent v3.2** — **34 outils** (recherche fédérée, annuaires déménageurs/inspecteurs, agences immobilières, 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.
## Rôle central dans l'écosystème
API·Ka est le **système nerveux du Groupe KA**, avec trois missions :
1. **API unifiée des plateformes** — un seul point d'entrée versionné (`/api/v1/{service}`) pour les données quotidiennes historisées des 11 services : mêmes conventions de pagination, mêmes enveloppes JSON, mêmes checksums, quel que soit le service interrogé. C'est ce qui alimente l'app iOS KA, Ka·Stats, les rapports PDF et les intégrations internes.
2. **Superviseur des connecteurs** — la santé des ~4 460 connecteurs de collecte de tout l'écosystème (les sources de lou-ka, immo-ka, rent-ka, etc.) est agrégée ici (`/api/v1/monitoring/connectors`), avec statuts `ok / degraded / broken / stale / retired`, fenêtres de fraîcheur par service et alertes journalisées.
3. **Agent conversationnel central** — le KA Agent répond en langage naturel sur les 13 sites via un seul backend (SSE), en s'appuyant sur les données live des plateformes plutôt que sur la base historisée : ce que l'agent dit est ce que les sites affichent.
## Fonctionnalités
- **11 collecteurs quotidiens** — un par plateforme Ka (Job-Ka intégré le 2026-08-18, House-Ka le 2026-08-27, Rent-Ka le 2026-08-28), 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, houseka, rentka.
- **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 **34 outils** sur les données live des plateformes : logements, propriétés, véhicules, rappels, emplois, épicerie et comparateur de prix, produits et boutiques QC, restos, plats, menus, inspections MAPAQ, sorties, créateurs, recherche web Québec, recherche globale fédérée, suggestions, facettes, fiches détail, estimateurs Vrai-Prix et ValoPlex, annuaires déménageurs/inspecteurs, agences immobilières, historique/coût réel/TAL logement, KA Scores, cartes d'annonces serveur, stats et état des services) + recherche floue en cascade + widget embarquable `GET /ka-agent.js` (v4 : bulle déplaçable, position mémorisée par site, cartes cliquables et boutons de choix), 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, compteurs de connecteurs) ; 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.
## Authentification
Deux façons d'accéder à l'API produit — **aucun secret n'est stocké dans ce repo** :
- **Session KA ID (SSO)** — le bouton « Se connecter avec KA » délègue au hub [groupe-ka.com](https://www.groupe-ka.com) (compte unique de l'écosystème) : `GET /api/auth/ka/login` → callback → session serveur, introspectable via `GET /api/auth/me`.
- **Jeton personnel `kapi_`** — généré (et révocable) sur [groupe-ka.com/compte](https://www.groupe-ka.com/compte), passé en en-tête `Authorization: Bearer kapi_…`. C'est la voie recommandée pour les scripts et intégrations.
- **Endpoints exemptés** (publics sans authentification) : `GET /health`, `GET /api/stats`, la supervision (`/api/v1/runs`, `/api/v1/monitoring/*`), les pages web et le KA Agent (`/api/agent/chat`, `/ka-agent.js`).
- **Apps natives** : `POST /api/ios/auth/exchange` échange le jeton du hub contre une session API (HS256, `aud` ka-ios / ka-android).
- Rate-limit global : 120 req/min.
## API (endpoints principaux)
Référence interactive complète : **Swagger sur [/docs](https://www.api-ka.com/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, compteurs de connecteurs |
| `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, houseka, rentka |
| 🔒 `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 (~4 460 suivis, statuts ok/degraded/broken/stale/retired) |
| `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 + 34 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) + 11 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 (`connector_health` sonde les 11 apps).
- **anthropic** SDK pour le KA Agent.
Collecteurs et cadence :
| Collecteur | Source | Cadence |
|---|---|---|
| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` · `jobka` · `houseka` · `rentka` | 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 # 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` … `RENTKA_SOURCE_URL` (×11) | 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 11 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/ (11), 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 (api, backfill, collectors, connector_health, retry, search, stats)
├── data/ # backups/YYYY-MM-DD/ (rétention 90 jours)
├── logs/ # logs centralisés + alerts.log
├── docs/ # screenshots/ (visite guidée + desktop/mobile WebP) · archive/
└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md
```
## Documentation
- **Guide en ligne** : [www.api-ka.com/doc/](https://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](https://www.api-ka.com/doc/api-ka-documentation.pdf) — la même documentation, téléchargeable.
- **Swagger interactif** : [www.api-ka.com/docs](https://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) |
| 2026-08-25 | **KA Agent v3.2** (33 → 34 outils, cartes serveur `afficher_cartes`, reprise après `max_tokens`) ; widget **ka-agent v4** ; statut `retired` au monitoring ; nav mobile v2 |
| 2026-08-27 | **House-Ka devient le 10ᵉ service** (`eb543c9`) — collecteur, modèle, CORS, supervision (17 sources) |
| 2026-08-28 | **Rent-Ka devient le 11ᵉ service** (`6c64acd`) — collecteur offset/2000, supervision (~680 sources) ; **README v4** + visite guidée en 10 captures |
## 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](https://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`).
```bash
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
| Plateforme | Vocation |
|---|---|
| [groupe-ka.com](https://www.groupe-ka.com) | portail du groupe et compte unique KA ID |
| [lou-ka.com](https://www.lou-ka.com) | logements à louer (Québec) |
| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre (Québec) |
| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière |
| [auto-ka.com](https://www.auto-ka.com) | véhicules |
| [fabri-ka.com](https://www.fabri-ka.com) | produits québécois |
| [food-ka.com](https://www.food-ka.com) | épicerie et alimentation |
| [resto-ka.com](https://www.resto-ka.com) | restaurants |
| [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements |
| [job-ka.com](https://www.job-ka.com) | emplois |
| [crea-ka.com](https://www.crea-ka.com) | créateurs de contenu |
| [trouve-ka.com](https://www.trouve-ka.com) | petites annonces |
| [house-ka.com](https://www.house-ka.com) | maisons à vendre (Canada hors Québec) |
| [rent-ka.com](https://www.rent-ka.com) | loyers (Canada hors Québec) |
| [api-ka.com](https://www.api-ka.com) | API de données *(ce repo)* |
## Contact
**Simon-Pierre Boucher** — fondateur, Groupe KA
📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)
---
© Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai
Ce repo vit sur **spbgit** ([git.spboucher.ai](https://git.spboucher.ai)).
