Supplier Orders API

Endpoints pour accéder, créer et mettre à jour les commandes d'achat auprès de vos fournisseurs.

Lister les commandes fournisseurs

GET /v1/public-api/supplier-orders

Scope requis: read:supplier-orders

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/supplier-orders?status=DELIVERED&dateFrom=2024-01-01" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "id": "so_001",
      "orderNumber": "PO-2024-000012",
      "supplierId": "sup_001",
      "supplierName": "TechnoDistrib SARL",
      "status": "DELIVERED",
      "items": [
        {
          "productId": "prod_001",
          "productName": "iPhone 15 Pro",
          "sku": "IPHONE-15-PRO-128",
          "quantity": 50,
          "unitPrice": 750.00
        },
        {
          "productId": "prod_002",
          "productName": "AirPods Pro",
          "sku": "AIRPODS-PRO-2",
          "quantity": 100,
          "unitPrice": 180.00
        }
      ],
      "totalHT": 55500.00,
      "tvaRate": 18,
      "totalTVA": 9990.00,
      "totalTTC": 65490.00,
      "notes": "Commande urgente - réapprovisionnement",
      "createdAt": "2024-01-15T09:00:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}

---

Obtenir une commande fournisseur

GET /v1/public-api/supplier-orders/:id

Scope requis: read:supplier-orders

Paramètres de chemin

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/supplier-orders/so_001" \
  -H "X-API-Key: sk_live_xxx"

Réponse

Même format que dans la liste, mais pour une seule commande.

---

Créer une commande fournisseur

POST /v1/public-api/supplier-orders

Scope requis: write:supplier-orders

Corps de la requête

Exemple de requête

curl -X POST "https://api.nerpsuite.com/v1/public-api/supplier-orders" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "supplierId": "sup_001",
    "items": [
      { "productId": "prod_001", "quantity": 50, "unitPrice": 750.00 },
      { "productId": "prod_002", "quantity": 100, "unitPrice": 180.00 }
    ],
    "notes": "Commande urgente - réapprovisionnement"
  }'

Réponse

Retourne la commande créée au même format que GET /supplier-orders/:id.

---

Mettre à jour une commande fournisseur

PATCH /v1/public-api/supplier-orders/:id

Scope requis: write:supplier-orders

Paramètres de chemin

Corps de la requête

Tous les champs sont optionnels. Seuls les champs fournis seront mis à jour.

Exemple de requête

curl -X PATCH "https://api.nerpsuite.com/v1/public-api/supplier-orders/so_001" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONFIRMED",
    "notes": "Confirmée par le fournisseur le 20/01"
  }'

Réponse

Retourne la commande mise à jour au même format que GET /supplier-orders/:id.

---

Statuts de commande fournisseur

Champs de réponse

Commande fournisseur

Article de commande

Cas d'usage

Analyse des coûts d'approvisionnement

async function getSupplierSpending(dateFrom, dateTo) {
  const response = await fetch(
    `/v1/public-api/supplier-orders?dateFrom=${dateFrom}&dateTo=${dateTo}&status=DELIVERED`,
    { headers: { 'X-API-Key': apiKey } }
  );

  const { data } = await response.json();

  // Grouper par fournisseur
  const bySupplier = {};
  for (const order of data) {
    if (!bySupplier[order.supplierName]) {
      bySupplier[order.supplierName] = { totalTTC: 0, orders: 0 };
    }
    bySupplier[order.supplierName].totalTTC += order.totalTTC;
    bySupplier[order.supplierName].orders++;
  }

  return bySupplier;
}

Calculer le coût moyen d'achat par produit

async function getAvgPurchasePrice(productId) {
  let allOrders = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `/v1/public-api/supplier-orders?page=${page}&limit=100`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const result = await response.json();
    allOrders = allOrders.concat(result.data);
    hasMore = page < result.totalPages;
    page++;
  }

  // Extraire les lignes du produit
  const lines = allOrders
    .flatMap(o => o.items)
    .filter(i => i.productId === productId);

  const totalQty = lines.reduce((sum, l) => sum + l.quantity, 0);
  const totalCost = lines.reduce((sum, l) => sum + (l.unitPrice * l.quantity), 0);

  return totalQty > 0 ? totalCost / totalQty : 0;
}