Aller au contenu principal

API Magasins - Documentation

Vue d'ensemble​

L'API magasins gère le référentiel des magasins de l'entreprise en intégration avec l'application référentiel. Elle fournit les informations essentielles sur chaque point de vente : coordonnées, localisation et moyens de contact.

🔗 Intégration Référentiel : Cette API fait partie intégrante du système de référentiel d'entreprise et sert de source de données master pour les informations magasins.

Architecture​

Principe de fonctionnement​

  • Lecture principalement : API orientée consultation des données magasins
  • Pagination intelligente : Support de la pagination avec validation automatique
  • Validation robuste : Contrôles automatiques des paramètres d'entrée
  • Gestion d'erreurs : Retours HTTP standardisés avec messages explicites

Endpoints disponibles​

GET /api/privee/magasins​

Liste paginée depuis la DB locale

Paramètres Query (optionnels)​

  • page : Numéro de page (défaut: 1, min: 1)
  • limit : Nombre d'éléments par page (défaut: 10, min: 1, max: 100)

Validation automatique​

  • ✅ page > 0
  • ✅ limit entre 1 et 100
  • ❌ Valeurs négatives → HTTP 400 avec message d'erreur

Réponse​

{
  "data": [
    {
      "id": 1,
      "name": "Fnac Paris",
      "address": "14 rue Voltaire",
      "status": "ouvert",
      "openingHours": "Lun-Sam 10h-20h",
      "manager": "Sophie Martin",
      "type": "centre-ville",
      "salesArea": 1500,
      "capacity": 300,
      "services": ["Retrait 1h", "SAV"]
    }
  ],
  "pageNumber": 1,
  "pageLimit": 10,
  "totalItems": 42
}

GET /api/privee/magasins/:id​

Récupération d'un magasin par son ID

Paramètres​

  • :id : Identifiant numérique du magasin

Réponses​

  • 200 OK : Magasin trouvé
  • 404 Not Found : Store with ID {id} not found

Réponse succès​

{
  "id": 1,
  "name": "Fnac Paris",
  "address": "14 rue Voltaire",
  "status": "ouvert",
  "openingHours": "Lun-Sam 10h-20h",
  "manager": "Sophie Martin",
  "type": "centre-ville",
  "salesArea": 1500,
  "capacity": 300,
  "services": ["Retrait 1h", "SAV"]
}

POST /api/privee/magasins/sync​

Déclenche une synchronisation depuis le Référentiel (itère sur les pages via meta.hasNextPage) et upsert en DB locale

Réponses​

{ "synced": 42, "total": 42 }

POST /api/privee/magasins​

** Crée un magasin via le Référentiel, puis sync la DB locale **

Request Body​

{
  "name": "Fnac Part-Dieu",
  "address": "Centre Commercial La Part-Dieu, Lyon",
  "status": "ouvert",
  "openingHours": "Lun-Sam 10h-20h",
  "manager": "Alice Martin",
  "type": "centre-ville",
  "salesArea": 1500,
  "capacity": 300,
  "services": ["drive", "SAV"]
}

Réponses​

  • 201 Created ou 200 OK : StoreDto

PATCH /api/privee/magasins/:id​

Met à jour un magasin via le Référentiel, puis sync la DB locale

Paramètres​

  • :id : Identifiant numérique du magasin

Request Body​

Tous champs optionnels ; seuls ceux fournis sont patchés :

{ "status": "fermé", "openingHours": "Lun-Sam 11h-19h" }

Réponses​

  • 200 OK : StoreDto

DELETE /api/privee/magasins/:id​

supprimer un magasin côté Référentiel, puis synchroniser la DB locale

Paramètres​

  • :id : Identifiant numérique du magasin

Réponses​

{ "deleted": true, "id": 123 }

Modèle de données​

StoreDto​

{
    id: number;
    name: string;
    address: string;
    status: string;
    openingHours?: string;
    manager?: string;
    type?: string;
    salesArea?: number;
    capacity?: number;
    services?: string[];
}

SyncResultDto​

{
  synced: number;
  total: number;
}

UpsertStoreDto​

{
    name: string;
    address: string;
    status: string;

    // Optionnels (POST/PATCH)
    openingHours?: string;
    manager?: string;
    type?: string;
    salesArea?: number;
    capacity?: number;
    services?: string[];
}

PaginationDto​

{
  page?: number;       // Numéro de page (défaut: 1)
  limit?: number;      // Limite par page (défaut: 10, max: 100)
}

Logique métier​

Validation des paramètres​

  • Transformation automatique : Les paramètres query string sont convertis en nombres
  • Valeurs par défaut : Application automatique si paramètres manquants
  • Limites de sécurité : Limite maximum de 100 éléments par page
  • Messages explicites : Erreurs détaillées en cas de validation échouée

Gestion d'erreurs standardisée​

  • 400 Bad Request : Paramètres invalides (page ≤ 0, limit hors limites)
  • 404 Not Found : Magasin inexistant
  • 500 Internal Server Error : Erreurs techniques

Exemples d'utilisation​

Récupération paginée​

# Première page (défaut)
GET /api/magasins

# Page spécifique avec limite
GET /api/magasins?page=2&limit=5

# Erreur de validation
GET /api/magasins?page=0  # → 400 Bad Request

Récupération individuelle​

# Magasin existant
GET /api/magasins/1  # → 200 OK

# Magasin inexistant
GET /api/magasins/999  # → 404 Not Found

Données de référence​

L'API utilise actuellement des données mockées représentant 5 magasins dans les principales villes françaises :

  • Paris (75001)
  • Lyon (69002)
  • Marseille (13001)
  • Toulouse (31000)
  • Nice (06000)

Les données mockées seront remplacées lorsque l'intégration avec referentiel sera opérationnelle.

Swagger Documentation​

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