Documentation API

Previabusiness expose une API REST JSON pour intégrer le scoring dans vos outils. Tous les endpoints sont accessibles via https://previabusiness.local/api/... (ou http://localhost:8000/api/... en développement).

URL de base : https://previabusiness.local/api/

Authentication

La plupart des endpoints API nécessitent une authentification via session Django. Pour vous authentifier :

  1. Créez un compte via POST /api/register
  2. Connectez-vous via POST /login/ (formulaire HTML)
  3. Utilisez le cookie de session sessionid dans vos requêtes suivantes
CSRF : Pour les requêtes POST/PUT/DELETE en JavaScript, incluez l'en-tête X-CSRFToken avec la valeur du cookie csrftoken.

Exemple avec curl

# 1. Connexion
curl -X POST https://previabusiness.local/login/ \
  -c cookies.txt \
  -d "username=email@example.com&password=MonMot2Passe"

# 2. Requête API authentifiée
curl -X POST https://previabusiness.local/api/score \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"siren": "315092296"}'

Clés API : tester en 2 minutes

Pour lire vos données depuis un script ou un outil externe, utilisez une clé API plutôt que la session. Les clés donnent un accès lecture seule aux endpoints /api/v1/.

Étape 1 : Créer la clé : dashboard → Paramètres → Clés API → « Créer une clé ». Le secret est affiché une seule fois : copiez-le immédiatement (seul un hash est conservé côté serveur, il ne peut pas être réaffiché).
Étape 2 : Appeler l'API : envoyez le secret dans l'en-tête Authorization: Token <secret>.

Exemple avec curl

# Lister les analyses de votre cabinet
export PB_TOKEN="votre_secret"

curl https://previabusiness.com/api/v1/analyses/ \
  -H "Authorization: Token $PB_TOKEN"

Endpoints lisibles avec une clé : GET /api/v1/analyses/, GET /api/v1/firms/, GET /api/v1/companies/{siren}/, GET /api/v1/markets/. Lecture seule : les analyses se lancent depuis le dashboard, pas par clé API. Une clé expire au bout de 30 jours, 3 clés actives maximum par utilisateur.

Référence complète : limites, codes d'erreur (401/403/404/429), révocation immédiate : voir docs/API.md, section « Authentification par clé API ».

Endpoints

GET /api/plans

Auth requise

Liste tous les plans d'abonnement disponibles.

Réponse

{
  "plans": [
    { "id": "free", "price": 0, "reports_per_month": 1 },
    { "id": "solo", "price": 3000, "reports_per_month": 20 },
    ...
  ]
}

POST /api/register

Auth non requise Rate limit: 3/min/IP

Crée un nouveau compte utilisateur avec abonnement Free.

Body

{
  "email": "user@example.com",
  "password": "Str0ng!Pass123",
  "company_name": "Ma TPE" // optionnel
}

Réponse (201)

{
  "success": true,
  "plan": "free",
  "message": "Inscription reussie. Verifiez votre email..."
}

POST /api/subscribe

Auth requise

Change l'abonnement de l'utilisateur connecté.

Body

{ "plan": "solo" }

Réponse

{
  "success": true,
  "plan": "solo",
  "reports_per_month": 20
}

POST /api/score

Auth requise Rate limit: 10/min

Calcule le scoring complet pour un SIREN. Synchrone : le résultat est retourné en une réponse JSON.

Body

{ "siren": "315092296" }

Réponse

{
  "score": 72.5,
  "grade": "vert",
  "dimensions": [...],
  "verdict": { "titre": "...", "description": "..." },
  "company": { "siren": "315092296", "nom": "..." },
  "recommendations": "..."
}

POST /api/score/stream

Auth requise Rate limit: 10/min

Lance le pipeline complet avec streaming SSE (Server-Sent Events). Le client reçoit des events step_start, step_progress, step_done et un event final avec le résultat complet.

Body

{ "siren": "315092296" }

Réponse (SSE)

