Référence technique

Présentation de l’API

56 section(s)

API AuditStock

Change logs

v16.0 → v17.0 — BREAKING CHANGE (23 octobre 2026)

La v17.0 devient la seule version prise en charge. Toutes les versions antérieures à 17 sont retirées du routage et de la documentation OpenAPI, et non simplement dépréciées. Chaque appel doit cibler explicitement /api/v17/... ; les anciennes URLs et les URLs sans version ne sont pas redirigées vers la v17.

La rupture concerne aussi les unités des achats, des réceptions et des prix : un produit peut être acheté par fût, carton ou rouleau tout en étant vendu et stocké au litre, à l’unité ou au mètre. Les paramètres supplémentaires restent facultatifs pour les intégrations qui achètent et vendent dans la même unité.

Élément concerné	Changement en v17	Adaptation de l’intégration
URLs de l’API	Versions antérieures à 17 et alias sans version retirés, pour les imports, le catalogue et les fonctions communes	Remplacer les URLs par `/api/v17/...` ; ne pas compter sur une version implicite
OpenAPI et Scalar	Un seul document : `/openapi/v17.json`, disponible dans Scalar à `/api`	Régénérer les clients depuis le schéma v17
Données existantes	Bascule sur une base recréée, sans migration des anciennes données	Prévoir un réimport global complet des produits et documents depuis la source
Ligne d’achat	Quantité et prix exprimés dans le conditionnement d’achat ; coefficient transmis par la commande	Fournir le contenu du conditionnement lorsque l’achat diffère du stock
Ligne de réception	Quantité réelle exclusivement exprimée dans l’unité de vente/stock	Envoyer `205` pour 205 litres reçus, et non `1` pour un fût reçu
Paramètres omis	Aucun héritage de conversion depuis une fiche fournisseur ou une autre commande	Transmettre le coefficient sur chaque ligne d’achat concernée ; absent, il vaut 1
Rapprochement des réceptions	Suivi par ligne d’achat ; les rapprochements ambigus sont refusés	Transmettre une référence de ligne stable lorsqu’un produit apparaît plusieurs fois

Unités de vente, de stock et conditionnements d’achat

L’API est la seule source de ces paramètres. AuditStock les affiche en lecture seule : ils ne sont pas saisis lors de la réception.

Un code produit possède une seule unité commune à la vente et au stock. Cette unité ne peut plus être modifiée après les premières opérations ; un changement nécessite un nouveau code produit.
Un couple produit/fournisseur possède un seul conditionnement d’achat. Proposer simultanément un bidon et un fût chez un même fournisseur nécessite deux produits distincts.
Des fournisseurs différents peuvent proposer des conditionnements différents pour le même produit : par exemple un fût de 208 litres chez A et un fût de 200 litres chez B.
Les paramètres de chaque commande sont conservés sur ses lignes. Une évolution ultérieure de la fiche fournisseur ne modifie pas les anciennes commandes.

Nouveaux champs des contrats d’import

Les noms ci-dessous sont ceux du corps JSON. Tous ces champs sont optionnels ; ne pas inventer une unité ou un coefficient pour un produit qui n’a pas besoin de conversion.

Contrat	Champ JSON	Type	Signification / si le champ est absent
`ProductImport`	`saleUnitName`	string nullable	Nom de l’unité commune à la vente et au stock ; absent, ne modifie pas l’unité d’un produit existant
`ProductImport`	`quantityUnitType`	enum nullable	Mode de quantité du produit ; absent, conserve les règles habituelles d’import
`PurchaseItem`	`saleUnitName`	string nullable	Unité commune au produit ; si elle est fournie, elle doit respecter son unité déjà utilisée
`PurchaseItem`	`saleQuantityUnitType`	enum nullable	Mode de quantité de vente/stock du produit
`PurchaseItem`	`purchaseUnitName`	string nullable	Nom du conditionnement acheté : `Fût`, `Litre`, `Mètre`, `Unité`, `Carton`…
`PurchaseItem`	`stockUnitsPerPurchaseUnit`	decimal nullable	Quantité de stock contenue dans un conditionnement ; absent ou `null` : coefficient effectif 1 sur cette ligne
`PurchaseItem`	`purchaseQuantityUnitType`	enum nullable	Mode entier ou décimal de la quantité achetée ; absent, n’ajoute pas de contrainte de quantité entière
`PurchaseItem`	`sourceLineCode`	string nullable	Référence stable de la ligne dans la commande source ; les références fournies doivent être uniques dans la commande
`ReceptionItem`	`purchaseLineCode`	string nullable	Référence `sourceLineCode` de la ligne d’achat réceptionnée ; sans référence, le rapprochement doit rester non ambigu
`ReceptionItem`	`saleUnitName`	string nullable	Unité de contrôle de la réception ; fournie, elle doit correspondre à l’unité de stock attendue

Les modes de quantité sont 0 = entier et 1 = décimal. Les modes d’achat et de vente sont indépendants : acheter uniquement des fûts entiers n’empêche pas de vendre des litres fractionnaires. Une réception complémentaire de 3 litres ne constitue pas un achat de fraction de fût.

Quantités, prix d’achat et calcul de conversion

Champ / valeur	Unité attendue en v17
`PurchaseItem.quantity`	Nombre de conditionnements achetés
`PurchaseItem.unitPurchasePriceWithoutTax`	Prix HT d’un conditionnement d’achat
Quantité attendue en stock	`quantity × stockUnitsPerPurchaseUnit` ; coefficient effectif 1 si absent
Montant d’achat HT	`quantity × unitPurchasePriceWithoutTax`
`ReceptionItem.quantity`	Quantité réellement reçue dans l’unité de vente/stock ; aucune seconde conversion à la réception
Coût nominal par unité de stock	`unitPurchasePriceWithoutTax ÷ stockUnitsPerPurchaseUnit` ; coefficient effectif 1 si absent

Exemple : 1 fût de 208 litres à 832 € HT représente 208 litres attendus, un montant d’achat de 832 € HT et un coût nominal de 4 € HT/litre. Les coûts unitaires transmis sur les documents de vente restent exprimés par unité de vente/stock, soit par litre dans cet exemple.

**Paramètres absents 😗* une commande sans stockUnitsPerPurchaseUnit est traitée avec le coefficient 1, même si le même produit avait été acheté précédemment en fûts de 208 litres. Ne pas omettre le coefficient en espérant qu’AuditStock le retrouve. Les imports sans particularité de conditionnement conservent ainsi le fonctionnement courant.

Réceptions partielles, reliquats et solde forcé

Le reliquat correspond à la quantité attendue en stock moins le cumul réellement reçu, avec un minimum de zéro. Le montant d’achat n’est pas recalculé en fonction des quantités reçues.

Étape pour la commande de 1 fût	Entrée en stock	Reste à recevoir	Montant d’achat HT
Commande : 1 × 208 litres	—	208 litres	832 €
Première réception API : 205 litres	205 litres	3 litres	832 €
Réception complémentaire API : 3 litres	3 litres	0 litre	832 €
Autre possibilité : solde forcé après la première réception	Aucune entrée supplémentaire	Reliquat fermé ; stock reçu maintenu à 205 litres	832 €

Le solde forcé ne crée pas les litres manquants et ne redistribue pas automatiquement leur coût sur les litres déjà reçus. Dans cet exemple, le coût nominal reste 4 € HT/litre : 205 litres reçus sont valorisés 820 € HT, tandis que le montant commandé reste 832 € HT.

Les réceptions doivent utiliser des codes de document distincts pour des livraisons complémentaires. Réutiliser le code d’une réception correspond à son réimport ou à sa correction, pas à l’ajout d’une nouvelle livraison. Un réimport identique ne doit pas doubler le stock.

Exemples d’appels v17

Ajouter l’en-tête X-Api-Key habituel. Les enveloppes des requêtes restent purchase et reception.

POST /api/v17/imports/import-purchase

{
  "purchase": {
    "code": "ACH-2026-001",
    "supplierCode": "FOURNISSEUR-A",
    "supplierName": "Fournisseur A",
    "creationDate": "2026-10-23T08:00:00Z",
    "items": [{
      "productCode": "HUILE-001",
      "productDesignation": "Huile vendue au litre",
      "supplierProductCode": "HUILE-FUT-208",
      "quantity": 1,
      "unitPurchasePriceWithoutTax": 832,
      "saleUnitName": "Litre",
      "saleQuantityUnitType": 1,
      "purchaseUnitName": "Fût",
      "stockUnitsPerPurchaseUnit": 208,
      "purchaseQuantityUnitType": 0,
      "sourceLineCode": "L001",
      "productType": 0
    }]
  }
}

POST /api/v17/imports/import-reception — première livraison de 205 litres :

{
  "reception": {
    "code": "REC-2026-001",
    "purchaseCode": "ACH-2026-001",
    "warehouseName": "PRINCIPAL",
    "receptionDate": "2026-10-23T09:00:00Z",
    "items": [{
      "productCode": "HUILE-001",
      "supplierProductCode": "HUILE-FUT-208",
      "quantity": 205,
      "saleUnitName": "Litre",
      "purchaseLineCode": "L001"
    }]
  }
}

Pour recevoir les 3 litres restants, envoyer une autre réception vers le même endpoint, avec un nouveau reception.code, le même purchaseCode, le même purchaseLineCode et quantity: 3.

Paramètres de l’import d’une commande fournisseur

POST /api/v17/imports/import-purchase reçoit un objet purchase contenant la commande complète. Son code identifie la commande : réutiliser ce code pour la mettre à jour et transmettre toutes ses lignes, pas seulement celles qui changent. Cet import de commande ne remplace pas l’import des quantités réellement réceptionnées.

Champ de `purchase`	Rôle et exemple
`code`	Référence unique et stable de commande dans la source, par exemple `ACH-2026-001`
`supplierCode`	Code interne du fournisseur, par exemple `SUP-001` ; ne pas confondre avec la référence fournisseur d’un produit
`supplierName`	Nom du fournisseur, utilisé notamment lors de sa création
`companyName`	Société rattachée à la commande, facultative ; retrouvée ou créée par son nom si renseignée
`creationDate`	Date de la commande au format ISO 8601 ; UTC recommandé, par exemple `2026-10-23T08:00:00Z`
`items`	Liste non vide des lignes de commande
`importFileName`	Facultatif : nom du fichier source sans chemin (512 caractères maximum), pour la traçabilité ; aucun fichier n’est téléchargé depuis ce champ
`isBalanced`	Booléen, `false` par défaut. Appliqué une fois lors de l’import global : `true` entraîne le solde forcé à l’étape dédiée, après traitement des documents et avant l’inventaire. L’import individuel ne l’applique pas directement

Le solde forcé par isBalanced: true reprend l’état soldé de la commande dans le système source, même si la quantité reçue est inférieure à la quantité attendue. Il clôt le reliquat sans créer de réception fictive ni modifier le montant d’achat. Par exemple, pour un fût de 208 litres à 832 € dont seuls 205 litres ont été reçus, l’import global conserve les 205 litres réellement reçus et les 832 € d’achat, puis solde les 3 litres restants. Avec isBalanced: false, cet indicateur ne demande aucun solde forcé : le reliquat reste ouvert tant qu’il n’est pas réceptionné ou soldé par une autre action.

Chaque élément de items décrit une ligne :

