Cas d'usage

L'API NERP Suite est conçue pour s'intégrer dans différents contextes métier. Voici les principaux scénarios d'utilisation avec les scopes et endpoints nécessaires.

---

1. Business Intelligence (Power BI, Metabase, Looker)

Connectez NERP Suite à votre outil de BI pour créer des dashboards de pilotage.

Scopes nécessaires : read:analytics, read:customer-orders, read:supplier-orders, read:accounting, read:products

Exemple : Dashboard Power BI

// Source de données Power BI - Ventes mensuelles
async function loadMonthlySales(year) {
  const response = await fetch(
    `https://api.nerpsuite.com/v1/public-api/analytics/sales?dateFrom=${year}-01-01&dateTo=${year}-12-31&groupBy=month`,
    { headers: { 'X-API-Key': apiKey } }
  );
  return await response.json();
  // Résultat directement exploitable comme source Power BI
}

// Source de données Power BI - Top 20 produits du trimestre
async function loadTopProducts(year, quarter) {
  const startMonth = (quarter - 1) * 3 + 1;
  const endMonth = startMonth + 2;
  const response = await fetch(
    `https://api.nerpsuite.com/v1/public-api/analytics/top-products?dateFrom=${year}-${String(startMonth).padStart(2, '0')}-01&dateTo=${year}-${String(endMonth).padStart(2, '0')}-31&limit=20`,
    { headers: { 'X-API-Key': apiKey } }
  );
  return await response.json();
}

---

2. Site e-commerce / Vitrine en ligne

Affichez votre catalogue et gérez les ventes depuis votre site web.

Scopes nécessaires : read:products, read:stock, read:categories, read:campaigns, write:customer-orders

Exemple : Page produit e-commerce

// Charger un produit avec son stock et les promotions actives
async function loadProductPage(productId) {
  const [product, stock, campaigns] = await Promise.all([
    fetch(`/v1/public-api/products/${productId}`, { headers }).then(r => r.json()),
    fetch(`/v1/public-api/stock/product/${productId}`, { headers }).then(r => r.json()),
    fetch(`/v1/public-api/campaigns/active`, { headers }).then(r => r.json()),
  ]);

  // Vérifier si une promo s'applique à ce produit
  const applicablePromo = campaigns.data.find(c =>
    c.targetAll || c.targetProductIds.includes(productId)
  );

  return {
    ...product,
    available: stock.data.reduce((sum, s) => sum + s.quantity, 0),
    discount: applicablePromo?.discountPercent || 0
  };
}

---

3. Application mobile vendeur / Caissier terrain

Équipez vos vendeurs d'une app mobile pour vendre et gérer les clients sur le terrain.

Scopes nécessaires : read:products, read:stock, read:customers, write:customers, write:customer-orders, read:campaigns

Exemple : Scan et vente rapide

// Le vendeur scanne un code-barres
async function scanAndSell(barcode, customerId, quantity) {
  // 1. Trouver le produit par SKU
  const product = await fetch(`/v1/public-api/products/sku/${barcode}`, { headers })
    .then(r => r.json());

  // 2. Vérifier le stock disponible
  const stock = await fetch(`/v1/public-api/stock/product/${product.id}`, { headers })
    .then(r => r.json());

  const bestBatch = stock.data.find(s => s.quantity >= quantity);
  if (!bestBatch) throw new Error('Stock insuffisant');

  // 3. Créer la commande
  const order = await fetch('/v1/public-api/orders', {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      customerId,
      items: [{ productId: product.id, batchId: bestBatch.batchId, quantity }]
    })
  }).then(r => r.json());

  return order;
}

---

4. Portail fournisseur

Donnez un accès dédié à vos fournisseurs pour qu'ils gèrent leurs commandes.

Scopes nécessaires : read:supplier-orders, write:supplier-orders

Exemple : Portail fournisseur

// Le fournisseur confirme une commande
async function confirmOrder(orderId) {
  const response = await fetch(`/v1/public-api/supplier-orders/${orderId}`, {
    method: 'PATCH',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'CONFIRMED' })
  });
  return await response.json();
}

// Le fournisseur crée une commande depuis son catalogue
async function createSupplierOrder(supplierId, items) {
  const response = await fetch('/v1/public-api/supplier-orders', {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      supplierId,
      items: items.map(i => ({
        productId: i.productId,
        quantity: i.quantity,
        unitPrice: i.unitPrice
      }))
    })
  });
  return await response.json();
}

---

5. Synchronisation ERP / Logiciel comptable

Connectez NERP Suite à votre ERP (Sage, QuickBooks, Odoo) ou logiciel comptable.

Scopes nécessaires : read:accounting, read:stock-movements, read:supplier-orders, read:customer-orders

Exemple : Export vers Sage

// Export mensuel des écritures vers Sage
async function exportToSage(year, month) {
  const dateFrom = `${year}-${String(month).padStart(2, '0')}-01`;
  const dateTo = `${year}-${String(month).padStart(2, '0')}-31`;

  let allEntries = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await fetch(
      `/v1/public-api/journal-entries?dateFrom=${dateFrom}&dateTo=${dateTo}&status=POSTED&page=${page}&limit=100`,
      { headers }
    ).then(r => r.json());

    allEntries = allEntries.concat(result.data);
    hasMore = page < result.totalPages;
    page++;
  }

  // Transformer pour Sage
  return allEntries.map(entry => ({
    date: entry.entryDate,
    journal: entry.journalType,
    reference: entry.entryNumber,
    libelle: entry.description,
    lignes: entry.lines.map(l => ({
      compte: l.accountId,
      debit: l.debit,
      credit: l.credit,
      libelle: l.description
    }))
  }));
}

