Aller au contenu principal

API Réapprovisionnement - Documentation

Vue d'ensemble​

L'API Réapprovisionnement gère les demandes de réapprovisionnement des magasins en intégration avec l'application achat. Elle fournit les informations essentielles sur chaque demande : statut, catégorie, dates de création et livraison.

🔗 Intégration Achat : Cette API fait partie intégrante du système d'approvisionnement d'entreprise et sert de source de données pour les demandes de réapprovisionnement par magasin.

Architecture​

Principe de fonctionnement​

  • Lecture principalement : API orientée consultation des données de réapprovisionnement
  • Filtrage par magasin : Support du filtrage automatique par identifiant magasin
  • 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/reapprovisionnements​

Récupération de tous les réassorts d'un magasin avec pagination

Paramètres Query​

  • store_id : Requis - Identifiant du magasin (entier > 0)
  • 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​

  • ✅ store_id requis et > 0
  • ✅ page > 0
  • ✅ limit entre 1 et 100
  • ❌ Paramètres manquants ou invalides → HTTP 400 avec message d'erreur

Réponse​

{
  "data": [
    {
      "id": 1,
      "name": "Réapprovisionnement Électronique Q1",
      "createdAt": "2023-01-01",
      "createdBy": "Achat",
      "status": "PENDING",
      "category": "Electronics",
      "shop": 1,
      "deliveryDate": "2023-01-15"
    }
  ],
  "totalItems": 3
}

GET /api/reapprovisionnements/:id​

Récupération d'un réapprovisionnement par son ID

Paramètres​

  • :id : Identifiant numérique du réapprovisionnement

Réponses​

  • 200 OK : Réapprovisionnement trouvé
  • 404 Not Found : Restocking with ID {id} not found

Réponse succès​

{
  "id": 1,
  "name": "Réapprovisionnement Électronique Q1",
  "createdAt": "2023-01-01",
  "createdBy": "Jean Dupont",
  "status": "PENDING",
  "category": "Electronics",
  "shop": 1,
  "deliveryDate": "2023-01-15"
}

Modèle de données​

RestockingDto​

{
  id: number;                    // Identifiant unique
  name: string;                  // Nom du réapprovisionnement
  createdAt?: string;            // Date de création (ISO 8601)
  createdBy?: string;            // Utilisateur créateur
  status?: 'PENDING' | 'COMPLETED' | 'CANCELLED' | 'ACCEPTED'; // Statut
  category?: string;             // Catégorie de produits
  shop?: number;                 // Identifiant du magasin
  deliveryDate?: string;         // Date de livraison prévue (ISO 8601)
}

GetRestockingsQueryDto​

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

RestockingApiResponse​

{
  data: RestockingDto[];         // Liste des réassorts
  totalItems: number;            // Nombre total d'éléments
}

Statuts disponibles​

États de réapprovisionnement​

  • PENDING : En attente de traitement
  • ACCEPTED : Accepté par le service achat
  • COMPLETED : Livraison effectuée
  • CANCELLED : Annulé

Logique métier​

Filtrage par magasin​

  • Obligatoire : Chaque requête doit spécifier un store_id
  • Isolation : Les données sont automatiquement filtrées par magasin
  • Sécurité : Empêche l'accès aux données d'autres magasins

Validation des paramètres​

  • Transformation automatique : Les paramètres query string sont convertis en nombres
  • Valeurs par défaut : Application automatique si paramètres optionnels 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 (store_id manquant, page ≤ 0, limit hors limites)
  • 404 Not Found : Réapprovisionnement inexistant
  • 500 Internal Server Error : Erreurs techniques

Exemples d'utilisation​

Récupération par magasin​

# Réapprovisionnements du magasin 1 (première page)
GET /api/reapprovisionnements?store_id=1

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

# Erreur de validation
GET /api/reapprovisionnements  # → 400 Bad Request (store_id manquant)
GET /api/reapprovisionnements?store_id=0  # → 400 Bad Request (store_id invalide)

Récupération individuelle​

# Réapprovisionnement existant
GET /api/reapprovisionnements/1  # → 200 OK

# Réapprovisionnement inexistant
GET /api/reapprovisionnements/999  # → 404 Not Found

Données de référence​

L'API utilise exclusivement les données provenant de l'application ACHAT externe via l'endpoint /api/publique/restock.

Transformation des données​

Toutes les données sont transformées pour correspondre au format interne et filtrées par magasin :

  • Magasin forcé : Tous les réassorts sont assignés au magasin ID 1
  • Pagination : Appliquée côté serveur après récupération des données
  • Filtrage : Par store_id après transformation

Format des données externes​

L'API externe peut retourner des données dans différents formats (camelCase ou snake_case) qui sont automatiquement normalisées :

{
  "id": 1,
  "name": "Restocking Item",
  "createdAt": "2023-01-01", // ou "created_at"
  "createdBy": "User Name", // ou "created_by"
  "status": "PENDING",
  "category": "Electronics",
  "deliveryDate": "2023-01-15" // ou "delivery_date"
}

Intégration externe​

API Achat (Active)​

L'API est maintenant intégrée avec l'application achat externe :

// Endpoint externe actuel
const baseUrl = this.configService.get('ORIGIN_APP_ACHAT');
const response = await this.httpService.get(`${baseUrl}/api/publique/restock`);

Configuration​

  • Variable d'environnement : ORIGIN_APP_ACHAT
  • Endpoint : /api/publique/restock
  • Paramètres : Aucun (récupère toutes les données)
  • Pagination : Côté serveur après récupération complète
  • Filtrage magasin : Appliqué côté serveur (shop = 1 pour tous les éléments)

Transformation des données​

Les données externes sont transformées pour correspondre au format interne :

const transformedData: RestockingDTO[] = externalData.map(
  (item: any, index: number) => ({
    id: item.id || index + 1,
    name: item.name || `Restocking ${item.id || index + 1}`,
    createdAt: item.createdAt || item.created_at,
    createdBy: item.createdBy || item.created_by,
    status: item.status || 'PENDING',
    category: item.category,
    shop: 1, // Forcé à 1 comme demandé
    deliveryDate: item.deliveryDate || item.delivery_date,
  })
);

Gestion des erreurs​

  • API obligatoire : L'API externe ACHAT est requise pour fonctionner
  • Logging détaillé : Traçabilité complète des appels API
  • Configuration requise : Variable d'environnement ORIGIN_APP_ACHAT obligatoire

Contexte magasin​

L'interface frontend utilise le contexte de magasin sélectionné pour automatiquement filtrer les réassorts appropriés.

Swagger Documentation​

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

Notes de développement​

  • L'API ACHAT externe est maintenant la source de données principale
  • Le filtrage par magasin garantit l'isolation des données (tous forcés à magasin 1)
  • La pagination côté serveur optimise les performances
  • Tous les endpoints suivent les conventions REST standard
  • La variable d'environnement ORIGIN_APP_ACHAT est obligatoire