Champ de ligne	Rôle et règle
`productCode`	Code interne du produit, stable entre la commande et la réception
`supplierProductCode`	Référence commerciale du produit chez ce fournisseur, par exemple `HUILE-FUT-208`
`productDesignation`	Désignation lisible du produit, par exemple `Huile vendue au litre`
`productType`	Nature du produit : 0 = Material, 1 = Service, 2 = NonAuditable ; détails ci-dessous. Omis : 0
`quantity`	Nombre de conditionnements commandés, strictement positif. Avec un mode d’achat entier, aucune fraction n’est autorisée. Zéro est refusé ; les lignes négatives sont ignorées avec avertissement
`unitPurchasePriceWithoutTax`	Prix HT d’un conditionnement, positif ou nul. Le montant de ligne est `quantity × unitPurchasePriceWithoutTax`
`saleUnitName`	Facultatif : nom de l’unité commune à la vente et au stock ; absent ou `null`, ne modifie pas l’unité existante
`saleQuantityUnitType`	Facultatif : `0` = Integer (entier), `1` = Decimal (décimal), pour la vente et le stock
`purchaseUnitName`	Facultatif : nom du conditionnement d’achat, par exemple `Fût`
`purchaseQuantityUnitType`	Facultatif : `0` = Integer (conditionnements entiers), `1` = Decimal (fractions autorisées). Indépendant du mode de vente
`stockUnitsPerPurchaseUnit`	Facultatif : nombre d’unités de stock par conditionnement, strictement positif. Absent ou `null` : 1 pour cette commande, sans héritage
`sourceLineCode`	Facultatif : référence stable de ligne, unique dans la commande. À transmettre pour lever les ambiguïtés entre plusieurs lignes du même produit ; voir l’exemple de rapprochement ci-dessous
`productCategoryBreadcrumb`	Chemin de catégories séparées par `/`, par exemple `Lubrifiants/Huiles moteur` ; chaîne vide si non renseigné
`productUrl`	Facultatif : URL publique de la fiche produit
`productImageUrl`	Facultatif : URL de l’image produit
`barCode`	Facultatif : code-barres du produit, transmis comme une chaîne de caractères

Les noms d’unités et les références de ligne fournis sont des textes bruts de 100 caractères au maximum. Les quantités et le coefficient doivent respecter la précision de six décimales et les limites de capacité décrites plus haut.

Choisir productType selon la nature du produit :

Valeur JSON	Nom	Utilisation
`0`	`Material` — Manufacturé	Marchandise physique stockable : huile, gourde, vis. C’est le cas courant et la valeur par défaut
`1`	`Service` — Service	Prestation, par exemple une heure de maintenance. Ce n’est pas la valeur à utiliser pour une gourde ou un fût d’huile suivi en stock
`2`	`NonAuditable` — Non auditable	Produit exclu de l’audit stock

Ces noms expliquent les valeurs numériques : les exemples JSON utilisent les nombres 0, 1 ou 2. productType ne désigne ni une unité, ni un conditionnement, ni un mode de quantité. L’achat de fût présenté plus haut correspond à productType: 0, saleQuantityUnitType: 1 (litres décimaux) et purchaseQuantityUnitType: 0 (fûts entiers).

Paramètres de l’import d’une réception fournisseur

POST /api/v17/imports/import-reception reçoit un objet reception décrivant une livraison réelle. Les quantités sont toujours exprimées dans l’unité de vente/stock, même si la commande est exprimée en fûts, cartons ou rouleaux. La réception ne nécessite aucune saisie manuelle : le système source transmet les valeurs réelles par l’API.

Champ de `reception`	Rôle et règle
`code`	Obligatoire : référence unique et stable de cette réception, par exemple `REC-2026-001`. Même code = réimport ou correction ; nouveau code = autre réception
`purchaseCode`	Obligatoire : `code` de la commande fournisseur, par exemple `ACH-2026-001`. La chaîne spéciale `"0"` désigne une réception sans commande
`warehouseName`	Obligatoire : nom de l’entrepôt destinataire, par exemple `PRINCIPAL`. L’entrepôt est retrouvé ou créé par son nom
`receptionDate`	Date réelle de réception au format ISO 8601 ; UTC recommandé, par exemple `2026-10-23T09:00:00Z`
`items`	Liste complète des lignes de cette réception, non vide pour une nouvelle réception. Lors d’une correction d’une réception existante, une liste vide permet d’en retirer les lignes
`importFileName`	Facultatif : nom du fichier source sans chemin, limité à 512 caractères, pour la traçabilité ; aucun téléchargement de fichier

Chaque élément de items décrit les quantités reçues sur une ligne :

Champ de ligne	Rôle et règle
`productCode`	Obligatoire : code interne du produit reçu ; doit correspondre au produit de la ligne de commande ciblée
`supplierProductCode`	Obligatoire : référence du produit chez le fournisseur, par exemple `HUILE-FUT-208`. Ce n’est pas une référence de ligne
`quantity`	Quantité réellement reçue dans l’unité de vente/stock, strictement positive et représentable avec au plus six décimales. Respecter le mode entier ou décimal du stock, indépendamment du mode d’achat
`saleUnitName`	Facultatif : nom de l’unité de vente/stock, par exemple `Litre`. S’il est fourni, il doit correspondre à l’unité attendue ; il ne modifie pas l’unité du produit et ne convertit pas la quantité
`purchaseLineCode`	Facultatif si le rapprochement par produit est unique ; nécessaire pour lever une ambiguïté. Reprendre le `sourceLineCode` de la ligne de commande. Une référence fournie doit exister pour le même produit dans la commande indiquée

Les noms d’unités et les références de ligne fournis sont des textes bruts de 100 caractères au maximum. Une réception ne peut pas comporter plusieurs entrées pour la même ligne d’achat : regrouper sa quantité reçue dans une seule entrée. Les lignes de quantité nulle sont refusées. Les lignes négatives sont ignorées avec avertissement ; elles ne permettent pas d’importer un retour fournisseur. Un document entièrement négatif est ignoré sans effet métier.

Exemple complet : réception partielle d’un fût acheté à 832 € pour 208 litres attendus. La commande ACH-2026-001 possède la ligne sourceLineCode: "L001", le produit HUILE-001 et l’unité de stock Litre.

{
  "reception": {
    "code": "REC-2026-001",
    "purchaseCode": "ACH-2026-001",
    "warehouseName": "PRINCIPAL",
    "receptionDate": "2026-10-23T09:00:00Z",
    "importFileName": "reception-REC-2026-001.json",
    "items": [
      {
        "productCode": "HUILE-001",
        "supplierProductCode": "HUILE-FUT-208",
        "purchaseLineCode": "L001",
        "saleUnitName": "Litre",
        "quantity": 205
      }
    ]
  }
}

AuditStock reçoit 205 litres, laisse 3 litres de reliquat et conserve le montant d’achat de 832 €. Le coût nominal reste 4 €/litre (832 / 208). Il ne faut envoyer ni quantity: 1 pour le fût ni quantity: 42640 (205 × 208) : le coefficient d’achat n’est pas appliqué une seconde fois.

Pour réceptionner les 3 litres complémentaires, envoyer une nouvelle réception, sans cumuler les quantités de la première :

{
  "reception": {
    "code": "REC-2026-002",
    "purchaseCode": "ACH-2026-001",
    "warehouseName": "PRINCIPAL",
    "receptionDate": "2026-10-24T09:00:00Z",
    "items": [
      {
        "productCode": "HUILE-001",
        "supplierProductCode": "HUILE-FUT-208",
        "purchaseLineCode": "L001",
        "saleUnitName": "Litre",
        "quantity": 3
      }
    ]
  }
}

Envoi	Effet
`REC-2026-001`, quantité `205`	Première réception de 205 litres, reliquat de 3 litres
Même `REC-2026-001`, contenu inchangé	Réimport détecté comme déjà traité ; pas de deuxième entrée de stock
`REC-2026-002`, quantité `3`	Réception complémentaire ; total reçu de 208 litres, reliquat nul
Même code d’une réception existante, quantité corrigée	Correction de cette réception, pas un ajout de la quantité transmise au contenu précédent

Pour corriger une réception, réutiliser son code et transmettre toutes les lignes à conserver avec leurs nouvelles quantités absolues. Par exemple, remplacer 205 par 204 sur REC-2026-001 corrige cette première réception à 204 litres ; ne pas envoyer -1 comme delta. Une liste items: [] est autorisée pour retirer les lignes d’une réception existante, mais pas pour créer une nouvelle réception. Une ligne d’achat déjà soldée n’accepte pas de quantité supplémentaire ; une correction ne peut alors pas augmenter la quantité de cette réception.

Prix et nature du produit : la réception ne transmet pas unitPurchasePriceWithoutTax, productType, purchaseUnitName, stockUnitsPerPurchaseUnit ou de mode de quantité. Ces paramètres proviennent de la commande et du produit. Pour une réception rattachée, le coût nominal est celui de la ligne d’achat ramené à l’unité de stock. Un écart de réception ne recalcule pas le montant d’achat ; le reliquat attend un complément ou un solde forcé. L’indicateur isBalanced appartient à la commande et est appliqué lors de l’import global, comme décrit plus haut.

Cas particuliers et résultat d’import :

Si purchaseCode désigne une commande absente, la réception est conservée en attente ; ce n’est pas une réception sans commande. Son rapprochement ultérieur dépend du traitement des documents en attente, notamment lors de l’import global.
Pour une réception volontairement sans commande, transmettre purchaseCode: "0" et omettre purchaseLineCode. Le même produit ne peut apparaître qu’une fois dans cette réception ; le coût provient du produit, en l’absence de ligne d’achat.
Si une référence purchaseLineCode fournie est introuvable, si le produit ne correspond pas, si l’unité est incohérente ou si plusieurs lignes correspondent sans référence, le traitement signale une erreur. Sans référence explicite, certains cas sans ligne ouverte correspondante produisent un avertissement : vérifier le résultat, pas seulement le statut HTTP.
Consulter systématiquement status, errors et warnings. Une mise en attente ou en file de traitement ne signifie pas que le stock a déjà été mis à jour.

Rôle de `sourceLineCode` et de `purchaseLineCode`

sourceLineCode identifie une ligne de la commande dans le système source. Ce n’est ni le code produit, ni le code de la commande. La valeur "sourceLineCode": null, notamment dans une commande récupérée par l’API, signifie qu’aucune référence de ligne source n’a été transmise.

Lors de l’import d’une réception, purchaseCode désigne la commande et purchaseLineCode reprend la valeur de sourceLineCode pour désigner la ligne réceptionnée. Le productCode doit également correspondre à celui de cette ligne.

Situation	Utilisation des références de ligne
Une seule ligne d’achat correspond au produit réceptionné	Champs facultatifs ; absents ou `null`, AuditStock tente le rapprochement par produit
Plusieurs lignes d’achat peuvent correspondre au même produit	Références nécessaires pour lever l’ambiguïté ; sans `purchaseLineCode`, la réception ambiguë est refusée
Une référence est transmise dans la réception	Elle doit correspondre à une référence `sourceLineCode` existante pour le même produit dans la commande indiquée
Réimport de commande ou réception complémentaire	Conserver la référence stable de la ligne ; ne pas en créer une nouvelle à chaque envoi

Il est recommandé de transmettre systématiquement ces références lorsque la source les possède, et en particulier pour les commandes contenant plusieurs lignes d’un même produit. Les références fournies doivent être uniques au sein de la commande ; une autre commande peut réutiliser L001.

Exemple de deux lignes du même produit dans la commande ACH-2026-002 : les extraits suivants montrent uniquement les champs utiles au rapprochement, à intégrer aux corps complets d’import présentés plus haut.

{
  "purchase": {
    "code": "ACH-2026-002",
    "items": [
      { "productCode": "PROD-001", "sourceLineCode": "L001", "quantity": 10 },
      { "productCode": "PROD-001", "sourceLineCode": "L002", "quantity": 10 }
    ]
  }
}

Pour réceptionner 3 unités sur la deuxième ligne, transmettre purchaseLineCode: "L002" :

{
  "reception": {
    "code": "REC-2026-002",
    "purchaseCode": "ACH-2026-002",
    "items": [
      { "productCode": "PROD-001", "purchaseLineCode": "L002", "quantity": 3 }
    ]
  }
}

