# Configuration Stripe pour Xpeditis

Ce guide explique comment configurer Stripe pour le système de licences et d'abonnements.

## 1. Prérequis

- Compte Stripe (https://dashboard.stripe.com)
- Accès aux clés API Stripe

## 2. Configuration du Dashboard Stripe

### 2.1 Créer les Produits

Dans le Dashboard Stripe, allez dans **Products** et créez les produits suivants :

| Produit | Description |
|---------|-------------|
| **Xpeditis Starter** | Plan Starter - Jusqu'à 5 utilisateurs |
| **Xpeditis Pro** | Plan Pro - Jusqu'à 20 utilisateurs |
| **Xpeditis Enterprise** | Plan Enterprise - Utilisateurs illimités |

### 2.2 Créer les Prix

Pour chaque produit, créez 2 prix (mensuel et annuel) :

#### Starter
| Type | Prix | Récurrence |
|------|------|------------|
| Mensuel | 49 EUR | /mois |
| Annuel | 470 EUR | /an (~20% de réduction) |

#### Pro
| Type | Prix | Récurrence |
|------|------|------------|
| Mensuel | 149 EUR | /mois |
| Annuel | 1430 EUR | /an (~20% de réduction) |

#### Enterprise
| Type | Prix | Récurrence |
|------|------|------------|
| Mensuel | Prix personnalisé | /mois |
| Annuel | Prix personnalisé | /an |

### 2.3 Récupérer les Price IDs

Après avoir créé les prix, notez les **Price IDs** (format: `price_xxxxx`) pour chaque prix.

## 3. Configuration du Webhook

### 3.1 Créer le Webhook Endpoint

1. Allez dans **Developers > Webhooks**
2. Cliquez sur **Add endpoint**
3. Configurez :
   - **Endpoint URL**: `https://votre-domaine.com/api/v1/subscriptions/webhook`
   - **Events to send**: Sélectionnez les événements suivants :
     - `checkout.session.completed`
     - `customer.subscription.created`
     - `customer.subscription.updated`
     - `customer.subscription.deleted`
     - `invoice.payment_failed`

4. Cliquez sur **Add endpoint**
5. Notez le **Webhook signing secret** (format: `whsec_xxxxx`)

### 3.2 Test Local avec Stripe CLI

Pour tester les webhooks en local :

```bash
# Installer Stripe CLI
brew install stripe/stripe-cli/stripe

# Se connecter à Stripe
stripe login

# Écouter les webhooks et les transférer en local
stripe listen --forward-to localhost:4000/api/v1/subscriptions/webhook

# Le CLI affichera le webhook secret à utiliser localement
# > Ready! Your webhook signing secret is whsec_xxxxx
```

## 4. Variables d'environnement

Ajoutez ces variables dans votre fichier `.env` du backend :

```bash
# Clés API Stripe
STRIPE_SECRET_KEY=sk_test_xxxxx           # Clé secrète (test ou live)
STRIPE_WEBHOOK_SECRET=whsec_xxxxx          # Secret du webhook

# Price IDs (créés dans le Dashboard)
STRIPE_STARTER_MONTHLY_PRICE_ID=price_xxxxx
STRIPE_STARTER_YEARLY_PRICE_ID=price_xxxxx
STRIPE_PRO_MONTHLY_PRICE_ID=price_xxxxx
STRIPE_PRO_YEARLY_PRICE_ID=price_xxxxx
STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_xxxxx
STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_xxxxx

# URL Frontend (pour les redirections)
FRONTEND_URL=http://localhost:3000
```

## 5. Configurer le Customer Portal

Le Customer Portal permet aux clients de gérer leur abonnement (changer de plan, annuler, mettre à jour le paiement).

1. Allez dans **Settings > Billing > Customer portal**
2. Activez les options souhaitées :
   - [x] Allow customers to update their payment methods
   - [x] Allow customers to update subscriptions
   - [x] Allow customers to cancel subscriptions
   - [x] Show invoice history

3. Configurez les produits autorisés dans le portal

## 6. Mode Test vs Production

### Mode Test (Développement)
- Utilisez `sk_test_xxxxx` comme clé secrète
- Les paiements ne sont pas réels
- Utilisez les cartes de test Stripe :
  - Succès: `4242 4242 4242 4242`
  - Échec: `4000 0000 0000 0002`
  - 3D Secure: `4000 0025 0000 3155`

### Mode Production
- Utilisez `sk_live_xxxxx` comme clé secrète
- Activez le mode live dans le Dashboard
- Assurez-vous d'avoir complété la vérification de compte

## 7. Flux d'abonnement

```
┌─────────────────┐
│ Page Subscription│
│ (Frontend)       │
└────────┬────────┘
         │ Clic "Upgrade"
         ▼
┌─────────────────┐
│ POST /checkout  │
│ (Backend)       │
└────────┬────────┘
         │ Crée Checkout Session
         ▼
┌─────────────────┐
│ Stripe Checkout │
│ (Stripe)        │
└────────┬────────┘
         │ Paiement réussi
         ▼
┌─────────────────┐
│ Webhook         │
│ checkout.       │
│ session.completed│
└────────┬────────┘
         │ Met à jour la subscription
         ▼
┌─────────────────┐
│ Base de données │
│ (PostgreSQL)    │
└─────────────────┘
```

## 8. Gestion des erreurs

### Paiement échoué
- Le webhook `invoice.payment_failed` est déclenché
- L'abonnement passe en statut `PAST_DUE`
- L'utilisateur est informé et peut mettre à jour son moyen de paiement

### Annulation
- Via le Customer Portal ou l'API
- L'abonnement reste actif jusqu'à la fin de la période
- À la fin de la période, le webhook `customer.subscription.deleted` est déclenché
- L'organisation repasse au plan FREE

## 9. Vérification

### Checklist de configuration

- [ ] Produits créés dans Stripe Dashboard
- [ ] Prix créés (mensuel + annuel pour chaque plan)
- [ ] Webhook endpoint configuré
- [ ] Customer Portal configuré
- [ ] Variables d'environnement ajoutées au `.env`
- [ ] Test avec Stripe CLI en local
- [ ] Test d'un paiement complet (checkout → webhook)

### Test manuel

1. Lancez le backend et le frontend
2. Connectez-vous en tant qu'ADMIN
3. Allez dans Settings > Subscription
4. Cliquez sur "Upgrade" sur un plan payant
5. Utilisez la carte de test `4242 4242 4242 4242`
6. Vérifiez que le plan est mis à jour dans la base de données
7. Vérifiez que les licences sont correctement comptées

## 10. Commandes utiles

```bash
# Voir les webhooks reçus
stripe events list --limit 10

# Déclencher un webhook manuellement
stripe trigger checkout.session.completed

# Voir les logs
stripe logs tail
```

## Support

Pour toute question sur Stripe :
- Documentation Stripe : https://stripe.com/docs
- Support Stripe : https://support.stripe.com