API Produits

Lister les produits

GET /v1/products

Paramètre	Type	Description
`skip`	integer	Pagination offset
`take`	integer	Pagination limite
`search`	string	Recherche par nom ou référence
`categoryId`	string	Filtrer par catégorie
`lowStock`	boolean	Uniquement les produits sous le seuil

Obtenir un produit

GET /v1/products/{id}

Réponse :

{
  "id": "clxprd001",
  "reference": "PRD-0042",
  "name": "Ordinateur portable Dell XPS",
  "description": "Dell XPS 13, 16 Go RAM, 512 Go SSD",
  "salePrice": 850000,
  "purchasePrice": 600000,
  "taxRate": {
    "id": "clxtax001",
    "name": "TVA 18%",
    "rate": 18
  },
  "unit": {
    "id": "clxunit01",
    "name": "Pièce",
    "symbol": "pce"
  },
  "stock": {
    "quantity": 12,
    "alertThreshold": 3,
    "isLow": false
  },
  "status": "ACTIVE",
  "createdAt": "2026-02-10T09:00:00Z"
}

Créer un produit

POST /v1/products

{
  "name": "Ordinateur portable Dell XPS",
  "description": "Dell XPS 13, 16 Go RAM, 512 Go SSD",
  "salePrice": 850000,
  "purchasePrice": 600000,
  "taxRateId": "clxtax001",
  "unitId": "clxunit01",
  "categoryId": "clxcat002",
  "trackStock": true,
  "initialStock": 10,
  "alertThreshold": 3
}

Contraintes métier

name est obligatoire.
salePrice et purchasePrice doivent être des montants positifs.
Si trackStock est true, initialStock et alertThreshold doivent être cohérents.
Les ajustements de stock doivent rester traçables (raison + date).

Modifier un produit

PATCH /v1/products/{id}

Mouvements de stock

GET /v1/products/{id}/stock-movements

Retourne l'historique des entrées/sorties de stock pour ce produit.

Ajustement de stock manuel

POST /v1/products/{id}/stock-adjustments

{
  "quantity": 5,
  "type": "IN",
  "reason": "Réception fournisseur",
  "date": "2026-05-10"
}

Champ `type`	Description
`IN`	Entrée de stock
`OUT`	Sortie de stock
`ADJUSTMENT`	Ajustement inventaire

Erreurs fréquentes

Code HTTP	`error.code`	Cas typique
`400`	`VALIDATION_ERROR`	Prix/quantité invalide
`404`	`NOT_FOUND`	Produit introuvable
`409`	`CONFLICT`	État incompatible pour l'opération
`422`	`BUSINESS_RULE_ERROR`	Sortie de stock impossible selon vos règles métier

Exemple d'erreur de stock :

{
  "error": {
    "code": "BUSINESS_RULE_ERROR",
    "message": "Mouvement refusé : quantité insuffisante pour une sortie de stock."
  }
}

Bonnes pratiques d'intégration

Utilisez lowStock=true pour alimenter vos alertes de réapprovisionnement.
Évitez les ajustements concurrents sur un même produit sans contrôle applicatif.
Conservez dans votre SI externe la référence du mouvement pour audit et rapprochement.

Produits

On this page