« Headless » est employé à tout-va, comme si découpler votre vitrine de votre back-end de commerce était toujours le bon choix. Ce n'est pas le cas. Mais quand ça l'est — une application mobile sur mesure, un site orienté contenu où le CMS pilote l'expérience, une borne en magasin, ou une vitrine dont les schémas d'interaction ne peuvent être exprimés par aucun modèle — vous avez besoin d'un back-end qui traite son API comme un produit à part entière plutôt que comme une réflexion après coup greffée sur un monolithe. Dirora est conçu ainsi : les mêmes opérations qui alimentent le tableau de bord d'administration et la vitrine par défaut sont exposées via une API REST propre, de sorte que vous pouvez composer le commerce dans n'importe quelle surface que vous construisez.
Ce guide s'adresse à l'ingénieur qui soupèse cette décision. Nous verrons comment l'API est organisée, comment fonctionnent l'authentification et la multi-location, les briques pratiques (catalogue, panier, paiement, webhooks), et — tout aussi important — quand vous ne devriez pas passer au headless et vous appuyer plutôt sur la vitrine intégrée.
Ce que « API-first » signifie réellement ici
L'API-first est un engagement architectural, pas un label marketing. Cela signifie que chaque capacité est conçue d'abord comme un point de terminaison d'API, et que les interfaces utilisateur sont des consommateurs de ce même contrat. En pratique, cela vous offre trois propriétés qui comptent lorsque vous construisez sur une plateforme :
Parité. Si l'administration peut le faire, votre intégration le peut aussi. Vous n'êtes jamais bloqué parce qu'une fonctionnalité « n'existe que dans l'interface ».
Stabilité. Comme les propres interfaces de la plateforme dépendent de l'API, les changements incompatibles nous coûtent cher à nous aussi — ce qui aligne nos intérêts sur les vôtres.
Composabilité. Vous pouvez adopter un seul élément (par exemple, des données produit en lecture seule pour un site marketing) sans reconstruire le paiement, et exploiter davantage l'API au fil du temps.
Sous le capot, Dirora fait tourner un back-end Go haute performance derrière cette API, de sorte que les points de terminaison à forte lecture — listes de produits, recherche, pages de collection — restent rapides sous charge. Si la structure interne de la plateforme vous intéresse, nous avons écrit sur la façon dont nous avons construit notre architecture en microservices et la façon dont nous gérons la multi-location.
Quand le headless en vaut la peine — et quand il n'en vaut pas
Passer au headless vous offre un contrôle total sur la couche de présentation. Cela vous confie aussi des responsabilités que la vitrine intégrée gère gratuitement : rendu côté serveur pour le SEO, optimisation des images, données structurées, mise en cache, accessibilité, et la longue traîne de cas limites du panier et du paiement. Soyez honnête sur ce compromis.
Le headless en vaut généralement la peine lorsque : vous déployez une application mobile native ; vous exploitez déjà une plateforme de contenu et souhaitez y intégrer le commerce ; vous avez des exigences de conception ou d'interaction qu'un thème ne peut réellement pas satisfaire ; ou vous intégrez le commerce dans un produit existant où la vitrine n'est qu'une surface parmi d'autres.
Le headless est généralement le mauvais choix lorsque : vous voulez une boutique esthétique, rapide et adaptée au SEO et que vous optez pour le headless surtout pour la « flexibilité ». La vitrine par défaut de Dirora propose déjà le rendu côté serveur, l'optimisation automatique des images et les données structurées, et l'éditeur de thème visuel vous permet de la personnaliser en profondeur — mise en page par glisser-déposer, aperçu en direct, historique annuler/rétablir et 41 widgets de vitrine — sans toucher du tout à l'API. Si vous n'avez pas besoin d'un front-end sur mesure, n'en construisez pas. Vous pouvez aussi mélanger les deux : faire tourner la vitrine standard pour votre boutique et n'utiliser l'API que pour des surfaces satellites comme une application ou une intégration partenaire.
Authentification et multi-location
Les requêtes authentifiées utilisent des jetons bearer, et chaque requête est cantonnée à un seul locataire afin que les données d'une boutique soient isolées de celles d'une autre. Les points de terminaison publics en lecture seule — listes de produits, pages de collection — sont conçus pour être appelés sans authentification, ce qui est exactement ce que vous voulez pour une vitrine qui restitue des données de catalogue à des visiteurs anonymes. Les opérations d'écriture et tout ce qui est propre au client nécessitent un jeton.
Traitez les identifiants comme n'importe quel secret : conservez les jetons côté serveur sur le serveur, n'expédiez jamais de clés privilégiées dans des bundles côté client, et utilisez les points de terminaison publics en lecture pour tout ce qui s'exécute dans le navigateur. Si vous construisez un front-end qui doit aussi écrire (ajouter au panier, passer des commandes), acheminez ces appels via votre propre backend-for-frontend afin que les identifiants sensibles ne quittent jamais votre infrastructure.
Le catalogue : produits, collections et recherche
La partie lecture est là où démarrent la plupart des projets headless. Vous pouvez récupérer les produits avec leurs variantes, images, tarifs et état des stocks, et parcourir les collections avec filtrage. Comme ces points de terminaison sont publics et compatibles avec la mise en cache, ils conviennent bien aux pages générées statiquement ou rendues côté serveur qui doivent être rapides et explorables.
Quelques remarques pratiques. Le multidevise et le multilingue sont de première classe — si votre boutique vend sur plusieurs marchés, demandez la langue et la devise dont vous avez besoin plutôt que de convertir côté client, afin que les prix et les textes restent cohérents avec ce que le paiement facturera. Si vous alimentez un catalogue pour développer dessus, l'importateur de produits CSV peut récupérer un catalogue existant depuis Shopify, Etsy, Big Cartel, Gumroad ou Sellfy, ce qui est un moyen plus rapide d'obtenir des données réalistes que de fabriquer des jeux d'essai à la main. Et si la recherche est centrale dans votre expérience, utilisez le point de terminaison de recherche plutôt que de tout récupérer et de filtrer côté client.
Panier, tunnel de commande et paiements
Le flux de panier et de commande peut être piloté par programmation : créer un panier, ajouter et mettre à jour des lignes d'article, appliquer des remises, et progresser jusqu'au paiement pour les clients invités comme connectés. Les paiements passent par Stripe, de sorte qu'une construction headless hérite des mêmes capacités que la vitrine standard — cartes aux taux standard sans majoration, Apple Pay, Google Pay, et le paiement fractionné via Klarna et Clearpay, avec PayPal également disponible. Les versements arrivent en deux à sept jours.
Un chiffre autour duquel il vaut la peine de concevoir : Dirora ne facture aucuns frais de transaction, sur aucun forfait. La seule ponction est de faibles frais de plateforme qui diminuent à mesure que vous grandissez — 1,5 % sur le forfait gratuit Starter, 0,75 % sur Pro, 0,25 % sur Business et 0 % sur Enterprise. Sur une construction headless où vous investissez déjà du temps d'ingénierie, il vaut la peine de vérifier exactement ce qu'une plateforme prélève sur chaque commande avant de vous engager ; nous détaillons les normes du secteur dans le pourcentage que prennent les plateformes e-commerce.
Webhooks : réagir aux événements en temps réel
Interroger une API pour savoir si quelque chose s'est produit est inutilement coûteux et lent. Les webhooks inversent la logique : vous vous abonnez à des événements — commande créée, paiement effectué, stock faible et autres — et Dirora envoie une requête à votre point de terminaison lorsqu'ils surviennent. C'est ainsi que vous maintenez un système d'entrepôt, un CRM, un outil comptable ou un prestataire logistique synchronisés sans un flux constant de requêtes.
Construisez votre récepteur de façon défensive. Vérifiez la signature de la charge utile afin de n'agir que sur des événements authentiques, répondez rapidement (effectuez le gros du travail de manière asynchrone après avoir accusé réception), et rendez vos gestionnaires idempotents — les réseaux relancent, et vous ne voulez pas qu'une livraison en double crée deux expéditions. Si vous préférez utiliser un connecteur existant plutôt que d'écrire votre propre récepteur, le répertoire des intégrations et l'écosystème d'applications en pleine croissance couvrent déjà de nombreux outils courants.
Limites de débit, performance et mise en production
L'accès à l'API est inclus sur chaque forfait avec des limites de débit raisonnables ; les intégrations à fort volume sur Enterprise peuvent négocier des plafonds plus élevés. Concevez comme si des limites existaient même quand vous en êtes loin : mettez en cache les lectures de catalogue, temporisez et réessayez en cas d'erreurs transitoires, et regroupez les requêtes lorsque l'API le permet. Cela vous garde vertueux dès maintenant et vous épargne une réécriture quand le trafic augmente.
Deux autres choses que les équipes headless sous-estiment systématiquement. Premièrement, la performance est votre responsabilité une fois que vous possédez le front-end — la vitrine par défaut de la plateforme est optimisée d'emblée, mais les Core Web Vitals de votre application sur mesure vous incombent, de sorte que nos notes sur l'optimisation des performances de la boutique s'appliquent directement. Deuxièmement, les domaines et le SSL nécessitent toujours une gestion : Dirora prend en charge les domaines personnalisés avec SSL automatique, et si vous pointez un front-end headless vers un sous-domaine ou un domaine apex, notre guide des domaines personnalisés et du SSL détaille le volet DNS.
Une recommandation pragmatique
La plupart des boutiques n'ont pas besoin d'être headless, et y recourir par défaut échange des semaines d'ingénierie contre une flexibilité que vous n'utiliserez peut-être jamais. Le schéma le plus solide que nous observons est hybride : faire tourner la vitrine standard en SSR pour votre boutique principale — rapide, explorable et maintenue pour vous — et utiliser l'API pour les surfaces qui en ont réellement besoin, comme une application mobile, une borne ou une intégration dans un autre produit. Ainsi, l'API prouve sa valeur exactement là où le code sur mesure apporte de la valeur, et la plateforme prend en charge les parties identiques pour tout le monde. Si vous hésitez encore sur l'endroit où construire, notre comparatif de plateformes honnête est un bon point de départ pour trancher.
Questions fréquentes
Dois-je passer au headless pour développer sur l'API de Dirora ?
Non. L'API est disponible sur chaque forfait et vous pouvez l'utiliser aux côtés de la vitrine standard — pour une application mobile, une intégration ou une synchronisation de données — sans remplacer votre front-end. Le headless complet (apporter votre propre vitrine) est une option, pas une obligation.
Que peut réellement faire l'API de Dirora ?
Comme Dirora est API-first, l'API reflète l'administration : lecture des données de catalogue (produits, variantes, collections, recherche), pilotage des paniers et du paiement, et abonnement aux événements webhook pour les commandes, les paiements et les stocks. Si une capacité existe dans le tableau de bord, elle est conçue pour être accessible via l'API.
Une vitrine headless sera-t-elle quand même bonne pour le SEO ?
C'est possible, mais le SEO devient votre responsabilité. La vitrine intégrée de Dirora propose par défaut le rendu côté serveur, les données structurées et l'optimisation des images ; un front-end sur mesure doit les implémenter lui-même. Si le SEO est une priorité et que vous n'avez pas de raison précise de passer au headless, la vitrine standard est généralement le choix le plus sûr.
Y a-t-il des frais de transaction sur les commandes pilotées par l'API ?
Non. Il n'y a aucuns frais de transaction sur aucun forfait, qu'une commande soit passée via la vitrine standard ou votre propre front-end headless. La seule ponction est de faibles frais de plateforme qui passent de 1,5 % sur le forfait gratuit à 0 % sur Enterprise.
Comment maintenir les systèmes externes synchronisés avec ma boutique ?
Utilisez les webhooks. Abonnez-vous à des événements comme commande créée, paiement effectué et stock faible, et envoyez-les à votre entrepôt, votre CRM ou votre outil comptable. Vérifiez la signature, répondez rapidement, et rendez vos gestionnaires idempotents afin que les livraisons relancées ne provoquent pas d'actions en double.