4nk/4NK_IA_front
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_IA_front/docs/API_BACKEND.md

464 lines
11 KiB
Markdown
Raw Blame History

# 📡 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_
Reference in New Issue View Git Blame Copy Permalink