# 📡 API Backend 4NK_IA - Documentation

## 🚀 **Vue d'ensemble**

L'API Backend 4NK_IA est un service d'extraction et d'analyse de documents utilisant l'OCR (Reconnaissance Optique de Caractères) et le NER (Reconnaissance d'Entités Nommées) pour traiter automatiquement les documents PDF et images.

### **Caractéristiques principales :**

- ✅ **Support multi-format** : PDF, JPEG, PNG, TIFF, TXT
- ✅ **OCR avancé** : Tesseract.js avec préprocessing d'images
- ✅ **Extraction PDF directe** : pdf-parse pour une précision maximale
- ✅ **NER intelligent** : Reconnaissance d'entités par règles
- ✅ **Format JSON standardisé** : Structure cohérente pour tous les documents
- ✅ **Préprocessing d'images** : Amélioration automatique de la qualité OCR
- ✅ **Gestion des doublons** : Système de hash SHA-256 pour éviter les fichiers dupliqués

---

## 🌐 **Endpoints de l'API**

### **Base URL :** `http://localhost:3001/api`

---

## 📋 **1. Health Check**

### **GET** `/api/health`

Vérifie l'état du serveur backend.

**Réponse :**

```json
{
  "status": "OK",
  "timestamp": "2025-09-15T22:45:50.123Z",
  "version": "1.0.0"
}
```

**Exemple d'utilisation :**

```bash
curl http://localhost:3001/api/health
```

---

## 📁 **2. Liste des fichiers de test**

### **GET** `/api/test-files`

Retourne la liste des fichiers de test disponibles.

**Réponse :**

```json
{
  "files": [
    {
      "name": "IMG_20250902_162159.jpg",
      "size": 245760,
      "type": "image/jpeg"
    }
  ]
}
```

---

## 📂 **3. Liste des fichiers uploadés**

### **GET** `/api/uploads`

Retourne la liste des fichiers uploadés avec leurs métadonnées et hash SHA-256.

**Réponse :**

```json
{
  "files": [
    {
      "name": "document-1757980637671.pdf",
      "size": 1015808,
      "hash": "a1b2c3d4e5f6...",
      "uploadDate": "2025-09-15T23:56:14.751Z",
      "modifiedDate": "2025-09-15T23:56:14.751Z"
    }
  ],
  "count": 1,
  "totalSize": 1015808
}
```

**Exemple d'utilisation :**

```bash
curl http://localhost:3001/api/uploads
```

**Notes :**

- Le hash SHA-256 permet d'identifier les fichiers identiques
- Les fichiers dupliqués sont automatiquement détectés lors de l'upload
- Seuls les fichiers uniques sont conservés dans le système

---

## 🔍 **4. Extraction de documents**

### **POST** `/api/extract`

Extrait et analyse un document (PDF, image ou texte) pour identifier les entités et informations structurées.

#### **Paramètres :**

- **`document`** (file, required) : Fichier à analyser (PDF, JPEG, PNG, TIFF, TXT)
- **Taille maximale :** 10MB

#### **Gestion des doublons :**

- Le système calcule automatiquement un hash SHA-256 de chaque fichier uploadé
- Si un fichier avec le même hash existe déjà, le doublon est supprimé
- Le traitement utilise le fichier existant, évitant ainsi les calculs redondants
- Les logs indiquent clairement si un fichier est nouveau ou déjà existant

#### **Réponse - Format JSON Standard :**

```json
{
  "document": {
    "id": "doc-1757976350123",
    "fileName": "facture_4NK_08-2025_04.pdf",
    "fileSize": 85819,
    "mimeType": "application/pdf",
    "uploadTimestamp": "2025-09-15T22:45:50.123Z"
  },
  "classification": {
    "documentType": "Facture",
    "confidence": 0.95,
    "subType": "Facture de prestation",
    "language": "fr",
    "pageCount": 1
  },
  "extraction": {
    "text": {
      "raw": "Janin Consulting - EURL au capital de 500 Euros...",
      "processed": "Janin Consulting - EURL au capital de soo Euros...",
      "wordCount": 165,
      "characterCount": 1197,
      "confidence": 0.95
    },
    "entities": {
      "persons": [
        {
          "id": "identity-0",
          "type": "person",
          "firstName": "Anthony",
          "lastName": "Janin",
          "role": "Gérant",
          "email": "ja.janin.anthony@gmail.com",
          "phone": "33 (0)6 71 40 84 13",
          "confidence": 0.9,
          "source": "rule-based"
        }
      ],
      "companies": [
        {
          "id": "company-0",
          "name": "Janin Consulting",
          "legalForm": "EURL",
          "siret": "815 322 912 00040",
          "rcs": "815 322 912 NANTERRE",
          "tva": "FR64 815 322 912",
          "capital": "500 Euros",
          "role": "Fournisseur",
          "confidence": 0.95,
          "source": "rule-based"
        }
      ],
      "addresses": [
        {
          "id": "address-0",
          "type": "siège_social",
          "street": "177 rue du Faubourg Poissonnière",
          "city": "Paris",
          "postalCode": "75009",
          "country": "France",
          "company": "Janin Consulting",
          "confidence": 0.9,
          "source": "rule-based"
        }
      ],
      "financial": {
        "amounts": [
          {
            "id": "amount-0",
            "type": "prestation",
            "description": "Prestation du mois d'Août 2025",
            "quantity": 10,
            "unitPrice": 550.0,
            "totalHT": 5500.0,
            "currency": "EUR",
            "confidence": 0.95
          }
        ],
        "totals": {
          "totalHT": 5500.0,
          "totalTVA": 1100.0,
          "totalTTC": 6600.0,
          "tvaRate": 0.2,
          "currency": "EUR"
        },
        "payment": {
          "terms": "30 jours après émission",
          "penaltyRate": "Taux BCE + 7 points",
          "bankDetails": {
            "bank": "CAISSE D'EPARGNE D'ILE DE FRANCE",
            "accountHolder": "Janin Anthony",
            "address": "1 rue Pasteur (78800)",
            "rib": "17515006000800309088884"
          }
        }
      },
      "dates": [
        {
          "id": "date-0",
          "type": "facture",
          "value": "29-août-25",
          "formatted": "2025-08-29",
          "confidence": 0.9,
          "source": "rule-based"
        }
      ],
      "contractual": {
        "clauses": [
          {
            "id": "clause-0",
            "type": "paiement",
            "content": "Le paiement se fera (maximum) 30 jours après l'émission de la facture.",
            "confidence": 0.9
          }
        ],
        "signatures": [
          {
            "id": "signature-0",
            "type": "électronique",
            "present": false,
            "signatory": null,
            "date": null,
            "confidence": 0.8
          }
        ]
      },
      "references": [
        {
          "id": "ref-0",
          "type": "facture",
          "number": "4NK_4",
          "confidence": 0.95
        }
      ]
    }
  },
  "metadata": {
    "processing": {
      "engine": "4NK_IA_Backend",
      "version": "1.0.0",
      "processingTime": "423ms",
      "ocrEngine": "pdf-parse",
      "nerEngine": "rule-based",
      "preprocessing": {
        "applied": false,
        "reason": "PDF direct text extraction"
      }
    },
    "quality": {
      "globalConfidence": 0.95,
      "textExtractionConfidence": 0.95,
      "entityExtractionConfidence": 0.9,
      "classificationConfidence": 0.95
    }
  },
  "status": {
    "success": true,
    "errors": [],
    "warnings": ["Aucune signature détectée"],
    "timestamp": "2025-09-15T22:45:50.123Z"
  }
}
```

#### **Exemples d'utilisation :**

**Avec curl (PDF) :**

```bash
curl -X POST \
  -F "document=@/path/to/document.pdf" \
  http://localhost:3001/api/extract
```

**Avec curl (TXT) :**

```bash
curl -X POST \
  -F "document=@/path/to/file.txt" \
  http://localhost:3001/api/extract
```

**Avec JavaScript (fetch) :**

```javascript
const formData = new FormData()
formData.append('document', fileInput.files[0])

const response = await fetch('http://localhost:3001/api/extract', {
  method: 'POST',
  body: formData,
})

const result = await response.json()
console.log(result)
```

---

## 📊 **Types de documents supportés**

### **1. Factures**

- **Détection automatique** : Mots-clés "facture", "tva", "siren", "montant"
- **Entités extraites** :
  - Sociétés (fournisseur/client)
  - Adresses de facturation
  - Montants et totaux
  - Conditions de paiement
  - Numéros de référence
  - Dates

### **2. Cartes Nationales d'Identité (CNI)**

- **Détection automatique** : Mots-clés "carte nationale d'identité", "cni", "mrz"
- **Entités extraites** :
  - Identités (nom, prénom)
  - Numéros CNI
  - Dates de naissance
  - Adresses

### **3. Contrats**

- **Détection automatique** : Mots-clés "contrat", "vente", "achat", "acte"
- **Entités extraites** :
  - Parties contractantes
  - Clauses contractuelles
  - Signatures
  - Dates importantes

### **4. Attestations**

- **Détection automatique** : Mots-clés "attestation", "certificat"
- **Entités extraites** :
  - Identités
  - Dates
  - Informations spécifiques

---

## 🔧 **Configuration et préprocessing**

### **Préprocessing d'images (pour JPEG, PNG, TIFF) :**

- **Redimensionnement** : Largeur cible 2000px
- **Amélioration du contraste** : Facteur 1.5
- **Luminosité** : Facteur 1.1
- **Conversion en niveaux de gris**
- **Amélioration de la netteté**
- **Réduction du bruit**

### **Extraction PDF directe :**

- **Moteur** : pdf-parse
- **Avantage** : Pas de conversion image, précision maximale
- **Confiance** : 95% par défaut

---

## ⚡ **Performances**

### **Temps de traitement typiques :**

- **PDF** : 200-500ms
- **Images** : 1-3 secondes (avec préprocessing)
- **Taille maximale** : 10MB

### **Confiance d'extraction :**

- **PDF** : 90-95%
- **Images haute qualité** : 80-90%
- **Images de qualité moyenne** : 60-80%

---

## 🚨 **Gestion d'erreurs**

### **Codes d'erreur HTTP :**

- **400** : Aucun fichier fourni
- **413** : Fichier trop volumineux (>10MB)
- **415** : Type de fichier non supporté
- **500** : Erreur de traitement interne

### **Exemple de réponse d'erreur :**

```json
{
  "success": false,
  "error": "Type de fichier non supporté",
  "details": "Seuls les formats PDF, JPEG, PNG et TIFF sont acceptés"
}
```

---

## 🛠️ **Dépendances techniques**

### **Moteurs OCR :**

- **Tesseract.js** : Pour les images
- **pdf-parse** : Pour les PDF

### **Préprocessing :**

- **Sharp.js** : Traitement d'images

### **NER :**

- **Règles personnalisées** : Patterns regex pour l'extraction d'entités

---

## 📝 **Notes d'utilisation**

1. **Format de sortie standardisé** : Tous les documents retournent le même format JSON
2. **Confiance** : Chaque entité extraite inclut un score de confiance
3. **Source** : Indication de la méthode d'extraction (rule-based, ML, etc.)
4. **Métadonnées complètes** : Informations sur le traitement et la qualité
5. **Gestion des erreurs** : Warnings et erreurs détaillés dans la réponse

---

## 🔄 **Évolutions futures**

- [ ] Support de l'IA/ML pour l'extraction d'entités
- [ ] Support de documents multi-pages
- [ ] Extraction de signatures manuscrites
- [ ] Support de langues supplémentaires
- [ ] API de validation des extractions
- [ ] Cache des résultats pour optimisation

---

_Documentation générée le 15/09/2025 - Version 1.0.0_