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

# Produits

> Apprenez à récupérer et gérer les produits via l'API Chariow

Les produits sont au cœur de votre boutique Chariow. Ce guide explique comment récupérer et travailler avec les produits via l'API publique.

## Types de produits

Chariow prend en charge plusieurs types de produits :

| Type           | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `downloadable` | Fichiers numériques que les clients peuvent télécharger après l'achat |
| `course`       | Cours en ligne avec chapitres et leçons structurés                    |
| `license`      | Licences logicielles avec gestion de l'activation et de la validation |
| `service`      | Services numériques, consultations ou travaux personnalisés           |
| `bundle`       | Collection de plusieurs produits vendus ensemble à prix réduit        |
| `coaching`     | Sessions de coaching ou de mentorat                                   |

## Catégories de produits

Les produits sont organisés selon les catégories suivantes :

| Catégorie                  | Valeur                      |
| -------------------------- | --------------------------- |
| Arts créatifs              | `creative_arts`             |
| Technologie                | `technology`                |
| Business et Finance        | `business_and_finance`      |
| Développement personnel    | `personal_development`      |
| Éducation et Apprentissage | `education_and_learning`    |
| Divertissement             | `entertainment`             |
| Santé et Bien-être         | `health_and_wellness`       |
| Littérature et Édition     | `literature_and_publishing` |
| Médias et Communication    | `media_and_communication`   |
| Divers                     | `miscellaneous`             |

## États des produits

Les produits peuvent être dans différents états :

* **Draft** - Non visible pour les clients, encore en cours de modification
* **Published** - Disponible à l'achat sur votre boutique
* **Archived** - Plus disponible mais conservé dans les archives

<Note>
  L'API publique retourne uniquement les produits **publiés**. Les produits en brouillon et archivés ne sont pas accessibles via l'API.
</Note>

## Lister les produits

Récupérez tous les produits publiés de votre boutique avec filtrage optionnel :

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/products?per_page=20&type=course" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chariow.com/v1/products?per_page=20&type=course', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });

  const result = await response.json();
  console.log(result.data); // Array of products
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.chariow.com/v1/products',
      params={'per_page': 20, 'type': 'course'},
      headers={'Authorization': 'Bearer sk_live_your_api_key'}
  )
  products = response.json()['data']
  ```
</CodeGroup>

### Paramètres de requête

| Paramètre  | Type    | Description                                                        |
| ---------- | ------- | ------------------------------------------------------------------ |
| `per_page` | integer | Nombre de produits par page (par défaut : 10, max : 100)           |
| `cursor`   | string  | Curseur de pagination de la réponse précédente                     |
| `search`   | string  | Recherche par nom ou slug de produit                               |
| `category` | string  | Filtrer par catégorie (ex. `technology`, `education_and_learning`) |
| `type`     | string  | Filtrer par type (ex. `course`, `license`, `bundle`)               |

### Pagination

L'API utilise une pagination basée sur les curseurs pour une récupération efficace des données :

```javascript theme={null}
let allProducts = [];
let cursor = null;

do {
  const url = cursor
    ? `https://api.chariow.com/v1/products?cursor=${cursor}`
    : 'https://api.chariow.com/v1/products';

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();
  allProducts.push(...result.data);
  cursor = result.pagination.next_cursor;
} while (cursor);