La réception est ainsi rattachée à L002, sans affecter L001. Sans purchaseLineCode, les deux lignes pourraient recevoir ces 3 unités : AuditStock refuse alors le rapprochement ambigu. Pour recevoir ensuite les 7 unités restantes de L002, utiliser un nouveau code de réception et conserver purchaseLineCode: "L002".

Validation et rapprochement des lignes

Un coefficient explicite doit être strictement positif, y compris lorsqu’il est inférieur à 1. Les quantités, coefficients et quantités converties doivent être représentables avec une précision maximale de six décimales, sans dépassement de capacité.
Un mode d’achat entier refuse une quantité d’achat fractionnaire. Le prix du conditionnement, le prix normalisé et le montant total doivent respecter la capacité monétaire.
Les noms d’unité, noms de conditionnement et références de ligne sont des textes bruts de 100 caractères au maximum ; une chaîne vide ou contenant du HTML est refusée.
Une référence purchaseLineCode fournie doit désigner une ligne du bon produit dans la commande indiquée. Une même réception ne peut pas contenir plusieurs entrées pour cette même ligne d’achat.
Sans référence de ligne, un rapprochement ambigu est refusé. Transmettre systématiquement les références source pour les commandes contenant plusieurs lignes du même produit.
Une référence d’achat existante ne peut pas être réutilisée pour un autre produit. Une ligne déjà réceptionnée ne peut pas être supprimée sans corriger d’abord les réceptions associées.
Prévoir les erreurs de validation et consulter les champs status, errors et warnings des résultats d’import ; ne pas assimiler la seule réussite HTTP à une importation métier réussie.

Adaptation des intégrations et réimport initial

Cibler /api/v17/... pour tous les appels, y compris le catalogue et les fonctions communes. Utiliser /openapi/v17.json et Api v17 dans Scalar (/api).
Mettre à jour les modèles clients avec les champs ci-dessus. Pour les achats sans conversion, conserver les messages ordinaires en omettant les nouveaux paramètres.
Pour chaque achat avec conversion, envoyer les paramètres propres à la ligne du document source, y compris ceux des documents historiques ; ne pas remplacer leur conditionnement par celui de la fiche fournisseur actuelle.
Envoyer toutes les réceptions en quantité réelle de stock. Conserver également les stocks initiaux, ventes, livraisons, retours, transferts et inventaires dans cette unité commune.
Organiser la bascule sur une base recréée, puis réimporter tous les produits et documents par le processus d’import global. Il n’y a ni migration des anciennes données ni coexistence d’anciennes versions d’API ; un simple changement de segment d’URL ne convertit pas les données existantes.
Vérifier le stock, les reliquats et les montants sur une réception partielle, une réception complémentaire, une correction, un solde forcé et un réimport identique. Contrôler aussi une commande sans paramètres après une commande avec conversion : elle doit utiliser le coefficient 1.

v15.0 → v16.0 — BREAKING CHANGE (13 octobre 2026)

Les fonctionnalités ci-dessous ont été introduites en v16 et restent disponibles en v17. Cette entrée est conservée dans l’historique ; la v16 et toutes les versions antérieures sont désormais retirées. Les exemples utilisent la version actuellement prise en charge, v17.

SIRET des documents de vente

Document / endpoint	Champ dans le corps JSON	Type	Si le champ est absent
`Sale` / `import-sale`	`sale.siretNumber`	string nullable	SIRET du client conservé
`Delivery` / `import-delivery`	`delivery.siretNumber`	string nullable	SIRET du client conservé
`DirectSale` / `import-direct-sale`	`directSale.siretNumber`	string nullable	SIRET du client conservé

Transmettre le SIRET comme une chaîne, afin de conserver les éventuels zéros initiaux. Le champ exact est SiretNumber en C# et siretNumber dans les exemples JSON.
Une valeur renseignée est nettoyée des espaces de début et de fin, puis enregistrée sur le client (Consumer) rattaché au document. Elle remplace son ancien SIRET et peut donc être visible sur ses autres documents.
null, une chaîne vide, une chaîne constituée d’espaces ou un champ omis n’effacent pas un SIRET déjà enregistré.
Pour une livraison liée à une commande, le SIRET est appliqué au client de cette commande. Si la livraison crée une vente directe, le SIRET est transmis à cette vente et à son client.
Les livraisons découpées entre plusieurs commandes conservent le SIRET du document source pour chaque traitement.
La mise à jour du SIRET d’un client existant intervient aussi lorsque le contenu commercial est inchangé et que l’import retourne AlreadyProcessed.
Le champ est informatif : l’import n’effectue pas de contrôle administratif du SIRET ni de vérification auprès d’un registre. Une erreur de sauvegarde du client est remontée par le résultat d’import.

Prix d’achat unitaire HT prioritaire

Ajouter UnitPurchasePriceWithoutTax dans les lignes SaleItem, DeliveryItem et DirectSaleItem ; son nom JSON est unitPurchasePriceWithoutTax. Il s’agit d’un nombre décimal unitaire HT, et non d’un montant total, d’un prix de vente ou d’un montant TTC.

Valeur envoyée	Comportement
Strictement positive	Coût d’achat commercial prioritaire
`0`	Valeur autorisée ; utilise le repli, ne force pas un coût nul
Champ omis	Valeur par défaut `0`, donc repli
Négative	Erreur de validation sur les lignes prises en compte
`null`	Non accepté : le champ est un `decimal` non nullable

Les lignes à quantité négative restent ignorées selon la règle existante ; la validation du prix s’applique aux lignes traitées.

**Ordre de priorité 😗*

Commande Sale : prix importé positif de la ligne ; sinon prix d’achat du produit, comme auparavant. La commande ne fournit pas d’entrepôt.
Livraison Delivery : prix importé positif de la ligne livrée ; sinon prix importé positif de la ligne de commande associée ; sinon repli existant. Pour une commande standard, ce repli conserve son coût de ligne. Pour une livraison directe, le stock de l’entrepôt livré prime sur le dernier prix d’achat.
Vente directe DirectSale : prix importé positif de la ligne ; sinon prix du stock de l’entrepôt ; sinon dernier prix d’achat.

Le prix d’une livraison peut différer de celui de sa commande : le prix propre à la livraison gagne pour la livraison, sans réécrire le coût de la commande standard. Une livraison sans commande préalable transmet ce champ à la vente directe qu’elle crée.

**Calculs et réimports 😗*

Le total d’achat HT d’une ligne est prix unitaire retenu × quantité : quantité commandée pour une vente, quantité livrée pour une livraison. Les montants TTC utilisent les règles de TVA existantes ; aucune seconde application de TVA n’est ajoutée.
Exemple : 7.25 HT pour 2.5 unités donne 18.125 HT avant les règles d’affichage monétaire.
Le coût retenu alimente les totaux commerciaux et les calculs de marge basés sur ces lignes.
Le prix prioritaire est conservé après sauvegarde et rechargement. Le complément automatique des prix manquants et le recalcul des livraisons directes ne l’écrasent pas.
Une modification du seul prix d’achat change l’empreinte d’import et déclenche une mise à jour. Un réimport identique reste AlreadyProcessed.
Renvoyer 0 ou omettre le champ retire la priorité propre à la ligne et réactive le repli. Sur une livraison, un prix importé positif de la commande peut alors être hérité.
Un réimport modifiant uniquement ce prix ne consomme pas une seconde fois le stock. Les quantités, les lots StockItem et leurs calculs de valorisation ne sont pas modifiés par cette nouvelle priorité.
Aucun recalcul global des documents historiques n’est lancé : réimporter les documents à corriger avec le prix souhaité.

Exemples d’appels v17

Ajouter l’en-tête X-Api-Key habituel à chaque requête. Les enveloppes restent sale, delivery et directSale.

POST /api/v17/imports/import-sale

{
  "sale": {
    "code": "SO-2026-001",
    "customerCode": "CLIENT-001",
    "siretNumber": "01234567890123",
    "creationDate": "2026-10-13T10:00:00Z",
    "items": [{
      "productCode": "PROD-001", "productDesignation": "Article",
      "quantity": 2.5, "unitSalePriceWithoutTax": 20,
      "unitPurchasePriceWithoutTax": 7.25
    }]
  }
}

POST /api/v17/imports/import-delivery

{
  "delivery": {
    "code": "DEL-2026-001", "saleCode": "SO-2026-001",
    "siretNumber": "01234567890123", "warehouseName": "PRINCIPAL",
    "deliveryDate": "2026-10-13T11:00:00Z",
    "items": [{ "productCode": "PROD-001", "quantity": 1.25,
      "unitPurchasePriceWithoutTax": 4.5 }]
  }
}

Cette livraison utilise 4.5 HT, même si la commande porte 7.25 HT.

POST /api/v17/imports/import-direct-sale

{
  "directSale": {
    "code": "DS-2026-001", "customerCode": "CLIENT-001",
    "siretNumber": "01234567890123", "warhouseName": "PRINCIPAL",
    "creationDate": "2026-10-13T12:00:00Z",
    "items": [{ "productCode": "PROD-001", "quantity": 2.5,
      "unitSalePriceWithoutTax": 20, "unitPurchasePriceWithoutTax": 7.25 }]
  }
}

Attention au nom actuel warhouseName sur DirectSale (orthographe du contrat existant), distinct de warehouseName sur Delivery.

Types de produit

ProductType est une valeur publique sérialisable. Les valeurs existantes sont conservées et Material reste la valeur par défaut pour les payloads qui ne fournissent pas le champ.

Valeur	Signification	Gestion du stock et de l'audit
`Material` (`0`)	Produit stockable et auditable	Les mouvements, historiques, calculs et analyses de stock sont actifs
`Service` (`1`)	Prestation de service	Pas de gestion de stock
`NonAuditable` (`2`)	Produit conservé dans les documents métier mais exclu de l'audit stock	Aucun mouvement, historique, anomalie, KPI de stock ou calcul de stock ; les KPI généraux et clientèle sont conservés

Lorsqu'un produit passe de Material ou Service à NonAuditable, ses données de stock et d'analyse associées sont supprimées définitivement. Les commandes, ventes, livraisons, réceptions, inventaires et lignes métier sont conservés. Repasser ensuite le produit en Material ne recrée pas l'ancien stock.

Méthodes d'import disponibles

Gestion de la date d'import

1. Démarrer une session d'import

Endpoint: POST /api/v17/imports/start-import-session

Versions d’API supportées : v17 uniquement, explicite dans l’URL

⚠️⚠️ BREAKING CHANGE en v12.0 - Cette méthode a été modifiée. Mettez à jour vos appels vers v17.

Permet de démarrer une session d'import massif.

Cette méthode :

Configure le systeme en mode file d'attente pour les imports
Définit le sens de traitement des données importées

Il faudra aller jusqu'a la fin de l'import pour finaliser la session via la methode Process-Import

⚠️ Important à partir de la v10.0

Il faut désormais indiquer dans le corps de la requête la direction de l'inventaire produit.

Cette information concerne uniquement l'import d'inventaire produit (notamment tarif et quantité) et permet d'indiquer si les données envoyées correspondent :

FromEnd : il s'agit d'un inventaire de fin
FromStart : il s'agit d'un inventaire de début

Ce paramètre change donc le sens métier du traitement appliqué à l'inventaire importé.

Par exemple :

utilisez FromStart si vous importez un inventaire de début
utilisez FromEnd si vous importez un inventaire de fin

Autrement dit, ce paramètre ne sert pas à décrire un simple ordre technique de lecture de fichier, mais bien à préciser la nature de l'inventaire produit importé.

Modèle : StartImportSessionRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Valeurs possibles
`direction`	string	✅	Type d'inventaire produit importé	`FromEnd` = inventaire de fin, `FromStart` = inventaire de début

