Schémas de données et Enums

Ce document détaille tous les types de données, enums et structures utilisés par l'API Référentiel.

Enums métiers

Statuts Produit

statutProduit: État du cycle de vie d'un produit

Valeur	Description	Utilisation
`actif`	Produit disponible à la vente	Produit en catalogue, stocks disponibles
`inactif`	Temporairement indisponible	Rupture de stock, produit saisonnier hors saison
`discontinue`	Arrêt définitif de commercialisation	Produit en fin de vie, ne sera plus réapprovisionné
`en_developpement`	Produit en cours de développement/test	Avant le lancement commercial
`obsolete`	Produit dépassé, remplacé	Remplacé par une nouvelle version

Défaut: actif

Catégories Produit

categories: Classification des produits

Valeur	Description	Exemples
`informatique`	Ordinateurs, composants, accessoires	PC, Mac, périphériques, composants
`telephonie`	Smartphones, tablettes, accessoires mobiles	iPhone, Samsung Galaxy, coques
`image_son`	TV, audio, photo, vidéo	Téléviseurs, enceintes, appareils photo
`electromenager`	Gros et petit électroménager	Réfrigérateurs, machines à laver, cafetières
`gaming`	Consoles, jeux vidéo, accessoires gaming	PlayStation, Xbox, manettes
`maison_connectee`	Domotique, objets connectés	Ampoules connectées, caméras, thermostats
`accessoires`	Câbles, housses, supports, etc.	Câbles HDMI, housses, supports
`services`	Extensions de garantie, services, formations	Garanties, installations, formations
`multimedia`	Stockage, lecteurs, supports physiques	Disques durs, clés USB, Blu-ray

Défaut: accessoires

Statuts Fournisseur

statut: État opérationnel du fournisseur

Valeur	Description
`actif`	Fournisseur opérationnel et autorisé
`inactif`	Temporairement désactivé
`suspendu`	Suspendu pour problème qualité/livraison
`bloque`	Bloqué pour problème juridique/financier
`en_validation`	Nouveau fournisseur en cours de validation

Défaut: en_validation

Statuts Contractuel

statutContractuel: État du contrat avec le fournisseur

Valeur	Description
`valide`	Contrat en cours et valide
`expire`	Contrat expiré, renouvellement nécessaire
`en_negociation`	Négociation/renouvellement en cours
`resilie`	Contrat résilié définitivement
`suspendu`	Contrat suspendu temporairement

Défaut: en_negociation

Statuts Relation Fournisseur

statutRelation: État de la relation commerciale produit-fournisseur

Valeur	Description	Priorité
`actif`	Relation commerciale active	Standard
`inactif`	Relation suspendue temporairement	-
`suspendu`	Suspendu pour problème qualité/livraison	-
`prefere`	Fournisseur préférentiel pour ce produit	⭐ Haute
`secours`	Fournisseur de backup/secours	Basse

Défaut: actif

Statuts Entrepôt

statut: État opérationnel de l'entrepôt

Valeur	Description
`operationnel`	Entrepôt en fonctionnement normal
`maintenance`	Maintenance programmée, capacité réduite
`ferme`	Fermé définitivement ou temporairement
`en_construction`	En cours de construction/aménagement

Défaut: operationnel

Types Entrepôt

typeEntrepot: Spécialisation de l'entrepôt

Valeur	Description	Produits adaptés
`informatique`	Produits high-tech, composants	Ordinateurs, périphériques, composants
`electromenager`	Gros et petit électroménager	Réfrigérateurs, lave-linge, fours
`accessoires`	Petits accessoires, câbles, périphériques	Câbles, housses, petits accessoires
`multimedia`	Livres, CD, DVD, jeux vidéo	Supports physiques, stockage
`generaliste`	Entrepôt non spécialisé, stockage mixte	Tous types de produits

Défaut: generaliste

Champ associé: estGrosVolume (boolean) - Indique si l'entrepôt dispose d'une infrastructure adaptée aux produits volumineux (gros électroménager, TV grand format).

Statuts Magasin

statut: État d'ouverture du magasin

Valeur	Description
`ouvert`	Magasin ouvert au public
`ferme`	Fermé définitivement
`renovation`	Travaux de rénovation en cours
`fermeture_temporaire`	Fermé temporairement (congés, incident)

Défaut: ouvert

