> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cas d'utilisation

> Découvrez des scénarios d'intégration concrets pour l'API Chariow

L'API Chariow permet une large gamme de scénarios d'intégration pour la vente de produits numériques. Voici cinq cas d'utilisation courants pour vous aider à démarrer.

## 1. Intégration de vitrine personnalisée

Créez une expérience d'achat entièrement personnalisée sur votre propre site web tout en utilisant Chariow pour le traitement des paiements et la livraison des produits.

### Scénario

Vous avez un site web ou une application web existante et souhaitez vendre des produits numériques sans rediriger les clients vers une boutique externe.

### Implémentation

<Steps>
  <Step title="Afficher les produits">
    Récupérez votre catalogue de produits via l'endpoint [Lister les produits](/api-reference/products/list-products) et affichez-les sur votre site.
  </Step>

  <Step title="Collecter les informations client">
    Créez un formulaire de paiement personnalisé pour collecter les détails du client (nom, email, téléphone).
  </Step>

  <Step title="Initier le paiement">
    Appelez l'[API Checkout](/api-reference/checkout/init-checkout) avec les données client et redirigez vers l'URL de paiement.
  </Step>

  <Step title="Gérer la finalisation">
    Utilisez une `redirect_url` personnalisée pour ramener les clients vers votre page de remerciement, et configurez les [Pulses](/fr/guides/pulses) pour des notifications de vente fiables.
  </Step>
</Steps>

### Exemple de code

```javascript theme={null}
// Récupérer les produits pour affichage
const products = await fetch('https://api.chariow.com/v1/products', {
  headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
}).then(res => res.json());

// Quand le client soumet le formulaire de paiement
async function handleCheckout(productId, customerData) {
  const response = await fetch('https://api.chariow.com/v1/checkout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      product_id: productId,
      email: customerData.email,
      first_name: customerData.firstName,
      last_name: customerData.lastName,
      phone: {
        number: customerData.phone,
        country_code: customerData.countryCode
      },
      redirect_url: 'https://votresite.com/merci?sale={sale_id}'
    })
  });

  const result = await response.json();

  if (result.data.step === 'payment') {
    window.location.href = result.data.payment.checkout_url;
  }
}
```

***

## 2. Gestion des licences logicielles

Vendez des logiciels avec génération automatique de clés de licence, validation et gestion des activations.

### Scénario

Vous développez des logiciels de bureau ou mobiles et devez les protéger avec des clés de licence, contrôler le nombre d'installations et gérer les activations.

### Implémentation

<Steps>
  <Step title="Vendre des produits licence">
    Créez des produits de type licence dans Chariow avec des limites d'activation configurées.
  </Step>

  <Step title="Valider au démarrage">
    Au lancement de votre logiciel, appelez l'endpoint [Obtenir la licence](/api-reference/licenses/get-license) pour vérifier si la licence est valide (vérifiez les champs `is_active`, `is_expired` et `can_activate`).
  </Step>

  <Step title="Activer à l'installation">
    À la première exécution, appelez [Activer la licence](/api-reference/licenses/activate-license) avec un identifiant machine unique.
  </Step>

  <Step title="Gérer les activations">
    Permettez aux utilisateurs de révoquer les licences lors du changement d'appareil via [Révoquer la licence](/api-reference/licenses/revoke-license).
  </Step>
</Steps>

### Exemple de code

```python theme={null}
import requests
import hashlib
import platform

def get_machine_id():
    """Générer un identifiant machine unique"""
    machine_info = f"{platform.node()}-{platform.machine()}-{platform.processor()}"
    return hashlib.sha256(machine_info.encode()).hexdigest()[:32]

def validate_license(license_key):
    """Vérifier si la licence est valide via l'endpoint Obtenir la licence"""
    response = requests.get(
        f'https://api.chariow.com/v1/licenses/{license_key}',
        headers={'Authorization': 'Bearer sk_live_your_api_key'}
    )
    data = response.json()
    return data['data']['is_active'] and not data['data']['is_expired']

def activate_license(license_key):
    """Activer la licence pour cette machine"""
    response = requests.post(
        'https://api.chariow.com/v1/licenses/activate',
        headers={'Authorization': 'Bearer sk_live_your_api_key'},
        json={
            'license_key': license_key,
            'identifier': get_machine_id(),
            'label': f"{platform.node()} - {platform.system()}"
        }
    )
    return response.json()

# Au démarrage de l'application
license_key = load_stored_license()
if not validate_license(license_key):
    show_license_expired_dialog()
```

