c6b5767d5d
- Ajout du système de hash SHA-256 pour éviter les doublons d'upload - Implémentation du cache JSON pour sauvegarder les résultats d'extraction - Nouvelles fonctions: calculateFileHash, findExistingFileByHash, saveJsonCache, getJsonCache - Nouvelles routes API: /api/cache, /api/cache/:hash, /api/uploads - Optimisation des performances: réutilisation des résultats en cache - Documentation mise à jour: API_BACKEND.md et nouveau fichier HASH_SYSTEM.md - Ajout du dossier cache/ au .gitignore
432 lines
11 KiB
Markdown
432 lines
11 KiB
Markdown
# 📡 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
|
|
- ✅ **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 ou image) pour identifier les entités et informations structurées.
|
|
|
|
#### **Paramètres :**
|
|
- **`document`** (file, required) : Fichier à analyser (PDF, JPEG, PNG, TIFF)
|
|
- **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.00,
|
|
"totalHT": 5500.00,
|
|
"currency": "EUR",
|
|
"confidence": 0.95
|
|
}
|
|
],
|
|
"totals": {
|
|
"totalHT": 5500.00,
|
|
"totalTVA": 1100.00,
|
|
"totalTTC": 6600.00,
|
|
"tvaRate": 0.20,
|
|
"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.90,
|
|
"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 :**
|
|
```bash
|
|
curl -X POST \
|
|
-F "document=@/path/to/document.pdf" \
|
|
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*
|