Analytics API

Endpoints pour récupérer des données de ventes agrégées et les performances des produits. Idéal pour alimenter Power BI ou tout autre outil de Business Intelligence.

Données de ventes agrégées

GET /v1/public-api/analytics/sales

Scope requis: read:analytics

Retourne les ventes agrégées par jour, semaine ou mois sur une période donnée.

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/analytics/sales?dateFrom=2024-01-01&dateTo=2024-03-31&groupBy=month" \
  -H "X-API-Key: sk_live_xxx"

Réponse

[
  {
    "period": "2024-01",
    "revenue": 1250000.00,
    "orders": 342,
    "avgBasket": 3654.97
  },
  {
    "period": "2024-02",
    "revenue": 980500.50,
    "orders": 287,
    "avgBasket": 3416.38
  },
  {
    "period": "2024-03",
    "revenue": 1450200.00,
    "orders": 401,
    "avgBasket": 3616.46
  }
]

Formats de période

Champs de réponse

---

Top produits

GET /v1/public-api/analytics/top-products

Scope requis: read:analytics

Retourne les produits les plus vendus par chiffre d'affaires sur une période donnée.

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/analytics/top-products?dateFrom=2024-01-01&dateTo=2024-03-31&limit=5" \
  -H "X-API-Key: sk_live_xxx"

Réponse

[
  {
    "productId": "prod_001",
    "productName": "iPhone 15 Pro",
    "sku": "IPHONE-15-PRO-128",
    "revenue": 498500.00,
    "quantity": 499,
    "orders": 487
  },
  {
    "productId": "prod_002",
    "productName": "AirPods Pro",
    "sku": "AIRPODS-PRO-2",
    "revenue": 215820.00,
    "quantity": 1199,
    "orders": 1150
  },
  {
    "productId": "prod_005",
    "productName": "Samsung Galaxy S24",
    "sku": "SAMSUNG-S24-256",
    "revenue": 187600.00,
    "quantity": 235,
    "orders": 220
  }
]

Champs de réponse

Cas d'usage

Dashboard Power BI - Courbe de ventes mensuelle

async function getMonthlySales(year) {
  const response = await fetch(
    `/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
}

Comparaison année sur année

async function compareYears(year1, year2) {
  const [sales1, sales2] = await Promise.all([
    fetch(`/v1/public-api/analytics/sales?dateFrom=${year1}-01-01&dateTo=${year1}-12-31&groupBy=month`, {
      headers: { 'X-API-Key': apiKey }
    }).then(r => r.json()),
    fetch(`/v1/public-api/analytics/sales?dateFrom=${year2}-01-01&dateTo=${year2}-12-31&groupBy=month`, {
      headers: { 'X-API-Key': apiKey }
    }).then(r => r.json())
  ]);

  return { [year1]: sales1, [year2]: sales2 };
}

Classement des produits par trimestre

async function getQuarterlyTopProducts(year, quarter) {
  const startMonth = (quarter - 1) * 3 + 1;
  const endMonth = startMonth + 2;
  const dateFrom = `${year}-${String(startMonth).padStart(2, '0')}-01`;
  const dateTo = `${year}-${String(endMonth).padStart(2, '0')}-31`;

  const response = await fetch(
    `/v1/public-api/analytics/top-products?dateFrom=${dateFrom}&dateTo=${dateTo}&limit=20`,
    { headers: { 'X-API-Key': apiKey } }
  );

  return await response.json();
}