***

## 3. Plugin de plateforme e-commerce

Créez un plugin ou une intégration pour les plateformes e-commerce (WordPress, Shopify, etc.) pour vendre des produits Chariow.

### Scénario

Vous souhaitez étendre une plateforme e-commerce existante pour vendre des produits numériques gérés dans Chariow, en synchronisant les produits et en traitant les commandes.

### Implémentation

<Steps>
  <Step title="Synchroniser le catalogue">
    Récupérez périodiquement les produits depuis Chariow et synchronisez-les avec la base de données de votre plateforme.
  </Step>

  <Step title="Gérer l'ajout au panier">
    Stockez les IDs de produits Chariow aux côtés des articles du panier de votre plateforme.
  </Step>

  <Step title="Traiter le paiement">
    Lors du paiement, créez des sessions de checkout Chariow pour chaque produit numérique.
  </Step>

  <Step title="Exécuter les commandes">
    Écoutez les [Pulses](/fr/guides/pulses) Chariow pour marquer les commandes comme exécutées dans votre plateforme.
  </Step>
</Steps>

### Exemple de code

```php theme={null}
<?php
// Exemple WordPress/WooCommerce

// Synchroniser les produits depuis Chariow
function sync_chariow_products() {
    $response = wp_remote_get('https://api.chariow.com/v1/products', [
        'headers' => [
            'Authorization' => 'Bearer ' . get_option('chariow_api_key')
        ]
    ]);

    $products = json_decode(wp_remote_retrieve_body($response), true);

    foreach ($products['data'] as $product) {
        update_or_create_wc_product($product);
    }
}

// Traiter le paiement pour un produit Chariow
function process_chariow_checkout($order_id) {
    $order = wc_get_order($order_id);

    foreach ($order->get_items() as $item) {
        $chariow_product_id = get_post_meta($item->get_product_id(), '_chariow_product_id', true);

        if ($chariow_product_id) {
            $response = wp_remote_post('https://api.chariow.com/v1/checkout', [
                'headers' => [
                    'Authorization' => 'Bearer ' . get_option('chariow_api_key'),
                    'Content-Type' => 'application/json'
                ],
                'body' => json_encode([
                    'product_id' => $chariow_product_id,
                    'email' => $order->get_billing_email(),
                    'first_name' => $order->get_billing_first_name(),
                    'last_name' => $order->get_billing_last_name(),
                    'phone' => [
                        'number' => preg_replace('/[^0-9]/', '', $order->get_billing_phone()),
                        'country_code' => $order->get_billing_country()
                    ]
                ])
            ]);

            $result = json_decode(wp_remote_retrieve_body($response), true);
            update_post_meta($order_id, '_chariow_sale_id', $result['data']['purchase']['id']);
        }
    }
}
```

***

## 4. Plateforme de cours avec contrôle d'accès

Construisez une plateforme d'apprentissage en ligne où l'accès aux cours est contrôlé par les achats Chariow.

### Scénario

Vous gérez une plateforme éducative et souhaitez vendre des cours, en contrôlant l'accès en fonction du statut d'achat et en gérant les inscriptions.

### Implémentation

<Steps>
  <Step title="Créer des produits cours">
    Configurez des produits de type cours dans Chariow avec votre contenu pédagogique.
  </Step>

  <Step title="Vérifier l'accès">
    Lorsque les utilisateurs tentent d'accéder au contenu du cours, vérifiez leur achat via l'endpoint [Obtenir la vente](/api-reference/sales/get-sale).
  </Step>

  <Step title="Gérer les inscriptions">
    Utilisez les [Pulses](/fr/guides/pulses) pour inscrire automatiquement les utilisateurs lorsque les achats sont finalisés.
  </Step>

  <Step title="Suivre la progression">
    Stockez la progression du cours dans votre base de données, liée à l'ID client Chariow.
  </Step>
</Steps>

### Exemple de code

