Subscriptions API

Gestion des plans d'abonnement, des souscriptions utilisateur et des operations de facturation.

Base URL : /api/v2

Plans d'abonnement

Endpoints Plans

Methode	Endpoint	Description	Auth
GET	/subscription-plans	Plans actifs disponibles	Non
GET	/subscription-plans/compare	Comparaison des plans (feature matrix)	Non
GET	/subscription-plans/:id	Details d'un plan par UUID	Non

GET /subscription-plans

Obtenir tous les plans d'abonnement disponibles.

GET /api/v2/subscription-plans

Reponse 200 OK

{
  "data": [
    {
      "id": "plan-free",
      "name": "Free",
      "description": "Acces basique avec publicites",
      "priceMonthly": 0,
      "priceYearly": 0,
      "currency": "EUR",
      "features": {
        "maxQuality": "SD_480",
        "maxScreens": 1,
        "hasAds": true,
        "hasDownloads": false,
        "hasHdr": false
      },
      "isPopular": false
    },
    {
      "id": "plan-premium",
      "name": "Premium",
      "description": "Full HD, telechargements, 4 ecrans",
      "priceMonthly": 9.99,
      "priceYearly": 99.99,
      "currency": "EUR",
      "features": {
        "maxQuality": "FHD_1080",
        "maxScreens": 4,
        "hasAds": false,
        "hasDownloads": true,
        "hasHdr": true
      },
      "isPopular": true,
      "badge": "Best Value"
    }
  ]
}

Comparaison des plans

Feature	Free	Basic	Premium	Ultimate
Prix/mois	0	4.99	9.99	14.99
Qualite max	SD	HD	FHD	4K
Ecrans	1	2	4	6
Publicites	Oui	Non	Non	Non
Telechargements	Non	Non	Oui	Oui
HDR	Non	Non	Oui	Oui
Dolby Atmos	Non	Non	Non	Oui
Acces anticipe	Non	Non	Non	Oui

---

Abonnements utilisateur

Endpoints

Methode	Endpoint	Description	Auth
GET	/subscriptions/current	Abonnement actif	Oui
GET	/subscriptions/history	Historique des abonnements	Oui
POST	/subscriptions	Souscrire a un plan	Oui
GET	/subscriptions/change-preview/:newPlanId	Previsualisation changement de plan	Oui
POST	/subscriptions/change	Changer de plan	Oui
POST	/subscriptions/cancel	Annuler l'abonnement	Oui
POST	/subscriptions/reactivate	Reactiver un abonnement annule	Oui
POST	/subscriptions/trial	Demarrer un essai gratuit	Oui
POST	/subscriptions/change-plan	Upgrade/downgrade de plan	Oui
PATCH	/subscriptions/payment-method	Mettre a jour le moyen de paiement	Oui
GET	/subscriptions/invoices	Historique de facturation	Oui

---

GET /subscriptions/current

Obtenir l'abonnement actif du compte.

GET /api/v2/subscriptions/current
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "id": "sub-uuid",
  "planId": "plan-premium",
  "planName": "Premium",
  "status": "ACTIVE",
  "billingCycle": "MONTHLY",
  "currentPeriodStart": "2025-01-01T00:00:00Z",
  "currentPeriodEnd": "2025-02-01T00:00:00Z",
  "cancelAtPeriodEnd": false,
  "features": {
    "maxQuality": "FHD_1080",
    "maxScreens": 4,
    "hasAds": false,
    "hasDownloads": true
  },
  "paymentMethod": {
    "type": "CARD",
    "last4": "4242",
    "brand": "visa",
    "expiryMonth": 12,
    "expiryYear": 2027
  },
  "nextBillingDate": "2025-02-01T00:00:00Z",
  "nextBillingAmount": 9.99,
  "daysRemaining": 17,
  "canUpgrade": true,
  "canDowngrade": true,
  "createdAt": "2024-06-01T00:00:00Z"
}

---

POST /subscriptions

Souscrire a un plan.

POST /api/v2/subscriptions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "planId": "plan-premium",
  "paymentMethodId": "pm-uuid",
  "autoRenew": true
}

Flux d'abonnement

1. GET /subscription-plans                           --> Choisir un plan
2. POST /subscriptions { planId, paymentMethodId }   --> Creer l'abonnement
   --> Si plan gratuit : activation immediate (ACTIVE)
   --> Si plan payant : statut PENDING + transaction PENDING
