4NK_IA_front/docs/API_BACKEND.md

📡 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 :

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

Exemple d'utilisation :

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 :

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

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

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 :

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

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

Avec JavaScript (fetch) :

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 :

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