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

### Endpoints

#### Upload de document

```http
POST /api/documents/upload
Content-Type: multipart/form-data

Body: FormData avec le fichier
```

**Réponse :**

```json
{
  "id": "doc_123456",
  "name": "acte_vente.pdf",
  "type": "application/pdf",
  "size": 1024000,
  "uploadDate": "2024-01-15T10:30:00Z",
  "status": "completed"
}
```

#### Extraction de données

```http
GET /api/documents/{documentId}/extract
```

**Réponse :**

```json
{
  "documentId": "doc_123456",
  "text": "Texte extrait du document...",
  "language": "fr",
  "documentType": "Acte de vente",
  "identities": [
    {
      "id": "1",
      "type": "person",
      "firstName": "Jean",
      "lastName": "Dupont",
      "birthDate": "1980-05-15",
      "nationality": "Française",
      "confidence": 0.95
    }
  ],
  "addresses": [
    {
      "street": "123 Rue de la Paix",
      "city": "Paris",
      "postalCode": "75001",
      "country": "France"
    }
  ],
  "properties": [
    {
      "id": "1",
      "type": "apartment",
      "address": {
        "street": "123 Rue de la Paix",
        "city": "Paris",
        "postalCode": "75001",
        "country": "France"
      },
      "surface": 75,
      "cadastralReference": "1234567890AB",
      "value": 250000
    }
  ],
  "contracts": [
    {
      "id": "1",
      "type": "sale",
      "parties": [],
      "amount": 250000,
      "date": "2024-01-15",
      "clauses": ["Clause de garantie", "Clause de condition suspensive"]
    }
  ],
  "signatures": ["Jean Dupont", "Marie Martin"],
  "confidence": 0.92
}
```

#### Analyse du document

```http
GET /api/documents/{documentId}/analyze
```

**Réponse :**

```json
{
  "documentId": "doc_123456",
  "documentType": "Acte de vente",
  "isCNI": false,
  "credibilityScore": 0.88,
  "summary": "Document analysé avec succès. Toutes les informations semblent cohérentes.",
  "recommendations": [
    "Vérifier l'identité des parties auprès des autorités compétentes",
    "Contrôler la validité des documents cadastraux"
  ]
}
```

#### Données contextuelles

```http
GET /api/documents/{documentId}/context
```

**Réponse :**

```json
{
  "documentId": "doc_123456",
  "cadastreData": {
    "status": "disponible",
    "reference": "1234567890AB"
  },
  "georisquesData": {
    "status": "aucun risque identifié"
  },
  "geofoncierData": {
    "status": "données disponibles"
  },
  "bodaccData": {
    "status": "aucune procédure en cours"
  },
  "infogreffeData": {
    "status": "entreprise en règle"
  },
  "lastUpdated": "2024-01-15T10:30:00Z"
}
```

#### Conseil IA

```http
GET /api/documents/{documentId}/conseil
```

**Réponse :**

```json
{
  "documentId": "doc_123456",
  "analysis": "Ce document présente toutes les caractéristiques d'un acte notarial standard.",
  "recommendations": [
    "Procéder à la vérification d'identité des parties",
    "Contrôler la validité des documents fournis"
  ],
  "risks": [
    "Risque faible : Vérification d'identité recommandée",
    "Risque moyen : Contrôle cadastral nécessaire"
  ],
  "nextSteps": [
    "Collecter les pièces d'identité des parties",
    "Vérifier les documents cadastraux",
    "Préparer l'acte final"
  ],
  "generatedAt": "2024-01-15T10:30:00Z"
}
```

## 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_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