Types Magasin

type: Format du point de vente

Valeur	Description	Surface typique	Caractéristiques
`megastore`	Grands magasins	> 2000 m²	Fnac des Ternes, Darty République
`magasin_centre_ville`	Magasins en centre-ville	500-1500 m²	Proximité, accessibilité piétonne
`magasin_centre_commercial`	Dans les centres commerciaux	800-2000 m²	Parking, galerie marchande
`magasin_peripherie`	En périphérie des villes	1000-2000 m²	Parking, zone commerciale
`concept_store`	Magasins spécialisés	300-1000 m²	Fnac Gaming, Darty Cuisine
`corner`	Corners dans d'autres enseignes	< 200 m²	Petit espace dédié
`drive`	Retrait commandes uniquement	< 100 m²	Drive piéton/auto
`showroom`	Exposition/démonstration	200-800 m²	Démonstration, conseil

Défaut: magasin_centre_ville

Services Disponibles

servicesDisponibles: Services proposés dans les magasins (array)

Valeur	Description
`click_collect`	Retrait en magasin (commande en ligne)
`livraison_domicile`	Livraison à domicile
`installation`	Service d'installation à domicile
`reparation`	Service après-vente/réparation
`reprise`	Reprise ancien matériel
`financement`	Solutions de financement (crédit, etc.)
`extension_garantie`	Extensions de garantie
`formation`	Formation/prise en main produit
`location`	Location de matériel
`maintenance`	Contrats de maintenance

Défaut: ['click_collect']

Schémas d'objets

Produit (ProduitDto)

{
  // Identifiants et champs système
  id: number;                      // Auto-généré
  createdAt: string;               // ISO 8601, auto-géré
  updatedAt: string;               // ISO 8601, auto-géré

  // Identifiants métiers
  ean: string;                     // OBLIGATOIRE - Unique - Code-barres 13 chiffres
  nom: string;                     // OBLIGATOIRE - Nom du produit

  // Prix et garantie
  prixDeVenteCents: number;        // OBLIGATOIRE - Prix en centimes (15000 = 150,00€)
  dureeGarantie?: number;          // Optionnel - Durée de garantie en jours

  // Classification
  categories: string;              // Enum categoriesProduit (défaut: "accessoires")
  marque?: string;                 // Optionnel - Marque du produit
  statutProduit: string;           // Enum statutProduit (défaut: "actif")

  // Description et médias
  description?: string;            // Optionnel - Description détaillée
  photosUrls: string[];            // Array d'URLs (défaut: [])
  documentationUrl?: string;       // Optionnel - Lien vers documentation

  // Caractéristiques physiques
  poids?: string;                  // Optionnel - Format libre (ex: "2.5kg")
  couleurs?: string;               // Optionnel - Format libre (ex: "Noir, Blanc")
  dimensions?: string;             // Optionnel - Format libre (ex: "15x10x5cm")
  caracteristiquesTechniques?: string; // Optionnel - Spécifications techniques

  // Cycle de vie
  dateFinReapprovisionnement?: string; // Optionnel - ISO 8601 (date uniquement)
  dateFinDeVie?: string;           // Optionnel - ISO 8601 (date uniquement)

  // Relations
  produitsComplementairesIds: number[]; // Array d'IDs de produits actifs (défaut: [])
  fournisseurs?: FournisseurProduitDto[]; // Optionnel - Si include=fournisseurs
}

Contraintes:

ean doit être unique
prixDeVenteCents ≥ 0
produitsComplementairesIds ne peut contenir que des IDs de produits actifs existants

Champs dépréciés (ne pas utiliser):

deprecatedSKU → Utiliser ean
deprecatedQuantiteMin → Utiliser la table fournisseur_produits
deprecatedPackaging → Utiliser la table fournisseur_produits
deprecatedPrixDAchatFournisseurCents → Utiliser la table fournisseur_produits

Fournisseur (FournisseurDto)