Exemple de requête:

{
  "direction": "FromEnd"
}

Exemple alternatif:

{
  "direction": "FromStart"
}

Valeur par défaut côté contrat : FromEnd

Réponse : HTTP 202 Accepted

2. Finaliser la session d'import

Endpoint: POST /api/v17/imports/process-import

Versions d’API supportées : v17 uniquement, explicite dans l’URL

⚠️⚠️ BREAKING CHANGE en v12.0 - Cette méthode requiert désormais le paramètre allowBackDating dans le corps de la requête (corps vide ou absent n'est plus accepté).

Permet de finaliser la session d'import en cours et de revenir à l'état normal.

⚠️ Information importante

Cette méthode ne doit être appelée qu'à la fin de l'import massif.
Traite et finalise toutes les données importées
Calcule les KPI finaux
Réautorise les imports pour la prochaine session
Le traitement peut prendre plusieurs heures selon le volume de données importées

Cette méthode :

Rétablit l'utilisation de la date système actuelle
Finalise tous les calculs de la session d'import
Passe l'état d'import en mode "Allowed"

Modèle : ProcessImportRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description
`allowBackDating`	boolean	✅	Vaut `true` pour autoriser l'import de données antérieures à la date courante ; `false` sinon

Exemple de requête (sans antériorité) :

{
  "allowBackDating": false
}

Exemple de requête (avec antériorité autorisée) :

{
  "allowBackDating": true
}

Réponse : HTTP 200 OK avec rapport de traitement

3. Rapport d'import

Endpoint: GET /api/v17/imports/report

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 5.0 de l'API.

Permet de récupérer un rapport synthétique des derniers imports effectués dans le système. Important : Cette méthode est en lecture seule et ne nécessite aucun paramètre.

Cette méthode retourne :

Les informations sur la dernière commande client importée (vente)
Les informations sur la dernière livraison importée
Les informations sur la dernière commande fournisseur importée (achat)
Les informations sur la dernière réception fournisseur importée
Le nombre total d'éléments importés pour chaque type

Réponse: ImportReport

Champ	Type	Description
`ImportAllowed`	bool	Indique qu'il est possible d'importer des données
`LastImportedSaleCode`	string	Code de la dernière commande client importée
`LastImportedSaleDate`	datetime	Date de la dernière commande client
`ImportedSaleCount`	int	Nombre total de commandes clients importées
`LastImportedDeliveryCode`	string	Code de la dernière livraison importée
`LastImportedDeliveryDate`	datetime	Date de la dernière livraison
`ImportedDeliveryCount`	int	Nombre total de livraisons importées
`LastImportedPurchaseCode`	string	Code de la dernière commande fournisseur importée
`LastImportedPurchaseDate`	datetime	Date de la dernière commande fournisseur
`ImportedPurchaseCount`	int	Nombre total de commandes fournisseur importées
`LastImportedReceptionCode`	string	Code de la dernière réception importée
`LastImportedReceptionDate`	datetime	Date de la dernière réception
`ImportedReceptionCount`	int	Nombre total de réceptions importées

Exemple de réponse:

{
  "lastImportedSaleCode": "SO-2025-0542",
  "lastImportedSaleDate": "2025-01-15T14:30:00Z",
  "importedSaleCount": 542,
  "lastImportedDeliveryCode": "DEL-2025-0489",
  "lastImportedDeliveryDate": "2025-01-15T16:45:00Z",
  "importedDeliveryCount": 489,
  "lastImportedPurchaseCode": "PO-2025-0128",
  "lastImportedPurchaseDate": "2025-01-14T09:00:00Z",
  "importedPurchaseCount": 128,
  "lastImportedReceptionCode": "REC-2025-0095",
  "lastImportedReceptionDate": "2025-01-15T11:20:00Z",
  "importedReceptionCount": 95
}

Cas d'usage: Idéal pour surveiller l'état des imports, vérifier que les synchronisations fonctionnent correctement, diagnostiquer des problèmes d'import, ou afficher un tableau de bord des imports dans votre application.

4. Import de la liste de produits initiale

Endpoint: POST /api/v17/imports/import-product-list

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer une liste de produits avec leur stock initial dans un entrepôt spécifique.

⚠️⚠️ BREAKING CHANGE en v14.0

Chaque ligne ProductImport peut indiquer le champ Type :

Material : produit stockable, géré en stock
Service : prestation de service, non gérée en stock et sans impact sur les quantités physiques
Si le champ Type est absent, la valeur par défaut est Material

⚠️ Informations importantes

Cet import n'est à réaliser qu'une seule fois lors de la création initiale du catalogue produit
La date initiale permet de définir à quelle date le stock initial a été constaté
Si la date initiale est antérieure à la date du jour, le système calculera automatiquement l'historique des stocks
L'entrepôt sera créé automatiquement s'il n'existe pas

Cette méthode :

Traite les produits en stock par lots de 100 pour optimiser les performances (limite de 100 produits par requête)
Ignore les produits déjà existants sans générer d'erreur
Valide chaque ligne individuellement et continue le traitement en cas d'erreur
Retourne un résultat détaillé avec le nombre de produits importés et la liste des erreurs
Crée automatiquement l'entrepôt spécifié s'il n'existe pas
Enregistre le stock initial à la date spécifiée

Modèle: ImportProductListRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`ImportList`	List<ProductImport>	✅	Liste des produits à importer	Max 100 produits
`WarehouseName`	string	✅	Nom de l'entrepôt où importer le stock	Max 200 caractères, créé si inexistant
`InitialDate`	datetime	✅	Date de référence du stock initial	Format ISO 8601, doit être ⇐ date du jour

Champs obligatoires pour chaque ProductImport:

Code : Code unique du produit (max 100 caractères)
Designation : Désignation du produit (max 500 caractères)
Quantity : Quantité initiale (décimale, >= 0)
PurchasePriceWithoutTax : Prix d'achat HT (>= 0)

Champs optionnels pour chaque ProductImport:

Type : Type de produit (Material, Service ou NonAuditable)

Réponse: ProductImportResult

ImportedRowCount : Nombre de produits importés avec succès
ErrorList : Liste des erreurs avec numéro de ligne et raison de l'échec

Exemple de requête:

{
  "importList": [
    {
      "code": "LAPTOP-DELL-XPS15",
      "designation": "Ordinateur portable Dell XPS 15",
      "quantity": 10,
      "purchasePriceWithoutTax": 1299.99,
      "type": "Material"
    },
    {
      "code": "INSTALLATION-SERVICE",
      "designation": "Prestation d'installation",
      "quantity": 0,
      "purchasePriceWithoutTax": 150.00,
      "type": "Service"
    }
  ],
  "warehouseName": "ENTREPOT PRINCIPAL",
  "initialDate": "2025-01-01T00:00:00Z"
}

Exemple de réponse en cas de succès:

{
  "importedRowCount": 2,
  "errorList": [],
  "status": "Success"
}

Exemple de réponse avec erreurs:

{
  "importedRowCount": 1,
  "errorList": [
    {
      "rowIndex": 2,
      "failReason": "Le code produit est obligatoire"
    }
  ],
  "status": "Success"
}

Validations effectuées :

Vérification que la liste contient au maximum 100 produits
Validation que le nom de l'entrepôt est renseigné
Validation que la date initiale est valide et non future
Pour chaque produit :
- Vérification que le code est unique et non vide (max 100 caractères)
- Vérification que la désignation est renseignée (max 500 caractères)
- Validation que la quantité est >= 0
- Validation que le prix d'achat est >= 0
- Validation que le type est renseigné avec une valeur Material, Service ou NonAuditable

Cas d'usage :

Initialisation d'un nouveau catalogue produit
Migration depuis un système externe avec inventaire initial
Reprise de stock à une date donnée (inventaire physique)
Import d'un stock de départ pour un nouvel entrepôt

Notes :

Si vous devez importer plus de 100 produits, effectuez plusieurs appels successifs
Les produits existants avec le même code sont ignorés (pas de mise à jour)
La date initiale est cruciale pour le calcul correct des KPI et de l'historique des stocks

4 bis. Import de la liste de produits initiale depuis un fichier

Endpoint: POST /api/v17/imports/import-product-list-from-file

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer le catalogue produit initial à partir d'un fichier envoyé en multipart/form-data.

Cette méthode :

lance un traitement en tâche longue
retourne une URL de résultat via HTTP 202 Accepted
accepte un fichier avec les paramètres de contexte d'import

Paramètres du formulaire :

Paramètre	Type	Obligatoire	Description
`file`	fichier	✅	Fichier à traiter
`warehouseName`	string	✅	Nom de l'entrepôt cible
`initialDate`	datetime	✅	Date de référence du stock initial

Réponse : HTTP 202 Accepted avec l'URL de récupération du résultat.

Exemple de réponse :

/api/v17/imports/initial-product-list-from-file-result/{longTaskId}

Récupération du résultat d'import fichier

Endpoint: GET /api/v17/imports/initial-product-list-from-file-result/{longTaskId}

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet de récupérer le résultat d'un import de produits initial lancé depuis un fichier.

Réponse : ImportInitialProductListFromFileResult

Retourne HTTP 200 OK si le résultat est prêt
Retourne HTTP 404 Not Found si le résultat n'est pas encore disponible ou a expiré

5. Import de commandes clients (Sales)

Endpoint: POST /api/v17/imports/import-sale

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer une commande client avec ses lignes de commande. Important : Si la commande existe déjà et que rien n'a changé, alors rien ne sera effectué en base, le statut de l'import sera AlreadyProcessed. Cette méthode :

Crée automatiquement les produits s'ils n'existent pas
Génère une hiérarchie de catégories de produits basée sur le ProductCategoryBreadcrumb
Détermine automatiquement le type d'unité (entier/décimal) selon les quantités
Permet de renseigner le CustomerName dans la commande ; le client est ajouté à la volée lors de l'import s'il n'existe pas encore
À partir de la v11.0, permet de renseigner CompanyName ; la société est retrouvée ou créée automatiquement puis rattachée à la commande client
À partir de la v13.0, permet de renseigner IsBalanced pour indiquer qu'une commande client est soldée
À partir de la v14.0, permet de renseigner ProductType sur chaque ligne pour indiquer si le produit est Material, Service ou NonAuditable ; la valeur par défaut est Material

Synchronisation automatique :

Si une commande avec le même Code est envoyée à nouveau, le système synchronise automatiquement toutes les informations
Les lignes de commande sont mises à jour (ajout, modification, suppression)
Les informations produits sont actualisées si elles ont changé
Cette fonctionnalité permet de corriger des erreurs ou de mettre à jour des commandes existantes

Modèle: Sale avec collection de SaleItem Sale

6. Import de livraisons clients (Deliveries)

Endpoint: POST /api/v17/imports/import-delivery

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer une livraison de commande client. Important : Si la livraison existe déjà et que rien n'a changé, alors rien ne sera effectué en base, le statut de l'import sera AlreadyProcessed.

Cette méthode :

Soustrait du stock physique les quantités livrées
Met à jour le stock physique de l'entrepôt spécifié
Calcule automatiquement la consommation moyenne quotidienne
Crée l'entrepôt automatiquement s'il n'existe pas
Permet de renseigner le CustomerCode (optionnel) pour renforcer le rattachement client lors de l'import

Synchronisation automatique :

Si une livraison avec le même Code est envoyée à nouveau, le système synchronise automatiquement toutes les informations
Les lignes de livraison sont mises à jour (ajout, modification, suppression)
Les mouvements de stock sont recalculés pour refléter les changements
Utile pour corriger des erreurs de saisie ou mettre à jour des livraisons partielles

Import sans commande préalable :

Si la commande référencée n’existe pas, une vente directe associée est créée, puis la livraison est enregistrée.
Le SIRET et le prix d’achat importé sont transmis à cette vente directe.
Les lignes conservent le comportement existant de création des produits et de synchronisation des quantités.

Modèle: Delivery avec collection de DeliveryItem

7. Import de commandes fournisseur (Purchases)

Endpoint: POST /api/v17/imports/import-purchase

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer une commande fournisseur. Important : Si la commande existe déjà et que rien n'a changé, alors rien ne sera effectué en base, le statut de l'import sera AlreadyProcessed.

Cette méthode :

Crée automatiquement le fournisseur s'il n'existe pas
Crée automatiquement les produits et catégories s'ils n'existent pas
Gère les quantités décimales pour les unités fractionnées
À partir de la v11.0, permet de renseigner CompanyName ; la société est retrouvée ou créée automatiquement puis rattachée à la commande fournisseur
À partir de la v14.0, permet de renseigner ProductType sur chaque ligne pour indiquer si le produit est Material, Service ou NonAuditable ; la valeur par défaut est Material

Synchronisation automatique :

Si une commande avec le même Code est envoyée à nouveau, le système synchronise automatiquement toutes les informations
Les lignes de commande sont mises à jour (ajout, modification, suppression)
Les informations produits et fournisseur sont actualisées si elles ont changé
Cette fonctionnalité permet de corriger des erreurs ou de mettre à jour des commandes existantes

Modèle: Purchase avec collection de PurchaseItem

8. Import de réceptions fournisseur (Receptions)

Endpoint: POST /api/v17/imports/import-reception

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer une réception de commande fournisseur. Important : Si la réception existe déjà et que rien n'a changé, alors rien ne sera effectué en base, le statut de l'import sera AlreadyProcessed.

Cette méthode :

Met à jour le stock physique (addition des quantités reçues)
Calcule le délai d'approvisionnement moyen (lead time)
Crée l'entrepôt automatiquement s'il n'existe pas

Synchronisation automatique :

Si une réception avec le même Code est envoyée à nouveau, le système synchronise automatiquement toutes les informations
Les lignes de réception sont mises à jour (ajout, modification, suppression)
Les mouvements de stock sont recalculés pour refléter les changements
Utile pour corriger des erreurs de saisie ou mettre à jour des réceptions partielles

Import sans commande préalable :

Si la commande fournisseur référencée par PurchaseCode n'existe pas dans le système, la réception n'est PAS créée
MAIS le système synchronise quand même les stocks pour les produits existants
Cela permet de mettre à jour les stocks même si la commande fournisseur n'a pas été importée au préalable
Les produits inexistants sont ignorés (pas de création automatique dans ce cas)

Modèle: Reception avec collection de ReceptionItem

9. Import de transferts de stock entre entrepôts

Endpoint: POST /api/v17/imports/import-stock-transfer

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'importer un ou plusieurs transferts de stock entre entrepôts.

⚠️ Informations importantes

Si un entrepôt source ou destination n'existe pas, une erreur d'importation sera générée
De la même manière, si un produit n'existe pas, une erreur est générée
Le stock source doit être suffisant pour effectuer le transfert
Les entrepôts source et destination doivent être différents

Cette méthode :

Décrémente le stock de l'entrepôt source
Incrémente le stock de l'entrepôt de destination
Valide que le stock source est suffisant avant le transfert
Gère les quantités décimales pour les unités fractionnées
Enregistre la date du transfert pour un historique précis

Modèle: ImportStockTransferListRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`StockTransfers`	List<StockTransfer>	✅	Liste des transferts à effectuer	Au moins 1 transfert

Champs obligatoires pour chaque StockTransfer:

Champ	Type	Obligatoire	Description	Contraintes
`TransferDate`	datetime	✅	Date du transfert de stock	Format ISO 8601
`ProductCode`	string	✅	Code unique du produit à transférer	Max 100 caractères
`SourceWarehouseName`	string	✅	Nom de l'entrepôt source	Doit exister
`DestinationWarehouseName`	string	✅	Nom de l'entrepôt de destination	Doit exister
`Quantity`	decimal	✅	Quantité à transférer	> 0

Exemple de requête:

{
  "stockTransfers": [
    {
      "transferDate": "2025-01-15T10:00:00Z",
      "productCode": "LAPTOP-DELL-XPS15",
      "sourceWarehouseName": "ENTREPOT PRINCIPAL",
      "destinationWarehouseName": "MAGASIN TOULOUSE",
      "quantity": 5.0
    },
    {
      "transferDate": "2025-01-15T11:30:00Z",
      "productCode": "MOUSE-LOGITECH",
      "sourceWarehouseName": "ENTREPOT PRINCIPAL",
      "destinationWarehouseName": "MAGASIN PARIS",
      "quantity": 10.0
    }
  ]
}

Exemple de réponse en cas de succès:

{
  "status": "Success",
  "importedRowCount": 2,
  "errorList": [],
  "warnings": []
}

Exemple de réponse avec erreurs:

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [
    {
      "rowIndex": 2,
      "failReason": "Stock insuffisant dans l'entrepôt source ENTREPOT PRINCIPAL pour le produit MOUSE-LOGITECH"
    }
  ],
  "warnings": []
}

