# API-Ka — L'API de données du Groupe Ka

API-Ka collecte, sauvegarde et centralise chaque jour les données des 8 plateformes de l'écosystème Groupe Ka dans une base PostgreSQL unifiée, puis les expose via une API publique sur www.api-ka.com — avec en prime le KA Agent (assistant IA de l'écosystème) et le hub SSO KA ID.

Aperçu de API-Ka

# Description

API-Ka est la plateforme centrale de l'écosystème Groupe Ka :

8 collecteurs quotidiens (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka) : fetch → validation → checksum → insertion → backup → journal de run, avec retry 3× (backoff 30 s → 2 min → 10 min).
Un scheduler (APScheduler) qui lance le job quotidien à 02:00, collecteurs en parallèle et indépendants, plus un backfill automatique des dates manquées (7 derniers jours).
Une API FastAPI publique (données paginées, historiques, stats, rapports PDF).
Le KA Agent — assistant IA central du Groupe Ka (Claude Haiku 4.5) en SSE, avec une boucle de 12 outils branchés sur les API publiques des plateformes (logements, propriétés, véhicules, emplois, épicerie, produits, restos, sorties, créateurs, web QC, stats live, état des services) et CORS ouvert aux 13 domaines de l'écosystème.
Le hub SSO KA ID (login ka_id partagé) + l'échange de jetons pour l'app iOS native KA.
Des backups quotidiens horodatés par service (data/backups/YYYY-MM-DD/, rétention 90 jours).

# Endpoints

# Données des plateformes

GET / — statut de la plateforme + version
GET /health — nœud (m3u96b), état DB, dernière collecte par service
GET /api/v1/{service} — données paginées (?page=&limit=, limit max 500)
GET /api/v1/{service}/latest — dernière collecte
GET /api/v1/{service}/date/{YYYY-MM-DD} — données d'une date précise
GET /api/v1/{service}/stats — enregistrements par jour, dernière réussite
GET /api/v1/runs — historique des collectes (filtrable par service/statut)

{service} ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka.

# Stats & rapports

GET /stats — tableau de bord analytique de la plateforme (page web)
GET /api/stats/dashboard — stats live de la plateforme
GET /api/stats/report — rapport PDF de la plateforme
GET /api/stats/ecosystem-report — rapport PDF consolidé des 12 plateformes du Groupe Ka (nombre de plateformes dynamique via ecosystem.json)

# KA Agent (IA)

POST /api/agent/chat — chat en SSE avec le KA Agent (boucle d'outils, prompt par site, cache système)
GET /ka-agent.js — widget de chat embarquable sur les sites du Groupe Ka

# Auth (KA ID / iOS)

GET /api/auth/ka/login + GET /api/auth/ka/callback — SSO KA ID (hub groupe-ka.com)
GET /api/auth/me, POST /api/auth/logout — session
POST /api/ios/auth/exchange — échange du ka_token (vérification HS256, aud=ka-ios) contre un profil hub signé pour l'app iOS KA

Assets de partage servis à la racine : og.png, favicon.svg, apple-touch-icon.png, page /contact.

# Stack

Python 3 — FastAPI + Uvicorn
PostgreSQL — SQLAlchemy 2 + Alembic (migrations), psycopg2
APScheduler — job quotidien + backfill
httpx — collecteurs et outils de l'agent
fpdf2 — rapports PDF
PM2 + ngrok — exécution résiliente et exposition publique
pytest — tests (tests/)

# Structure

text

/opt/api-ka
├── src/
│   ├── api/            # FastAPI : main, routes/ (health, services, runs, stats, agent, auth, iosauth), web/, PDF
│   ├── collectors/     # 8 collecteurs quotidiens (un par plateforme Ka)
│   ├── scheduler/      # daily_job.py (02:00) + backfill.py
│   ├── database/       # modèles + init DB
│   ├── utils/          # backup.py (dumps quotidiens, rétention 90 j)
│   └── config.py
├── scripts/            # deploy_m3u96b.sh, start_ngrok.sh…
├── systemd/            # unités historiques (le déploiement actuel utilise PM2)
├── tests/              # pytest
├── data/               # backups/YYYY-MM-DD/
├── logs/
├── alembic.ini · pyproject.toml · requirements.txt
└── docs/screenshot.png

# Démarrage local

bash

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Initialiser la base
python -m src.database.db --init

# API en dev
uvicorn src.api.main:app --reload --port 8000

# Collecte manuelle immédiate (tous les services)
python -m src.scheduler.daily_job --now

# Backfill d'une date manquée
python -m src.scheduler.backfill --date 2026-08-15

# Vérifier la santé
curl http://127.0.0.1:8000/health

# Tests
pytest tests/ -v

# Déploiement

Nœud : M3U96b (Mac Studio, cluster MacLustr) — répertoire /opt/api-ka. Chaque service vérifie le hostname au démarrage et refuse de tourner ailleurs en production.
Port : 8000 (API liée à 127.0.0.1, exposée uniquement via le tunnel).
Domaine : https://www.api-ka.com (tunnel ngrok).
PM2 (3 process, auto-restart) :
- apika-api — l'API FastAPI/Uvicorn sur le port 8000
- apika-scheduler — le job quotidien 02:00 + backfill
- apika-ngrok — le tunnel www.api-ka.com