// Connexion établie
event: connected
data: {"siren": "315092296"}

// Progression
event: step_start
data: {"step": "official", "detail": "Donnees officielles", "progress": 15}

// Résultat final
event: final
data: {"score": 72.5, "grade": "vert", "pdf_path": "...", ...}

POST /api/score/batch

Auth requise Rate limit: 5/min

Lance le scoring pour plusieurs SIRENs en une seule requête. Le traitement est asynchrone : interrogez GET /api/score/batch/{"{job_id}"} pour le statut.

Body

{ "sirens": ["315092296", "552120222"] }

Réponse (202)

{
  "job_id": "batch_abc123def456",
  "total": 2,
  "queued": 2,
  "analysis_ids": [1, 2]
}

Contraintes

  • Maximum 50 SIRENs par requête
  • Tous les SIRENs doivent être valides (9 chiffres)
  • Le quota de l'utilisateur est vérifié avant l'ajout

GET /api/score/batch/{job_id}

Auth requise

Consulte le statut d'un batch de scoring lancé via POST /api/score/batch.

Réponse

{
  "job_id": "batch_abc123",
  "total": 2,
  "completed": 1,
  "failed": 0,
  "pending": 1,
  "results": {
    "1": { "siren": "315092296", "status": "completed", "score": 72.5, "grade": "vert" },
    "2": { "siren": "552120222", "status": "running" }
  }
}

GET /api/score/pdf

Auth requise

Télécharge le PDF du rapport de scoring pour un SIREN donné.

Query params

?siren=315092296

Réponse

Fichier PDF (Content-Type: application/pdf). Statut 404 si le rapport n'existe pas.

GET /api/analyses

Auth requise

Liste l'historique des analyses de l'utilisateur connecté.

Query params

?limit=20 // max 100, défaut 20

Réponse

{
  "analyses": [...],
  "total": 15,
  "quota_used": 8,
  "quota_limit": 20
}

GET /api/model-presets

Auth requise

Liste les modèles IA disponibles pour l'exploration et l'analyse marché.

GET /api/firm

Auth requise

Retourne les informations du cabinet de l'utilisateur et la liste des membres.

POST /api/firm/create

Auth requise

Crée un cabinet. L'utilisateur devient administrateur.

Body

{ "name": "Mon Cabinet" }

POST /api/firm/invite

Auth requise Rôle admin

Invite un utilisateur existant dans le cabinet.

Body

{ "email": "collaborateur@example.com", "role": "analyst" }

GET /api/rgpd/export

Auth requise

Exporte toutes les données personnelles de l'utilisateur (RGPD Art. 15, 20).

DELETE /api/rgpd/delete

Auth requise

Supprime toutes les données personnelles de l'utilisateur (RGPD Art. 17). Les logs d'audit sont conservés (C. com. art. L224).

Rate Limiting

Previabusiness applique des limites de débit pour protéger l'infrastructure :

Endpoint Limite Type
POST /api/register 3 requêtes/min Par IP
POST /api/score 10 requêtes/min Par utilisateur
POST /api/score/stream 10 requêtes/min Par utilisateur
POST /api/score/batch 5 requêtes/min Par utilisateur
POST /api/subscribe 5 requêtes/min Par utilisateur
Autres endpoints Non limités n.d.

En cas de dépassement, le serveur retourne 429 Too Many Requests.

Codes d'erreur

Code HTTP Signification Cause fréquente
400 Bad Request SIREN invalide, JSON malformé, paramètre manquant
302 / 401 Non authentifié Session manquante ou expirée
403 Forbidden Quota dépassé, accès refusé
404 Not Found SIREN inexistant, PDF non trouvé, batch introuvable
409 Conflict Email déjà utilisé, déjà membre du cabinet
429 Too Many Requests Rate limit dépassé
500 Internal Server Error Erreur inattendue : contacter le support

Toutes les erreurs retournent un corps JSON : {"error": "Description du problème"}