{
  // Identifiants et champs système
  id: number;                      // Auto-généré
  createdAt: string;               // ISO 8601, auto-géré
  updatedAt: string;               // ISO 8601, auto-géré

  // Identifiants métiers
  nomLegal: string;                // OBLIGATOIRE - Raison sociale
  codeFournisseur: string;         // OBLIGATOIRE - Unique - Code interne

  // Informations légales
  siret?: string;                  // Optionnel - 14 chiffres
  adresse?: string;                // Optionnel - Adresse complète

  // Contact
  email?: string;                  // Optionnel - Email de contact
  telephone?: string;              // Optionnel - Numéro de téléphone
  interlocuteurs: string[];        // Array de noms (défaut: [])

  // Documents et statuts
  documentsContractuelUrls: string[]; // Array d'URLs (défaut: [])
  statut: string;                  // Enum statutFournisseur (défaut: "en_validation")
  statutContractuel: string;       // Enum statutContractuel (défaut: "en_negociation")

  // Relations
  produits?: ProduitSummaryDto[];  // Optionnel - Si include=produits
}

Contraintes:

codeFournisseur doit être unique
siret doit être valide (14 chiffres) si fourni

Champs dépréciés (ne pas utiliser):

deprecatedProduitsFournisSkus → Utiliser la table fournisseur_produits

Entrepôt (EntrepotDto)

{
  // Identifiants et champs système
  id: number;                      // Auto-généré
  createdAt: string;               // ISO 8601, auto-géré
  updatedAt: string;               // ISO 8601, auto-géré

  // Informations de base
  nom: string;                     // OBLIGATOIRE - Nom de l'entrepôt
  adresse: string;                 // OBLIGATOIRE - Adresse complète

  // Spécialisation et capacités
  typeEntrepot: string;            // Enum typeEntrepot (défaut: "generaliste")
  estGrosVolume?: boolean;         // Optionnel - Infrastructure produits volumineux (défaut: false)
  statut: string;                  // Enum statutEntrepot (défaut: "operationnel")

  // Opérationnel
  horaires?: string;               // Optionnel - Format libre
  responsableLogistique?: string;  // Optionnel - Nom du responsable

  // Capacités
  capaciteStockage?: number;       // Optionnel - En unités (palettes, cartons, etc.)
  capaciteLogistique?: number;     // Optionnel - Capacité de traitement

  // Rôles et zone
  rolesLogistiques: string[];      // Array de rôles (défaut: [])
  zoneGeographiqueDesservie?: string; // Optionnel - Région/département
}

Exemples de rolesLogistiques: ["stockage", "expedition", "reception", "preparation_commandes", "cross_docking"]

Magasin (MagasinDto)

{
  // Identifiants et champs système
  id: number;                      // Auto-généré
  createdAt: string;               // ISO 8601, auto-géré
  updatedAt: string;               // ISO 8601, auto-géré

  // Informations de base
  nom: string;                     // OBLIGATOIRE - Nom du magasin
  adresse: string;                 // OBLIGATOIRE - Adresse complète

  // Classification et statut
  type: string;                    // Enum typeMagasin (défaut: "magasin_centre_ville")
  statut: string;                  // Enum statutMagasin (défaut: "ouvert")

  // Services et équipe
  servicesDisponibles: string[];   // Array de services (défaut: ["click_collect"])
  responsable?: string;            // Optionnel - Nom du responsable

  // Caractéristiques physiques
  horaires?: string;               // Optionnel - Format libre
  surfaceVente?: number;           // Optionnel - Surface en m²
  capaciteDAccueil?: number;       // Optionnel - Nombre de personnes
}

Relation Fournisseur-Produit (FournisseurProduitRowDto)

{
  // Identifiants et champs système
  id: number;                      // Auto-généré
  createdAt: string;               // ISO 8601, auto-géré
  updatedAt: string;               // ISO 8601, auto-géré

  // Relations
  fournisseurId: number;           // OBLIGATOIRE - ID du fournisseur
  produitId: number;               // OBLIGATOIRE - ID du produit

  // Informations commerciales
  prixFournisseurCents?: number;   // Optionnel - Prix d'achat en centimes
  delaiLivraisonJours?: number;    // Optionnel - Délai de livraison en jours
  quantiteMinimaleCommande?: number; // Optionnel - Quantité minimale
  referenceFournisseur?: string;   // Optionnel - Référence chez le fournisseur

  // Packaging
  packaging?: number;              // Optionnel - Unités par carton/package

  // Statut
  statutRelation: string;          // Enum statutRelationFournisseur (défaut: "actif")

  // Extensions (si chargées)
  fournisseur?: FournisseurDto;    // Optionnel - Détails du fournisseur
  produit?: ProduitDto;            // Optionnel - Détails du produit
}