Validations effectuées:

Vérification de l'existence du produit dans le système
Vérification de l'existence de l'entrepôt source
Vérification de l'existence de l'entrepôt de destination
Validation que la date du transfert est valide (non future)
Validation que la quantité est strictement positive (> 0)
Validation que les entrepôts source et destination sont différents
Vérification du stock disponible dans l'entrepôt source (doit être >= quantité)

Cas d'usage :

Gérer les mouvements de stock entre différents points de vente ou entrepôts
Réaliser des transferts inter-magasins
Équilibrer les stocks entre plusieurs emplacements
Réorganiser les stocks en fonction des besoins géographiques
Traçabilité complète des mouvements avec date et heure précises

Notes :

Les transferts sont traités individuellement, une erreur sur un transfert n'empêche pas les autres de s'effectuer
La date du transfert permet de maintenir un historique précis des mouvements de stock
Si le stock source est insuffisant, le transfert est rejeté avec un message d'erreur explicite
Les mouvements de stock sont enregistrés dans l'historique pour traçabilité

10. Retour client

Endpoint: POST /api/v17/imports/customer-delivery-return

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 4.0 de l'API.

Permet d'enregistrer le retour d'un ou plusieurs produits par un client suite à une livraison. Important : Le retour client ajoute la quantité retournée au stock physique de l'entrepôt d'origine.

Cette méthode :

Vérifie que la commande client (SaleCode) et la livraison (DeliveryCode) existent
Vérifie que le produit existe et a bien été livré dans la livraison référencée
Ajoute la quantité retournée au stock physique de l'entrepôt
Crée un mouvement de stock de type "Retour client"
Valide que la quantité retournée est positive
Enregistre la date du retour pour traçabilité

Modèle: AddCustomerDeliveryReturnRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`CustomerDeliveryReturns`	List	✅	Liste des retours à enregistrer	Au moins 1 retour
`CreationDate`	datetime	✅	Date du retour	Format ISO 8601

Champs obligatoires pour chaque CustomerDeliveryReturn:

Champ	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code unique du produit retourné	Max 100 caractères
`SaleCode`	string	✅	Code de la commande client d'origine	Doit exister
`DeliveryCode`	string	✅	Code de la livraison concernée	Doit exister
`Quantity`	decimal	✅	Quantité retournée	> 0

Exemple de requête:

{
  "customerDeliveryReturns": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "saleCode": "SO-2025-0542",
      "deliveryCode": "DEL-2025-0489",
      "quantity": 1.0
    },
    {
      "productCode": "MOUSE-LOGITECH",
      "saleCode": "SO-2025-0542",
      "deliveryCode": "DEL-2025-0489",
      "quantity": 2.0
    }
  ],
  "creationDate": "2025-01-16T09:30:00Z"
}

Exemple de réponse en cas de succès:

{
  "status": "Success",
  "importedRowCount": 2,
  "errorList": [],
  "warnings": []
}

Exemple de réponse avec erreurs:

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [
    {
      "rowIndex": 2,
      "failReason": "Le produit MOUSE-LOGITECH n'a pas été livré dans la livraison DEL-2025-0489"
    }
  ],
  "warnings": []
}

Validations effectuées:

Validation que la date de retour est valide (non future)
Vérification de l'existence de la commande client
Vérification de l'existence de la livraison
Vérification de l'existence du produit
Validation que le produit faisait partie de la livraison
Validation que la quantité est strictement positive (> 0)
Validation que la quantité retournée ne dépasse pas la quantité livrée

Cas d'usage:

Gérer les retours produits des clients
Traiter les produits défectueux ou non conformes
Gérer les erreurs de livraison
Annuler partiellement des livraisons
Traçabilité complète des retours avec date précise

Notes :

Les retours sont traités individuellement, une erreur sur un retour n'empêche pas les autres de s'effectuer
Le stock de l'entrepôt d'origine est augmenté de la quantité retournée
Un mouvement de stock est enregistré pour traçabilité

11. Retour fournisseur

Endpoint: POST /api/v17/imports/supplier-reception-return

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 4.0 de l'API.

Permet d'enregistrer le retour d'un ou plusieurs produits à un fournisseur suite à une réception. Important : Le retour fournisseur retire la quantité retournée du stock physique de l'entrepôt.

Cette méthode :

Vérifie que la commande fournisseur (PurchaseCode) et la réception (ReceptionCode) existent
Vérifie que le produit existe et a bien été reçu dans la réception référencée
Retire la quantité retournée du stock physique de l'entrepôt
Crée un mouvement de stock de type "Retour fournisseur"
Valide que la quantité retournée est positive
Protège contre les stocks négatifs (stock ramené à 0 avec création d'anomalie si nécessaire)
Enregistre la date du retour pour traçabilité

Modèle: AddSupplierReceptionReturnRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`SupplierReceptionReturns`	List	✅	Liste des retours à enregistrer	Au moins 1 retour
`CreationDate`	datetime	✅	Date du retour	Format ISO 8601

Champs obligatoires pour chaque SupplierReceptionReturn:

Champ	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code unique du produit retourné	Max 100 caractères
`PurchaseCode`	string	✅	Code de la commande fournisseur d'origine	Doit exister
`ReceptionCode`	string	✅	Code de la réception concernée	Doit exister
`Quantity`	decimal	✅	Quantité retournée	> 0

Exemple de requête:

{
  "supplierReceptionReturns": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "purchaseCode": "PO-2025-0128",
      "receptionCode": "REC-2025-0095",
      "quantity": 2.0
    },
    {
      "productCode": "MOUSE-LOGITECH",
      "purchaseCode": "PO-2025-0128",
      "receptionCode": "REC-2025-0095",
      "quantity": 5.0
    }
  ],
  "creationDate": "2025-01-16T10:00:00Z"
}

Exemple de réponse en cas de succès:

{
  "status": "Success",
  "importedRowCount": 2,
  "errorList": [],
  "warnings": []
}

Exemple de réponse avec erreurs:

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [
    {
      "rowIndex": 2,
      "failReason": "Le produit MOUSE-LOGITECH n'a pas été reçu dans la réception REC-2025-0095"
    }
  ],
  "warnings": []
}

Validations effectuées:

Validation que la date de retour est valide (non future)
Vérification de l'existence de la commande fournisseur
Vérification de l'existence de la réception
Vérification de l'existence du produit
Validation que le produit faisait partie de la réception
Validation que la quantité est strictement positive (> 0)
Validation que la quantité retournée ne dépasse pas la quantité reçue

Gestion des anomalies :

Si le stock disponible est insuffisant, une anomalie de stock est automatiquement créée
Le stock est ramené à 0 et la différence est enregistrée comme anomalie
Cette protection évite les stocks négatifs tout en conservant la traçabilité

