docs: README v2 — galerie multi-pages, style du site, documentation, contact · 9debd68 · api-ka

1

1

2

3

−# API·Ka

3

+

4

−

4

+ <a href="https://www.api-ka.com"><img src="https://www.api-ka.com/og.png" width="760" alt="API·Ka — La donnée de l'écosystème, par API"></a>

5

−**L'API centrale du Groupe KA : collecte quotidienne des données des plateformes de l'écosystème, base PostgreSQL unifiée, API publique et KA Agent (IA).**

5

+

6

−

6

+<h1 align="center">API·Ka</h1>

7

−[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com)](https://www.api-ka.com)

7

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

8

−![Nœud](https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square)

9

−![Port](https://img.shields.io/badge/port-8000-141814?style=flat-square)

10

−![PM2](https://img.shields.io/badge/process-PM2-2b037a?style=flat-square)

11

8

12

−![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)

9

+

13

−![FastAPI](https://img.shields.io/badge/FastAPI-API-009688?style=flat-square&logo=fastapi&logoColor=white)

10

+ <a href="https://www.api-ka.com"><img src="https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com&up_color=3b5bdb&up_message=en%20ligne" alt="Site"></a>

14

−![PostgreSQL](https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white)

11

+ <a href="https://www.api-ka.com/doc/"><img src="https://img.shields.io/badge/📖_documentation-%2Fdoc-3b5bdb?style=flat-square" alt="Documentation"></a>

15

−![APScheduler](https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square)

12

+ <a href="https://www.api-ka.com/doc/api-ka-documentation.pdf"><img src="https://img.shields.io/badge/guide-PDF-3b5bdb?style=flat-square" alt="PDF"></a>

16

−![Groupe KA](https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square)

13

+ <img src="https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square" alt="Nœud">

14

+ <img src="https://img.shields.io/badge/port-8000-141814?style=flat-square" alt="Port">

15

+ <img src="https://img.shields.io/badge/process-PM2-2b037a?style=flat-square" alt="PM2">

16

+

17

+

18

+ <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">

19

+ <img src="https://img.shields.io/badge/FastAPI-API-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI">

20

+ <img src="https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL">

21

+ <img src="https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square" alt="APScheduler">

22

+ <img src="https://img.shields.io/badge/Groupe-KA-3b5bdb?style=flat-square" alt="Groupe KA">

23

+

17

24

18

**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, **8 collecteurs** (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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.

25

**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, **8 collecteurs** (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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.

19

26

20

Elle héberge aussi le **KA Agent** — l'assistant IA central du groupe (Claude Haiku, SSE, boucle d'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** (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).

27

Elle héberge aussi le **KA Agent** — l'assistant IA central du groupe (Claude Haiku, SSE, boucle d'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** (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).

21

28

22

−## Captures d'écran

29

+## Visite guidée

23

−

30

+

24

−

31

+<table>

25

− <img src="docs/screenshots/api-ka-desktop.png" width="640" alt="Accueil — desktop">

32

+ <tr>

26

− <img src="docs/screenshots/api-ka-mobile.png" width="200" alt="Accueil — mobile">

33

+ <td align="center"><img src="docs/screenshots/api-ka-desktop.png" width="420"> Accueil — le site de documentation de l'API (desktop)</td>

27

−

34

+ <td align="center"><img src="docs/screenshots/api-ka-mobile.png" width="220"> Accueil — version mobile</td>

35

+ </tr>

36

+ <tr>

37

+ <td align="center"><img src="src/api/web/doc/img/etape1.png" width="420"> Étape 1 · Explorez le site de documentation</td>

38

+ <td align="center"><img src="src/api/web/doc/img/etape2.png" width="420"> Étape 2 · Parcourez l'API dans Swagger (/docs)</td>

39

+ </tr>

40

+ <tr>

41

+ <td align="center" colspan="2"><img src="src/api/web/doc/img/etape3.png" width="420"> Étape 3 · Surveillez les collectes sur /stats</td>

42

+ </tr>

43

+</table>

28

44

29

## Fonctionnalités

45

## Fonctionnalités

30

46

39

- **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`.

55

- **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`.

40

- **SEO du site de doc** — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.

56

- **SEO du site de doc** — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.

41

57

58

+## API (endpoints principaux)

59

+

60

+Référence interactive complète : **Swagger sur [/docs](https://www.api-ka.com/docs)**. 🔒 = session KA ID ou jeton Bearer `kapi_` requis.

61

+

62

+| Endpoint | Rôle |

63

+|---|---|

64

+| `GET /health` | santé : nœud, état DB, dernière collecte par service |

65

+| 🔒 `GET /api/v1/{service}` | données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka |

66

+| 🔒 `GET /api/v1/{service}/latest` · `/date/{YYYY-MM-DD}` | dernière collecte, collecte d'une date précise |

67

+| 🔒 `GET /api/v1/{service}/stats` | statistiques du service |

68

+| 🔒 `GET /api/v1/louka/fairvalue/{uid}` | juste prix d'une annonce Lou·Ka |

69

+| `GET /api/v1/runs` | historique des runs de collecte (supervision) |

70

+| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` | santé des connecteurs de l'écosystème |

71

+| `GET /api/stats/dashboard` · `/report` · `/catalog` · `POST /api/stats/report/custom` | tableau de bord + rapports PDF (catalogue, personnalisés) |

72

+| `GET /api/stats/ecosystem-report` | rapport PDF consolidé des 13 plateformes |

73

+| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` | KA Agent (Claude Haiku + outils live) et son widget embarquable |

74

+| `GET /api/search` · `GET /api/suggest` | recherche transversale (incl. recherche floue) et suggestions |

75

+| `GET /api/auth/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout` | SSO KA ID |

76

+| `POST /api/ios/auth/exchange` | échange de jeton pour l'app iOS (`aud=ka-ios`) |

77

+

42

## Architecture

78

## Architecture

43

79

44

−- **FastAPI + Uvicorn** (`src/api/`) : routes health, services, runs, stats, agent, auth, iosauth + pages web et PDF (fpdf2).

80

+- **FastAPI + Uvicorn** (`src/api/`) : routes health, services, runs, monitoring, stats, search, agent, auth, iosauth + pages web et PDF (fpdf2).

45

- **PostgreSQL** via **SQLAlchemy 2** (+ **Alembic** pour les migrations, `psycopg2`) : une table de données par service + journal `collection_runs`.

81

- **PostgreSQL** via **SQLAlchemy 2** (+ **Alembic** pour les migrations, `psycopg2`) : une table de données par service + journal `collection_runs`.

46

- **Collecteurs** (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 8 collecteurs concrets, httpx.

82

- **Collecteurs** (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 8 collecteurs concrets, httpx.

47

- **Scheduler** (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.

83

- **Scheduler** (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.

48

- **Utils** (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.

84

- **Utils** (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.

49

- **anthropic** SDK pour le KA Agent.

85

- **anthropic** SDK pour le KA Agent.

50

86

87

+Collecteurs et cadence :

88

+

89

+| Collecteur | Source | Cadence |

90

+|---|---|---|

91

+| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` | API publique de chaque plateforme Ka | quotidien 02:00 (parallèle, indépendants) |

92

+| backfill | dates manquées des 7 derniers jours | au démarrage du job quotidien |

93

+| backups | dump horodaté par service (`data/backups/YYYY-MM-DD/`) | quotidien, rétention 90 jours |

94

+

51

Processus PM2 sur le nœud :

95

Processus PM2 sur le nœud :

52

96

53

−| Processus | Rôle |

97

+| Processus | Rôle | Cadence |

54

−|---|---|

98

+|---|---|---|

55

−| `apika-api` | l'API FastAPI/Uvicorn sur le port **8000** (liée à 127.0.0.1) |

99

+| `apika-api` | l'API FastAPI/Uvicorn sur le port **8000** (liée à 127.0.0.1) | continu |

56

−| `apika-scheduler` | le job quotidien 02:00 + backfill |

100

+| `apika-scheduler` | le job quotidien 02:00 + backfill (`python -m src.scheduler.daily_job`) | quotidien 02:00 |

57

−| `apika-ngrok` | tunnel ngrok vers **www.api-ka.com** |

101

+| `apika-ngrok` | tunnel ngrok vers **www.api-ka.com** | continu |

102

+

103

+Points de configuration notables (`src/config.py`, variables d'environnement — aucun secret dans le repo) : URL PostgreSQL, clé Anthropic du KA Agent, secret SSO partagé avec le hub KA ID, garde-fou de hostname (`m3u96b`).

58

104

59

## Structure du repo

105

## Structure du repo

60

106

70

└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md

116

└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md

71

```

117

```

72

118

119

+## Documentation

120

+

121

+- **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.

122

+- **Guide PDF** : [api-ka-documentation.pdf](https://www.api-ka.com/doc/api-ka-documentation.pdf) — la même documentation, téléchargeable.

123

+- **Swagger interactif** : [www.api-ka.com/docs](https://www.api-ka.com/docs) — tous les endpoints, schémas et essais en direct.

124

+- Les captures du guide sont versionnées dans `src/api/web/doc/img/` (etape1 → etape3).

125

+

73

## Développement (remote-first)

126

## Développement (remote-first)

74

127

75

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

128

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

100

153

101

## Écosystème Groupe KA

154

## Écosystème Groupe KA

102

155

103

−- [groupe-ka.com](https://www.groupe-ka.com) — portail du groupe et compte unique KA ID

156

+| Plateforme | Vocation |

104

−- [lou-ka.com](https://www.lou-ka.com) — logements à louer

157

+|---|---|

105

−- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre

158

+| [groupe-ka.com](https://www.groupe-ka.com) | portail du groupe et compte unique KA ID |

106

−- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière

159

+| [lou-ka.com](https://www.lou-ka.com) | logements à louer |

107

−- [auto-ka.com](https://www.auto-ka.com) — véhicules

160

+| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre |

108

−- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois

161

+| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière |

109

−- [food-ka.com](https://www.food-ka.com) — épicerie et alimentation

162

+| [auto-ka.com](https://www.auto-ka.com) | véhicules |

110

−- [resto-ka.com](https://www.resto-ka.com) — restaurants

163

+| [fabri-ka.com](https://www.fabri-ka.com) | produits québécois |

111

−- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements

164

+| [food-ka.com](https://www.food-ka.com) | épicerie et alimentation |

112

−- [job-ka.com](https://www.job-ka.com) — emplois

165

+| [resto-ka.com](https://www.resto-ka.com) | restaurants |

113

−- [crea-ka.com](https://www.crea-ka.com) — créateurs de contenu

166

+| [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements |

114

−- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces

167

+| [job-ka.com](https://www.job-ka.com) | emplois |

115

−- [api-ka.com](https://www.api-ka.com) — API de données *(ce repo)*

168

+| [crea-ka.com](https://www.crea-ka.com) | créateurs de contenu |

169

+| [trouve-ka.com](https://www.trouve-ka.com) | petites annonces |

170

+| [api-ka.com](https://www.api-ka.com) | API de données *(ce repo)* |

171

+

172

+## Contact

173

+

174

+**Simon-Pierre Boucher** — fondateur, Groupe KA

175

+📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)

116

176

117

---

177

---

118

178

119

179

spb/api-ka

docs: README v2 — galerie multi-pages, style du site, documentation, contact

Theme

				`@@ -1,30 +1,46 @@`
1	<!-- Auteur : Simon-Pierre Boucher — contact@spboucher.ai -->	1	<!-- Auteur : Simon-Pierre Boucher — contact@spboucher.ai -->
2		2
3	−# API·Ka	3	+<p align="center">
4	−	4	+ <a href="https://www.api-ka.com"><img src="https://www.api-ka.com/og.png" width="760" alt="API·Ka — La donnée de l'écosystème, par API"></a>
5	−L'API centrale du Groupe KA : collecte quotidienne des données des plateformes de l'écosystème, base PostgreSQL unifiée, API publique et KA Agent (IA).	5	+</p>
6	−	6	+<h1 align="center">API·Ka</h1>
7	−[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com)](https://www.api-ka.com)	7	+<p align="center"><b>La donnée de l'écosystème, par API</b></p>
8	−![Nœud](https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square)
9	−![Port](https://img.shields.io/badge/port-8000-141814?style=flat-square)
10	−![PM2](https://img.shields.io/badge/process-PM2-2b037a?style=flat-square)
11		8
12	−![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)	9	+<p align="center">
13	−![FastAPI](https://img.shields.io/badge/FastAPI-API-009688?style=flat-square&logo=fastapi&logoColor=white)	10	+ <a href="https://www.api-ka.com"><img src="https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com&up_color=3b5bdb&up_message=en%20ligne" alt="Site"></a>
14	−![PostgreSQL](https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white)	11	+ <a href="https://www.api-ka.com/doc/"><img src="https://img.shields.io/badge/📖_documentation-%2Fdoc-3b5bdb?style=flat-square" alt="Documentation"></a>
15	−![APScheduler](https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square)	12	+ <a href="https://www.api-ka.com/doc/api-ka-documentation.pdf"><img src="https://img.shields.io/badge/guide-PDF-3b5bdb?style=flat-square" alt="PDF"></a>
16	−![Groupe KA](https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square)	13	+ <img src="https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square" alt="Nœud">
		14	+ <img src="https://img.shields.io/badge/port-8000-141814?style=flat-square" alt="Port">
		15	+ <img src="https://img.shields.io/badge/process-PM2-2b037a?style=flat-square" alt="PM2">
		16	+</p>
		17	+<p align="center">
		18	+ <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
		19	+ <img src="https://img.shields.io/badge/FastAPI-API-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI">
		20	+ <img src="https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL">
		21	+ <img src="https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square" alt="APScheduler">
		22	+ <img src="https://img.shields.io/badge/Groupe-KA-3b5bdb?style=flat-square" alt="Groupe KA">
		23	+</p>
17		24
18	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, 8 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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.	25	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, 8 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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.
19		26
20	Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku, SSE, boucle d'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 (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).	27	Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku, SSE, boucle d'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 (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).
21		28
22	−## Captures d'écran	29	+## Visite guidée
23	−	30	+
24	−<p align="center">	31	+<table>
25	− <img src="docs/screenshots/api-ka-desktop.png" width="640" alt="Accueil — desktop">	32	+ <tr>
26	− <img src="docs/screenshots/api-ka-mobile.png" width="200" alt="Accueil — mobile">	33	+ <td align="center"><img src="docs/screenshots/api-ka-desktop.png" width="420"><br><sub><b>Accueil — le site de documentation de l'API (desktop)</b></sub></td>
27	−</p>	34	+ <td align="center"><img src="docs/screenshots/api-ka-mobile.png" width="220"><br><sub><b>Accueil — version mobile</b></sub></td>
		35	+ </tr>
		36	+ <tr>
		37	+ <td align="center"><img src="src/api/web/doc/img/etape1.png" width="420"><br><sub><b>Étape 1 · Explorez le site de documentation</b></sub></td>
		38	+ <td align="center"><img src="src/api/web/doc/img/etape2.png" width="420"><br><sub><b>Étape 2 · Parcourez l'API dans Swagger (/docs)</b></sub></td>
		39	+ </tr>
		40	+ <tr>
		41	+ <td align="center" colspan="2"><img src="src/api/web/doc/img/etape3.png" width="420"><br><sub><b>Étape 3 · Surveillez les collectes sur /stats</b></sub></td>
		42	+ </tr>
		43	+</table>
28		44
29	## Fonctionnalités	45	## Fonctionnalités
30		46
				`@@ -39,22 +55,52 @@ Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude`
39	- 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`.	55	- 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`.
40	- SEO du site de doc — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.	56	- SEO du site de doc — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.
41		57
		58	+## API (endpoints principaux)
		59	+
		60	+Référence interactive complète : Swagger sur [/docs](https://www.api-ka.com/docs). 🔒 = session KA ID ou jeton Bearer `kapi_` requis.
		61	+
		62	+\| Endpoint \| Rôle \|
		63	+\|---\|---\|
		64	+\| `GET /health` \| santé : nœud, état DB, dernière collecte par service \|
		65	+\| 🔒 `GET /api/v1/{service}` \| données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka \|
		66	+\| 🔒 `GET /api/v1/{service}/latest` · `/date/{YYYY-MM-DD}` \| dernière collecte, collecte d'une date précise \|
		67	+\| 🔒 `GET /api/v1/{service}/stats` \| statistiques du service \|
		68	+\| 🔒 `GET /api/v1/louka/fairvalue/{uid}` \| juste prix d'une annonce Lou·Ka \|
		69	+\| `GET /api/v1/runs` \| historique des runs de collecte (supervision) \|
		70	+\| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` \| santé des connecteurs de l'écosystème \|
		71	+\| `GET /api/stats/dashboard` · `/report` · `/catalog` · `POST /api/stats/report/custom` \| tableau de bord + rapports PDF (catalogue, personnalisés) \|
		72	+\| `GET /api/stats/ecosystem-report` \| rapport PDF consolidé des 13 plateformes \|
		73	+\| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` \| KA Agent (Claude Haiku + outils live) et son widget embarquable \|
		74	+\| `GET /api/search` · `GET /api/suggest` \| recherche transversale (incl. recherche floue) et suggestions \|
		75	+\| `GET /api/auth/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout` \| SSO KA ID \|
		76	+\| `POST /api/ios/auth/exchange` \| échange de jeton pour l'app iOS (`aud=ka-ios`) \|
		77	+
42	## Architecture	78	## Architecture
43		79
44	−- FastAPI + Uvicorn (`src/api/`) : routes health, services, runs, stats, agent, auth, iosauth + pages web et PDF (fpdf2).	80	+- FastAPI + Uvicorn (`src/api/`) : routes health, services, runs, monitoring, stats, search, agent, auth, iosauth + pages web et PDF (fpdf2).
45	- PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, `psycopg2`) : une table de données par service + journal `collection_runs`.	81	- PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, `psycopg2`) : une table de données par service + journal `collection_runs`.
46	- Collecteurs (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 8 collecteurs concrets, httpx.	82	- Collecteurs (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 8 collecteurs concrets, httpx.
47	- Scheduler (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.	83	- Scheduler (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.
48	- Utils (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.	84	- Utils (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.
49	- anthropic SDK pour le KA Agent.	85	- anthropic SDK pour le KA Agent.
50		86
		87	+Collecteurs et cadence :
		88	+
		89	+\| Collecteur \| Source \| Cadence \|
		90	+\|---\|---\|---\|
		91	+\| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` \| API publique de chaque plateforme Ka \| quotidien 02:00 (parallèle, indépendants) \|
		92	+\| backfill \| dates manquées des 7 derniers jours \| au démarrage du job quotidien \|
		93	+\| backups \| dump horodaté par service (`data/backups/YYYY-MM-DD/`) \| quotidien, rétention 90 jours \|
		94	+
51	Processus PM2 sur le nœud :	95	Processus PM2 sur le nœud :
52		96
53	−\| Processus \| Rôle \|	97	+\| Processus \| Rôle \| Cadence \|
54	−\|---\|---\|	98	+\|---\|---\|---\|
55	−\| `apika-api` \| l'API FastAPI/Uvicorn sur le port 8000 (liée à 127.0.0.1) \|	99	+\| `apika-api` \| l'API FastAPI/Uvicorn sur le port 8000 (liée à 127.0.0.1) \| continu \|
56	−\| `apika-scheduler` \| le job quotidien 02:00 + backfill \|	100	+\| `apika-scheduler` \| le job quotidien 02:00 + backfill (`python -m src.scheduler.daily_job`) \| quotidien 02:00 \|
57	−\| `apika-ngrok` \| tunnel ngrok vers www.api-ka.com \|	101	+\| `apika-ngrok` \| tunnel ngrok vers www.api-ka.com \| continu \|
		102	+
		103	+Points de configuration notables (`src/config.py`, variables d'environnement — aucun secret dans le repo) : URL PostgreSQL, clé Anthropic du KA Agent, secret SSO partagé avec le hub KA ID, garde-fou de hostname (`m3u96b`).
58		104
59	## Structure du repo	105	## Structure du repo
60		106
				`@@ -70,6 +116,13 @@ Processus PM2 sur le nœud :`
70	└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md	116	└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md
71	```	117	```
72		118
		119	+## Documentation
		120	+
		121	+- 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.
		122	+- Guide PDF : [api-ka-documentation.pdf](https://www.api-ka.com/doc/api-ka-documentation.pdf) — la même documentation, téléchargeable.
		123	+- Swagger interactif : [www.api-ka.com/docs](https://www.api-ka.com/docs) — tous les endpoints, schémas et essais en direct.
		124	+- Les captures du guide sont versionnées dans `src/api/web/doc/img/` (etape1 → etape3).
		125	+
73	## Développement (remote-first)	126	## Développement (remote-first)
74		127
75	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.	128	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.
				`@@ -100,19 +153,26 @@ pm2 restart apika-api # après un changement en produ`
100		153
101	## Écosystème Groupe KA	154	## Écosystème Groupe KA
102		155
103	−- [groupe-ka.com](https://www.groupe-ka.com) — portail du groupe et compte unique KA ID	156	+\| Plateforme \| Vocation \|
104	−- [lou-ka.com](https://www.lou-ka.com) — logements à louer	157	+\|---\|---\|
105	−- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre	158	+\| [groupe-ka.com](https://www.groupe-ka.com) \| portail du groupe et compte unique KA ID \|
106	−- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière	159	+\| [lou-ka.com](https://www.lou-ka.com) \| logements à louer \|
107	−- [auto-ka.com](https://www.auto-ka.com) — véhicules	160	+\| [immo-ka.com](https://www.immo-ka.com) \| propriétés à vendre \|
108	−- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois	161	+\| [vrai-prix.com](https://www.vrai-prix.com) \| estimation immobilière \|
109	−- [food-ka.com](https://www.food-ka.com) — épicerie et alimentation	162	+\| [auto-ka.com](https://www.auto-ka.com) \| véhicules \|
110	−- [resto-ka.com](https://www.resto-ka.com) — restaurants	163	+\| [fabri-ka.com](https://www.fabri-ka.com) \| produits québécois \|
111	−- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements	164	+\| [food-ka.com](https://www.food-ka.com) \| épicerie et alimentation \|
112	−- [job-ka.com](https://www.job-ka.com) — emplois	165	+\| [resto-ka.com](https://www.resto-ka.com) \| restaurants \|
113	−- [crea-ka.com](https://www.crea-ka.com) — créateurs de contenu	166	+\| [sorti-ka.com](https://www.sorti-ka.com) \| sorties et événements \|
114	−- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces	167	+\| [job-ka.com](https://www.job-ka.com) \| emplois \|
115	−- [api-ka.com](https://www.api-ka.com) — API de données (ce repo)	168	+\| [crea-ka.com](https://www.crea-ka.com) \| créateurs de contenu \|
		169	+\| [trouve-ka.com](https://www.trouve-ka.com) \| petites annonces \|
		170	+\| [api-ka.com](https://www.api-ka.com) \| API de données (ce repo) \|
		171	+
		172	+## Contact
		173	+
		174	+Simon-Pierre Boucher — fondateur, Groupe KA
		175	+📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)
116		176
117	---	177	---
118		178
119		179