APIMis à jour le 6 juin 2026

Mouvements de stock

Enregistrer des entrées et sorties de stock par lot via l'API, avec traitement partiel et idempotence.

La ressource stock-movements permet d'enregistrer des entrées et sorties de stock par lot, par exemple depuis un terminal de point de vente, un WMS ou un script d'intégration.

Endpoints

Méthode	Chemin	Scope
`POST`	`/api/v1/stock-movements`	`write:products`

Enregistrer des mouvements

POST /api/v1/stock-movements

Vous envoyez un lot de 1 à 200 mouvements. La quantité est signée : +N est une entrée, −N est une sortie.

Idempotent

Cet appel accepte l'en-tête Idempotency-Key. Rejouer la même clé renvoie le même résultat sans ré-appliquer les mouvements. Indispensable si votre intégration peut retenter après une coupure réseau. Voir Idempotence.

Corps de la requête

Champ	Type	Requis	Notes
`movements`	tableau, 1 à 200 éléments	Oui	Le lot de mouvements
`movements[].productId`	texte	Oui	Le produit concerné
`movements[].quantity`	nombre signé	Oui	`+` entrée / `−` sortie
`movements[].reason`	texte, 280 caractères max	Non	Motif libre (« Casse », « Réception », …)
`movements[].refKind`	texte, 60 caractères max	Non	Type de pièce liée (libre)
`movements[].refId`	texte, 120 caractères max	Non	Identifiant de la pièce liée
`movements[].unitCost`	nombre	Non	Coût unitaire, pour la valorisation

Réponse

Le traitement est mouvement par mouvement : chacun réussit ou échoue indépendamment. Le code HTTP reflète le résultat du lot :

Code	Cas
`200`	Tous les mouvements ont été appliqués
`207`	Traitement partiel : certains mouvements sont passés (`applied`), d'autres ont échoué (`errors`)
`422`	Aucun mouvement n'a pu être appliqué (`stock_adjust_failed`)

Quel que soit le code, la réponse sépare les mouvements appliqués des mouvements en erreur :

{
  "data": {
    "applied": [
      { "productId": "…", "before": 5, "after": 8, "delta": 3 }
    ],
    "errors": [
      { "productId": "…", "error": "…" }
    ]
  }
}

Vérifiez toujours `errors`

Un code 207 signale qu'une partie seulement des mouvements est passée. Un produit inexistant, non suivi en stock, ou refusé par la politique de stock négatif se retrouve dans errors pendant que les autres passent. Ne vous fiez pas au seul code HTTP : parcourez errors après chaque appel.

Chaque mouvement appliqué émet l'événement webhook stock.movement (voir Webhooks). Un mouvement qui fait passer un produit sous son seuil ou à zéro déclenche en plus stock.low ou stock.out.

Exemple

curl -X POST "https://app.naskel.io/api/v1/stock-movements" \
  -H "Authorization: Bearer nsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3…" \
  -d '{
    "movements": [
      { "productId": "prod_123", "quantity": -2, "reason": "Casse" },
      { "productId": "prod_456", "quantity": 50, "reason": "Réception", "refKind": "purchase_order", "refId": "po_789", "unitCost": 4.20 }
    ]
  }'

Mouvement ou ajustement ?

Deux façons de modifier un stock par l'API :

Mouvement (cette page) : vous décrivez une variation (+50 reçus, −2 cassés). À utiliser pour les flux du quotidien.
Ajustement (POST /products/{id}/adjust) : vous décrivez la quantité constatée, le serveur calcule le delta. À utiliser pour un inventaire physique.