Cas d'usage:

Gérer les retours de produits défectueux ou non conformes aux fournisseurs
Traiter les erreurs de réception
Annuler partiellement des réceptions
Gérer les produits endommagés pendant le transport
Traçabilité complète des retours avec date précise

Notes :

Les retours sont traités individuellement, une erreur sur un retour n'empêche pas les autres de s'effectuer
Le stock de l'entrepôt est diminué de la quantité retournée
Un mouvement de stock est enregistré pour traçabilité

12. Ajout de stock libre

Endpoint: POST /api/v17/imports/add-free-product-stock

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 5.0 de l'API.

Permet d'ajouter manuellement du stock pour un produit dans un entrepôt spécifique, sans lien avec une réception ou un document source. Important : Cette méthode est idéale pour les ajustements de stock positifs, les inventaires, ou les entrées de stock exceptionnelles.

Cette méthode :

Vérifie que le produit existe dans le système
Vérifie que l'entrepôt existe dans le système
Ajoute la quantité spécifiée au stock physique de l'entrepôt
Crée un mouvement de stock de type "Entrée manuelle"
Enregistre le motif de l'ajustement pour traçabilité
Enregistre la date de l'ajustement pour historique

Modèle: AddFreeProductStockRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`ProductStock`	ProductStock	✅	Données du produit et ajustement	Voir tableau ci-dessous
`CreationDate`	datetime	✅	Date de l'ajustement	Format ISO 8601

Champs obligatoires pour ProductStock:

Champ	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code unique du produit	Max 100 caractères
`WarehouseName`	string	✅	Nom de l'entrepôt concerné	Doit exister
`Quantity`	decimal	✅	Quantité à ajouter	> 0
`Reason`	string	✅	Motif de l'ajustement	Obligatoire pour traçabilité

Exemple de requête:

{
  "productStock": {
    "productCode": "LAPTOP-DELL-XPS15",
    "warehouseName": "MAGASIN TOULOUSE",
    "quantity": 10.0,
    "reason": "Inventaire annuel - Correction positive"
  },
  "creationDate": "2025-01-16T14:00:00Z"
}

Exemple de réponse en cas de succès:

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [],
  "warnings": []
}

Exemple de réponse avec erreurs:

{
  "status": "Failed",
  "importedRowCount": 0,
  "errorList": [
    {
      "rowIndex": 1,
      "failReason": "Le produit LAPTOP-DELL-XPS15 n'existe pas dans le système"
    }
  ],
  "warnings": []
}

Validations effectuées:

Validation que la date d'ajustement est valide (non future)
Vérification de l'existence du produit
Vérification de l'existence de l'entrepôt
Validation que la quantité est strictement positive (> 0)
Validation que le motif est renseigné et non vide

Cas d'usage:

Corrections d'inventaire positives
Entrées de stock exceptionnelles (dons, échantillons)
Régularisations suite à erreur de comptage
Ajustements manuels lors d'un inventaire physique
Traçabilité complète avec date et motif précis

13. Retrait de stock libre

Endpoint: POST /api/v17/imports/remove-free-product-stock

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 5.0 de l'API.

Permet de retirer manuellement du stock pour un produit dans un entrepôt spécifique, sans lien avec une livraison ou un document source. Important : Cette méthode est idéale pour les ajustements de stock négatifs, les pertes, les casses, ou les sorties de stock exceptionnelles.

Cette méthode :

Vérifie que le produit existe dans le système
Vérifie que l'entrepôt existe dans le système
Retire la quantité spécifiée du stock physique de l'entrepôt
Crée un mouvement de stock de type "Sortie manuelle"
Enregistre le motif de l'ajustement pour traçabilité
Protège contre les stocks négatifs (crée une anomalie de stock si la quantité est insuffisante)
Enregistre la date de l'ajustement pour historique

Modèle: RemoveFreeProductStockRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`ProductStock`	ProductStock	✅	Données du produit et ajustement	Voir tableau ci-dessous
`CreationDate`	datetime	✅	Date de l'ajustement	Format ISO 8601

Champs obligatoires pour ProductStock:

Champ	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code unique du produit	Max 100 caractères
`WarehouseName`	string	✅	Nom de l'entrepôt concerné	Doit exister
`Quantity`	decimal	✅	Quantité à retirer	> 0
`Reason`	string	✅	Motif de l'ajustement	Obligatoire pour traçabilité

Exemple de requête:

{
  "productStock": {
    "productCode": "LAPTOP-DELL-XPS15",
    "warehouseName": "MAGASIN TOULOUSE",
    "quantity": 5.0,
    "reason": "Casse - Produit endommagé lors du transport"
  },
  "creationDate": "2025-01-16T14:30:00Z"
}

Exemple de réponse en cas de succès:

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [],
  "warnings": []
}

Exemple de réponse avec stock insuffisant (anomalie créée):

{
  "status": "Success",
  "importedRowCount": 1,
  "errorList": [],
  "warnings": [
    "Stock insuffisant pour LAPTOP-DELL-XPS15 dans MAGASIN TOULOUSE. Anomalie de stock créée."
  ]
}

Validations effectuées:

Validation que la date d'ajustement est valide (non future)
Vérification de l'existence du produit
Vérification de l'existence de l'entrepôt
Validation que la quantité est strictement positive (> 0)
Validation que le motif est renseigné et non vide

Gestion des anomalies:

Si le stock disponible est insuffisant, une anomalie de stock est automatiquement créée
Le stock est ramené à 0 et la différence est enregistrée comme anomalie
Cette protection évite les stocks négatifs tout en conservant la traçabilité
Un avertissement est retourné dans la réponse pour informer de la création d'anomalie

Cas d'usage:

Corrections d'inventaire négatives
Pertes et vols
Produits cassés ou périmés
Sorties exceptionnelles (échantillons, dons)
Régularisations suite à erreur de comptage
Traçabilité complète avec date et motif précis

14. Import de vente directe (membre)

Endpoint: POST /api/v17/imports/import-direct-sale

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Note : Cette fonctionnalité est disponible à partir de la version 6.0 de l'API.

Permet d'importer une vente directe (vente membre) qui impacte directement le stock sans passer par le processus classique commande/livraison. Important : Cette méthode est idéale pour les ventes au comptoir, les ventes en boutique physique, ou toute vente nécessitant une sortie immédiate du stock.

Cette méthode :

Crée automatiquement une commande client de type "Vente directe" (MemberOrder)
Retire immédiatement la quantité vendue du stock physique de l'entrepôt
Crée automatiquement les produits s'ils n'existent pas
Détermine automatiquement le type d'unité (entier/décimal) selon les quantités
Crée un mouvement de stock de type "Vente directe"

Synchronisation automatique :

Si une vente directe avec le même Code est envoyée à nouveau, le système synchronise automatiquement toutes les informations
Les lignes de vente sont mises à jour (ajout, modification, suppression)
Les mouvements de stock sont recalculés pour refléter les changements
Les informations produits et client sont actualisées si elles ont changé
Cette fonctionnalité permet de corriger des erreurs ou de mettre à jour des ventes existantes

Différence avec import-sale + import-delivery :

import-sale crée une commande client sans impacter le stock
import-delivery retire le stock lors de la livraison de la commande
import-direct-sale fait les deux en une seule opération : création de la vente ET retrait du stock immédiat
Idéal pour les flux de vente où il n'y a pas de séparation entre la commande et la livraison

Modèle: ImportDirectSaleRequest avec DirectSale contenant une collection de DirectSaleItem

Champs obligatoires pour DirectSale:

Code : Code unique de la vente directe (max 100 caractères)
CreationDate : Date de la vente (format ISO 8601)
CustomerCode : Code unique du client (max 100 caractères)
WarhouseName : Nom de l'entrepôt où le stock sera retiré
Items : Liste des lignes de vente (au moins 1 ligne)

Champs obligatoires pour DirectSaleItem:

ProductCode : Code unique du produit (max 100 caractères)
ProductDesignation : Désignation du produit (max 500 caractères)
Quantity : Quantité vendue (décimale, > 0)
UnitSalePriceWithoutTax : Prix unitaire HT (>= 0)

Champs optionnels pour DirectSale :

SiretNumber : SIRET du client ; absent ou vide, conserve la valeur existante

Champs optionnels pour DirectSaleItem:

UnitPurchasePriceWithoutTax : prix d’achat unitaire HT positif prioritaire ; zéro ou absent déclenche le repli
ProductCategoryBreadcrumb : Hiérarchie de catégories (ex: "Électronique > Ordinateurs > Portables")
ProductType : Type de produit (Material, Service ou NonAuditable), Material par défaut ; les produits non matériels ne génèrent aucun mouvement de stock

Exemple de requête:

{
  "directSale": {
    "code": "DS-2025-0001",
    "creationDate": "2025-01-15T14:30:00Z",
    "customerCode": "CUST001",
    "siretNumber": "01234567890123",
    "warhouseName": "MAGASIN TOULOUSE",
    "items": [
      {
        "productCode": "PROD001",
        "productDesignation": "Ordinateur portable Dell",
        "productCategoryBreadcrumb": "Électronique > Ordinateurs > Portables",
        "quantity": 1.0,
        "unitSalePriceWithoutTax": 750.00,
        "unitPurchasePriceWithoutTax": 500.00,
        "discountRate": 10.0
      },
      {
        "productCode": "PROD002",
        "productDesignation": "Souris sans fil",
        "productCategoryBreadcrumb": "Électronique > Accessoires",
        "quantity": 2.0,
        "unitSalePriceWithoutTax": 15.00,
        "discountRate": 0.0
      }
    ]
  }
}

Validations effectuées:

Vérification que le code de vente est unique (ou déjà existant pour synchronisation)
Validation que la date de vente est cohérente avec la date d'import définie
Vérification de l'existence de l'entrepôt (création automatique si nécessaire)
Validation que toutes les quantités sont strictement positives
Vérification du stock disponible dans l'entrepôt (création d'anomalie si stock insuffisant)
Validation de la cohérence des prix (>= 0)
Validation des taux de remise (0-100%)

Gestion des anomalies:

Si le stock disponible est insuffisant pour un produit, une anomalie de stock est automatiquement créée
Le stock est ramené à 0 et la différence est enregistrée comme anomalie
La vente est quand même créée pour maintenir la traçabilité des opérations

Cas d'usage: Idéal pour les ventes au comptoir, les ventes en boutique physique, les ventes événementielles (salons, marchés), les ventes directes aux membres d'une association, ou toute situation où la commande et la livraison sont simultanées.

15. Annulation d'un bon de livraison client

Endpoint: POST /api/v17/imports/cancel-delivery

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'annuler un bon de livraison client existant identifié par son code. Important : L'annulation restitue intégralement les quantités livrées en stock et recalcule le statut de la commande associée.

Cette méthode :

Vérifie que le bon de livraison identifié par DeliveryCode existe
Restitue les quantités livrées au stock physique de l'entrepôt d'origine
Supprime toutes les lignes du bon de livraison
Supprime le bon de livraison
Recalcule automatiquement le statut de la commande client associée (passage de Balanced/Closed à WaitingDelivery/Open)
Archive les entités supprimées pour traçabilité

Modèle: CancelDeliveryRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`DeliveryCode`	string	✅	Code unique du bon de livraison à annuler	Doit exister
`Reason`	string	✅	Motif de l'annulation	Non vide
`CancelDate`	datetime	✅	Date de l'annulation	Format ISO 8601

Exemple de requête :

{
  "deliveryCode": "DEL-2025-0489",
  "reason": "Erreur de saisie - livraison annulée à la demande du client",
  "cancelDate": "2025-01-16T10:00:00Z"
}

Exemple de réponse en cas de succès :

{
  "status": "Success",
  "errors": {},
  "warnings": []
}