3. POST /webhooks/stripe ou /webhooks/paypal         --> Confirmation paiement
   --> Subscription passe a ACTIVE

---

GET /subscriptions/change-preview/:newPlanId

Previsualisation du changement de plan (prorata, credit, montant du).

GET /api/v2/subscriptions/change-preview/plan-ultimate
Authorization: Bearer <access_token>

---

POST /subscriptions/change

Changer de plan d'abonnement.

POST /api/v2/subscriptions/change
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "newPlanId": "plan-ultimate",
  "immediate": true
}

Flux de changement de plan

1. GET /subscriptions/change-preview/:newPlanId  --> Voir le prorata
2. POST /subscriptions/change { newPlanId, immediate: true }
   --> UPGRADE avec montant du > 0 : transaction de paiement creee
   --> DOWNGRADE ou upgrade gratuit : plan mis a jour immediatement
   --> immediate: false : changement programme au renouvellement

---

POST /subscriptions/cancel

Annuler l'abonnement.

POST /api/v2/subscriptions/cancel
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reason": "too_expensive",
  "immediate": false
}

Reponse 200 OK

{
  "id": "sub-uuid",
  "status": "ACTIVE",
  "cancelAtPeriodEnd": true,
  "canceledAt": "2025-01-15T10:30:00Z",
  "accessEndsAt": "2025-02-01T00:00:00Z",
  "message": "Your subscription will end on February 1, 2025"
}

---

POST /subscriptions/reactivate

Reactiver un abonnement en attente d'annulation (avant la fin de la periode).

POST /api/v2/subscriptions/reactivate
Authorization: Bearer <access_token>

---

Moyens de paiement

Methode	Endpoint	Description	Auth
GET	/payment-methods	Lister mes moyens de paiement	Oui
GET	/payment-methods/default	Moyen par defaut (204 si aucun)	Oui
GET	/payment-methods/summary	Resume des paiements	Oui
GET	/payment-methods/transactions	Historique des transactions	Oui
GET	/payment-methods/:id	Details d'un moyen	Oui
POST	/payment-methods	Ajouter un moyen	Oui
POST	/payment-methods/:id/set-default	Definir comme defaut	Oui
DELETE	/payment-methods/:id	Supprimer un moyen	Oui

Types supportes

Type	Description
CARD	Carte bancaire (Visa, Mastercard, Amex)
MOBILE_MONEY	Mobile Money
PAYPAL	PayPal
APPLE_PAY	Apple Pay
GOOGLE_PAY	Google Pay
BANK_ACCOUNT	Virement bancaire

Providers

STRIPE, PAYPAL, ORANGE_MONEY, MTN_MONEY, MANUAL

info

Maximum 5 moyens de paiement par utilisateur.

Statuts d'abonnement

Statut	Description
ACTIVE	Abonnement actif
TRIALING	En periode d'essai gratuit
PAST_DUE	Paiement echoue, periode de grace
CANCELED	Annule, acces jusqu'a la fin de la periode
UNPAID	Paiement echoue, acces suspendu
EXPIRED	Abonnement termine

Cycle de vie d'un abonnement

[Aucun abonnement] --> Free
Free --> Trialing (demarrer l'essai)
Free --> Active (souscrire)
Trialing --> Active (fin d'essai + paiement OK)
Trialing --> Canceled (fin d'essai sans paiement)
Active --> Active (renouvellement)
Active --> Canceled (annulation)
Active --> PastDue (echec de paiement)
PastDue --> Active (paiement reussi)
PastDue --> Unpaid (fin de la periode de grace)
Canceled --> Active (reactivation)
Canceled --> Expired (fin de la periode)
Unpaid --> Active (paiement OK)
Unpaid --> Expired (suspension du compte)

Webhooks de paiement

Methode	Endpoint	Description	Auth
POST	/webhooks/stripe	Webhook Stripe (signature verifiee)	Signature
POST	/webhooks/paypal	Webhook PayPal (signature verifiee)	Signature

L'authentification se fait par signature cryptographique du provider, pas par JWT.

Codes d'erreur

Code	HTTP	Description
SUB_001	404	Aucun abonnement actif
SUB_002	409	Deja abonne
SUB_003	409	Periode d'essai deja utilisee
SUB_004	400	ID de plan invalide
SUB_005	402	Paiement requis
SUB_006	402	Paiement echoue
SUB_007	409	Impossible de reactiver