Aller au contenu principal

API Produits - Documentation

Vue d'ensemble​

L'API Produits gère le catalogue de produits via un système de synchronisation avec l'application "Référentiel". Le principe fondamental est que nous demandons les informations produits à l'app "Référentiel" et les synchronisons localement pour optimiser les performances et assurer la disponibilité.

Architecture​

Principe de fonctionnement​

  • Source de vérité : L'application "Référentiel" est la source de vérité pour les données produits
  • Synchronisation unidirectionnelle : Nous récupérons les données depuis le Référentiel (pas d'écriture)
  • Cache local : Les produits sont stockés localement pour optimiser les performances
  • Identification unique : Chaque produit est identifié par son EAN (code-barres)

Logique métier​

Synchronisation des produits​

1. Batch quotidien automatique​

Un job CRON s'exécute quotidiennement à 3h du matin pour synchroniser automatiquement tous les produits :

  • Fréquence : Tous les jours à 3h00 (fuseau Europe/Paris)

  • Processus :

    1. Récupération de tous les produits depuis l'app "Référentiel"
    2. Filtrage des produits avec EAN valide (les produits sans EAN sont ignorés)
    3. Vérification des produits déjà existants en base locale
    4. Insertion uniquement des nouveaux produits (pas de mise à jour)
    5. Logging détaillé des résultats de synchronisation

  • Stratégie d'insertion : Seuls les nouveaux produits sont ajoutés (basé sur l'EAN)

  • Gestion des erreurs : Échecs tracés dans la table cronJobStatus

2. Bouton "Actualiser" manuel​

Un endpoint dédié permet la synchronisation manuelle via l'interface utilisateur :

  • Endpoint : POST /api/privee/produits/sync
  • Utilisation : Bouton "Actualiser" dans l'interface
  • Cas d'usage :
    • Synchronisation immédiate après ajout de nouveaux produits dans le Référentiel
    • Récupération urgente de données après incident
    • Tests et vérifications manuelles

Gestion des données​

Validation et filtrage​

  • EAN obligatoire : Les produits sans EAN valide sont automatiquement exclus
  • Déduplication : Basée sur l'EAN pour éviter les doublons
  • Intégrité : Préservation de la cohérence des données référentielles

Structure des données​

Les produits synchronisés incluent :

  • Identifiants : EAN
  • Informations produit : Nom, description, marque
  • Données commerciales : Prix de vente, prix d'achat fournisseur
  • Métadonnées : Photos, catégories, caractéristiques techniques
  • Statut : Actif/Inactif dans le catalogue

Avantages de cette approche​

  • Performance : Accès rapide aux données via le cache local
  • Disponibilité : Service maintenu même si le Référentiel est temporairement indisponible
  • Consistance : Synchronisation régulière garantit la cohérence des données
  • Traçabilité : Historique complet des synchronisations
  • Flexibilité : Synchronisation manuelle pour les cas urgents

Intégration avec le Référentiel​

Communication​

  • Direction : Unidirectionnelle (Référentiel → Gestion)
  • Protocole : API HTTP REST
  • Service : ReferentielService gère la communication
  • Méthode principale : getAllProducts() pour récupération complète

Swagger Documentation​

Cette API est documentée dans Swagger UI accessible à /api/swagger avec tous les schémas DTO et exemples de requêtes pour :

  • Consultation des produits (pagination, recherche)
  • Récupération par ID, EAN
  • Synchronisation manuelle