API & Sécurité

API Externe & Sécurité

Intégration sécurisée avec Finance_App via notre API et système d'authentification

L'API externe de Finance_App permet à vos applications de s'intégrer de manière sécurisée avec notre plateforme. Cette documentation technique vous guide à travers les points d'accès disponibles et les mécanismes de sécurité mis en place.

Sécurité et Authentification

Authentification par API Keys

Chaque service externe reçoit un couple client_id/client_secret unique pour s'authentifier de manière sécurisée.

Connexions HTTPS

Toutes les communications avec l'API sont chiffrées via TLS pour garantir la confidentialité des données.

Isolation des Données

Chaque service externe n'a accès qu'aux projets explicitement liés à son identifiant.

Liens de Partage Sécurisés

Génération automatique de liens de partage avec contrôle d'accès et expiration configurable.

Authentification à l'API

Toutes les requêtes à l'API doivent inclure les identifiants du service externe dans les en-têtes HTTP:

En-têtes HTTP

{
  "x-client-id": "votre-client-id",
  "x-client-secret": "votre-client-secret",
  "Content-Type": "application/json"
}

Pour obtenir vos identifiants d'API, contactez l'administrateur de la plateforme. Gardez vos identifiants secrets et ne les exposez jamais dans du code client.

Points d'Accès (Endpoints)

GET/api/external

Test de l'API

Vérifie que l'API est en ligne et que vos identifiants sont valides.

Exemple de réponse:

{
  "status": "online",
  "message": "API externe Finance_App opérationnelle"
}

POST/api/external/projects

Création de projet

Crée un utilisateur (ou utilise un existant), un projet, et charge des données initiales en une seule requête.

Corps de la requête:

Requête

{
  "user": {
    "email": "utilisateur@example.com",
    "name": "Nom Utilisateur"
  },
  "project": {
    "title": "Mon Nouveau Projet",
    "description": "Description du projet",
    "startDate": "2025-06-10",
    "externalId": "PROJ-123" // Obligatoire et unique
  },
  "forecast": {
    "startYear": 2025,
    "growthRate": 5.0 // Optionnel (défaut: 0)
  },
  "data": {
    "requestedAmount": 150000, // Optionnel
    "articles": [
      {
        "title": "Produit 1",
        "articleType": "PRODUCT",
        "unitPrice": 15.0,
        "productionPrice": 5.0
      }
    ],
    "personnelCharges": [
      {
        "title": "Employé 1",
        "monthlyValues": [
          { "month": 1, "value": 1500 },
           ...
        ]
      }
    ],
    "operationCharges": [
      {
        "title": "Charge 1",
        "monthlyValues": [
          { "month": 1, "value": 300 },
           ...
        ]
      }
    ]
  }
}

Réponse en cas de succès (201):

Réponse 201

{
  "success": true,
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "projectTitle": "Mon Nouveau Projet",
  "projectUrl": "https://finance-app.example.com/projects/550e8400-e29b-41d4-a716-446655440000",
  "shareLink": "https://finance-app.example.com/s/abcd1234"
}

Réponse en cas de conflit (409):

Réponse 409

{
  "error": "Cet ID externe est déjà associé à un projet existant",
  "existingProjectId": "550e8400-e29b-41d4-a716-446655440000",
  "existingProjectTitle": "Mon Projet Existant"
}

Notes importantes :

Si l'utilisateur avec l'email spécifié existe déjà, il sera utilisé au lieu d'en créer un nouveau
Le champ project.externalId est obligatoire et doit être unique pour chaque service externe
Si un externalId est déjà utilisé, l'API renverra une erreur 409 (Conflict) avec les détails du projet existant
Le paramètre growthRate contrôle les taux de croissance automatiques appliqués aux prévisions
Toutes les sections de données (articles, personnelCharges, operationCharges) sont optionnelles
Trois prévisions sont automatiquement créées (année de base, année+1, année+2)
Les charges du personnel sont répliquées dans les trois prévisions avec une augmentation de 5% par an (ou selon le growthRate spécifié)
Si un champ requestedAmount est spécifié, il sera réparti équitablement sur les trois prévisions
La réponse contient un lien de partage permanent automatiquement créé pour ce projet