Exemple de réponse en cas d'échec (code inconnu) :

{
  "status": "Failed",
  "errors": {
    "DeliveryCode": "No delivery found with code DEL-2025-0489"
  },
  "warnings": []
}

Validations effectuées :

Vérification de l'existence du bon de livraison
Vérification que l'entrepôt de l'origine est accessible
Vérification du stock disponible pour la restitution (création d'anomalie si nécessaire)

Comportement selon l'état d'import :

Mode Processing : retourne 400 BadRequest (imports désactivés)
Mode Preparation : mis en file d'attente, retourne 202 Accepted avec l'identifiant de l'activité
Mode Allowed : traitement immédiat, retourne 200 OK

Cas d'usage :

Corriger une livraison envoyée par erreur
Annuler une livraison suite à un retour complet du client
Remettre une commande en attente de livraison après correction

16. Annulation d'une réception fournisseur

Endpoint: POST /api/v17/imports/cancel-reception

Versions d’API supportées : v17 uniquement, explicite dans l’URL

Permet d'annuler une réception fournisseur existante identifiée par son code. Important : L'annulation retire intégralement les quantités reçues du stock et recalcule le statut de la commande fournisseur associée.

Cette méthode :

Vérifie que la réception identifiée par ReceptionCode existe
Retire les quantités reçues du stock physique de l'entrepôt
Supprime toutes les lignes de la réception
Supprime la réception
Recalcule automatiquement le statut de la commande fournisseur associée (passage de Balanced à Submitted)
Archive les entités supprimées pour traçabilité

Cas particulier : Si la réception ne contient aucune ligne (réception vide), elle est simplement supprimée et un avertissement est retourné.

Modèle: CancelReceptionRequest

Paramètres de la requête :

Paramètre	Type	Obligatoire	Description	Contraintes
`ReceptionCode`	string	✅	Code unique de la réception fournisseur à annuler	Doit exister
`Reason`	string	✅	Motif de l'annulation	Non vide
`CancelDate`	datetime	✅	Date de l'annulation	Format ISO 8601

Exemple de requête :

{
  "receptionCode": "REC-2025-0095",
  "reason": "Réception importée par erreur - marchandise non reçue",
  "cancelDate": "2025-01-16T11:00:00Z"
}

Exemple de réponse en cas de succès :

{
  "status": "Success",
  "errors": {},
  "warnings": []
}

Exemple de réponse - réception vide supprimée :

{
  "status": "Success",
  "errors": {},
  "warnings": ["Reception had no items, it has been deleted"]
}

Exemple de réponse en cas d'échec (code inconnu) :

{
  "status": "Failed",
  "errors": {
    "ReceptionCode": "No reception found with code REC-2025-0095"
  },
  "warnings": []
}

Validations effectuées :

Vérification de l'existence de la réception
Vérification du stock disponible pour le retrait (protégé contre les stocks négatifs)
Rollback transactionnel en cas d'erreur sur l'un des articles

Comportement selon l'état d'import :

Mode Processing : retourne 400 BadRequest (imports désactivés)
Mode Preparation : mis en file d'attente, retourne 202 Accepted avec l'identifiant de l'activité
Mode Allowed : traitement immédiat, retourne 200 OK

Cas d'usage :

Corriger une réception saisie par erreur
Annuler une réception dont la marchandise a été refusée ou retournée intégralement
Remettre une commande fournisseur soldée en attente de réception

Modèles de données d'import

Cette section détaille tous les modèles de données utilisés dans l'API d'import AuditStock avec des exemples concrets et des explications sur chaque propriété.

ProductImport - Import de produit

Représente un produit à importer dans le système lors de l'import initial du catalogue.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique du produit	Max 100 caractères
`Designation`	string	✅	Nom ou description du produit	Max 500 caractères
`Quantity`	decimal	✅	Quantité initiale en stock	>= 0
`PurchasePriceWithoutTax`	decimal	✅	Prix d'achat HT	>= 0, 2 décimales
`ProductType`	ProductType	❌	Type de produit importé	`Material`, `Service` ou `NonAuditable`, défaut `Material`

Exemple JSON :

{
  "code": "LAPTOP-DELL-XPS15",
  "designation": "Ordinateur portable Dell XPS 15 - Intel i7 - 16Go RAM",
  "quantity": 10,
  "purchasePriceWithoutTax": 1299.99,
  "type": "Material"
}

Notes importantes :

Les produits existants avec le même code sont ignorés sans générer d'erreur
À partir de la v14.0, Type permet de distinguer les produits stockables (Material), les prestations de service (Service) et les produits exclus de l'audit (NonAuditable) ; la valeur par défaut est Material
Un produit Service n'est pas géré en stock et n'affecte pas les quantités physiques
La quantité peut être 0 si le produit n'a pas encore de stock initial
Le prix d'achat est utilisé pour les calculs de valorisation du stock

Sale - Commande client

Représente une commande client avec ses lignes de commande.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique de la commande	Max 100 caractères, unique
`CustomerCode`	string	✅	Code du client	Max 100 caractères
`CustomerName`	string	❌	Nom du client	Max 500 caractères
`CompanyName`	string	❌	Nom de la société (v11.0+)	Max 500 caractères
`CreationDate`	datetime	✅	Date de création de la commande	Format ISO 8601
`SiretNumber`	string nullable	❌	SIRET du client associé (v17)	Absent/vide : conserve la valeur existante ; espaces externes supprimés
`Items`	List	✅	Liste des lignes de commande	Au moins 1 ligne

Exemple JSON complet :

{
  "code": "SO-2025-0542",
  "customerCode": "CUST-12345",
  "siretNumber": "01234567890123",
  "customerName": "Dupont Jean",
  "companyName": "AuditStock Toulouse",
  "creationDate": "2025-01-15T10:30:00Z",
  "items": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "productDesignation": "Dell XPS 15 - Intel i7",
      "productUrl": "https://exemple.com/products/dell-xps15",
      "productImageUrl": "https://exemple.com/images/dell-xps15.jpg",
      "productCategoryBreadcrumb": "Informatique/Ordinateurs/Portables",
      "barCode": "1234567890123",
      "quantity": 2,
      "unitSalePriceWithoutTax": 1599.00,
      "unitPurchasePriceWithoutTax": 1299.99,
      "discountRate": 5.0
    },
    {
      "productCode": "MOUSE-LOGITECH-MX3",
      "productDesignation": "Souris Logitech MX Master 3",
      "productCategoryBreadcrumb": "Informatique/Périphériques/Souris",
      "quantity": 2,
      "unitSalePriceWithoutTax": 99.99,
      "discountRate": 0.0
    }
  ]
}

SaleItem - Ligne de commande client

Représente une ligne dans une commande client.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`ProductDesignation`	string	✅	Nom du produit	Max 500 caractères
`ProductUrl`	string	❌	URL de la fiche produit	URL valide
`ProductImageUrl`	string	❌	URL de l'image produit	URL valide
`ProductCategoryBreadcrumb`	string	❌	Hiérarchie de catégories	Séparées par "/"
`ProductType`	ProductType	❌	Type de produit importé	`Material`, `Service` ou `NonAuditable`, défaut `Material`
`BarCode`	string	❌	Code-barres EAN/UPC	Max 50 caractères
`Quantity`	decimal	✅	Quantité commandée	> 0
`UnitPurchasePriceWithoutTax`	decimal	❌	Prix d’achat unitaire HT prioritaire (v17)	>= 0 ; défaut 0 = repli ; non nullable
`UnitSalePriceWithoutTax`	decimal	✅	Prix unitaire de vente HT	>= 0
`DiscountRate`	decimal	❌	Taux de remise (%)	0-100

Notes :

Si le produit n'existe pas, il est créé automatiquement
Si CustomerName est renseigné lors de l'import d'une Sale, le client est ajouté à la volée s'il n'existe pas
Le ProductCategoryBreadcrumb permet de créer une hiérarchie de catégories (ex: "Électronique/Audio/Casques")
Le type d'unité (entier/décimal) est déterminé automatiquement selon les quantités

Delivery - Livraison client

Représente une livraison de commande client qui impacte le stock.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique de la livraison	Max 100 caractères, unique
`SaleCode`	string	✅	Code de la commande client	Doit exister
`CustomerCode`	string	❌	Code du client	Optionnel
`WarehouseName`	string	✅	Nom de l'entrepôt	Créé si inexistant
`DeliveryDate`	datetime	✅	Date de livraison	Format ISO 8601
`SiretNumber`	string nullable	❌	SIRET du client associé (v17)	Absent/vide : conserve la valeur existante ; espaces externes supprimés
`Items`	List	✅	Liste des lignes livrées	Au moins 1 ligne

Exemple JSON complet :

{
  "code": "DEL-2025-0489",
  "saleCode": "SO-2025-0542",
  "customerCode": "CUST-12345",
  "siretNumber": "01234567890123",
  "warehouseName": "ENTREPOT TOULOUSE",
  "deliveryDate": "2025-01-15T14:30:00Z",
  "items": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "quantity": 2,
      "unitPurchasePriceWithoutTax": 1299.99,
      "saleCode": "SO-2025-0542",
      "productType": "Material"
    },
    {
      "productCode": "MOUSE-LOGITECH-MX3",
      "quantity": 2
    }
  ]
}

Important :

La livraison retire la quantité du stock physique de l'entrepôt
Sans commande préalable, une vente directe associée est créée ; le SIRET et le prix d’achat importé lui sont transmis
Permet de corriger une livraison existante en renvoyant le même code avec des modifications

DeliveryItem - Ligne de livraison

Représente une ligne dans une livraison client.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`Quantity`	decimal	✅	Quantité livrée	> 0
`SaleCode`	string	❌	Code de commande client cible pour cette ligne	Si absent, vide ou `0`, utilise `Delivery.SaleCode`
`UnitPurchasePriceWithoutTax`	decimal	❌	Prix d’achat unitaire HT prioritaire (v17)	>= 0 ; défaut 0 = repli ; non nullable
`UnitSalePriceWithoutTax`	decimal	❌	Prix unitaire de vente HT	Optionnel
`ProductType`	ProductType	❌	Type de produit	`Material` par défaut ; `Service` et `NonAuditable` ne génèrent pas de mouvement de stock

Purchase - Commande fournisseur

Représente une commande passée à un fournisseur.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique de la commande	Max 100 caractères, unique
`SupplierCode`	string	✅	Code du fournisseur	Max 100 caractères
`SupplierName`	string	✅	Nom du fournisseur	Max 500 caractères
`CompanyName`	string	❌	Nom de la société (v11.0+)	Max 500 caractères
`CreationDate`	datetime	✅	Date de création	Format ISO 8601
`Items`	List	✅	Liste des lignes	Au moins 1 ligne

Exemple JSON complet :

{
  "code": "PO-2025-0128",
  "supplierCode": "SUP-DELL-FR",
  "supplierName": "Dell France",
  "companyName": "AuditStock Toulouse",
  "creationDate": "2025-01-10T09:00:00Z",
  "items": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "productDesignation": "Dell XPS 15 - Intel i7",
      "productCategoryBreadcrumb": "Informatique/Ordinateurs/Portables",
      "quantity": 20,
      "unitPurchasePriceWithoutTax": 1299.99
    }
  ]
}

Notes :

Le fournisseur est créé automatiquement s'il n'existe pas
À partir de la v11.0, si CompanyName est renseigné lors de l'import d'un Purchase, la société est ajoutée à la volée si elle n'existe pas
Les produits sont créés automatiquement s'ils n'existent pas
À partir de la v13.0, permet de renseigner IsBalanced pour indiquer qu'une commande fournisseur est soldée

PurchaseItem - Ligne de commande fournisseur

