API de Le Stock

Vue d’ensemble

Chaque structure a son espace, à son adresse : l’API d’un espace se trouve à cette même adresse, sous /api/v1/. Une clé ne vaut que pour l’espace qui l’a créée.

https://votre-espace.app.stockapp.fr/api/v1/

• Lecture seule. L’API ne crée, ne modifie et ne supprime rien : seules les requêtes GET sont admises. Le stock ne bouge que dans l’application, par une personne.
• De serveur à serveur. L’API ne répond pas aux scripts d’une page web d’un autre site (aucun en-tête CORS) : la clé secrète n’a rien à faire dans un navigateur.
• JSON, en HTTPS. Les réponses sont en UTF-8 et ne sont jamais à mettre en cache.

Obtenir une clé

Un administrateur de l’espace ouvre Réglages → API, nomme la clé — du nom du logiciel qui s’en servira — et la crée. Elle a deux valeurs :

• la clé API (lsk_…) identifie la clé. Elle reste affichée dans les réglages et se lit au Journal de l’espace ;
• la clé secrète (lss_…) l’authentifie. Elle n’est affichée qu’une fois, à la création : Le Stock n’en garde qu’une empreinte. Perdue, elle ne se retrouve pas : on révoque la clé et on en crée une autre.

Un espace porte 5 clés actives au plus : une par logiciel branché. Révoquer une clé coupe l’accès de ce logiciel dès sa requête suivante, sans toucher aux autres. Création et révocation sont tracées au Journal de l’espace.

Authentification

Chaque requête porte les deux valeurs en authentification HTTP « Basic » : la clé API comme identifiant, la clé secrète comme mot de passe. Tous les outils savent le faire.

curl -u "CLE_API:CLE_SECRETE" https://votre-espace.app.stockapp.fr/api/v1/ping

Sans clé, avec une clé inconnue ou révoquée, ou avec une clé secrète fausse, la réponse est la même : 401, sans dire laquelle des deux valeurs est en cause.

Requêtes et réponses

Une réponse réussie porte "ok": true et ses données dans data : une liste pour une ressource, un objet pour une ligne lue par son identifiant (/products/12).

• Pagination. Les listes sont rendues par identifiant croissant, 100 lignes à la fois (limit : 200 au plus). pagination.next_after donne l’identifiant à passer en after pour la page suivante ; null : c’était la dernière.
• Dates. Un jour s’écrit 2026-10-12 ; une date-heure, en ISO 8601 avec son décalage : 2026-10-12T09:30:00+02:00. Dans un paramètre, une date-heure sans décalage est lue à l’heure de Paris ; le + d’un décalage s’encode %2B dans une adresse.
• Nombres. Quantités et prix sont des nombres décimaux (3.0) : trois décimales au plus pour une quantité, quatre pour un prix. Les prix sont hors taxes.
• Valeur absente. Un champ sans valeur vaut null ; il est toujours présent.
• Paramètres. Un paramètre inconnu ou mal formé est refusé (422), jamais ignoré : un filtre mal écrit ne rend pas tout sans rien dire.

Erreurs et limites

Une erreur porte "ok": false, un code stable dans error et une explication en français dans message, à journaliser — pas à tester.

{
    "ok": false,
    "error": "INVALID_PARAMETER",
    "message": "Paramètre inconnu : « statut »."
}

Deux limites protègent le service, partagé entre toutes les structures :

• Débit. 5 requêtes par seconde et par espace, avec 20 requêtes d’avance pour une rafale. Au-delà : 429, à réessayer une seconde plus tard.
• Clés refusées. 15 appels refusés en 15 minutes depuis une même adresse IP, et cette adresse reçoit 429 pendant 15 minutes, même avec une bonne clé. Un logiciel dont la clé a été révoquée doit donc cesser d’appeler.

Vérifier la clé

Dit à quel espace la clé donne accès. À appeler pour le bouton « Tester la connexion » de votre logiciel.

GET /api/v1/ping

{
    "ok": true,
    "data": {
        "space": {
            "slug": "cabinet-des-lilas",
            "name": "Cabinet des Lilas"
        },
        "key": {
            "id": "lsk_3f9a1c0b7d2e4a6f8c10",
            "name": "Logiciel de commande"
        },
        "access": "read",
        "api_version": "v1",
        "time": "2026-10-12T09:30:00+02:00"
    }
}

Produits

Les fiches du catalogue, avec le stock disponible de chacune.

GET /api/v1/products
GET /api/v1/products/{id}

Lue par son identifiant, la ligne porte en plus supplier_refs : références du produit chez ses fournisseurs, l’habituelle en tête.

