APIMis à jour le 6 juin 2026

Produits

Lister et lire vos produits, leur état de stock, et ajuster un stock sur inventaire physique via l'API.

La ressource products permet de lister vos produits, d'en lire un, et d'ajuster son stock sur inventaire physique. L'enveloppe (authentification, pagination, format des réponses) est identique aux autres ressources.

Lecture et ajustement seulement

À ce jour, l'API publique ne crée pas de produit : il n'existe pas de POST /api/v1/products, ni de PATCH ou de DELETE. Les produits se créent et se modifient dans l'application. L'API sert à les lire et à ajuster les stocks (inventaire et mouvements).

Endpoints

Méthode	Chemin	Scope
`GET`	`/api/v1/products`	`read:products`
`GET`	`/api/v1/products/{id}`	`read:products`
`POST`	`/api/v1/products/{id}/adjust`	`write:products`

Lister les produits

GET /api/v1/products

Paramètres de requête

Paramètre	Type	Notes
`limit`	nombre	Défaut 20, maximum 100 (voir Pagination)
`offset`	nombre	Défaut 0
`trackStock`	`true` \| `false`	Ne renvoyer que les produits suivis (ou non suivis) en stock
`supplierId`	texte	Filtrer par fournisseur
`q`	texte	Recherche sur le nom, la référence et le code-barres

Champs renvoyés

id, name, reference, barcode, unit, unitPrice, costPrice, taxRate, supplierId, trackStock, stockQuantity, stockThreshold, updatedAt, et un champ dérivé stockState.

Champ	Type	Notes
`unitPrice`	nombre	Prix de vente unitaire, dans l'unité monétaire de l'espace (euros), comme `lines[].unitPrice` sur les factures
`costPrice`	nombre	Coût d'achat unitaire, même unité
`trackStock`	booléen	`true` si le produit est suivi en stock
`stockQuantity`	nombre	Stock courant (présent si `trackStock` est `true`)
`stockThreshold`	nombre	Seuil d'alerte de stock faible
`stockState`	texte	État dérivé : `ok`, `low`, `out` ou `untracked`

Le champ stockState résume l'état de stock sans calcul de votre côté :

Valeur	Sens
`ok`	Stock au-dessus du seuil d'alerte
`low`	Stock sous le seuil d'alerte (stock faible)
`out`	Stock à zéro (rupture)
`untracked`	Produit non suivi en stock (`trackStock` est `false`)

Exemple

curl -H "Authorization: Bearer nsk_live_…" \
     "https://app.naskel.io/api/v1/products?trackStock=true&q=cable&limit=20"

Lire un produit

GET /api/v1/products/{id} renvoie le même objet qu'en liste, enveloppé dans data. Un identifiant inconnu renvoie une erreur 404 not_found.

Ajuster un stock (inventaire physique)

POST /api/v1/products/{id}/adjust

Vous transmettez la quantité physiquement constatée, et le serveur calcule le delta avec le stock courant puis enregistre l'ajustement. C'est l'opération à utiliser pour un inventaire : vous décrivez ce que vous comptez, pas la variation.

Idempotent

Cet appel accepte l'en-tête Idempotency-Key. Rejouer la même clé renvoie le même résultat sans appliquer l'ajustement une seconde fois. Voir Idempotence.

Corps de la requête

Champ	Type	Requis	Notes
`countedQuantity`	nombre, 0 ou plus	Oui	Quantité physiquement constatée
`note`	texte, 280 caractères max	Non	Motif de l'ajustement

Réponse

Code 200. La réponse contient l'avant/après et l'identifiant du mouvement créé :

{
  "data": {
    "productId": "…",
    "before": 12,
    "after": 20,
    "delta": 8,
    "movementId": "…"
  }
}

Erreurs

HTTP	`code`	Quand
404	`not_found`	Le produit n'existe pas
422	`stock_adjust_failed`	L'ajustement est refusé par le moteur de stock (par exemple, une politique de stock négatif bloquante)

Un ajustement appliqué émet l'événement webhook stock.adjusted (voir Webhooks).

Exemple

curl -X POST "https://app.naskel.io/api/v1/products/prod_123/adjust" \
  -H "Authorization: Bearer nsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3…" \
  -d '{ "countedQuantity": 20, "note": "Inventaire annuel" }'

Voir aussi

Mouvements de stock : enregistrer des entrées et sorties
Scopes et permissions
Codes d'erreur
Côté application : Stock et inventaire