Store Platforms

Intégration de l’API Wix : authentification, webhooks et piège du Catalog V3

Découvrez l’intégration de l’API Wix : OAuth, clés API, jetons, Catalog V1 et V3, webhooks et gestion des 12 tentatives avec du code fonctionnel.

Photo de profil de Long Nguyen

Long Nguyen

Développeur fullstack · Ingénieur IA · Chercheur

• • 5 min de lecture •

Ce que couvre l’intégration de l’API Wix

Une intégration de l’API Wix repose sur du code qui lit ou modifie les données Wix (produits, commandes, contacts, réservations) via l’API REST ou le SDK JavaScript de Wix, ou qui réagit aux événements Wix grâce aux webhooks. Elle peut s’exécuter directement sur le site Wix, sur votre propre serveur ou dans une application installée sur les sites d’autres utilisateurs.

L’emplacement d’exécution du code détermine la méthode d’authentification, et ce choix influence tout le reste. La documentation Wix distingue cinq scénarios :

Scénario Où s’exécute votre code Authentification
Extension d’un site Wix Sur le site Wix Authentification de l’hôte, appliquée automatiquement
Application gérée par Wix (CLI ou Blocks) Hébergée par Wix Intégrée ; Wix fournit des jetons d’instance d’application pour le code backend
Application autogérée Sur votre serveur, installée sur les sites de marchands OAuth
Projet headless Sur la stack de votre choix OAuth pour les visiteurs et les membres ; client credentials ou clé API pour les opérations d’administration
Automatisation externe Sur votre serveur, dans un script ou un job CI Clé API

La plupart des projets visant à « connecter ma boutique Wix à un autre système » relèvent des deux dernières catégories. Déterminez votre cas avant d’écrire la moindre ligne de code : les identifiants, la durée de validité des jetons et le modèle d’autorisations diffèrent.

OAuth ou clé API : quelle authentification Wix choisir ?

Wix prend en charge OAuth et les clés API pour le code exécuté en dehors du tableau de bord Wix, de l’éditeur ou du site. Ces deux méthodes ne sont pas interchangeables.

  OAuth Clé API
Idéal pour Les applications installées sur de nombreux sites, ainsi que les identités de visiteurs, de membres et d’applications L’automatisation serveur à serveur, les intégrations externes et les opérations d’administration sur les sites que vous gérez
Durée de validité Jeton d’accès valide pendant 4 heures Valide jusqu’à sa révocation ou sa rotation dans le tableau de bord Wix
Renouvellement Jetons de visiteurs et de membres : refresh token valable 365 jours par défaut, renouvelé à chaque utilisation. Jetons d’application : pas de refresh token, il faut en générer un nouveau Sans objet
Délivré par Le client OAuth de votre application ou de votre projet headless Le propriétaire ou copropriétaire du compte, depuis le tableau de bord
Modèle d’autorisations Scopes accordés à l’application Scopes et accès aux sites (tous les sites du compte ou uniquement certains sites)
Applications Wix tierces Obligatoire Non disponible

La règle pratique pour les projets réels est la suivante : si l’intégration doit être installée par plusieurs marchands ou publiée dans l’App Market, développez une application et utilisez OAuth. Si elle relie le site Wix d’une seule entreprise à son ERP, son entrepôt ou ses outils de marketplace, une clé API limitée constitue le chemin le plus court. Les client credentials d’un projet headless sont une autre option si vous avez seulement besoin d’un accès administrateur au site associé à ce projet.

Traitez une clé API comme un mot de passe de compte. Limitez-la au nombre de sites et aux scopes strictement nécessaires à l’intégration, stockez-la dans un gestionnaire de secrets et gardez à l’esprit que les appels au niveau du site ne fonctionnent qu’avec des clés générées depuis le compte propriétaire du site. Si vous réalisez cette intégration pour un client, c’est à lui de créer la clé, car seuls les propriétaires et copropriétaires du compte peuvent le faire.

Obtenir un jeton d’accès Wix avec les client credentials

Pour les opérations d’administration d’un projet headless, le flux client credentials échange l’identifiant et le secret de votre client OAuth contre un jeton à courte durée de validité. Exécutez-le uniquement dans du code backend. Le secret n’est affiché qu’une seule fois lors de sa génération dans Headless Settings : enregistrez-le immédiatement.

