4NK_IA_front/docs/API.md

Documentation API - 4NK IA Front Notarial

Vue d'ensemble

L'application 4NK IA Front Notarial communique avec plusieurs APIs pour fournir une expérience complète d'analyse de documents notariaux.

API Backend Principal

Base URL

http://localhost:8000 (développement)

Modes d'API pris en charge

• Mode simple (VITE_BACKEND_MODE=simple) : endpoints sous /api/notary/...
• Mode complet (VITE_BACKEND_MODE=complete) : endpoints sous /api/documents/...

La variable d'environnement VITE_BACKEND_MODE pilote dynamiquement le choix des endpoints côté front.

Endpoints

Upload de document

POST /api/notary/upload   # mode simple
POST /api/documents/upload # mode complet
Content-Type: multipart/form-data

Body: FormData avec le fichier

Réponse (champs attendus et utilisés par le front) :

{
  "document_id": "doc_123456",            // ou "id"
  "mime_type": "application/pdf",         // ou "mimeType"
  "functional_type": "CNI"                // ou "functionalType" (type fonctionnel métier)
}

Le front mappe en Document:

{
  "id": "doc_123456",
  "name": "acte_vente.pdf",
  "mimeType": "application/pdf",
  "functionalType": "CNI",
  "size": 1024000,
  "uploadDate": "<date locale>",
  "status": "completed",
  "previewUrl": "blob:..."
}

Extraction de données

GET /api/notary/documents/{documentId}        # mode simple (détails document + résultats)
GET /api/documents/{documentId}/extract       # mode complet

Analyse du document

GET /api/documents/{documentId}/analyze       # mode complet

(mode simple: synthèse construite côté front à partir de /api/notary/documents/{documentId})

Données contextuelles

GET /api/documents/{documentId}/context       # mode complet

(mode simple: non disponible — fallback de démonstration)

Conseil IA

GET /api/documents/{documentId}/conseil       # mode complet

(mode simple: non disponible — fallback de démonstration)

APIs Externes

Cadastre

URL : https://api.cadastre.gouv.fr Usage : Vérification des références cadastrales et des propriétés

Géorisques

URL : https://www.georisques.gouv.fr/api Usage : Analyse des risques géologiques et environnementaux

Géofoncier

URL : https://api.geofoncier.fr Usage : Données foncières et géographiques

BODACC

URL : https://api.bodacc.fr Usage : Vérification des procédures collectives et des entreprises

Infogreffe

URL : https://api.infogreffe.fr Usage : Informations sur les entreprises et leurs dirigeants

Gestion d'erreur

Codes d'erreur HTTP

• 200 : Succès
• 400 : Requête malformée
• 404 : Ressource non trouvée
• 405 : Méthode non autorisée
• 500 : Erreur serveur interne

Erreurs de connexion

• ERR_NETWORK : Erreur de réseau
• ERR_CONNECTION_REFUSED : Connexion refusée
• ERR_TIMEOUT : Timeout de la requête

Fallback automatique

En cas d'erreur, l'application bascule automatiquement vers des données de démonstration pour maintenir l'expérience utilisateur.

Configuration

Variables d'environnement

VITE_API_URL=http://localhost:8000
VITE_BACKEND_MODE=simple
VITE_CADASTRE_API_URL=https://api.cadastre.gouv.fr
VITE_GEORISQUES_API_URL=https://www.georisques.gouv.fr/api
VITE_GEOFONCIER_API_URL=https://api.geofoncier.fr
VITE_BODACC_API_URL=https://api.bodacc.fr
VITE_INFOGREFFE_API_URL=https://api.infogreffe.fr

Configuration Axios

const apiClient = axios.create({
  baseURL: BASE_URL,
  timeout: 60000, // 60 secondes
  headers: {
    'Content-Type': 'application/json'
  }
})

Authentification

Headers requis

Authorization: Bearer {token}
Content-Type: application/json

Gestion des tokens

• Refresh automatique : Renouvellement des tokens expirés
• Intercepteurs : Ajout automatique des headers d'authentification
• Logout automatique : Déconnexion en cas d'erreur 401

Rate Limiting

Limites par défaut

• 100 requêtes/minute par utilisateur
• 1000 requêtes/heure par utilisateur
• Backoff exponentiel en cas de dépassement

Headers de réponse

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Monitoring et logs

Métriques collectées

• Temps de réponse : Latence des requêtes
• Taux d'erreur : Pourcentage d'échecs
• Utilisation : Nombre de requêtes par endpoint

Logs

• Requêtes : Log de toutes les requêtes API
• Erreurs : Log détaillé des erreurs
• Performance : Métriques de performance

Tests

Tests d'intégration

// Test d'upload de document
test('should upload document successfully', async () => {
  const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
  const result = await documentApi.upload(file)
  expect(result.id).toBeDefined()
  expect(result.status).toBe('completed')
})

Tests de fallback

// Test du mode démonstration
test('should return demo data on API error', async () => {
  // Mock de l'erreur API
  mockAxios.onPost('/api/documents/upload').reply(500)

  const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
  const result = await documentApi.upload(file)

  expect(result.id).toMatch(/^demo-/)
  expect(result.name).toBe('test.pdf')
})

Sécurité

Validation des données

• Sanitization : Nettoyage des entrées utilisateur
• Validation : Vérification des types et formats
• Escape : Protection contre les injections

CORS

// Configuration CORS
const corsOptions = {
  origin: ['http://localhost:3000', 'https://app.4nkweb.com'],
  credentials: true,
  optionsSuccessStatus: 200
}

HTTPS

• Redirection automatique : HTTP vers HTTPS en production
• HSTS : HTTP Strict Transport Security
• Certificats SSL : Certificats valides et à jour