Voir la documentation sur la structure des données

GET/api/external/get-project

Récupération d'un projet

Récupère toutes les données d'un projet identifié par son ID externe.

Paramètres: ?externalId=id-dans-votre-systeme

Exemple de requête:

Requête GET

GET /api/external/get-project?externalId=PROJ-123
Headers: {
  "x-client-id": "votre-client-id",
  "x-client-secret": "votre-client-secret"
}

Réponse en cas de succès (200):

Réponse 200

{
  "success": true,
  "project": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Mon Nouveau Projet",
    "description": "Description du projet",
    "startDate": "2025-06-10",
    "externalId": "PROJ-123",
    "forecasts": [
      {
        "id": "660f9500-f39c-51e5-b817-556766550000",
        "title": "Prévision par défaut",
        "startYear": 2025
      }
    ]
  }
}

GET/api/external/verify-forecast-state

Vérification des prévisions

Vérifie l'état d'une prévision pour s'assurer qu'elle est cohérente.

Paramètres: ?forecastId=uuid-de-la-prévision

Exemple de requête:

Requête GET

GET /api/external/verify-forecast-state?forecastId=660f9500-f39c-51e5-b817-556766550000
Headers: {
  "x-client-id": "votre-client-id",
  "x-client-secret": "votre-client-secret"
}

Réponse en cas de succès (200):

Réponse 200

{
  "success": true,
  "projectId": "uuid-du-projet-finance-app",
  "projectTitle": "Nom du projet",
  "projectUrl": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/dashboard",
  "forecasts": [
    {
      "forecastId": "uuid-prévision-1",
      "year": 2025,
      "articlesCount": 3,
      "budgetEntriesByType": {
        "REVENUE": 2,
        "PERSONNEL": 5,
        "OPERATION": 4,
        "EXTERNAL_INCOME": 1
      },
      "hasData": true,
      "urls": {
        "overview": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/overview",
        "articles": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/articles",
        "personnelCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/charges-personnel",
        "operationCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/charges-exploitation",
        "taxesCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/taxes-impots",
        "fixedCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/charges-fixes",
        "establishmentCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/besoins-demarrage",
        "externalIncome": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-1/entrees-externes"
      }
    },
    {
      "forecastId": "uuid-prévision-2",
      "year": 2026,
      "articlesCount": 0,
      "budgetEntriesByType": {
        "PERSONNEL": 5,
        "OPERATION": 4,
        "EXTERNAL_INCOME": 1
      },
      "hasData": true,
      "urls": {
        "overview": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-2/overview",
        "articles": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-2/articles",
        "personnelCharges": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-2/charges-personnel"
        // Autres URLs similaires (omises pour concision)
      }
    },
    {
      "forecastId": "uuid-prévision-3",
      "year": 2027,
      "articlesCount": 0,
      "budgetEntriesByType": {
        "PERSONNEL": 5,
        "OPERATION": 4,
        "EXTERNAL_INCOME": 1
      },
      "hasData": true,
      "urls": {
        "overview": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-3/overview",
        "articles": "https://finance-app.domain.com/projects/uuid-du-projet-finance-app/data/forecasts/uuid-prévision-3/articles"
        // Autres URLs similaires (omises pour concision)
      }
    }
  ]
}

Codes d'Erreur

Code	Description
200	Succès
400	Requête incorrecte (données manquantes ou invalides)
401	Authentification incorrecte (client ID ou secret invalides)
404	Ressource non trouvée
409	Conflit (ex: ID externe déjà utilisé)

Documentation complète

Pour une documentation détaillée de chaque endpoint, des structures de données et des exemples de code, consultez la page Structure des données.