Représente une ligne dans une commande fournisseur.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`ProductDesignation`	string	✅	Nom du produit	Max 500 caractères
`ProductCategoryBreadcrumb`	string	❌	Hiérarchie de catégories	Séparées par "/"
`ProductType`	ProductType	❌	Type de produit importé	`Material`, `Service` ou `NonAuditable`, défaut `Material`
`Quantity`	decimal	✅	Quantité commandée	> 0
`UnitPurchasePriceWithoutTax`	decimal	✅	Prix d'achat unitaire HT	>= 0

Reception - Réception fournisseur

Représente une réception de marchandises d'un fournisseur qui augmente le stock.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique de la réception	Max 100 caractères, unique
`PurchaseCode`	string	✅	Code de la commande fournisseur	Doit exister
`WarehouseName`	string	✅	Nom de l'entrepôt	Créé si inexistant
`ReceptionDate`	datetime	✅	Date de réception	Format ISO 8601
`Items`	List	✅	Liste des lignes reçues	Au moins 1 ligne

Exemple JSON complet :

{
  "code": "REC-2025-0095",
  "purchaseCode": "PO-2025-0128",
  "warehouseName": "ENTREPOT TOULOUSE",
  "receptionDate": "2025-01-15T11:20:00Z",
  "items": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "quantity": 20
    }
  ]
}

Important :

La réception ajoute la quantité au stock physique de l'entrepôt
Si la commande fournisseur n'existe pas, la réception n'est pas créée MAIS le stock est synchronisé pour les produits existants
Calcule automatiquement le délai d'approvisionnement (lead time)

ReceptionItem - Ligne de réception

Représente une ligne dans une réception fournisseur.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`Quantity`	decimal	✅	Quantité reçue	> 0

StockTransfer - Transfert de stock

Représente un transfert de stock entre deux entrepôts.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`TransferDate`	datetime	✅	Date du transfert	Format ISO 8601
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`SourceWarehouseName`	string	✅	Entrepôt source	Doit exister
`DestinationWarehouseName`	string	✅	Entrepôt destination	Doit exister
`Quantity`	decimal	✅	Quantité transférée	> 0

Exemple JSON complet :

{
  "transferDate": "2025-01-15T16:00:00Z",
  "productCode": "LAPTOP-DELL-XPS15",
  "sourceWarehouseName": "ENTREPOT TOULOUSE",
  "destinationWarehouseName": "MAGASIN PARIS",
  "quantity": 5
}

Validations :

Le produit doit exister
Les deux entrepôts doivent exister
Le stock source doit être suffisant
Les entrepôts source et destination doivent être différents

DirectSale - Vente directe

Représente une vente directe (membre) qui crée la commande et retire le stock immédiatement.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`Code`	string	✅	Code unique de la vente	Max 100 caractères, unique
`CreationDate`	datetime	✅	Date de la vente	Format ISO 8601
`CustomerCode`	string	❌	Code du client	Défaut DIVERS si absent ou vide
`WarhouseName`	string	✅	Entrepôt de prélèvement	Créé si inexistant
`SiretNumber`	string nullable	❌	SIRET du client associé (v17)	Absent/vide : conserve la valeur existante ; espaces externes supprimés
`Items`	List	✅	Liste des lignes vendues	Au moins 1 ligne

Exemple JSON complet :

{
  "code": "DS-2025-0001",
  "creationDate": "2025-01-15T14:30:00Z",
  "customerCode": "MEMBER-12345",
  "siretNumber": "01234567890123",
  "warhouseName": "MAGASIN TOULOUSE",
  "items": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "productDesignation": "Dell XPS 15 - Intel i7",
      "productCategoryBreadcrumb": "Informatique/Ordinateurs/Portables",
      "quantity": 1,
      "unitSalePriceWithoutTax": 1599.00,
      "unitPurchasePriceWithoutTax": 1299.99,
      "discountRate": 10.0
    }
  ]
}

Différence avec Sale + Delivery :

import-sale crée une commande sans impacter le stock
import-delivery retire le stock lors de la livraison
import-direct-sale fait les deux en une seule opération

DirectSaleItem - Ligne de vente directe

Représente une ligne dans une vente directe.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`ProductDesignation`	string nullable	❌	Nom du produit	Optionnel
`ProductCategoryBreadcrumb`	string	❌	Hiérarchie de catégories	Séparées par "/"
`ProductType`	ProductType	❌	Type de produit importé	`Material`, `Service` ou `NonAuditable`, défaut `Material`
`Quantity`	decimal	✅	Quantité vendue	> 0
`UnitPurchasePriceWithoutTax`	decimal	❌	Prix d’achat unitaire HT prioritaire (v17)	>= 0 ; défaut 0 = repli ; non nullable
`UnitSalePriceWithoutTax`	decimal	✅	Prix unitaire HT	>= 0
`DiscountRate`	decimal	❌	Taux de remise (%)	0-100

CustomerDeliveryReturn - Retour client

Représente le retour d'un produit par un client.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit retourné	Max 100 caractères
`SaleCode`	string	✅	Code de la commande client	Doit exister
`DeliveryCode`	string	✅	Code de la livraison	Doit exister
`Quantity`	decimal	✅	Quantité retournée	> 0

Exemple JSON :

{
  "customerDeliveryReturns": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "saleCode": "SO-2025-0542",
      "deliveryCode": "DEL-2025-0489",
      "quantity": 1
    }
  ]
}

Effet : Ajoute la quantité retournée au stock physique de l'entrepôt d'origine.

SupplierReceptionReturn - Retour fournisseur

Représente le retour d'un produit à un fournisseur.

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit retourné	Max 100 caractères
`PurchaseCode`	string	✅	Code de la commande fournisseur	Doit exister
`ReceptionCode`	string	✅	Code de la réception	Doit exister
`Quantity`	decimal	✅	Quantité retournée	> 0

Exemple JSON :

{
  "supplierReceptionReturns": [
    {
      "productCode": "LAPTOP-DELL-XPS15",
      "purchaseCode": "PO-2025-0128",
      "receptionCode": "REC-2025-0095",
      "quantity": 2
    }
  ]
}

Effet : Retire la quantité retournée du stock physique de l'entrepôt (protégé contre les stocks négatifs).

ProductStock - Ajustement de stock libre

Représente un ajustement manuel de stock (ajout ou retrait).

Propriétés :

Propriété	Type	Obligatoire	Description	Contraintes
`ProductCode`	string	✅	Code du produit	Max 100 caractères
`WarehouseName`	string	✅	Nom de l'entrepôt	Doit exister
`Quantity`	decimal	✅	Quantité à ajuster	> 0
`Reason`	string	✅	Motif de l'ajustement	Obligatoire pour traçabilité

Exemple JSON (ajout) :

{
  "productStock": {
    "productCode": "LAPTOP-DELL-XPS15",
    "warehouseName": "MAGASIN TOULOUSE",
    "quantity": 10,
    "reason": "Inventaire annuel - Correction positive"
  }
}

Exemple JSON (retrait) :

{
  "productStock": {
    "productCode": "LAPTOP-DELL-XPS15",
    "warehouseName": "MAGASIN TOULOUSE",
    "quantity": 3,
    "reason": "Casse - Produit endommagé lors du transport"
  }
}

Cas d'usage :

Corrections d'inventaire
Pertes et casses
Vols
Dons et échantillons
Régularisations

ImportResult - Résultat d'import

Retour standard pour toutes les opérations d'import.

Propriétés :

Propriété	Type	Description
`Status`	ImportStatus	Statut de l'import (Success, Failed, Invalid, etc.)
`ImportedRowCount`	int	Nombre de lignes importées avec succès
`ErrorList`	List	Liste des erreurs rencontrées
`Warnings`	List	Avertissements (non bloquants)

Valeurs de ImportStatus :

Success : Import réussi
Created : Entité créée
Updated : Entité mise à jour
AlreadyProcessed : Déjà traité (aucune modification)
Enqueued : Mis en file d'attente (mode préparation)
Failed : Échec de l'import
Invalid : Données invalides

Exemple de réponse :

{
  "status": "Success",
  "importedRowCount": 5,
  "errorList": [],
  "warnings": [
    "Product PROD001 already exists, skipped"
  ]
}

ProductImportError - Erreur d'import

Détail d'une erreur lors de l'import.

Propriétés :

Propriété	Type	Description
`RowIndex`	int	Numéro de ligne en erreur
`FailReason`	string	Description de l'erreur

Exemple :

{
  "rowIndex": 3,
  "failReason": "Le code produit est obligatoire"
}

Récapitulatif des versions d'API

Version prise en charge : v17 uniquement. Toutes les versions antérieures sont retirées.

Endpoint	v17
ping	✅
start-import-session	✅
process-import	✅
import-product-list	✅
import-product-list-from-file	✅
initial-product-list-from-file-result	✅
import-sale	✅
import-delivery	✅
import-purchase	✅
import-reception	✅
import-stock-transfer	✅
customer-delivery-return	✅
supplier-reception-return	✅
add-free-product-stock	✅
remove-free-product-stock	✅
report	✅
import-direct-sale	✅
cancel-delivery	✅
cancel-reception	✅

Légende : ✅ Disponible et supporté en v17. Toutes les versions antérieures sont retirées.

Flux d'import recommandé en v17 :

POST /api/v17/imports/start-import-session → Démarre la session
Importer vos données (produits, ventes, livraisons, commandes fournisseur, réceptions, etc.)
Vérifier l'état avec GET /api/v17/imports/report
POST /api/v17/imports/process-import → Finalise la session
En cas d'erreur après import : POST /api/v17/imports/cancel-delivery ou POST /api/v17/imports/cancel-reception

Explorez l'Api d'AuditStock

API AuditStock

Change logs

v16.0 → v17.0 — BREAKING CHANGE (23 octobre 2026)

Unités de vente, de stock et conditionnements d’achat

Nouveaux champs des contrats d’import

Quantités, prix d’achat et calcul de conversion

Réceptions partielles, reliquats et solde forcé

Exemples d’appels v17

Paramètres de l’import d’une commande fournisseur

Paramètres de l’import d’une réception fournisseur

Rôle de `sourceLineCode` et de `purchaseLineCode`

Validation et rapprochement des lignes

Adaptation des intégrations et réimport initial

v15.0 → v16.0 — BREAKING CHANGE (13 octobre 2026)

SIRET des documents de vente

Prix d’achat unitaire HT prioritaire

Exemples d’appels v17

Types de produit

Méthodes d'import disponibles

Gestion de la date d'import

1. Démarrer une session d'import

2. Finaliser la session d'import

3. Rapport d'import

4. Import de la liste de produits initiale

4 bis. Import de la liste de produits initiale depuis un fichier

Récupération du résultat d'import fichier

5. Import de commandes clients (Sales)

6. Import de livraisons clients (Deliveries)

7. Import de commandes fournisseur (Purchases)

8. Import de réceptions fournisseur (Receptions)

9. Import de transferts de stock entre entrepôts

10. Retour client

11. Retour fournisseur

12. Ajout de stock libre

13. Retrait de stock libre

14. Import de vente directe (membre)

15. Annulation d'un bon de livraison client

16. Annulation d'une réception fournisseur

Modèles de données d'import

ProductImport - Import de produit

Sale - Commande client

SaleItem - Ligne de commande client

Delivery - Livraison client

DeliveryItem - Ligne de livraison

Purchase - Commande fournisseur

PurchaseItem - Ligne de commande fournisseur

Reception - Réception fournisseur

ReceptionItem - Ligne de réception

StockTransfer - Transfert de stock

DirectSale - Vente directe

DirectSaleItem - Ligne de vente directe

CustomerDeliveryReturn - Retour client

SupplierReceptionReturn - Retour fournisseur

ProductStock - Ajustement de stock libre

ImportResult - Résultat d'import

ProductImportError - Erreur d'import

Récapitulatif des versions d'API