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)

Endpoints

Upload de document

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

Body: FormData avec le fichier

Réponse :

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

Extraction de données

GET /api/documents/{documentId}/extract

Réponse :

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

GET /api/documents/{documentId}/analyze

Réponse :

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

GET /api/documents/{documentId}/context

Réponse :

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

GET /api/documents/{documentId}/conseil

Réponse :

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

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

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