📋 API Documentation

Service Paramètre - Gestion des Catégories

📑 Table des Matières

🔍 Vue d'ensemble

L'API des catégories permet de gérer les catégories associées aux stations dans le système ERP. Cette API suit les principes de l'architecture microservices et ne contient pas de contraintes de clés étrangères.

ℹ️ Architecture Microservices

Cette API ne contient pas de clés étrangères vers d'autres services. La validation des stations se fait via des appels API inter-services.

Base URL

http://192.168.1.14:4000/api/settings/categorie

Authentification

Actuellement, aucune authentification n'est requise pour accéder à cette API.

🚀 Endpoints

GET Récupérer une catégorie par ID

GET /api/settings/categorie/id/:id
Récupère une catégorie spécifique par son ID.

Paramètres de l'URL

id
Integer
ID de la catégorie (obligatoire)
GET /api/settings/categorie/id/1
200 OK Réponse en cas de succès 
{
  "success": true,
  "categorie": {
    "id": 1,
    "station_id": 1,
    "user_id": 1,
    "libelle": "Catégorie Test",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
404 Not Found Catégorie introuvable 
{
  "success": false,
  "message": "Catégorie introuvable"
}

GET Récupérer les catégories par station

GET /api/settings/categorie/:station_id
Récupère toutes les catégories associées à une station spécifique.

Paramètres de l'URL

station_id
Integer
ID de la station (obligatoire)
GET /api/settings/categorie/1
200 OK Réponse en cas de succès 
{
  "success": true,
  "categories": [
    {
      "id": 1,
      "station_id": 1,
      "user_id": 1,
      "libelle": "Catégorie Test",
      "created_at": "2024-01-01T10:00:00.000Z",
      "updated_at": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "filters": {
    "station_id": 1
  }
}

GET Récupérer les catégories par utilisateur et station

GET /api/settings/categorie/:user_id/:station_id
Récupère toutes les catégories associées à un utilisateur et une station spécifiques.

Paramètres de l'URL

user_id
Integer
ID de l'utilisateur (obligatoire)
station_id
Integer
ID de la station (obligatoire)
GET /api/settings/categorie/1/2
200 OK Réponse en cas de succès 
{
  "success": true,
  "categories": [
    {
      "id": 1,
      "station_id": 2,
      "user_id": 1,
      "libelle": "Catégorie Test",
      "created_at": "2024-01-01T10:00:00.000Z",
      "updated_at": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "filters": {
    "user_id": 1,
    "station_id": 2
  }
}

POST Créer une nouvelle catégorie

POST /api/settings/categorie
Crée une nouvelle catégorie pour une station et un utilisateur donnés.

Corps de la requête (JSON)

station_id
Integer
ID de la station (obligatoire)
user_id
Integer
ID de l'utilisateur (obligatoire)
libelle
String
Libellé de la catégorie (obligatoire, max 255 caractères)
POST /api/settings/categorie
Content-Type: application/json

{
  "station_id": 1,
  "user_id": 1,
  "libelle": "Nouvelle catégorie"
}
200 OK Réponse en cas de succès 
{
  "success": true,
  "message": "Catégorie créée avec succès",
  "categorie": {
    "id": 1,
    "station_id": 1,
    "user_id": 1,
    "libelle": "Nouvelle catégorie",
    "created_at": "2024-01-01T10:00:00.000Z",
    "updated_at": "2024-01-01T10:00:00.000Z"
  }
}

PUT Mettre à jour une catégorie

PUT /api/settings/categorie/:id
Met à jour une catégorie existante. Tous les champs sont optionnels.

Paramètres de l'URL

id
Integer
ID de la catégorie à modifier (obligatoire)

Corps de la requête (JSON)

station_id
Integer
Nouvel ID de la station (optionnel)
user_id
Integer
Nouvel ID de l'utilisateur (optionnel)
libelle
String
Nouveau libellé (optionnel, max 255 caractères)
PUT /api/settings/categorie/1
Content-Type: application/json

{
  "libelle": "Catégorie modifiée"
}
200 OK Réponse en cas de succès 
{
  "success": true,
  "message": "Catégorie mise à jour avec succès",
  "categorie": {
    "id": 1,
    "station_id": 1,
    "user_id": 1,
    "libelle": "Catégorie modifiée",
    "created_at": "2024-01-01T10:00:00.000Z",
    "updated_at": "2024-01-01T11:00:00.000Z"
  }
}

📊 Modèles de Données

Modèle Catégorie

id
Integer
Identifiant unique (clé primaire, auto-incrémenté)
station_id
Integer
ID de la station associée (obligatoire)
user_id
Integer
ID de l'utilisateur propriétaire (obligatoire)
libelle
String(255)
Libellé de la catégorie (obligatoire, unique par station)
created_at
Timestamp
Date de création (automatique)
updated_at
Timestamp
Date de dernière modification (automatique)

🔑 Contraintes

• Le libellé doit être unique par station
• Aucune contrainte de clé étrangère (architecture microservices)
• Les timestamps sont gérés automatiquement par Sequelize

💡 Exemples d'Utilisation

JavaScript (Fetch API)

// Récupérer les catégories d'une station
fetch('http://192.168.1.14:4000/api/settings/categorie/1')
  .then(response => response.json())
  .then(data => console.log(data));

// Créer une nouvelle catégorie
fetch('http://192.168.1.14:4000/api/settings/categorie', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    station_id: 1,
    user_id: 1,
    libelle: 'Nouvelle catégorie'
  })
})
.then(response => response.json())
.then(data => console.log(data));

cURL

# Récupérer les catégories par station
curl -X GET "http://192.168.1.14:4000/api/settings/categorie/1"

# Récupérer les catégories par user et station
curl -X GET "http://192.168.1.14:4000/api/settings/categorie/1/2"

# Créer une catégorie
curl -X POST "http://192.168.1.14:4000/api/settings/categorie" \
  -H "Content-Type: application/json" \
  -d '{
    "station_id": 1,
    "user_id": 1,
    "libelle": "Nouvelle catégorie"
  }'

# Modifier une catégorie
curl -X PUT "http://192.168.1.14:4000/api/settings/categorie/1" \
  -H "Content-Type: application/json" \
  -d '{
    "libelle": "Catégorie modifiée"
  }'

❌ Gestion des Erreurs

Codes d'Erreur Communs

400 Bad Request Paramètres manquants ou invalides 
{
  "success": false,
  "message": "station_id est obligatoire"
}
400 Bad Request Libellé déjà existant 
{
  "success": false,
  "message": "Une catégorie avec ce libellé existe déjà pour cette station"
}
500 Internal Server Error Erreur serveur 
{
  "success": false,
  "message": "Erreur serveur",
  "error": "Détails de l'erreur technique"
}

Messages d'Erreur Spécifiques

  • station_id est obligatoire - Le paramètre station_id est manquant
  • user_id et station_id sont obligatoires - Les deux paramètres sont requis
  • Tous les champs sont obligatoires - Champs manquants lors de la création
  • Le libellé doit être une chaîne non vide - Validation du libellé
  • Une catégorie avec ce libellé existe déjà pour cette station - Contrainte d'unicité
  • Catégorie introuvable - ID de catégorie inexistant

📝 Notes Importantes

🏗️ Architecture Microservices

Cette API ne contient pas de contraintes de clés étrangères. La validation des stations et utilisateurs se fait via des appels API inter-services.

🔄 Tri des Résultats

Toutes les requêtes de récupération trient les résultats par date de création décroissante (plus récent en premier).

✅ Validation

• Le libellé est automatiquement nettoyé (trim)
• L'unicité du libellé est vérifiée par station
• Les paramètres numériques sont convertis en entiers

🌐 Gateway

Cette API est accessible via le gateway sur le port 4000. Le service direct est disponible sur le port 3002.