Contraintes:

La paire (fournisseurId, produitId) doit être unique
Les IDs doivent référencer des entités existantes

Schémas de réponses

Réponse paginée

Tous les endpoints GET avec pagination retournent ce format :

{
  rows: T[];           // Données de la page courante
  total: number;       // Nombre total d'éléments
  page: number;        // Page courante
  limit: number;       // Éléments par page
  totalPages: number;  // Nombre total de pages
}

Réponse batch update

{
  succes: boolean; // Succès global
  modifies: number; // Nombre d'éléments modifiés
  resultats: Array<{
    index: number; // Index dans le tableau envoyé
    id: number; // ID de l'entité
    ean?: string; // EAN (produits uniquement)
    nomLegal?: string; // Nom légal (fournisseurs uniquement)
    nom?: string; // Nom (entrepôts/magasins)
    statut: 'ok' | 'error'; // Statut de la mise à jour
    erreur?: string; // Message d'erreur si statut = 'error'
  }>;
}

Réponse suppression en lot

{
  succes: boolean; // Succès global
  supprimes: number; // Nombre d'éléments supprimés
  resultats: Array<{
    index: number; // Index dans le tableau d'IDs
    id: number; // ID de l'entité
    ean?: string; // EAN (produits uniquement)
    nomLegal?: string; // Nom légal (fournisseurs uniquement)
    nom?: string; // Nom (entrepôts/magasins)
    statut: 'ok' | 'error'; // Statut de la suppression
  }>;
}

Réponse import

{
  succes: boolean;              // Succès global
  created: number;              // Nombre d'éléments créés
  failed: number;               // Nombre d'échecs
  errors?: Array<{
    line: number;               // Numéro de ligne dans le fichier
    error: string;              // Message d'erreur
  }>
}

Formats de données

Dates

Toutes les dates sont au format ISO 8601 :

Avec heure : 2025-01-25T14:30:00.000Z
Date uniquement : 2025-01-25

Les champs createdAt et updatedAt incluent l'heure. Les champs de cycle de vie (dateFinReapprovisionnement, dateFinDeVie) sont généralement fournis sans heure.

Prix

Tous les prix sont en centimes d'euros (entier) :

15000 = 150,00€
9999 = 99,99€

Pour convertir :

const prixEuros = prixDeVenteCents / 100;
const prixCents = Math.round(prixEuros * 100);

Arrays

Les arrays sont toujours initialisés à [] par défaut si non fournis :

photosUrls: string[]
interlocuteurs: string[]
servicesDisponibles: string[]
rolesLogistiques: string[]

Booléens

estGrosVolume?: boolean - Infrastructure pour produits volumineux
Valeurs possibles : true, false, undefined (si optionnel)

Champs texte libres

Certains champs n'ont pas de format strict :

poids: "2.5kg", "168g", etc.
dimensions: "15x10x5cm", "147x71x7.6mm", etc.
horaires: "10h-20h", "8h-18h du lundi au vendredi", etc.

Validation

Champs obligatoires par entité

Produit:

ean (unique)
nom
prixDeVenteCents

Fournisseur:

nomLegal
codeFournisseur (unique)

Entrepôt:

nom
adresse

Magasin:

nom
adresse

Relation Fournisseur-Produit:

fournisseurId (doit exister)
produitId (doit exister)

Contraintes de validation

EAN: Doit être unique, généralement 13 chiffres
Prix: Doivent être ≥ 0
Email: Format email valide si fourni
SIRET: 14 chiffres si fourni
IDs: Entiers positifs
Arrays batch: 1-500 éléments maximum
Pagination: page 1-1000, limit 1-100

Champs dépréciés

⚠️ Ne pas utiliser ces champs - Ils seront supprimés dans une version future :

Produits:

deprecatedSKU → Utiliser ean
deprecatedQuantiteMin → Gérer via fournisseur_produits
deprecatedPackaging → Gérer via fournisseur_produits
deprecatedPrixDAchatFournisseurCents → Gérer via fournisseur_produits

Fournisseurs:

deprecatedProduitsFournisSkus → Utiliser la table de jointure fournisseur_produits

Exemples complets

Produit complet

