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

```text
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

```http
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) :**

```json
{
  "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`:

```json
{
  "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

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

#### Analyse du document

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

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

#### Données contextuelles

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

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

#### Conseil IA

```http
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

```env
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

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

## Authentification

### Headers requis

```http
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

```http
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

```typescript
// 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

```typescript
// 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

```typescript
// 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