```javascript theme={null}
// Middleware Express.js pour le contrôle d'accès aux cours

async function verifyCourseAccess(req, res, next) {
  const { courseSlug } = req.params;
  const userEmail = req.user.email;

  // Trouver la vente pour cet utilisateur et ce cours
  const salesResponse = await fetch(
    `https://api.chariow.com/v1/sales?product_slug=${courseSlug}&customer_email=${userEmail}`,
    {
      headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
    }
  );

  const sales = await salesResponse.json();
  const validSale = sales.data.find(sale => sale.status === 'completed');

  if (!validSale) {
    return res.status(403).json({
      error: 'Accès refusé',
      message: 'Veuillez acheter ce cours pour accéder au contenu',
      purchase_url: `/checkout/${courseSlug}`
    });
  }

  req.sale = validSale;
  next();
}

// Gestionnaire de webhook Pulse pour l'inscription automatique
app.post('/webhooks/chariow', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'sale.completed') {
    const { customer, product } = data;

    // Inscrire automatiquement l'utilisateur au cours
    await db.enrollments.create({
      user_email: customer.email,
      course_id: product.id,
      enrolled_at: new Date(),
      sale_id: data.id
    });

    // Envoyer l'email de bienvenue
    await sendCourseWelcomeEmail(customer.email, product.name);
  }

  res.status(200).send('OK');
});
```

***

## 5. Suivi des affiliés et des campagnes

Suivez l'attribution des ventes à travers les campagnes marketing et les partenaires affiliés.

### Scénario

Vous menez des campagnes marketing ou avez des partenaires affiliés et devez suivre quelles ventes proviennent de quelles sources pour calculer les commissions ou mesurer le ROI.

### Implémentation

<Steps>
  <Step title="Créer des IDs de campagne">
    Générez des identifiants de campagne uniques pour chaque canal marketing ou affilié.
  </Step>

  <Step title="Passer la campagne au checkout">
    Incluez le paramètre `campaign_id` lors de l'initiation des paiements.
  </Step>

  <Step title="Suivre via les Pulses">
    Capturez les données de campagne depuis les Pulses de vente pour attribuer les conversions.
  </Step>

  <Step title="Générer des rapports">
    Utilisez l'endpoint [Lister les ventes](/api-reference/sales/list-sales) avec des filtres de campagne pour générer des rapports d'attribution.
  </Step>
</Steps>

### Exemple de code

```javascript theme={null}
// Suivre la campagne depuis les paramètres URL
function getCheckoutDataWithCampaign(productId, customerData) {
  const urlParams = new URLSearchParams(window.location.search);
  const campaignId = urlParams.get('ref') || urlParams.get('utm_campaign') || urlParams.get('affiliate');

  const checkoutData = {
    product_id: productId,
    email: customerData.email,
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    phone: {
      number: customerData.phone,
      country_code: customerData.countryCode
    }
  };

  if (campaignId) {
    checkoutData.campaign_id = campaignId;
  }

  return checkoutData;
}

// Backend : Générer un rapport d'affilié
async function generateAffiliateReport(affiliateId, startDate, endDate) {
  const response = await fetch(
    `https://api.chariow.com/v1/sales?campaign_id=${affiliateId}&from=${startDate}&to=${endDate}`,
    {
      headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
    }
  );

  const sales = await response.json();

  const report = {
    affiliate_id: affiliateId,
    period: { start: startDate, end: endDate },
    total_sales: sales.data.length,
    total_revenue: sales.data.reduce((sum, sale) => sum + sale.amount.value, 0),
    commission: 0
  };

  // Calculer une commission de 20%
  report.commission = report.total_revenue * 0.20;

  return report;
}
```

***

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Bonnes pratiques" icon="shield-check" href="/fr/guides/best-practices">
    Apprenez les bonnes pratiques de l'API checkout pour la production
  </Card>

  <Card title="Guide du paiement" icon="cart-shopping" href="/fr/guides/checkout">
    Plongez dans le flux de paiement
  </Card>

  <Card title="Pulses" icon="webhook" href="/fr/guides/pulses">
    Configurez les webhooks pour des notifications en temps réel
  </Card>

  <Card title="Référence API" icon="code" href="/api-reference/introduction">
    Explorez la documentation complète de l'API
  </Card>
</CardGroup>