Stock API

Endpoints pour accéder aux niveaux de stock en temps réel. Le stock est organisé par lots (batches), permettant une traçabilité complète avec numéros de lot, codes-barres et dates d'expiration.

Lister tout le stock

GET /v1/public-api/stock

Scope requis: read:stock

Paramètres de requête

Exemple de requête

# Tout le stock
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock" \
  -H "X-API-Key: sk_live_xxx"

# Stock d'un entrepôt spécifique
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock?warehouseId=wh_001" \
  -H "X-API-Key: sk_live_xxx"

# Seulement les produits en stock bas
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock?lowStock=true" \
  -H "X-API-Key: sk_live_xxx"

# Recherche par numéro de lot ou code-barres
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock?search=LOT-2025-001" \
  -H "X-API-Key: sk_live_xxx"

# Recherche par code-barres EAN-13
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock?search=2002501250001" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "productId": "clx1234567890",
      "productName": "iPhone 15 Pro",
      "sku": "IPHONE-15-PRO-128",
      "warehouseId": "wh_001",
      "warehouseName": "Entrepôt Principal",
      "quantity": 50,
      "minStock": 10,
      "isLowStock": false,
      "batchId": "batch_abc123",
      "batchNumber": "LOT-2025-001",
      "barcode": "2002501250001",
      "expiryDate": null
    },
    {
      "productId": "clx9876543210",
      "productName": "Yaourt Nature Bio",
      "sku": "YAOURT-BIO-500",
      "warehouseId": "wh_001",
      "warehouseName": "Entrepôt Principal",
      "quantity": 120,
      "minStock": 50,
      "isLowStock": false,
      "batchId": "batch_def456",
      "batchNumber": "LOT-2025-002",
      "barcode": "2002501250018",
      "expiryDate": "2025-03-15T00:00:00.000Z"
    }
  ],
  "total": 423,
  "page": 1,
  "limit": 20,
  "totalPages": 22
}

---

Rechercher un lot par identifiant

GET /v1/public-api/stock/batch/:identifier

Scope requis: read:stock

Retourne un lot spécifique en recherchant par son numéro de lot ou son code-barres. Idéal pour les scans de codes-barres.

Paramètres de chemin

Exemple de requête

# Recherche par numéro de lot
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock/batch/LOT-2025-001" \
  -H "X-API-Key: sk_live_xxx"

# Recherche par code-barres EAN-13
curl -X GET "https://api.nerpsuite.com/v1/public-api/stock/batch/2002501250001" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "productId": "clx1234567890",
  "productName": "iPhone 15 Pro",
  "sku": "IPHONE-15-PRO-128",
  "warehouseId": "wh_001",
  "warehouseName": "Entrepôt Principal",
  "quantity": 50,
  "minStock": 10,
  "isLowStock": false,
  "batchId": "batch_abc123",
  "batchNumber": "LOT-2025-001",
  "barcode": "2002501250001",
  "expiryDate": null
}

Réponse si non trouvé

Retourne null si aucun lot ne correspond à l'identifiant.

---

Stock par produit

GET /v1/public-api/stock/product/:productId

Scope requis: read:stock

Retourne tous les lots d'un produit spécifique dans tous les entrepôts.

Paramètres de chemin

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/stock/product/clx1234567890" \
  -H "X-API-Key: sk_live_xxx"

Réponse

[
  {
    "productId": "clx1234567890",
    "productName": "iPhone 15 Pro",
    "sku": "IPHONE-15-PRO-128",
    "warehouseId": "wh_001",
    "warehouseName": "Entrepôt Principal",
    "quantity": 50,
    "minStock": 10,
    "isLowStock": false,
    "batchId": "batch_abc123",
    "batchNumber": "LOT-2025-001",
    "barcode": "2002501250001",
    "expiryDate": null
  },
  {
    "productId": "clx1234567890",
    "productName": "iPhone 15 Pro",
    "sku": "IPHONE-15-PRO-128",
    "warehouseId": "wh_002",
    "warehouseName": "Boutique Centre",
    "quantity": 8,
    "minStock": 5,
    "isLowStock": false,
    "batchId": "batch_xyz789",
    "batchNumber": "LOT-2025-003",
    "barcode": "2002501250025",
    "expiryDate": null
  }
]

Champs de réponse

Cas d'usage

Scan de code-barres

Utilisez l'endpoint /batch/:identifier pour identifier rapidement un lot lors d'un scan :

async function onBarcodeScan(barcode) {
  const batch = await fetch(`/v1/public-api/stock/batch/${barcode}`, {
    headers: { 'X-API-Key': apiKey }
  }).then(r => r.json());

  if (batch) {
    console.log(`Produit: ${batch.productName}`);
    console.log(`Lot: ${batch.batchNumber}`);
    console.log(`Quantité disponible: ${batch.quantity}`);
    if (batch.expiryDate) {
      console.log(`Expire le: ${new Date(batch.expiryDate).toLocaleDateString()}`);
    }
  } else {
    console.log('Lot non trouvé');
  }
}

Synchronisation e-commerce

Utilisez l'endpoint stock pour synchroniser les disponibilités avec votre boutique en ligne :

const stock = await fetch('/v1/public-api/stock/product/prod_123', {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

const totalAvailable = stock.reduce((sum, s) => sum + s.quantity, 0);
await updateEcommerceStock(productId, totalAvailable);

Alertes de stock bas

Récupérez périodiquement les produits en stock bas pour déclencher des réapprovisionnements :

const lowStockItems = await fetch('/v1/public-api/stock?lowStock=true', {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

for (const item of lowStockItems.data) {
  await createPurchaseOrderAlert(item);
}

Gestion des dates d'expiration

Recherchez les lots qui expirent bientôt :

const stock = await fetch('/v1/public-api/stock', {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

const thirtyDaysFromNow = new Date();
thirtyDaysFromNow.setDate(thirtyDaysFromNow.getDate() + 30);

const expiringSoon = stock.data.filter(item => {
  if (!item.expiryDate) return false;
  return new Date(item.expiryDate) <= thirtyDaysFromNow;
});

for (const item of expiringSoon) {
  console.log(`${item.productName} (Lot: ${item.batchNumber}) expire le ${item.expiryDate}`);
}