DEV Community

Cover image for Comment utiliser les APIs BigCommerce: Guide du développeur pour l'intégration e-commerce
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser les APIs BigCommerce: Guide du développeur pour l'intégration e-commerce

En bref

Les API BigCommerce vous permettent de gérer les produits, les commandes, les clients et les opérations de la boutique de manière programmatique. Vous vous authentifiez avec des jetons API (pour le côté serveur) ou OAuth (pour les applications), appelez des points d'extrémité REST à api.bigcommerce.com et gérez les webhooks pour des mises à jour en temps réel. Pour les tests, utilisez Apidog pour enregistrer vos appels API, valider les réponses et partager des collections avec votre équipe.

Essayez Apidog dès aujourd'hui

Introduction

BigCommerce propulse plus de 60 000 boutiques en ligne. Chacune a besoin d'intégrations personnalisées : synchronisation d'inventaire, traitement des commandes, gestion des clients, traitement des paiements. C'est là qu'interviennent les API.

La plateforme offre trois types d'API : l'API Storefront (commerce découplé), l'API Management (opérations back-end) et l'API Payments (transactions). La plupart des développeurs travaillent avec l'API Management. Elle gère les produits, les commandes, les clients et tout ce qui se passe en coulisses.

La courbe d'apprentissage n'est pas abrupte, mais la documentation peut sembler accablante. Vous vous retrouverez à jongler entre les documents d'authentification, les références API et les guides de webhook juste pour accomplir une tâche simple.

Ce guide se concentre sur ce que vous utiliserez réellement : les produits, les commandes, les clients et les webhooks. Vous apprendrez l'authentification, les modèles courants et comment tester vos intégrations avant qu'elles ne touchent une boutique en direct.

💡 Astuce : Si vous créez des intégrations BigCommerce, Apidog vous aide à concevoir, tester et documenter ces appels API. Enregistrez les requêtes sous forme de collections, utilisez des variables d'environnement pour différentes boutiques et validez que les réponses correspondent aux schémas attendus. Il détecte les erreurs avant qu'elles n'affectent de vrais clients.

Testez vos API BigCommerce avec Apidog - gratuit

À la fin de ce guide, vous serez en mesure de :

  • Configurer correctement l'authentification BigCommerce
  • Gérer les produits, les variantes et l'inventaire
  • Traiter les commandes et gérer les données clients
  • Configurer des webhooks pour des mises à jour en temps réel
  • Tester et documenter vos intégrations avec Apidog

Authentification : obtenir l'accès à votre boutique

BigCommerce propose deux méthodes d'authentification selon ce que vous construisez.

Méthode 1 : Jetons API (pour les intégrations personnalisées)

Pour un script ou service lié à une seule boutique, utilisez les jetons API.

Créer un compte API :

  1. Accédez au panneau d'administration de votre boutique
  2. Paramètres → Comptes API → Créer un compte API
  3. Choisissez "V3/V2 API Token"
  4. Sélectionnez les portées nécessaires (Produits, Commandes, Clients, etc.)
  5. Enregistrez vos identifiants

Vous obtiendrez :

  • URL de la boutique : mystore.mybigcommerce.com
  • Jeton d'accès : abc123def456...
  • ID client : abc123...
  • Secret client : xyz789...

Premier appel avec curl :

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

Le store-hash correspond à la partie après /stores/ dans votre URL API ou URL d'administration.

Méthode 2 : OAuth (pour les applications du marché)

Pour une application sur le marché BigCommerce, utilisez OAuth.

Flux OAuth :

  1. L'utilisateur clique sur "Installer" sur votre application dans le marketplace
  2. BigCommerce redirige vers votre URL de callback avec un code d'authentification
  3. Votre serveur échange ce code contre un jeton d'accès
  4. Stockez le jeton d'accès pour les appels API futurs

Échange du code contre un jeton d'accès :

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})

const { access_token, context } = await response.json()
// access_token à utiliser pour les appels API
// context contient le store_hash
Enter fullscreen mode Exit fullscreen mode

Utiliser le jeton :

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

Gestion des produits et du catalogue

L'API catalogue V3 permet de gérer produits, variantes, catégories et marques.