L’endpoint de jeton est https://www.wixapis.com/oauth2/token, et la réponse inclut un expires_in de 14400 secondes. Ne demandez pas un nouveau jeton à chaque appel. Mettez-le en cache et renouvelez-le peu avant son expiration :

let cached = { token: null, expiresAt: 0 };

async function getWixToken() {
  const now = Date.now();
  if (cached.token && now < cached.expiresAt - 5 * 60 * 1000) {
    return cached.token;
  }
  const res = await fetch('https://www.wixapis.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: process.env.WIX_CLIENT_ID,
      client_secret: process.env.WIX_CLIENT_SECRET
    })
  });
  if (!res.ok) throw new Error('Wix token request failed: ' + res.status);
  const data = await res.json();
  cached = { token: data.access_token, expiresAt: now + data.expires_in * 1000 };
  return cached.token;
}

async function wixPost(path, body) {
  const token = await getWixToken();
  const res = await fetch('https://www.wixapis.com' + path, {
    method: 'POST',
    headers: { 'Authorization': token, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  return res.json();
}

Notez que le jeton doit être placé dans l’en-tête Authorization exactement tel qu’il est renvoyé, sans préfixe supplémentaire. Une clé API est envoyée dans ce même en-tête. Si un appel renvoie une erreur 401, le jeton a très probablement expiré : il est donc utile d’ajouter autour de wixPost un mécanisme de renouvellement suivi d’une seule nouvelle tentative.

Wix Stores Catalog V1 ou V3 : le piège de la plupart des intégrations

C’est à cet endroit que les intégrations de boutiques cessent souvent de fonctionner sans avertissement. Wix Stores possède deux API de catalogue produit, et chaque site utilise l’une ou l’autre. Selon la documentation Wix sur la gestion des versions du catalogue, ces deux versions ne sont pas rétrocompatibles, tous les sites passeront à terme à V3 et vous devez appeler l’endpoint GetCatalogVersion au début de chaque flux pour savoir quelle API utiliser. Chaque version déclenche également ses propres webhooks : une intégration destinée à fonctionner sur tous les sites doit donc s’abonner aux événements V1 et V3.

Le guide de migration de Wix précise aussi qu’il n’existe pas de procédure de migration automatique et qu’une application doit prendre en charge les deux versions pour pouvoir être installée sur les sites nouveaux comme existants. Voici les différences qui comptent en pratique :

Élément Catalog V1 Catalog V3
Produits sans options Produit simple Une variante par défaut avec un tableau choices vide ; toute entité achetable est une variante
Variantes dans les résultats de recherche Gérées par les appels V1 Les endpoints Query et Search ne renvoient pas les variantes ; utilisez la Read-Only Variants API
Stock stock.quantity sur le produit Inventory Items API, avec recherche par productId et/ou variantId
Prix remisé price et discountedPrice Avec une remise : le prix V1 devient compareAtPrice et discountedPrice V1 devient actualPrice. Sans remise : price devient actualPrice
Options Options avec managedVariants à true ou false Customizations API : options (qui créent des variantes) et modifiers (qui n’en créent pas)
Champs texte personnalisés customTextFields Modifiers de type FREE_TEXT
Pagination numericId utilisé pour la pagination par curseur Pagination par curseur intégrée à Query et Search
Événements Webhooks V1 Webhooks V3 avec une structure de payload différente

L’erreur coûteuse consiste à développer sur V3 parce qu’elle est plus récente, puis à découvrir que la boutique d’un marchand utilise encore V1 — ou l’inverse. Placez un adaptateur entre votre logique métier et Wix afin que la vérification de version ne soit effectuée qu’une seule fois :

// One interface, two implementations. Business logic never sees the version.
const catalog = (await isCatalogV3(siteAuth))
  ? new CatalogV3(siteAuth)
  : new CatalogV1(siteAuth);

const products = await catalog.listProducts();
const stock = await catalog.getStock(productId);

La séparation du stock et des variantes dans V3 est la principale source de reprise : ce qui était auparavant une seule lecture produit devient une requête produit, une requête de variantes et une recherche d’inventaire. Si vous préférez ne pas maintenir vous-même deux chemins de code, c’est précisément le type de mission couvert par notre service d’intégration Wix et de plateformes e-commerce.

Gérer les webhooks Wix sans perdre d’événements

Wix envoie les données des webhooks sous la forme d’un JSON Web Token signé dans le corps de la requête. Vous devez le vérifier avec la clé publique disponible dans la page Webhooks du tableau de bord de votre application. Le comportement décrit ci-dessous provient de la documentation Wix sur les webhooks :

  • Votre endpoint doit renvoyer HTTP 200 dans les 1250 ms, faute de quoi Wix considère la livraison comme échouée.
  • En cas d’échec, jusqu’à 12 tentatives supplémentaires sont effectuées selon un calendrier de relance.
  • Un webhook renvoyé peut arriver après un événement plus récent traité avec succès dès la première tentative : les événements peuvent donc être retardés et arriver dans le désordre.
  • Les webhooks ne contiennent pas toujours l’entité complète, et Wix recommande de prévoir les événements en double.
  • Les sites qui utilisent une ancienne version majeure de votre application ne reçoivent pas les nouveaux webhooks ajoutés.

Un délai de 1250 ms ne laisse pas le temps d’écrire dans une base de données ou d’effectuer des appels API supplémentaires. Le gestionnaire doit vérifier la signature, transmettre l’événement à une file de traitement, puis renvoyer 200. Rien de plus :

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();

app.post('/webhooks/wix', express.text({ type: '*/*' }), function (req, res) {
  let event;
  try {
    event = jwt.verify(req.body, process.env.WIX_APP_PUBLIC_KEY, {
      algorithms: ['RS256']
    });
  } catch (err) {
    return res.sendStatus(401);
  }
  queue.add(event); // your own job queue: parse and process later
  res.sendStatus(200);
});

Si vous développez avec le Wix CLI, les extensions d’événements prennent en charge le payload à votre place : ce gestionnaire n’est donc nécessaire que pour les applications auto-hébergées. L’onglet Logs de la page Webhooks du tableau de bord de l’application est le premier endroit à consulter lorsque des événements semblent manquer.

Un modèle de synchronisation qui résiste aux relances et aux pannes

Les livraisons pouvant être répétées, retardées ou reçues dans le désordre, un gestionnaire qui dirait « le stock a changé, soustrayons 1 » finirait par dériver. Le payload Wix signale qu’un changement a eu lieu, mais ne constitue pas un registre comptable. Le modèle suivant est fiable :

  1. Accusez réception rapidement. Vérifiez l’événement, placez un petit job en file (type d’événement et ID de l’entité), puis renvoyez 200.
  2. Relisez les données au lieu de faire confiance au payload. Le worker récupère l’entité actuelle via l’API Wix : l’état enregistré est ainsi toujours le plus récent.
  3. Effectuez un upsert avec l’ID de l’entité Wix. L’exécution deux fois du même job doit produire le même résultat.
  4. Effectuez une réconciliation planifiée. Wix recommande lui-même des requêtes API périodiques pour confirmer l’exactitude des webhooks. Une requête nocturne sur les produits ou commandes récemment modifiés permet de repérer ce qu’un webhook aurait manqué.
  5. Limitez la concurrence et appliquez un backoff sur les erreurs HTTP 429. Ce sont les imports en masse qui mettent le plus souvent les intégrations face aux limites de requêtes.

Les étapes 2 et 4 font la différence entre une intégration qui fonctionne en démonstration et une intégration qui reste fiable pendant des mois.

Erreurs de l’API Wix et leurs causes

Symptôme Cause probable Solution
Erreur 401 sur tous les appels REST Le jeton d’accès OAuth a expiré (durée de validité de 4 heures) Générez ou actualisez un jeton, puis réessayez une seule fois
Erreur 401 sur un appel Stores : jeton d’autorisation invalide ou Wix Stores non installé Le jeton n’appartient pas à ce site ou le site n’utilise pas Wix Stores Vérifiez que Stores est installé sur le site et que le jeton a été émis pour celui-ci
Erreur 403 avec une clé API La clé ne possède pas le scope nécessaire à l’opération ou le site cible ne fait pas partie des sites autorisés par la clé Modifiez les scopes et l’accès aux sites dans l’API Keys Manager
Un appel au niveau du site échoue avec une clé valide La clé a été générée depuis un autre compte que celui qui possède le site Utilisez une clé issue du compte propriétaire
Les produits n’ont aucune variante après le passage à V3 Query et Search en V3 ne renvoient pas les variantes Utilisez la Read-Only Variants API
L’intégration fonctionne sur une boutique mais échoue sur une autre Les deux boutiques utilisent des versions de catalogue différentes Appelez d’abord GetCatalogVersion et adaptez le traitement
Certains sites ne reçoivent jamais un nouveau webhook Le site utilise une ancienne version majeure de votre application Demandez aux marchands de mettre l’application à jour et consultez l’onglet Logs
Le même événement est traité deux fois Une relance a eu lieu après l’absence d’un 200 ou un dépassement du délai de 1250 ms Dédupliquez les événements et rendez les gestionnaires idempotents

Développer en interne ou faire appel à un prestataire

Un export unidirectionnel en lecture seule depuis une seule boutique Wix, pris en charge par une équipe disposant d’un développeur backend, peut raisonnablement être réalisé en interne. La situation change lorsque l’un des points suivants s’applique :

  • La synchronisation est bidirectionnelle (commandes entrantes, stock et suivi sortants) entre des marketplaces, un ERP ou un système de gestion d’entrepôt.
  • Plusieurs boutiques Wix sont concernées : vous devrez alors gérer les deux versions du catalogue.
  • Personne dans votre équipe ne souhaite assumer durablement la fiabilité des webhooks, la gestion des jetons et la réconciliation.

Avant de solliciter quelqu’un, rédigez cinq réponses : dans quel sens les données circulent, quelles entités sont concernées (produits, commandes, clients), quelle version du catalogue utilise chaque boutique, qui possède le compte Wix autorisé à créer une clé API et ce qui doit se passer lorsqu’une synchronisation échoue à 3 heures du matin. Ces cinq réponses représentent l’essentiel du périmètre.

Pour obtenir un second avis ou une estimation, demandez un devis gratuit pour votre intégration Wix en indiquant votre boutique, le système à connecter et les données concernées. Le tarif est défini en fonction du périmètre.

FAQ

Questions fréquentes

Wix possède-t-il une API publique ?

Oui. Wix propose une API REST pour accéder via HTTP à ses solutions métier et aux données des sites, notamment aux produits et commandes Wix Stores, ainsi qu’un SDK JavaScript et des webhooks pour les événements.

Dois-je développer une application Wix pour connecter ma propre boutique à un autre système ?

Pas nécessairement. Pour l’automatisation serveur à serveur sur les sites que vous gérez, une clé API est prévue pour cet usage. Un projet headless peut également utiliser les client credentials pour les appels d’administration. En revanche, une application avec OAuth est nécessaire si vous la distribuez via l’App Market de Wix ou si elle doit être installée sur les sites d’autres marchands.

Combien de temps un jeton d’accès Wix reste-t-il valide ?

Les jetons d’accès OAuth sont valides pendant 4 heures. Les jetons de visiteurs et de membres sont accompagnés d’un refresh token valable 365 jours par défaut, tandis que les jetons d’application issus des client credentials n’ont pas de refresh token et doivent être générés à nouveau. Les clés API restent valides jusqu’à leur révocation ou leur rotation.

Puis-je utiliser une clé API Wix dans une application Wix tierce ?

Non. Les clés API Wix ne sont pas disponibles pour les applications tierces. Ces applications doivent s’authentifier avec OAuth.

Quelle est la différence entre Wix Stores Catalog V1 et V3 ?

Il s’agit de deux API de catalogue produit distinctes et non rétrocompatibles. Dans V3, chaque produit possède au moins une variante, le stock se trouve dans l’Inventory Items API, les options et modifiers sont gérés via la Customizations API et les endpoints de requête V3 ne renvoient pas les variantes. Appelez GetCatalogVersion pour savoir quelle version utilise un site.

Dans quel délai mon endpoint doit-il répondre à un webhook Wix ?

Il doit répondre dans les 1250 ms avec un statut HTTP 200. Dans le cas contraire, Wix effectue jusqu’à 12 nouvelles tentatives : les doublons et les événements reçus dans le désordre sont donc normaux, et votre gestionnaire doit être idempotent.

Restez informé avec Netalith

Recevez des ressources de développement, des mises à jour produit et des offres spéciales directement dans votre boîte mail.