# Cas d'usage d'une API e-commerce : sept projets impossibles avec un widget

> Quand un widget de boutique n'a pas la bonne forme : e-commerce intégré à un SaaS, catalogue multi-supports, boutiques en marque blanche, UX sur mesure, agents IA, BI personnalisée. Avec des exemples de code du SDK JS de Shoprocket.

Ryan Badger - 4 août 2025 - 5 min de lecture

## À quoi sert une API e-commerce pour l'intégration

La plupart des plateformes e-commerce vous donnent un widget. Vous collez un script, vous obtenez une boutique. Ça convient très bien à 95 % des boutiques.

Une API de commerce, c'est ce que vous sortez quand vous voulez faire ce qu'un widget ne sait pas faire : afficher des produits dans votre propre interface, intégrer le paiement dans le tableau de bord d'un SaaS, distribuer un catalogue sur plusieurs supports (web + mobile + voix), ou construire des parcours d'achat sur mesure qu'aucune plateforme ne propose d'origine.

Shoprocket propose les deux. Le [widget](https://v3.shoprocket.io/fr/blog/commerce-headless-trois-niveaux-quelle-option-choisir.md) est l'option par défaut. Le [SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) sert quand le widget ne suffit plus, ou quand vous n'en avez jamais eu besoin.

## Les cas d'usage qui exigent une API, pas un widget

Ce sont les projets pour lesquels un widget ne suffit pas. Si votre idée figure dans cette liste, vous êtes en territoire API.

### 1. Le commerce à l'intérieur de votre produit SaaS

Le tableau de bord de votre SaaS a déjà sa propre interface. Vous voulez que vos clients achètent des modules complémentaires, des packs de crédits, des offres premium ou des goodies physiques sans quitter votre application.

Un widget serait la mauvaise forme : il ne connaît pas vos utilisateurs, ne respecte pas votre design system et suppose une boutique en pleine page. L'API vous permet d'afficher des fiches produit avec vos propres composants, d'appeler `cart.addItem()` au clic sur un bouton, et d'ouvrir votre propre panneau de paiement (ou de rediriger vers un paiement hébergé si vous préférez différer le travail de conformité).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Afficher les modules complémentaires dans votre tableau de bord SaaS
const addons = await sr.products.list({ category: 'addons' })

// L'utilisateur clique sur le bouton "Ajouter des crédits"
await sr.cart.addItem(addon.id, 1)
```

### 2. Un catalogue multi-supports (web + appli native + voix + chat)

Un seul catalogue de produits, affiché différemment à chaque endroit. La boutique web montre la fiche produit complète, l'appli iOS native une liste compacte, l'assistant vocal décrit les articles à voix haute, une intégration de chat répond avec un lien d'achat.

Les quatre supports appellent la même API. Quand vous modifiez le prix d'un produit dans le tableau de bord Shoprocket, chaque support le reflète à la requête suivante. Aucune synchronisation de contenu par support.

### 3. Des boutiques en marque blanche / pour partenaires

Vous êtes une plateforme où d'autres personnes vendent leurs produits : une place de marché communautaire, un annuaire de partenaires, un réseau de franchise avec un site par revendeur. Chaque partenaire a une identité de marque qui lui appartient, pas à vous.

Le site de chaque partenaire fait tourner votre framework mais appelle l'API de commerce avec sa propre `publicKey`. Ses produits, ses commandes, ses versements, le tout cloisonné par compte. Aucun widget ne vient gêner son identité de marque.

### 4. Une expérience d'achat entièrement sur mesure

Des configurateurs de produit interactifs (PC montés sur mesure, bijoux personnalisés, mobilier fait à la commande). Des visionneuses de produit en 3D. Des galeries photo « shop the room » où cliquer sur des pixels d'une image ajoute le produit au panier. Des boutons de réachat rapide dans un e-mail.

Le widget ne sait faire aucun de ces cas. L'API, si. Vous affichez l'interface imaginée par votre designer ; l'API gère la mécanique commerciale derrière.

### 5. Les agents IA et le commerce agentique

Un agent IA (ChatGPT, Claude, un agent sur mesure) capable de parcourir des produits et de finaliser des achats pour le compte de l'utilisateur. L'agent a besoin d'un accès programmatique à votre catalogue et à votre panier, pas d'un widget DOM qu'il devrait analyser.

Shoprocket propose des flux pour les protocoles de commerce IA en plus de l'accès API standard. Un agent à qui l'on demande « qu'est-ce qui est en stock à moins de 50 $ avec livraison gratuite » obtient une réponse structurée, pas une capture d'écran à décortiquer.

### 6. Le commerce intégré aux outils de contenu

Une page Notion dont les blocs peuvent être achetables. Un design Framer avec des zones cliquables pour acheter. Un outil de newsletter où les abonnés peuvent toucher une fiche produit et payer sans quitter l'e-mail. Le tout construit sur une API.

### 7. Les rapports sur mesure et les tableaux de bord BI

Le tableau de bord Shoprocket affiche le chiffre d'affaires, la conversion, les meilleurs produits. Ce qu'il n'affiche pas, ce sont *vos* indicateurs à vous : valeur vie client par cohorte, commandes par source de parrainage, marge après coût fournisseur. L'API expose les données de commandes et de clients pour que vous les envoyiez vers votre propre outil de BI, tableur ou tableau de bord interne.

## Ce que le SDK vous offre aujourd'hui

Depuis `@shoprocket/core` :

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

Plus l'API REST complète pour tout ce que le SDK n'encapsule pas encore (commandes, clients, remises, écriture de produits). Consultez [api.shoprocket.io/docs](https://api.shoprocket.io/docs) pour la référence complète.

## Quand l'approche API d'abord est une erreur

Quelques cas où le widget est le bon choix et où l'API est excessive :

- **Une boutique simple de 10 à 200 produits.** Le widget s'en charge parfaitement ; écrire votre propre interface de catalogue, c'est refaire un travail déjà résolu.
- **Vous n'avez pas de capacité d'ingénierie front-end dédiée.** L'approche API d'abord vous oblige à livrer et maintenir vos propres états de chargement, interface de variantes, gestion d'erreurs, accessibilité et i18n sur 21 langues. Ce sont des semaines de travail que le widget vous offre.
- **Votre priorité est la vitesse de lancement.** Le widget, c'est quelques minutes ; l'approche API d'abord, c'est des semaines au minimum.

Prenez le widget par défaut. Passez à l'API quand vous butez sur quelque chose que le widget ne sait pas faire.

## Un premier projet réaliste

Le projet « j'ai besoin de l'API » le plus courant : un produit SaaS qui veut vendre des crédits, des abonnements ou des modules ponctuels dans son propre tableau de bord.

La démarche :

1. Installez `@shoprocket/core` dans votre front-end
2. Créez dans Shoprocket une catégorie nommée « Add-ons » ou similaire
3. Ajoutez des produits avec les tarifs et descriptions exacts que vous voulez
4. Affichez la liste de produits dans votre tableau de bord avec votre propre bibliothèque de composants
5. Au clic, ajoutez au panier et redirigez vers le paiement hébergé de Shoprocket (ou intégrez le paiement en ligne si le travail supplémentaire ne vous effraie pas)
6. Configurez un point d'entrée webhook pour recevoir les événements `order.paid`, afin de provisionner ce que l'achat débloque (crédits, accès, expédition)

Voilà. Une poignée de fichiers, une journée de travail pour quelqu'un habitué à appeler des API. Pas de widget, pas d'iframe, aucun compromis sur l'interface de votre produit.

## Ce que nous ne recommandons pas

Ne reconstruisez pas une interface de catalogue complète qui ressemble beaucoup à ce que fait déjà le widget. Si vous passez des semaines sur une « grille de produits avec filtres et recherche », vous écrivez ce que le widget livre en quelques minutes. Utilisez le widget pour cette forme-là, et l'API pour les formes vraiment différentes.

> **Astuce :** si vous songez à passer à l'API d'abord parce que le style par défaut du widget ne correspond pas à votre marque, essayez d'abord les [points d'accroche de style du widget](https://github.com/shoprocket/shoprocket-js). Le widget accepte bien plus de personnalisation CSS qu'il n'y paraît. Une reconstruction complète via l'API est un chantier bien plus lourd.

## En bref

- **Widget** = option par défaut, couvre 95 % des boutiques
- **API / SDK** = quand le widget n'a pas la bonne forme (e-commerce intégré à un SaaS, multi-supports, marque blanche, UX sur mesure, agents IA, BI personnalisée)
- **Périmètre actuel du SDK :** produits, panier, sessions ; plus l'API REST complète pour les commandes / clients / remises
- **Schéma du premier projet :** un tableau de bord SaaS qui vend des crédits ou des modules via le SDK, avec un provisionnement piloté par webhook
- **Ne reconstruisez pas via l'API** ce que le widget fait déjà bien ; choisissez votre forme

[Démarrez un essai gratuit](https://app-v3.shoprocket.io/signup) et récupérez une clé publique ; le SDK est gratuit sur toutes les offres Shoprocket. 14 jours, sans carte.

---

- HTML version: https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget
- Language: Français (fr)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)