Lister les produits 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Exemple de réponse :

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Créer un produit 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json

{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium cotton blend hoodie",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}
Enter fullscreen mode Exit fullscreen mode

Mettre à jour les variantes de produit

Pour gérer différentes options (taille, couleur) :

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Black"
    },
    {
      "option_display_name": "Size",
      "label": "Medium"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Gérer l'inventaire

Mettre à jour l'inventaire d'un produit :

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

Ou pour une variante spécifique :

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Commandes et exécution

L'API Orders V2 gère la création, la mise à jour et l'exécution des commandes.

Lister les commandes 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Exemple de réponse :

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Obtenir les détails de la commande 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Obtenir les produits de la commande 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Mettre à jour le statut de la commande 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "status_id": 12
}
Enter fullscreen mode Exit fullscreen mode

Principaux statuts :

  • 0 : Incomplet
  • 11 : En attente d'exécution
  • 12 : Terminé
  • 5 : Annulé
  • 4 : Remboursé

Créer un envoi (exécution) 

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Clients et segmentation

L'API Customers V3 gère les données clients, adresses et groupes.

Lister les clients 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Exemple de réponse :

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Créer un client 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json

{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}
Enter fullscreen mode Exit fullscreen mode

Mettre à jour un client 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Client fidèle - support prioritaire",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Webhooks pour les mises à jour en temps réel

Les webhooks notifient votre application lors d'événements dans une boutique. BigCommerce pousse les données vers vos endpoints.

Créer un webhook 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

Portées disponibles :

  • store/order/created - Nouvelle commande passée
  • store/order/updated - Statut de commande modifié
  • store/order/archived - Commande archivée
  • store/product/created - Produit ajouté
  • store/product/updated - Produit modifié
  • store/product/deleted - Produit supprimé
  • store/customer/created - Nouveau client
  • store/inventory/updated - Stock modifié

Vérifier les signatures de webhook

BigCommerce signe les webhooks pour garantir leur légitimité :

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Signature invalide')
  }

  // Traitez le webhook
  console.log('Commande créée :', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Tester les API BigCommerce avec Apidog

Les API BigCommerce exigent une authentification et des en-têtes cohérents. Tester manuellement avec curl devient vite fastidieux. Apidog simplifie vos workflows de tests.

Interface utilisateur d'Apidog montrant une requête API BigCommerce pour lister les produits.

1. Configuration de l'environnement

Définissez un environnement pour chaque boutique :

# Boutique de production
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Boutique de staging
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. Scripts de pré-requête

Ajoutez automatiquement les en-têtes d'authentification :

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})
pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})
Enter fullscreen mode Exit fullscreen mode

3. Valider les réponses

Testez que les produits possèdent les champs requis :