{
    "ok": true,
    "data": [
        {
            "id": 12,
            "commercial_name": "Gants Nitrile Taille M",
            "internal_reference": "HYG-004",
            "barcode": "03760012345673",
            "manufacturer": "Medistock",
            "manufacturer_reference": "GN-M-100",
            "category": "Hygiène",
            "order_unit": "Boîte de 100",
            "storage_location": "Armoire Stérilisation",
            "description": null,
            "book_subtitle": null,
            "book_collection": null,
            "book_edition": null,
            "book_published": null,
            "book_extent": null,
            "book_ark": null,
            "status": "active",
            "minimal_stock": 4.0,
            "stock_total": 3.0,
            "below_minimum": true,
            "created_at": "2026-09-02T08:41:12+02:00",
            "updated_at": "2026-10-06T17:03:55+02:00"
        }
    ],
    "pagination": {
        "limit": 100,
        "next_after": null
    }
}

Lots

Chaque réception d’un produit : numéro de lot, péremption, quantité restante.

GET /api/v1/lots
GET /api/v1/lots/{id}

{
    "ok": true,
    "data": [
        {
            "id": 87,
            "product_id": 12,
            "commercial_name": "Gants Nitrile Taille M",
            "lot_number": "L24B0917",
            "expiry_date": "2028-03-31",
            "quantity_remaining": 3.0,
            "quantity_purchased": 10.0,
            "status": "in_stock",
            "purchase_date": "2026-09-18",
            "supplier_id": 2,
            "supplier_reference": "774512",
            "unit_price_excl_tax": 6.9,
            "storage_location": "Armoire Stérilisation",
            "barcode": null,
            "created_at": "2026-09-18T11:20:03+02:00",
            "updated_at": "2026-10-09T14:12:48+02:00"
        }
    ],
    "pagination": {
        "limit": 100,
        "next_after": null
    }
}

Mouvements

Le registre du stock : entrées, sorties, corrections. Un mouvement n’est jamais supprimé ni modifié ; il peut être annulé.

GET /api/v1/movements
GET /api/v1/movements/{id}

{
    "ok": true,
    "data": [
        {
            "id": 1543,
            "movement_at": "2026-10-09T14:12:48+02:00",
            "movement_type": "stock_out",
            "product_id": 12,
            "lot_id": 87,
            "quantity": 2.0,
            "stock_delta": -2.0,
            "reason": null,
            "status": "active",
            "cancelled_at": null
        }
    ],
    "pagination": {
        "limit": 100,
        "next_after": null
    }
}

Fournisseurs

Les fournisseurs de la structure. Ni contact, ni adresse e-mail, ni téléphone.

GET /api/v1/suppliers
GET /api/v1/suppliers/{id}

{
    "ok": true,
    "data": [
        {
            "id": 2,
            "name": "Dentalis Distribution",
            "website": "https://www.dentalis.example",
            "shipping_fee": 9.9,
            "archived": false,
            "created_at": "2026-09-02T08:30:00+02:00",
            "updated_at": "2026-09-02T08:30:00+02:00"
        }
    ],
    "pagination": {
        "limit": 100,
        "next_after": null
    }
}

Produits à commander

Les produits actifs au seuil ou en dessous, le plus en manque en tête, avec leur fournisseur habituel et leur dernier prix d’achat. Liste complète, sans pagination.

GET /api/v1/reorder

{
    "ok": true,
    "data": [
        {
            "product_id": 12,
            "commercial_name": "Gants Nitrile Taille M",
            "internal_reference": "HYG-004",
            "manufacturer": "Medistock",
            "manufacturer_reference": "GN-M-100",
            "order_unit": "Boîte de 100",
            "minimal_stock": 4.0,
            "stock_total": 3.0,
            "missing": 1.0,
            "supplier_id": 2,
            "supplier_name": "Dentalis Distribution",
            "supplier_reference": "774512",
            "packaging": "Carton de 10 boîtes",
            "product_url": null,
            "last_unit_price_excl_tax": 6.9,
            "last_purchase_date": "2026-09-18"
        }
    ]
}

État du stock

Le stock en quelques nombres, calculés à l’instant de la requête : fiches, lots, péremptions, valeur. Pour un tableau de bord, ou pour ouvrir une analyse.

GET /api/v1/summary

{
    "ok": true,
    "data": {
        "products_active": 142,
        "products_in_stock": 131,
        "products_out_of_stock": 11,
        "products_below_minimum": 9,
        "lots_in_stock": 318,
        "lots_expired": 2,
        "lots_expiring": 14,
        "expiry_warning_days": 90,
        "stock_value_excl_tax": 8412.37,
        "lots_without_price": 27,
        "time": "2026-10-12T09:30:00+02:00"
    }
}

Consommation

Ce qui est sorti du stock et ce qui y est entré sur une période, cumulé par produit, mouvements annulés exclus. Seuls les produits qui ont bougé sur la période y figurent, le plus sorti en tête. Liste complète, sans pagination.

GET /api/v1/consumption?from=2026-10-01

{
    "ok": true,
    "data": [
        {
            "product_id": 12,
            "commercial_name": "Gants Nitrile Taille M",
            "internal_reference": "HYG-004",
            "category": "Hygiène",
            "order_unit": "Boîte de 100",
            "quantity_out": 14.0,
            "quantity_lost": 1.0,
            "quantity_in": 20.0,
            "quantity_corrected": -1.0,
            "movements": 17,
            "last_out_at": "2026-10-09T14:12:48+02:00",
            "stock_total": 3.0
        }
    ]
}

