Aller au contenu principal

API publique et intégration

Cette section explique comment les autres applications peuvent consommer notre API et comprendre nos fonctionnalités.

Accès au Swagger​

Les routes ci-dessus sont exposées par l’application (voir backend/src/main.ts).

Base URL​

Authentification​

  • Public: pas d’authentification sur les routes publiques listées ci-dessous.
  • Interne: certaines routes internes peuvent nécessiter une configuration d’accès au niveau du réseau ou du reverse-proxy.

Conventions générales​

  • Format: JSON UTF-8
  • Champs temporels: ISO 8601 (string) dans les réponses (sérialisation automatique des Date).
  • Soft delete: promotion_data utilise dateSuppression. À ce jour, GET /api/publique/data ne filtre pas automatiquement les entrées “supprimées”.
  • Découverte des endpoints: via Swagger (liens ci-dessus). Les ressources publiques sont préfixées par /api/publique/....
  • Pagination/tri/filtres: non disponibles pour l’instant; exposés dès que nécessaires.

Ressources publiques principales​

Promotion data — /api/publique/data​

Gestion des données de promotions. Voir contrôleur backend/src/promotion-data/promotion-data.controller.ts et schéma backend/src/db/schema.ts (promotionDataTable).

  • GET /api/publique/data → 200: PromotionData[]
  • POST /api/publique/data → 201: PromotionData créé
  • PUT /api/publique/data/:id → 200: PromotionData mis à jour, 404 si non trouvé
  • DELETE /api/publique/data/:id → 204: pas de contenu, 404 si non trouvé
  • POST /api/publique/data/fidelite → 201: PromotionData créé depuis l'application Fidélité

Modèle PromotionData (réponse)​

Champs:

  • Identifiants et dates

    • id: number (identifiant technique)
    • dateCreation: datetime ISO (création)
    • dateModification: datetime ISO (dernière mise à jour)
    • dateSuppression: datetime ISO | null (soft delete)

  • Classification

    • categoriePromotion: EVENT | DESTOCKAGE | FIDELITE | PANIER | PRODUIT | PRODUIT_CATEGORIE
    • typePromotion: POURCENTAGE | MONTANT_FIXE | PRODUIT_OFFERT | SEUIL_PANIER

  • Ciblage (null = tous, tableau = liste d'IDs ciblés)

    • idClient: string[] | null (validé via /api/private/clients/{id})
    • idProduit: string[] | null (validé via le référentiel)
    • idMagasin: string[] | null (validé via /api/private/magasins/{id})
    • categorieProduit: string | null (catégorie de produit ciblée, avec autocomplétion)

  • Valeurs et conditions

    • valeurPromotion: number (montant ou pourcentage selon uniteValeur)
    • uniteValeur: PERCENT ou EURO
    • autoAppliquee: boolean (true par défaut)
    • seuilMontant: number | null (montant minimum en centimes)
    • quantiteAchat: number | null (quantité d'achat requise)
    • description: string (description marketing)

  • Période de validité

    • dateDebut: datetime ISO
    • dateFin: datetime ISO

  • Métadonnées

    • applicationCreatrice: string (origine de la promotion, ex: 'FIDELITE')
    • applicationsConcernees: string[] (applications cibles, parmi: 'FIDELITE', 'E-COMMERCE', 'MAGASIN', 'PROMOTION')

Payload création (POST) exemple​

{
  "categoriePromotion": "FIDELITE",
  "typePromotion": "POURCENTAGE",
  "uniteValeur": "PERCENT",
  "valeurPromotion": 15,
  "dateDebut": "2025-09-27T12:34:56.000Z",
  "dateFin": "2025-10-31T23:59:59.000Z",
  "idClient": ["CLIENT123", "CLIENT456"],
  "idProduit": ["SKU-ABC-123", "SKU-DEF-456"],
  "idMagasin": ["MAG001", "MAG002"],
  "categorieProduit": "ELECTRONIQUE",
  "description": "-10% pour les membres fidèles sur l'électronique",
  "applicationCreatrice": "app-promo",
  "applicationConcernee": "frontend-web",
  "autoAppliquee": true,
  "seuilMontant": 5000,
  "quantiteAchat": 2
}

Payload mise à jour (PUT) exemple​

{
  "valeurPromotion": 20,
  "dateFin": "2025-11-15T23:59:59.000Z",
  "description": "-20% pour les membres fidèles sur l'électronique",
  "seuilMontant": 3000,
  "quantiteAchat": 1
}

Réponse création (201) exemple​

{
  "id": 42,
  "categoriePromotion": "FIDELITE",
  "typePromotion": "POURCENTAGE",
  "uniteValeur": "PERCENT",
  "valeurPromotion": 15,
  "dateDebut": "2025-09-27T12:34:56.000Z",
  "dateFin": "2025-10-31T23:59:59.000Z",
  "idClient": ["CLIENT123", "CLIENT456"],
  "idProduit": ["SKU-ABC-123", "SKU-DEF-456"],
  "idMagasin": ["MAG001", "MAG002"],
  "categorieProduit": "ELECTRONIQUE",
  "description": "-10% pour les membres fidèles sur l'électronique",
  "applicationCreatrice": "app-promo",
  "applicationConcernee": "frontend-web",
  "autoAppliquee": true,
  "seuilMontant": 5000,
  "quantiteAchat": 2,
  "dateCreation": "2025-09-27T12:34:56.000Z",
  "dateModification": "2025-09-27T12:34:56.000Z",
  "dateSuppression": null
}

Erreurs typiques​

  • 400 Bad Request: body mal formé ou types invalides.
  • 404 Not Found: entité non trouvée (PUT, DELETE).
  • 500 Internal Server Error: erreur serveur inattendue.

Fidélité — /api/publique​

Gestion des données clients et création de promotions provenant de l'application Fidélité via la passerelle Kong. Voir contrôleur backend/src/fidelite/fidelite.controller.ts.

  • GET /api/publique/clients → 200: ClientData[] - Liste de tous les clients
  • GET /api/publique/clients/:id → 200: ClientData - Récupère un client par son ID
  • POST /api/publique/promotions → 201: PromotionData - Crée une promotion depuis Fidélité

Modèle ClientData (réponse)​

Champs:

  • id: number (identifiant)
  • civilite: string
  • nom: string
  • prenom: string
  • anniversaire: datetime ISO
  • adresseMail: string
  • telephone: string
  • niveauFidelisation: string (Standard | Platine | Premium)
  • pointsFidelite: number
  • dateDebutFidelisation: datetime ISO
  • createdAt: datetime ISO
  • updatedAt: datetime ISO
  • deletedAt: datetime ISO | null

Autres ressources (internes/non publiques)​

Ces contrôleurs existent dans le code mais ne sont pas exposés sous /api/publique/....

  • Référentiel produits — /api/publique/produits
    • GET /api/publique/produits → 200: liste de tous les produits
    • GET /api/publique/produits/:id → 200: récupère un produit par son ID
    • Voir backend/src/referentiel/referentiel.controller.ts

Paramètres et erreurs typiques​

  • :id est un entier positif.
  • 400 Bad Request: paramètre id invalide, body mal formé.
  • 404 Not Found: entité non trouvée.
  • 422 Unprocessable Entity: violation métier/contraintes (si implémenté côté service/validation).
  • 500 Internal Server Error: erreur serveur inattendue.

Découvrir/essayer l’API​

  • Utiliser le Swagger pour tester les routes et voir les schémas exposés.
  • Les DTOs principaux: CreatePromotionDataDto, UpdatePromotionDataDto (backend/src/promotion-data/dto/...).