pm.test('Les produits ont les champs requis', () => {
  const response = pm.response.json()
  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('La pagination fonctionne', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})
Enter fullscreen mode Exit fullscreen mode

Testez les API BigCommerce avec Apidog - gratuit

Erreurs courantes et correctifs

401 Non autorisé

Cause : Jeton d'accès invalide ou manquant.

Correctif :

  1. Vérifiez l'en-tête X-Auth-Token
  2. Assurez-vous que le jeton n'est pas révoqué
  3. Vérifiez les bonnes portées sur le compte API

403 Interdit

Cause : Jeton valide mais sans la portée requise.

Correctif :

  1. Vérifiez les autorisations du compte API
  2. Ajoutez la portée manquante
  3. Générez un nouveau jeton avec des autorisations étendues

404 Introuvable

Cause : Mauvais endpoint ou ressource inexistante.

Correctif :

  1. Vérifiez le store hash
  2. Vérifiez la version de l'API (v2 vs v3)
  3. Assurez-vous que l'ID de ressource existe

429 Trop de requêtes

Cause : Dépassement de la limite de débit.

Correctif : Respectez les limites (Produits : 10 000/h, Commandes : 30 000/h). Surveillez X-Rate-Limit-Remaining et implémentez un backoff.

async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')
      await new Promise(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 Entité non traitable

Cause : Erreur de validation dans la requête.

Correctif : Consultez la réponse pour obtenir le détail.

{
  "errors": {
    "price": "Le prix doit être supérieur à zéro",
    "sku": "Le SKU existe déjà"
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternatives et comparaisons

Fonctionnalité BigCommerce Shopify WooCommerce
Version de l'API V2 et V3 REST et GraphQL REST
Limites de débit 10K-30K/heure 2/min (leaky bucket) Dépend de l'hébergement
Webhooks Oui Oui Oui (plugin)
GraphQL Non Oui Non
Qualité du SDK Bonne Excellente PHP uniquement
Multi-boutiques Oui Non Non

L'API V3 de BigCommerce est plus cohérente que l'approche fragmentée de Shopify, mais l'API GraphQL de Shopify offre plus de flexibilité pour les requêtes complexes.

Cas d'utilisation réels

Synchronisation d'inventaire multicanal. Une marque vend sur BigCommerce, Amazon et en boutique physique. Elle utilise l'API Produits pour synchroniser les stocks sur tous les canaux et éviter la survente. Les endpoints de synchronisation sont testés dans Apidog avant chaque déploiement.

Automatisation des commandes. Une entreprise d'abonnement déclenche l'exécution via des webhooks lors de la création de commandes. L'API Commandes met à jour les numéros de suivi, et l'entrepôt reçoit les listes de préparation automatiquement.

Segmentation des clients. Un site e-commerce segmente ses acheteurs avec l'API Clients en fonction de l'historique d'achat. Les VIP sont ajoutés à un groupe spécial. Une tâche planifiée met à jour ces groupes chaque semaine.

Conclusion

Voici ce que vous avez appris :

  • L'authentification utilise des jetons API (intégrations simples) ou OAuth (applications du marché)
  • L'API de catalogue V3 gère les produits et variantes
  • L'API de commandes V2 gère le traitement et l'exécution des commandes
  • L'API Clients V3 gère les données clients
  • Les webhooks transmettent les mises à jour en temps réel à vos endpoints
  • Testez et documentez avec Apidog pour fiabiliser vos intégrations

Prochaines étapes :

  1. Créez un compte API dans votre boutique BigCommerce
  2. Effectuez votre premier appel API pour lister les produits
  3. Configurez un webhook pour la création de commandes
  4. Enregistrez vos appels API dans Apidog
  5. Développez votre intégration

Testez les API BigCommerce avec Apidog - gratuit

FAQ

Quelle est la différence entre les API V2 et V3 ?

La V3 est l'API la plus récente et la plus cohérente. Utilisez-la pour les produits, catégories, marques et clients. La V2 gère les commandes. Vous utiliserez souvent les deux.

Comment obtenir le hachage de ma boutique ?

Il figure dans l'URL d'administration : https://store-abc123.mybigcommerce.com/manage. La partie abc123 est le hash. Il est aussi visible dans les paramètres du compte API.

Puis-je utiliser l'API sur une boutique d'essai ?

Oui, les boutiques d'essai BigCommerce possèdent un accès API complet. Parfait pour le développement et les tests.

Quelle est la limite de débit pour les appels API ?

Selon le endpoint : Produits : 10 000/h. Commandes : 30 000/h. Consultez X-Rate-Limit-Remaining dans les en-têtes de réponse.

Comment gérer la pagination ?

Utilisez les paramètres de requête page et limit. La limite par défaut est 50. Vérifiez meta.pagination dans les réponses et bouclez jusqu'à tout récupérer.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )
  const data = await response.json()
  allProducts.push(...data.data)

  if (page >= data.meta.pagination.total_pages) break
  page++
}
Enter fullscreen mode Exit fullscreen mode

Puis-je télécharger des images de produits via l'API ?

Oui. Utilisez le endpoint des images de produit :

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

Comment gérer les devises et les multi-boutiques ?

Chaque boutique possède une devise de base. La multi-devise se gère côté vitrine, pas via l'API. Pour plusieurs boutiques, créez des comptes API séparés et utilisez des environnements différents dans Apidog.

Que se passe-t-il si mon endpoint de webhook est en panne ?

BigCommerce réessaie les webhooks échoués avec backoff exponentiel. Après 5 échecs sur 24h, le webhook est désactivé. Surveillez vos endpoints et configurez des alertes en cas d'erreur.

Top comments (0)