console.log(`Retrieved ${allProducts.length} products`);
```

### Exemple de réponse

```json theme={null}
{
  "data": [
    {
      "id": "prd_abc123",
      "name": "Complete Web Development Course",
      "slug": "web-development-course",
      "description": "A comprehensive course covering modern web development...",
      "type": "course",
      "category": {
        "value": "education_and_learning",
        "label": "Education and Learning"
      },
      "status": "published",
      "is_free": false,
      "pictures": {
        "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
        "cover": "https://cdn.chariow.com/products/cover.jpg"
      },
      "pricing": {
        "type": "one_time",
        "price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "current_price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "effective": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "sale_price": null,
        "minimum_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "price_off": null
      },
      "has_variant_pricing": false,
      "quantity": null,
      "settings": {
        "is_shipping_address_required": false
      },
      "rating": {
        "average": 4.8,
        "count": 245
      },
      "on_sale_until": null,
      "sales_count": {
        "raw": 1250,
        "formatted": "1,250"
      },
      "seo": null,
      "custom_cta_text": {
        "value": null,
        "label": null
      },
      "fields": null,
      "store": null,
      "bundle": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more": true
  }
}
```

## Récupérer un produit unique

Récupérez les informations détaillées d'un produit spécifique par son ID public ou son slug :

<CodeGroup>
  ```bash cURL (by ID) theme={null}
  curl -X GET "https://api.chariow.com/v1/products/prd_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```bash cURL (by slug) theme={null}
  curl -X GET "https://api.chariow.com/v1/products/web-development-course" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  // By public ID
  const response = await fetch('https://api.chariow.com/v1/products/prd_abc123', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });

  const product = (await response.json()).data;
  console.log(product.name, product.pricing);
  ```

  ```python Python theme={null}
  import requests

  # By public ID
  response = requests.get(
      'https://api.chariow.com/v1/products/prd_abc123',
      headers={'Authorization': 'Bearer sk_live_your_api_key'}
  )
  product = response.json()['data']
  ```
</CodeGroup>

### Détails du produit

Le point de terminaison pour un produit unique retourne des informations complètes incluant :

* **Tarification** : Prix actuel, prix de base, prix effectif, prix de vente (si applicable), prix minimum, prix suggéré et pourcentage de réduction (`price_off`)
* **Images** : Miniature et images de couverture via `pictures`
* **Catégorie** : Catégorie du produit avec valeur et libellé
* **Tarification par variante** : Indique si le produit a une tarification par variante (`has_variant_pricing`)
* **Évaluations** : Note moyenne et nombre d'avis via `rating`
* **Ventes** : Nombre de ventes (si non masqué) via `sales_count`
* **Quantité** : Informations sur le stock (si le produit a une quantité limitée)
* **Paramètres** : Paramètres du produit tels que `is_shipping_address_required`
* **Expiration de la promotion** : Date et heure `on_sale_until` pour la tarification promotionnelle temporaire
* **Texte CTA personnalisé** : Texte d'appel à l'action personnalisé via `custom_cta_text`
* **Offre groupée** : Informations sur les économies pour les produits groupés
* **Champs personnalisés** : Champs de produit supplémentaires via `fields` (lorsque chargés)
* **SEO** : Métadonnées SEO via `seo` (lorsque chargées)
* **Boutique** : Informations sur la boutique (lorsque chargées)

## Types de tarification

Les produits peuvent avoir différents modèles de tarification :

<AccordionGroup>
  <Accordion title="Paiement unique" icon="credit-card">
    Un prix fixe que les clients paient une fois pour accéder au produit. C'est le type de tarification le plus courant.

    ```json theme={null}
    {
      "pricing": {
        "type": "one_time",
        "price": {
          "value": 49,
          "formatted": "$49.00",
          "short": "49",
          "currency": "USD"
        },
        "current_price": {
          "value": 49,
          "formatted": "$49.00",
          "short": "49",
          "currency": "USD"
        },
        "effective": {
          "value": 49,
          "formatted": "$49.00",
          "short": "49",
          "currency": "USD"
        },
        "sale_price": null,
        "minimum_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "price_off": null
      }
    }
    ```
  </Accordion>

  <Accordion title="Prix libre" icon="hand-holding-dollar">
    Les clients choisissent le montant à payer, avec un prix minimum et un prix suggéré optionnels. Utile pour les dons, les logiciels à contribution ou la tarification déterminée par le client.

    ```json theme={null}
    {
      "pricing": {
        "type": "what_you_want",
        "price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "current_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "effective": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "sale_price": null,
        "minimum_price": {
          "value": 5,
          "formatted": "$5.00",
          "short": "5",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 25,
          "formatted": "$25.00",
          "short": "25",
          "currency": "USD"
        },
        "price_off": null
      }
    }
    ```
  </Accordion>

  <Accordion title="Gratuit" icon="gift">
    Produits disponibles gratuitement, souvent utilisés pour la génération de leads, les cadeaux ou les contenus d'exemple.

    ```json theme={null}
    {
      "pricing": {
        "type": "free",
        "price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "current_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "effective": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "sale_price": null,
        "minimum_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "price_off": null
      },
      "is_free": true
    }
    ```
  </Accordion>

  <Accordion title="Prix promotionnel" icon="tag">
    Les produits peuvent avoir des prix promotionnels temporaires avec une date d'expiration. Le `current_price` reflète le prix actif.

    ```json theme={null}
    {
      "pricing": {
        "type": "one_time",
        "price": {
          "value": 149,
          "formatted": "$149.00",
          "short": "149",
          "currency": "USD"
        },
        "current_price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "effective": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "sale_price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "minimum_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "price_off": "34%"
      },
      "on_sale_until": "2025-02-28T23:59:59Z"
    }
    ```
  </Accordion>
</AccordionGroup>

## Offres groupées

Les offres groupées combinent plusieurs produits à un prix réduit. Lors de la récupération d'une offre groupée, vous recevrez des informations sur la valeur totale du groupe et les économies réalisées :

```json theme={null}
{
  "id": "prd_bundle123",
  "name": "Complete Developer Bundle",
  "slug": "developer-bundle",
  "type": "bundle",
  "pricing": {
    "type": "one_time",
    "price": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "current_price": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "effective": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "sale_price": null,
    "minimum_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "price_off": null
  },
  "bundle": {
    "value": {
      "value": 297,
      "formatted": "$297.00",
      "short": "297",
      "currency": "USD"
    },
    "savings": {
      "amount": {
        "value": 98,
        "formatted": "$98.00",
        "short": "98",
        "currency": "USD"
      },
      "percentage": "33%"
    }
  }
}
```

<Note>
  Le `bundle.value` indique la valeur totale si tous les produits étaient achetés séparément, tandis que `pricing.current_price` indique le prix réduit de l'offre groupée. Le `bundle.savings` montre combien les clients économisent en achetant l'offre groupée.
</Note>

## Travailler avec les données de produit

### Filtrer les produits

Vous pouvez combiner plusieurs filtres pour affiner vos requêtes de produits :

```javascript theme={null}
// Get all free courses
const response = await fetch(
  'https://api.chariow.com/v1/products?type=course&category=education_and_learning',
  {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  }
);

