Partenaires

Le module partners gère les commerçants d'EtherBay qui acceptent les EtherPoints : fiche de l'entreprise, offres de récompense, import de lots de codes promo et statistiques de consommation. Un compte PARTNER n'agit que sur les entreprises dont il est propriétaire ; un ADMIN agit sur toutes. La suspension d'un partenaire relève du module Administration Mairie, la consommation des offres du module Boutique et récompenses.

Le guide Ajouter un commerçant partenaire enchaîne ces routes pour un nouveau commerçant.

#Routes

#Règle de propriété

assertPartnerAccess(partner, actor) est appelée par toutes les routes qui visent une entreprise existante, ainsi que par POST /marketplace/redeem.

La relation Partner.owner est déclarée avec onDelete: SetNull : si le compte propriétaire est supprimé de la base, l'entreprise devient orpheline et seul un administrateur peut encore la gérer. L'anonymisation RGPD ne supprime pas la ligne User et ne détache donc pas l'entreprise.

#GET /partners

Renvoie partners, la liste complète triée par date de création décroissante, entreprises suspendues comprises. Chaque entreprise contient toutes ses colonnes (id, name, logoUrl, isActive, ownerId, createdAt) et ses offres avec _count.claimedRewards. Pour n'afficher que les offres disponibles, les clients utilisent GET /marketplace/catalog.

#POST /partners

Un PARTNER devient toujours propriétaire de l'entreprise qu'il crée, quel que soit ownerId. Un ADMIN peut désigner un propriétaire ou laisser l'entreprise sans propriétaire. L'entreprise est créée avec isActive = true : elle apparaît dans le catalogue dès sa première offre, sans validation préalable de la Mairie.

{
  "success": true,
  "message": "Entreprise partenaire créée avec succès",
  "data": {
    "partner": { "id": "019a7c60-3a1b-7e2c-9d4f-6b8a0c2e4f17", "name": "Fromagerie des Quais", "logoUrl": "https://assets.etherbay.fr/partners/default.png", "isActive": true, "ownerId": "019a7c5f-...", "createdAt": "2026-11-11T15:10:02.118Z" }
  }
}

#POST /partners/offers

L'offre est créée active avec remainingStock = totalStock. Si expiresAt est fourni, il est écrit dans la clé Redis partner:offer_expiry:<offerId> et renvoyé dans la réponse.

{
  "success": true,
  "message": "Offre partenaire créée avec succès",
  "data": {
    "offer": { "id": "019a7c61-...", "partnerId": "019a7c60-...", "title": "Un plateau découverte offert", "costInPoints": 300, "totalStock": 30, "remainingStock": 30, "isActive": true, "createdAt": "2026-11-11T15:12:40.004Z", "expiresAt": "2026-12-31T23:59:59+01:00" }
  }
}

#POST /partners/codes/upload

Importe des codes promo fournis par le commerçant. Ils seront distribués avant les codes générés lors des échanges.

#Règles

1. L'offre doit exister (404 Offre partenaire introuvable) et l'acteur doit avoir accès à son entreprise.
2. Si codes contient au moins un élément, il est utilisé et csvContent est ignoré.
3. Sinon csvContent est découpé sur les retours à la ligne, virgules et points-virgules. Les éléments de moins de 3 caractères et l'en-tête code (toute casse) sont écartés. La longueur maximale de 64 caractères n'est pas vérifiée dans ce cas.
4. Sans aucun code retenu : 400 Aucun code promo valide fourni dans le lot (CSV ou liste).
5. Les doublons du lot sont retirés, puis le lot est fusionné sans doublon avec la réserve existante de la clé Redis partner:codes:<rewardId>.
6. totalStock et remainingStock de l'offre augmentent du nombre de codes du lot.

curl -s -X POST http://localhost:2053/api/v1/partners/codes/upload \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rewardId":"019a7c61-0e5d-7a3b-8c2f-4d6e8a0b2c19","csvContent":"code\nBOUL-2026-0001\nBOUL-2026-0002\nBOUL-2026-0003"}'

{
  "success": true,
  "message": "Lot de codes promos uniques injecté avec succès",
  "data": { "rewardId": "019a7c61-0e5d-7a3b-8c2f-4d6e8a0b2c19", "injectedCount": 3, "totalPoolAvailable": 3, "totalStock": 103, "remainingStock": 103 }
}

#GET /partners/:partnerId/consumption

partnerId n'est pas validé par Zod ; un identifiant inconnu donne 404 Entreprise partenaire introuvable. La réponse agrège toutes les offres de l'entreprise :

{
  "success": true,
  "message": "Indicateur de consommation des codes récupéré",
  "data": {
    "partner": { "id": "019a7c4f-...", "name": "La Boulangerie du Port d'EtherBay", "logoUrl": "https://assets.etherbay.fr/partners/default.png", "isActive": true },
    "summary": { "totalStock": 150, "remainingStock": 141, "claimedCount": 9, "redeemedInStoreCount": 4, "consumptionPercentage": 6 },
    "offersBreakdown": [
      { "rewardId": "019a7c50-...", "title": "-15% sur les viennoiseries et pains spéciaux", "costInPoints": 100, "totalStock": 100, "remainingStock": 94, "claimedCount": 6, "redeemedInStoreCount": 3, "consumptionRatePercent": 6 }
    ]
  }
}

Le repository charge toutes les lignes ClaimedReward de l'entreprise pour les compter en mémoire : le coût de la route croît avec le nombre de codes distribués.

#Erreurs du module