Campaigns API

Endpoints pour accéder aux campagnes marketing actives.

Lister les campagnes actives

GET /v1/public-api/campaigns/active

Scope requis: read:campaigns

Retourne uniquement les campagnes actuellement actives (date de début passée et date de fin future).

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/campaigns/active" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "id": "camp_summer2024",
      "name": "Soldes d'été 2024",
      "description": "Jusqu'à 30% de réduction sur une sélection d'articles",
      "discountType": "PERCENTAGE",
      "discountValue": 30,
      "minPurchase": 50.00,
      "maxDiscount": 200.00,
      "promoCode": "SUMMER30",
      "targetTiers": ["SILVER", "GOLD", "PLATINUM"],
      "startDate": "2024-07-01T00:00:00Z",
      "endDate": "2024-08-31T23:59:59Z",
      "isActive": true
    },
    {
      "id": "camp_welcome",
      "name": "Bienvenue",
      "description": "10% de réduction pour les nouveaux clients",
      "discountType": "PERCENTAGE",
      "discountValue": 10,
      "minPurchase": null,
      "maxDiscount": 50.00,
      "promoCode": "WELCOME10",
      "targetTiers": ["BRONZE"],
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z",
      "isActive": true
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

---

Obtenir une campagne

GET /v1/public-api/campaigns/:id

Scope requis: read:campaigns

Paramètres de chemin

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/campaigns/camp_summer2024" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "id": "camp_summer2024",
  "name": "Soldes d'été 2024",
  "description": "Jusqu'à 30% de réduction sur une sélection d'articles",
  "discountType": "PERCENTAGE",
  "discountValue": 30,
  "minPurchase": 50.00,
  "maxDiscount": 200.00,
  "promoCode": "SUMMER30",
  "targetTiers": ["SILVER", "GOLD", "PLATINUM"],
  "startDate": "2024-07-01T00:00:00Z",
  "endDate": "2024-08-31T23:59:59Z",
  "isActive": true
}

Champs de réponse

Types de réduction

Niveaux de fidélité

Les campagnes peuvent cibler des niveaux de fidélité spécifiques :

Cas d'usage

Afficher les promotions sur votre site

async function getActivePromotions() {
  const response = await fetch('/v1/public-api/campaigns/active', {
    headers: { 'X-API-Key': apiKey }
  });

  const campaigns = await response.json();

  // Filtrer les campagnes avec code promo public
  return campaigns.data.filter(c => c.promoCode);
}

Vérifier l'éligibilité d'un client

function isCustomerEligible(campaign, customerTier) {
  // Si pas de restriction de tier, tout le monde est éligible
  if (!campaign.targetTiers || campaign.targetTiers.length === 0) {
    return true;
  }

  return campaign.targetTiers.includes(customerTier);
}

// Exemple
const campaign = { targetTiers: ['GOLD', 'PLATINUM'] };
isCustomerEligible(campaign, 'GOLD');    // true
isCustomerEligible(campaign, 'BRONZE');  // false

Calculer la réduction

function calculateDiscount(campaign, cartTotal) {
  // Vérifier le minimum d'achat
  if (campaign.minPurchase && cartTotal < campaign.minPurchase) {
    return 0;
  }

  let discount;

  if (campaign.discountType === 'PERCENTAGE') {
    discount = (cartTotal * campaign.discountValue) / 100;
  } else {
    discount = campaign.discountValue;
  }

  // Appliquer le plafond
  if (campaign.maxDiscount && discount > campaign.maxDiscount) {
    discount = campaign.maxDiscount;
  }

  return discount;
}

// Exemple
const campaign = {
  discountType: 'PERCENTAGE',
  discountValue: 20,
  minPurchase: 50,
  maxDiscount: 100
};

calculateDiscount(campaign, 200);  // 40€ (20% de 200)
calculateDiscount(campaign, 600);  // 100€ (plafonné)
calculateDiscount(campaign, 30);   // 0€ (minimum non atteint)