// Search for products
const searchResponse = await fetch(
  'https://api.chariow.com/v1/products?search=web+development',
  {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  }
);
```

### Comprendre les évaluations

Les produits incluent des informations d'évaluation avec la note moyenne et le nombre total :

```json theme={null}
{
  "rating": {
    "average": 4.8,
    "count": 245
  }
}
```

* **average** : Note de 0 à 5
* **count** : Nombre total d'évaluations reçues

### Quantité en stock

Pour les produits avec stock limité, le champ `quantity` fournit des informations détaillées :

```json theme={null}
{
  "quantity": {
    "value": 100,
    "remaining": {
      "value": 35,
      "percent": "35%"
    },
    "sold": {
      "value": 65,
      "percent": "65%"
    },
    "total": 100
  }
}
```

Les produits sans stock limité auront `quantity: null`.

### Formatage des prix

Tous les objets de prix incluent quatre champs pour un affichage flexible :

* **value** : Valeur numérique du montant (ex. `99` pour \$99.00)
* **formatted** : Chaîne prête à afficher (ex. `$99.00`, `£99.00`, `€99.00`)
* **short** : Chaîne abrégée lisible avec `forHumans` (ex. `99`, `5K`, `1.25M`)
* **currency** : Code de devise ISO (ex. `USD`, `EUR`, `GBP`)

```javascript theme={null}
// Using the formatted price
const product = response.data;
console.log(`Buy now for ${product.pricing.current_price.formatted}`);

const price = product.pricing.current_price.value;
if (price < 50) {
  console.log('Affordable option!');
}
```

## Cas d'utilisation courants

### Créer un catalogue de produits

```javascript theme={null}
async function buildProductCatalogue(category) {
  const products = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({
      per_page: 50,
      category: category,
      ...(cursor && { cursor })
    });

    const response = await fetch(
      `https://api.chariow.com/v1/products?${params}`,
      {
        headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
      }
    );

    const result = await response.json();
    products.push(...result.data);
    cursor = result.pagination.next_cursor;
  } while (cursor);

  return products;
}

// Get all technology products
const techProducts = await buildProductCatalogue('technology');
```

### Afficher les produits en promotion

```javascript theme={null}
async function getSaleProducts() {
  const response = await fetch('https://api.chariow.com/v1/products?per_page=100', {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();

  // Filter products currently on sale
  return result.data.filter(product =>
    product.pricing.sale_price !== null &&
    product.on_sale_until &&
    new Date(product.on_sale_until) > new Date()
  );
}
```

### Trouver les produits populaires

```javascript theme={null}
async function getPopularProducts(minRating = 4.5, minReviews = 50) {
  const response = await fetch('https://api.chariow.com/v1/products?per_page=100', {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();

  return result.data
    .filter(p => p.rating.average >= minRating && p.rating.count >= minReviews)
    .sort((a, b) => b.rating.average - a.rating.average);
}
```

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Utiliser la pagination par curseur" icon="arrows-rotate">
    Utilisez toujours la pagination basée sur les curseurs au lieu de récupérer tous les produits en une seule fois. Cela garantit une récupération efficace des données et évite les dépassements de délai.
  </Accordion>

  <Accordion title="Mettre en cache les données de produit" icon="database">
    Les données de produit ne changent pas fréquemment. Envisagez de mettre en cache les produits localement et de les actualiser périodiquement pour réduire les appels API.
  </Accordion>

  <Accordion title="Gérer les images manquantes" icon="image">
    Tous les produits n'ont pas d'images miniatures ou de couverture. Vérifiez toujours les valeurs `null` avant d'afficher les images.
  </Accordion>

  <Accordion title="Afficher les prix formatés" icon="sterling-sign">
    Utilisez le champ `formatted` des objets de prix pour l'affichage. Cela garantit un formatage correct des devises et des symboles.
  </Accordion>

  <Accordion title="Vérifier l'expiration des promotions" icon="clock">
    Lors de l'affichage des prix promotionnels, vérifiez que `on_sale_until` est dans le futur pour éviter d'afficher des promotions expirées.
  </Accordion>
</AccordionGroup>

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Lister les produits" icon="list" href="/api-reference/products/list-products">
    Consultez la référence API pour lister les produits
  </Card>

  <Card title="Récupérer un produit" icon="box" href="/api-reference/products/get-product">
    Consultez la référence API pour récupérer un produit
  </Card>

  <Card title="Guide de paiement" icon="shopping-cart" href="/fr/guides/checkout">
    Apprenez à créer des sessions de paiement
  </Card>

  <Card title="Authentification" icon="key" href="/fr/introduction/authentication">
    Apprenez comment fonctionne l'authentification API
  </Card>
</CardGroup>