Achats

Les réceptions d’une période, cumulées par fournisseur, le montant le plus élevé en tête : ce qui a été reçu, et pour combien d’après les prix d’achat enregistrés. Réceptions annulées exclues, frais de port non compris. Une réception est datée au jour. Liste complète, sans pagination.

GET /api/v1/purchases?from=2026-10-01

{
    "ok": true,
    "data": [
        {
            "supplier_id": 2,
            "supplier_name": "Dentalis Distribution",
            "receptions": 23,
            "products": 18,
            "amount_excl_tax": 1284.6,
            "receptions_without_price": 2,
            "last_purchase_date": "2026-09-18"
        }
    ]
}

Interroger le stock avec Claude

L’API se branche aussi à un assistant. Une extension pour Claude Desktop, sur Mac et sur Windows, laisse Claude lire votre espace pour répondre à vos questions : ce qui périme bientôt, ce qu’il faut commander, ce qui a été consommé ou acheté sur une période, ce qui dort en stock.

Télécharger l’extension Le Stock pour Claude (version 1.2.0, fichier .mcpb).

1. Dans Le Stock, un administrateur ouvre Réglages → API, crée une clé — nommée « Claude », par exemple — et garde sous la main l’adresse de l’API et les deux valeurs de la clé.
2. Ouvrez le fichier téléchargé : Claude Desktop propose d’installer l’extension. Sinon, glissez le fichier dans la fenêtre de Claude Desktop.
3. Renseignez l’adresse de l’API, la clé API et la clé secrète. La clé secrète est gardée par le trousseau de votre ordinateur.
4. Posez votre question : « Qu’est-ce qui périme dans les deux mois ? », « Que faut-il commander cette semaine ? ».

• Lecture seule. Claude ne peut ni sortir, ni entrer, ni corriger du stock, ni toucher au catalogue : l’extension ne sait que lire, comme l’API.
• Ce que Claude reçoit. Ce que rend l’API, rien de plus : ni les comptes, ni un nom de personne, ni les notes de l’équipe. La description des fiches n’est pas transmise, sauf si vous cochez cette option dans les réglages de l’extension : elle peut venir d’une base publique que chacun peut modifier.
• Où vont ces données. De votre espace à votre ordinateur, puis à Claude, sous votre compte Anthropic et à ses conditions : c’est vous qui branchez cet assistant, Le Stock ne lui envoie rien de lui-même. Le détail est dans la politique de confidentialité.
• Des réponses à vérifier. Un assistant peut se tromper en lisant ou en comptant. Pour décider, le chiffre qui fait foi est celui de l’application.
• Retirer l’accès. Révoquez la clé dans Réglages → API : l’extension cesse de lire dès sa requête suivante.

Un autre assistant ? Le fichier est une archive zip. Son serveur (server/index.js, Node 18 ou plus) suit le protocole MCP et se lance depuis tout logiciel qui sait démarrer un serveur MCP local, avec les variables LESTOCK_API_URL, LESTOCK_API_KEY et LESTOCK_API_SECRET.

Suivre le stock dans le temps

Pour tenir une copie à jour sans tout relire à chaque fois :

• Nouveaux mouvements. Gardez l’identifiant du dernier mouvement lu et demandez la suite : /movements?after=1543. Un mouvement n’est jamais supprimé ni modifié.
• Annulations. Un mouvement ancien peut être annulé après coup : demandez-les à part, depuis votre dernier passage, avec /movements?cancelled_since=2026-10-12T08:00:00%2B02:00, et retirez leur stock_delta de vos totaux.
• État du stock. /lots?updated_since=… rend les lots touchés depuis une date, mouvements compris ; /products donne le stock disponible de chaque fiche.
• Catalogue. /products?updated_since=… rend les fiches modifiées. Une fiche retirée du catalogue est archivée (status) ; une fiche qui n’a jamais servi peut être supprimée : son identifiant répond alors 404.

Compatibilité

Dans la version 1, nous ajoutons : un champ, un paramètre, une ressource, une valeur à une liste de types. Nous ne retirons et ne renommons rien. Écrivez donc votre logiciel pour ignorer un champ qu’il ne connaît pas. Un changement incompatible ouvrirait une version 2, à une autre adresse ; la version 1 continuerait de répondre.

Ce que l’API ne rend jamais

• les comptes de l’espace, leurs adresses e-mail, leurs appareils ;
• un nom de personne : ni l’auteur d’un mouvement, ni le contact d’un fournisseur ;
• les notes et commentaires de l’équipe : notes d’une fiche ou d’un fournisseur, commentaire d’un mouvement, motif d’une annulation ;
• une donnée de patient : Le Stock n’en contient aucune.

La structure reste responsable de ce qu’elle confie au logiciel qu’elle branche. Le détail est dans la politique de confidentialité.