Passer au contenu principal
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 :
TypeDescription
downloadableFichiers numériques que les clients peuvent télécharger après l’achat
courseCours en ligne avec chapitres et leçons structurés
licenseLicences logicielles avec gestion de l’activation et de la validation
serviceServices numériques, consultations ou travaux personnalisés
bundleCollection de plusieurs produits vendus ensemble à prix réduit

Catégories de produits

Les produits sont organisés selon les catégories suivantes :
CatégorieValeur
Arts créatifscreative_arts
Technologietechnology
Business et Financebusiness_and_finance
Développement personnelpersonal_development
Éducation et Apprentissageeducation_and_learning
Divertissemententertainment
Santé et Bien-êtrehealth_and_wellness
Littérature et Éditionliterature_and_publishing
Médias et Communicationmedia_and_communication
Diversmiscellaneous

É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
L’API publique retourne uniquement les produits publiés. Les produits en brouillon et archivés ne sont pas accessibles via l’API.

Lister les produits

Récupérez tous les produits publiés de votre boutique avec filtrage optionnel :
curl -X GET "https://api.chariow.com/v1/products?per_page=20&type=course" \
  -H "Authorization: Bearer sk_live_your_api_key"

Paramètres de requête

ParamètreTypeDescription
per_pageintegerNombre de produits par page (par défaut : 10, max : 100)
cursorstringCurseur de pagination de la réponse précédente
searchstringRecherche par nom ou slug de produit
categorystringFiltrer par catégorie (ex. technology, education_and_learning)
typestringFiltrer 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 :
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

{
  "data": [
    {
      "id": "prd_abc123",
      "name": "Complete Web Development Course",
      "slug": "web-development-course",
      "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",
        "current_price": {
          "amount": 99.00,
          "currency": "USD",
          "formatted": "$99.00"
        },
        "price": {
          "amount": 99.00,
          "currency": "USD",
          "formatted": "$99.00"
        }
      }
    }
  ],
  "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 :
curl -X GET "https://api.chariow.com/v1/products/prd_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

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 de vente (si applicable) et pourcentage de réduction
  • Images : Miniature et images de couverture
  • Évaluations : Note moyenne et nombre d’avis
  • Ventes : Nombre de ventes (si non masqué)
  • Quantité : Informations sur le stock (si le produit a une quantité limitée)
  • Offre groupée : Informations sur les économies pour les produits groupés
  • Champs personnalisés : Champs de produit supplémentaires (lorsque chargés)
  • SEO : Métadonnées SEO (lorsque chargées)

Types de tarification

Les produits peuvent avoir différents modèles de tarification :
Un prix fixe que les clients paient une fois pour accéder au produit. C’est le type de tarification le plus courant.
{
  "pricing": {
    "type": "one_time",
    "current_price": {
      "amount": 49.00,
      "currency": "USD",
      "formatted": "$49.00"
    },
    "price": {
      "amount": 49.00,
      "currency": "USD",
      "formatted": "$49.00"
    },
    "sale_price": null,
    "price_off": null
  }
}
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.
{
  "pricing": {
    "type": "what_you_want",
    "min_price": {
      "amount": 5.00,
      "currency": "USD",
      "formatted": "$5.00"
    },
    "suggested_price": {
      "amount": 25.00,
      "currency": "USD",
      "formatted": "$25.00"
    }
  }
}
Produits disponibles gratuitement, souvent utilisés pour la génération de leads, les cadeaux ou les contenus d’exemple.
{
  "pricing": {
    "type": "free",
    "current_price": {
      "amount": 0,
      "currency": "USD",
      "formatted": "$0.00"
    }
  },
  "is_free": true
}
Les produits peuvent avoir des prix promotionnels temporaires avec une date d’expiration. Le current_price reflète le prix actif.
{
  "pricing": {
    "type": "one_time",
    "current_price": {
      "amount": 99.00,
      "currency": "USD",
      "formatted": "$99.00"
    },
    "price": {
      "amount": 149.00,
      "currency": "USD",
      "formatted": "$149.00"
    },
    "sale_price": {
      "amount": 99.00,
      "currency": "USD",
      "formatted": "$99.00"
    },
    "price_off": "34%"
  },
  "on_sale_until": "2025-02-28T23:59:59Z"
}

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 :
{
  "id": "prd_bundle123",
  "name": "Complete Developer Bundle",
  "slug": "developer-bundle",
  "type": "bundle",
  "pricing": {
    "type": "one_time",
    "current_price": {
      "amount": 199.00,
      "currency": "USD",
      "formatted": "$199.00"
    }
  },
  "bundle": {
    "value": {
      "amount": 297.00,
      "currency": "USD",
      "formatted": "$297.00"
    },
    "savings": {
      "amount": {
        "amount": 98.00,
        "currency": "USD",
        "formatted": "$98.00"
      },
      "percentage": "33%"
    }
  }
}
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.

Travailler avec les données de produit

Filtrer les produits

Vous pouvez combiner plusieurs filtres pour affiner vos requêtes de produits :
// 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 :
{
  "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 :
{
  "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 trois champs pour un affichage flexible :
  • amount : Nombre décimal (ex. 99.00)
  • currency : Code de devise ISO (ex. USD, EUR, GBP)
  • formatted : Chaîne prête à afficher (ex. $99.00, £99.00, €99.00)
// Using the formatted price
const product = response.data;
console.log(`Buy now for ${product.pricing.current_price.formatted}`);

// Working with the numeric amount
if (product.pricing.current_price.amount < 50) {
  console.log('Affordable option!');
}

Cas d’utilisation courants

Créer un catalogue de produits

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

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

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

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.
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.
Tous les produits n’ont pas d’images miniatures ou de couverture. Vérifiez toujours les valeurs null avant d’afficher les images.
Utilisez le champ formatted des objets de prix pour l’affichage. Cela garantit un formatage correct des devises et des symboles.
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.

Prochaines étapes