{
  "id": 123,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-20T14:45:00.000Z",
  "ean": "1234567890123",
  "nom": "Samsung Galaxy S24 Ultra 256GB",
  "prixDeVenteCents": 129900,
  "dureeGarantie": 730,
  "categories": "telephonie",
  "marque": "Samsung",
  "statutProduit": "actif",
  "description": "Smartphone flagship 2024 avec S Pen intégré",
  "photosUrls": [
    "https://cdn.example.com/s24-ultra-front.jpg",
    "https://cdn.example.com/s24-ultra-back.jpg"
  ],
  "documentationUrl": "https://docs.samsung.com/s24-ultra",
  "poids": "234g",
  "couleurs": "Titanium Black, Titanium Gray, Titanium Violet",
  "dimensions": "162.3 x 79 x 8.6 mm",
  "caracteristiquesTechniques": "Snapdragon 8 Gen 3, 12GB RAM, Ecran 6.8\" Dynamic AMOLED 2X",
  "dateFinReapprovisionnement": null,
  "dateFinDeVie": "2028-12-31",
  "produitsComplementairesIds": [124, 125, 126]
}

Fournisseur complet

{
  "id": 1,
  "createdAt": "2024-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-20T15:30:00.000Z",
  "nomLegal": "Samsung Electronics France SAS",
  "codeFournisseur": "SAMS001",
  "siret": "12345678901234",
  "adresse": "12 rue de Séoul, 75001 Paris",
  "email": "commercial@samsung.fr",
  "telephone": "+33123456789",
  "interlocuteurs": ["Jean Dupont (Commercial)", "Marie Martin (Logistique)"],
  "documentsContractuelUrls": ["https://storage/contrats/samsung-2024.pdf"],
  "statut": "actif",
  "statutContractuel": "valide"
}

Relation complète

{
  "id": 456,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-20T14:45:00.000Z",
  "fournisseurId": 1,
  "produitId": 123,
  "prixFournisseurCents": 95000,
  "delaiLivraisonJours": 5,
  "quantiteMinimaleCommande": 10,
  "referenceFournisseur": "SM-S928B-256GB-BLK",
  "packaging": 12,
  "statutRelation": "prefere"
}

Notes importantes

Le champ deletedAt existe en base de données pour le soft-delete mais n'est jamais exposé dans les réponses API.
Les IDs sont auto-générés et ne peuvent pas être spécifiés lors de la création.
Les champs système (createdAt, updatedAt) sont automatiquement gérés et ne peuvent pas être modifiés manuellement.
Les enums sont sensibles à la casse (toujours en minuscules avec underscores).

Enums métiers​

Statuts Produit​

Catégories Produit​

Statuts Fournisseur​

Statuts Contractuel​

Statuts Relation Fournisseur​

Statuts Entrepôt​

Types Entrepôt​

Statuts Magasin​

Types Magasin​

Services Disponibles​

Schémas d'objets​

Produit (ProduitDto)​

Fournisseur (FournisseurDto)​

Entrepôt (EntrepotDto)​

Magasin (MagasinDto)​

Relation Fournisseur-Produit (FournisseurProduitRowDto)​

Schémas de réponses​

Réponse paginée​

Réponse batch update​

Réponse suppression en lot​

Réponse import​

Formats de données​

Dates​

Prix​

Arrays​

Booléens​

Champs texte libres​

Validation​

Champs obligatoires par entité​

Contraintes de validation​

Champs dépréciés​

Exemples complets​

Produit complet​

Fournisseur complet​

Relation complète​

Notes importantes​

Enums métiers

Statuts Produit

Catégories Produit

Statuts Fournisseur

Statuts Contractuel

Statuts Relation Fournisseur

Statuts Entrepôt

Types Entrepôt

Statuts Magasin

Types Magasin

Services Disponibles

Schémas d'objets

Produit (ProduitDto)

Fournisseur (FournisseurDto)

Entrepôt (EntrepotDto)

Magasin (MagasinDto)

Relation Fournisseur-Produit (FournisseurProduitRowDto)

Schémas de réponses

Réponse paginée

Réponse batch update

Réponse suppression en lot

Réponse import

Formats de données

Dates

Prix

Arrays

Booléens

Champs texte libres

Validation

Champs obligatoires par entité

Contraintes de validation

Champs dépréciés

Exemples complets

Produit complet

Fournisseur complet

Relation complète

Notes importantes