---

6. Automatisation & Alertes (Webhooks)

Réagissez en temps réel aux événements NERP Suite sans polling.

Scopes nécessaires : read:webhooks, write:webhooks

Exemple : Notification Slack sur stock bas

// 1. Enregistrer le webhook (une seule fois)
await fetch('/v1/public-api/webhooks', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://votre-serveur.com/webhooks/nerpsuite',
    events: ['stock.low-alert', 'batch.expiring-alert'],
    description: 'Alertes stock vers Slack'
  })
});
// Sauvegardez le "secret" retourné pour vérifier les signatures !

// 2. Votre serveur reçoit les notifications
app.post('/webhooks/nerpsuite', (req, res) => {
  // Vérifier la signature HMAC
  const signature = req.headers['x-webhook-signature'];
  const expected = crypto.createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) return res.sendStatus(401);

  const { event, data } = req.body;

  if (event === 'stock.low-alert') {
    slack.send({
      channel: '#stock-alerts',
      text: `Alerte : ${data.productName} n'a plus que ${data.quantity} unités en stock`
    });
  }

  if (event === 'batch.expiring-alert') {
    slack.send({
      channel: '#stock-alerts',
      text: `Lot ${data.batchNumber} expire le ${data.expiryDate}`
    });
  }

  res.sendStatus(200);
});

---

7. Intégration marketplace (Jumia, Amazon, Shopify)

Synchronisez votre inventaire avec les plateformes de vente en ligne.

Scopes nécessaires : read:products, read:stock, read:categories, write:customer-orders, read:webhooks, write:webhooks

Exemple : Sync stock vers marketplace

// Synchronisation périodique du stock vers Jumia/Amazon
async function syncStockToMarketplace() {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await fetch(
      `/v1/public-api/stock?page=${page}&limit=100`,
      { headers }
    ).then(r => r.json());

    for (const item of result.data) {
      await marketplace.updateStock(item.sku, {
        quantity: item.quantity,
        available: !item.isLowStock
      });
    }

    hasMore = page < result.totalPages;
    page++;
  }
}

// OU en temps réel avec un webhook sur stock.movement-created

---

8. Gestion multi-entrepôts / Logistique

Pilotez vos entrepôts et optimisez la logistique.

Scopes nécessaires : read:warehouses, read:stock, read:stock-movements, read:webhooks, write:webhooks

Exemple : Dashboard logistique

// Vue d'ensemble de tous les entrepôts
async function getWarehouseOverview() {
  const warehouses = await fetch('/v1/public-api/warehouses', { headers })
    .then(r => r.json());

  const overview = [];
  for (const wh of warehouses.data) {
    const stock = await fetch(
      `/v1/public-api/stock?warehouseId=${wh.id}&limit=100`,
      { headers }
    ).then(r => r.json());

    overview.push({
      warehouse: wh.name,
      location: wh.location,
      totalProducts: stock.total,
      lowStockCount: stock.data.filter(s => s.isLowStock).length,
      lowStockItems: stock.data.filter(s => s.isLowStock).map(s => s.productName)
    });
  }

  return overview;
}

---

9. Application de fidélité client

Offrez une app dédiée à vos clients fidèles.

Scopes nécessaires : read:customers, read:campaigns, read:products

---

10. Audit & Conformité

Assurez la traçabilité complète pour vos auditeurs et inspections.

Scopes nécessaires : read:accounting, read:stock-movements, read:customer-orders, read:supplier-orders

Exemple : Export pour audit annuel

// Exporter toutes les données d'une année pour un audit
async function exportAuditData(year) {
  const dateFrom = `${year}-01-01`;
  const dateTo = `${year}-12-31`;

  const [entries, orders, supplierOrders, movements] = await Promise.all([
    fetchAll(`/v1/public-api/journal-entries?dateFrom=${dateFrom}&dateTo=${dateTo}&status=POSTED`),
    fetchAll(`/v1/public-api/orders?dateFrom=${dateFrom}&dateTo=${dateTo}`),
    fetchAll(`/v1/public-api/supplier-orders?dateFrom=${dateFrom}&dateTo=${dateTo}`),
    fetchAll(`/v1/public-api/stock-movements?dateFrom=${dateFrom}&dateTo=${dateTo}`)
  ]);

  return { entries, orders, supplierOrders, movements };
}

// Helper pour récupérer toutes les pages
async function fetchAll(baseUrl) {
  let all = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await fetch(
      `${baseUrl}&page=${page}&limit=100`,
      { headers }
    ).then(r => r.json());

    all = all.concat(result.data);
    hasMore = page < result.totalPages;
    page++;
  }

  return all;
}

---

Récapitulatif des scopes par scénario

Bonne pratique : Créez une clé API dédiée par scénario avec uniquement les scopes nécessaires. N'accordez jamais plus de permissions que requis.