DEV Community

Cover image for Comment Utiliser l'API Magento 2: Guide Complet d'Intégration E-commerce (2026)
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment Utiliser l'API Magento 2: Guide Complet d'Intégration E-commerce (2026)

En bref

L'API Magento 2 (Adobe Commerce) permet aux développeurs de s'intégrer aux boutiques e-commerce de manière programmatique. Elle utilise des points de terminaison REST, SOAP et GraphQL avec l'authentification OAuth 1.0a et par jeton, donnant accès aux produits, commandes, clients, inventaire, et plus encore, avec des limites de débit configurables. Ce guide couvre la configuration de l'authentification, les opérations CRUD, les webhooks, les points de terminaison personnalisés et les stratégies d'intégration en production.

Essayez Apidog dès aujourd'hui

Introduction

Adobe Commerce (Magento) propulse plus de 250 000 boutiques e-commerce, générant plus de 155 milliards de dollars en valeur annuelle brute de marchandises. Pour les développeurs qui créent des intégrations e-commerce, des connecteurs ERP ou des applications mobiles, l'intégration de l'API Magento n'est pas une option, elle est essentielle pour atteindre cette vaste base de marchands.

Voici la réalité : les marchands gérant plusieurs canaux de vente perdent 20 à 30 heures par semaine en saisie manuelle de données entre Magento et d'autres systèmes. Une intégration API Magento solide automatise la synchronisation des produits, le traitement des commandes, les mises à jour d'inventaire et la gestion des données clients.

Ce guide vous présente le processus complet d'intégration de l'API Magento 2. Vous apprendrez l'authentification OAuth 1.0a et par jeton, les points de terminaison REST/SOAP/GraphQL, la gestion des produits et des commandes, les webhooks, le développement d'API personnalisées et les stratégies de déploiement en production. À la fin, vous disposerez d'une intégration Magento prête pour la production.

💡 Astuce : Apidog simplifie les tests d'intégration API. Testez vos points de terminaison Magento, validez les flux d'authentification, inspectez les réponses API et déboguez les problèmes d'intégration dans un seul espace de travail. Importez des spécifications API, simulez des réponses et partagez des scénarios de test avec votre équipe.

Qu'est-ce que l'API Magento 2 ?

Magento 2 propose trois types d'API pour accéder aux données e-commerce :

  • API REST : basée sur JSON pour les applications web et mobiles
  • API SOAP : basée sur XML pour les intégrations d'entreprise
  • GraphQL : basée sur des requêtes pour des applications frontend efficaces

L'API gère :

  • Produits, catégories et inventaire
  • Commandes, factures et expéditions
  • Clients et groupes de clients
  • Panier et processus de commande
  • Promotions et règles de tarification
  • Pages et blocs CMS
  • Configuration de la boutique

Fonctionnalités Clés

Fonctionnalité Description
Protocoles Multiples REST, SOAP, GraphQL
OAuth 1.0a Accès sécurisé tiers
Authentification par jeton Jetons administrateur et d'intégration
Webhooks Opérations asynchrones via files d'attente
Limitation de débit Configurable par installation
Points de terminaison Personnalisés Étendre avec des API personnalisées
Multi-Boutique API unique, plusieurs vues de magasin

Comparaison des API

Type d'API Protocole Cas d'utilisation
REST JSON Applications mobiles, intégrations
SOAP XML Systèmes d'entreprise (SAP, Oracle)
GraphQL GraphQL Frontend, PWA

Versions de Magento

Version Statut Fin du support
Magento 2.4.x Actuel Actif
Adobe Commerce 2.4.x Actuel Actif
Magento 1.x Fin de vie Juin 2020 (À ne pas utiliser)

Démarrage : Configuration de l'authentification

Étape 1 : Créer un compte administrateur ou une intégration

  1. Connectez-vous au panneau d'administration de Magento
  2. Accédez à Système > Permissions > Tous les utilisateurs
  3. Créez un utilisateur administrateur (pour le jeton admin) OU
  4. Accédez à Système > Extensions > Intégrations
  5. Créez une nouvelle intégration (pour OAuth)

Étape 2 : Choisir la méthode d'authentification

Méthode Idéal pour Durée de vie du jeton
Jeton Admin Intégrations internes Configurable (par défaut : 4h)
Jeton d'intégration Applications tierces Jusqu'à révocation
OAuth 1.0a Applications de marketplace Jusqu'à révocation
Jeton client Applications orientées client Configurable

Étape 3 : Obtenir le jeton administrateur (méthode la plus simple)

Générez un jeton administrateur pour les intégrations internes :

const MAGENTO_BASE_URL = process.env.MAGENTO_BASE_URL;
const MAGENTO_ADMIN_USERNAME = process.env.MAGENTO_ADMIN_USERNAME;
const MAGENTO_ADMIN_PASSWORD = process.env.MAGENTO_ADMIN_PASSWORD;

const getAdminToken = async () => {
  const response = await fetch(`${MAGENTO_BASE_URL}/rest/V1/integration/admin/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: MAGENTO_ADMIN_USERNAME,
      password: MAGENTO_ADMIN_PASSWORD
    })
  });

  if (!response.ok) {
    throw new Error('Invalid admin credentials');
  }

  // La réponse est une chaîne de caractères (le jeton), pas du JSON
  const token = await response.text();
  return token;
};

// Utilisation
const token = await getAdminToken();
console.log(`Admin token: ${token}`);
// Stockez en toute sécurité - utilisez pour les appels API ultérieurs
Enter fullscreen mode Exit fullscreen mode

Note de sécurité : Stockez les jetons en toute sécurité :

# Fichier .env
MAGENTO_BASE_URL="https://store.example.com"
MAGENTO_ADMIN_USERNAME="api_user"
MAGENTO_ADMIN_PASSWORD="secure_password_here"
MAGENTO_ACCESS_TOKEN="obtained_via_auth"
Enter fullscreen mode Exit fullscreen mode

Étape 4 : Créer une intégration (recommandé pour les tiers)

  1. Allez à Système > Extensions > Intégrations
  2. Cliquez sur Ajouter une nouvelle intégration
  3. Remplissez les détails :
    • Nom : « Mon intégration »
    • E-mail : votre-email@example.com
    • URL de rappel : (pour OAuth)
    • URL de lien d'identité : (pour OAuth)
  4. Définissez les permissions API :
    • Ressources : Sélectionnez les permissions nécessaires (Produits, Commandes, Clients, Inventaire recommandé)
  5. Cliquez sur Enregistrer
  6. Cliquez sur Activer sur la nouvelle intégration
  7. Copiez le jeton d'accès et le secret du jeton

Étape 5 : Obtenir le jeton client

Pour les applications orientées client :

const getCustomerToken = async (email, password) => {
  const response = await fetch(`${MAGENTO_BASE_URL}/rest/V1/integration/customer/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: email,
      password: password
    })
  });

  if (!response.ok) {
    throw new Error('Invalid customer credentials');
  }

  const token = await response.text();
  return token;
};

// Utilisation
const customerToken = await getCustomerToken('customer@example.com', 'password123');
Enter fullscreen mode Exit fullscreen mode

Étape 6 : Effectuer des appels API authentifiés

Créez un client API réutilisable :

const magentoRequest = async (endpoint, options = {}) => {
  const token = await getAdminToken(); // Ou récupérez le jeton stocké

  const response = await fetch(`${MAGENTO_BASE_URL}/rest${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Magento API Error: ${error.message}`);
  }

  return response.json();
};

// Utilisation
const products = await magentoRequest('/V1/products');
console.log(`Trouvé ${products.items.length} produits`);
Enter fullscreen mode Exit fullscreen mode

Gestion des produits

Récupération des produits

Récupérez les produits avec filtrage :

const getProducts = async (filters = {}) => {
  const params = new URLSearchParams();

  // Construire les critères de recherche
  if (filters.search) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'sku');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', `%${filters.search}%`);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'like');
  }

  if (filters.priceFrom) {
    params.append('searchCriteria[filterGroups][1][filters][0][field]', 'price');
    params.append('searchCriteria[filterGroups][1][filters][0][value]', filters.priceFrom);
    params.append('searchCriteria[filterGroups][1][filters][0][conditionType]', 'gteq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);
  params.append('searchCriteria[currentPage]', filters.page || 1);

  const response = await magentoRequest(`/V1/products?${params.toString()}`);
  return response;
};

// Utilisation
const products = await getProducts({ search: 'shirt', priceFrom: 20, limit: 50 });

products.items.forEach(product => {
  console.log(`${product.sku}: ${product.name} - $${product.price}`);
});
Enter fullscreen mode Exit fullscreen mode

Récupération d'un seul produit

Récupérez un produit par SKU :

const getProduct = async (sku) => {
  const response = await magentoRequest(`/V1/products/${sku}`);
  return response;
};

// Utilisation
const product = await getProduct('TSHIRT-001');
console.log(`Nom : ${product.name}`);
console.log(`Prix : $${product.price}`);
console.log(`Stock : ${product.extension_attributes?.stock_item?.qty}`);
Enter fullscreen mode Exit fullscreen mode

Création d'un produit

Créez un produit simple :

const createProduct = async (productData) => {
  const product = {
    product: {
      sku: productData.sku,
      name: productData.name,
      attribute_set_id: productData.attributeSetId || 4, // Ensemble par défaut
      type_id: 'simple',
      price: productData.price,
      status: productData.status || 1, // 1=activé, 2=désactivé
      visibility: productData.visibility || 4, // 4=Catalogue et recherche
      weight: productData.weight || 1,
      extension_attributes: {
        stock_item: {
          qty: productData.qty || 0,
          is_in_stock: productData.qty > 0 ? true : false
        }
      },
      custom_attributes: [
        {
          attribute_code: 'description',
          value: productData.description
        },
        {
          attribute_code: 'short_description',
          value: productData.shortDescription
        },
        {
          attribute_code: 'color',
          value: productData.color
        },
        {
          attribute_code: 'size',
          value: productData.size
        }
      ]
    }
  };

  const response = await magentoRequest('/V1/products', {
    method: 'POST',
    body: JSON.stringify(product)
  });

  return response;
};

// Utilisation
const newProduct = await createProduct({
  sku: 'TSHIRT-NEW-001',
  name: 'Premium Cotton T-Shirt',
  price: 29.99,
  qty: 100,
  description: 'High-quality cotton t-shirt',
  shortDescription: 'Premium cotton tee',
  color: 'Blue',
  size: 'M'
});

console.log(`Produit créé : ${newProduct.id}`);
Enter fullscreen mode Exit fullscreen mode

Mise à jour d'un produit

Mettez à jour les informations du produit :

const updateProduct = async (sku, updates) => {
  const product = {
    product: {
      sku: sku,
      ...updates
    }
  };

  const response = await magentoRequest(`/V1/products/${sku}`, {
    method: 'PUT',
    body: JSON.stringify(product)
  });

  return response;
};

// Utilisation - Mettre à jour le prix et le stock
await updateProduct('TSHIRT-001', {
  price: 24.99,
  extension_attributes: {
    stock_item: {
      qty: 150,
      is_in_stock: true
    }
  }
});
Enter fullscreen mode Exit fullscreen mode

Suppression d'un produit

Supprimez un produit :

const deleteProduct = async (sku) => {
  await magentoRequest(`/V1/products/${sku}`, {
    method: 'DELETE'
  });

  console.log(`Produit ${sku} supprimé`);
};
Enter fullscreen mode Exit fullscreen mode

Types de produits

Type Description Cas d'utilisation
Simple SKU unique, pas de variations Produits standards
Configurable Parent avec variations enfants Options de taille/couleur
Groupé Collection de produits simples Lots de produits
Virtuel Produits non physiques Services, téléchargements
Pack Packs de produits personnalisables Kits à assembler
Téléchargeable Produits numériques E-books, logiciels

Gestion des commandes

Récupération des commandes

Récupérez les commandes avec filtrage :

const getOrders = async (filters = {}) => {
  const params = new URLSearchParams();

  if (filters.status) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'status');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', filters.status);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'eq');
  }

  if (filters.dateFrom) {
    params.append('searchCriteria[filterGroups][1][filters][0][field]', 'created_at');
    params.append('searchCriteria[filterGroups][1][filters][0][value]', filters.dateFrom);
    params.append('searchCriteria[filterGroups][1][filters][0][conditionType]', 'gteq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);
  params.append('searchCriteria[currentPage]', filters.page || 1);

  const response = await magentoRequest(`/V1/orders?${params.toString()}`);
  return response;
};

// Utilisation - Obtenir les commandes en attente des 7 derniers jours
const orders = await getOrders({
  status: 'pending',
  dateFrom: '2026-03-18 00:00:00',
  limit: 50
});

orders.items.forEach(order => {
  console.log(`Commande n°${order.increment_id} : ${order.customer_email} - $${order.grand_total}`);
});
Enter fullscreen mode Exit fullscreen mode

Récupération d'une seule commande

Récupérez une commande par ID :

const getOrder = async (orderId) => {
  const response = await magentoRequest(`/V1/orders/${orderId}`);
  return response;
};

// Utilisation
const order = await getOrder(12345);
console.log(`Commande n°${order.increment_id}`);
console.log(`Statut : ${order.status}`);
console.log(`Total : $${order.grand_total}`);
console.log(`Articles :`);
order.items.forEach(item => {
  console.log(`  - ${item.name} x ${item.qty_ordered}`);
});
Enter fullscreen mode Exit fullscreen mode

Flux des statuts de commande 

pending → processing → complete
        → canceled
        → on_hold
        → payment_review
Enter fullscreen mode Exit fullscreen mode

Mise à jour du statut de commande

Changez le statut de la commande :

const updateOrderStatus = async (orderId, newStatus) => {
  // Note : La mise à jour directe du statut nécessite un point de terminaison personnalisé
  // Utilisez plutôt le flux de gestion des commandes :

  // Pour annuler :
  await magentoRequest(`/V1/orders/${orderId}/cancel`, {
    method: 'POST'
  });

  // Pour mettre en attente :
  await magentoRequest(`/V1/orders/${orderId}/hold`, {
    method: 'POST'
  });

  // Pour retirer de la mise en attente :
  await magentoRequest(`/V1/orders/${orderId}/unhold`, {
    method: 'POST'
  });
};
Enter fullscreen mode Exit fullscreen mode

Création d'une facture

Générez une facture pour la commande :

const createInvoice = async (orderId, items = [], notify = true, appendComment = false, comment = null) => {
  const invoice = {
    capture: true, // true = capture le paiement
    last: true,
    items: items // Tableau de {order_item_id, qty}
  };

  if (comment) {
    invoice.comment = comment;
    invoice.notify_customer = notify ? 1 : 0;
    invoice.append_comment = appendComment ? 1 : 0;
  }

  const response = await magentoRequest(`/V1/order/${orderId}/invoice`, {
    method: 'POST',
    body: JSON.stringify(invoice)
  });

  return response;
};

// Utilisation - Facturer et capturer la commande complète
const invoiceId = await createInvoice(12345, [], true, false, 'Thank you for your order!');
console.log(`Facture créée : ${invoiceId}`);
Enter fullscreen mode Exit fullscreen mode

Création d'une expédition

Expédiez la commande :

const createShipment = async (orderId, items = [], notify = true, appendComment = false, comment = null, tracks = []) => {
  const shipment = {
    items: items, // Tableau de {order_item_id, qty}
    notify: notify ? 1 : 0,
    append_comment: appendComment ? 1 : 0,
    comment: comment,
    tracks: tracks // Tableau de {numéro_de_suivi, titre, code_transporteur}
  };

  const response = await magentoRequest(`/V1/order/${orderId}/ship`, {
    method: 'POST',
    body: JSON.stringify(shipment)
  });

  return response;
};

// Utilisation - Expédier avec suivi
const shipmentId = await createShipment(12345, [], true, false, 'Your order has shipped!', [
  {
    track_number: '1Z999AA10123456784',
    title: 'Tracking Number',
    carrier_code: 'ups'
  }
]);
console.log(`Expédition créée : ${shipmentId}`);
Enter fullscreen mode Exit fullscreen mode

Gestion des clients

Récupération des clients

Récupérez les clients :

const getCustomers = async (filters = {}) => {
  const params = new URLSearchParams();

  if (filters.email) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'email');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', filters.email);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'eq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);

  const response = await magentoRequest(`/V1/customers/search?${params.toString()}`);
  return response;
};

// Utilisation
const customers = await getCustomers({ email: 'customer@example.com' });
customers.items.forEach(customer => {
  console.log(`${customer.firstname} ${customer.lastname} - ${customer.email}`);
});
Enter fullscreen mode Exit fullscreen mode

Création d'un client

Enregistrez un nouveau client :

const createCustomer = async (customerData) => {
  const customer = {
    customer: {
      websiteId: customerData.websiteId || 1,
      email: customerData.email,
      firstname: customerData.firstname,
      lastname: customerData.lastname,
      middlename: customerData.middlename || '',
      gender: customerData.gender || 0,
      store_id: customerData.storeId || 0,
      extension_attributes: {
        is_subscribed: customerData.subscribed || false
      }
    },
    password: customerData.password
  };

  const response = await magentoRequest('/V1/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Utilisation
const newCustomer = await createCustomer({
  email: 'newcustomer@example.com',
  firstname: 'John',
  lastname: 'Doe',
  password: 'SecurePass123!',
  subscribed: true
});

console.log(`Client créé : ID ${newCustomer.id}`);
Enter fullscreen mode Exit fullscreen mode

Gestion de l'inventaire (MSI)

Obtention du statut de stock

Vérifiez le stock du produit :

const getStockStatus = async (sku) => {
  const response = await magentoRequest(`/V1/products/${sku}/stockItems/1`);
  return response;
};

// Utilisation
const stock = await getStockStatus('TSHIRT-001');
console.log(`Qté : ${stock.qty}`);
console.log(`En stock : ${stock.is_in_stock}`);
console.log(`Qté min : ${stock.min_qty}`);
Enter fullscreen mode Exit fullscreen mode

Mise à jour du stock

Mettez à jour la quantité du produit :

const updateStock = async (sku, qty, isInStock = null) => {
  const stockItem = {
    stockItem: {
      qty: qty,
      is_in_stock: isInStock !== null ? isInStock : qty > 0
    }
  };

  const response = await magentoRequest(`/V1/products/${sku}/stockItems/1`, {
    method: 'PUT',
    body: JSON.stringify(stockItem)
  });

  return response;
};

// Utilisation
await updateStock('TSHIRT-001', 100, true);
Enter fullscreen mode Exit fullscreen mode

Webhooks et opérations asynchrones

Configuration des webhooks

Magento utilise des files d'attente de messages pour les notifications asynchrones :

// Magento n'a pas de webhooks natifs
// Utilisez ces approches à la place :

// 1. Interrogez régulièrement le point de terminaison des commandes
const pollNewOrders = async (lastOrderId) => {
  const orders = await getOrders({
    dateFrom: new Date().toISOString()
  });

  const newOrders = orders.items.filter(o => o.id > lastOrderId);
  return newOrders;
};

// 2. Utilisez les événements Adobe I/O (Adobe Commerce uniquement)
// Configurez les événements dans Adobe Developer Console

// 3. Créez un module de webhook personnalisé
// Voir : https://devdocs.magento.com/guides/v2.4/extension-dev-guide/message-queues/message-queues.html
Enter fullscreen mode Exit fullscreen mode

Limitation de débit

Comprendre les limites de débit

Les limites de débit de Magento sont configurables :

  • Par défaut : Aucune limite (à configurer dans l'Admin)
  • Recommandé : 100-1000 requêtes/minute

Configurez dans l'Admin : Boutiques > Configuration > Services > API Web > Sécurité

Mise en œuvre de la gestion des limites de débit 

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await magentoRequest(endpoint, options);
      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};
Enter fullscreen mode Exit fullscreen mode

Liste de contrôle pour le déploiement en production

Avant la mise en ligne :

  • [ ] Utilisez des jetons d'intégration (pas les identifiants administrateur) en production
  • [ ] Stockez les jetons en toute sécurité (base de données chiffrée)
  • [ ] Implémentez la limitation de débit et la mise en file d'attente des requêtes
  • [ ] Ajoutez une gestion complète des erreurs
  • [ ] Configurez la journalisation pour tous les appels API
  • [ ] Créez une alternative de webhook (interrogation ou Adobe I/O)
  • [ ] Testez avec le volume de données de production
  • [ ] Implémentez une logique de réessai pour les requêtes échouées

Cas d'utilisation concrets

Intégration ERP

Un fabricant synchronise l'inventaire :

  • Défi : Mises à jour manuelles du stock entre l'ERP et Magento
  • Solution : Synchronisation API bidirectionnelle toutes les 15 minutes
  • Résultat : Inventaire en temps réel, aucune survente

Application mobile

Un détaillant crée une application d'achat :

  • Défi : Expérience mobile native requise
  • Solution : API GraphQL pour la navigation des produits, REST pour le processus de commande
  • Résultat : Augmentation de 40 % du taux de conversion mobile

Conclusion

L'API Magento 2 offre des fonctionnalités e-commerce complètes. Points clés à retenir :

  • API REST, SOAP et GraphQL disponibles
  • Authentification par jeton pour les intégrations
  • Opérations CRUD complètes pour les produits, commandes, clients
  • MSI pour une gestion avancée de l'inventaire
  • Limites de débit configurables par installation
  • Apidog rationalise les tests API et la collaboration d'équipe

Section FAQ

Comment m'authentifier avec l'API Magento ?

Utilisez le jeton administrateur pour les intégrations internes ou créez une intégration dans Système > Extensions pour OAuth. Jeton client pour les applications orientées client.

Quelle est la différence entre REST et GraphQL dans Magento ?

REST fournit des opérations CRUD complètes. GraphQL est optimisé pour les requêtes frontend avec une récupération de données efficace.

Comment créer un produit via l'API ?

POST à /V1/products avec les données du produit, y compris SKU, nom, prix et stock_item dans extension_attributes.

Puis-je recevoir des webhooks pour les nouvelles commandes ?

Magento ne dispose pas de webhooks natifs. Utilisez l'interrogation, les événements Adobe I/O (Adobe Commerce) ou créez un module personnalisé.

Comment mettre à jour les quantités de stock ?

PUT à /V1/products/{sku}/stockItems/1 avec les valeurs qty et is_in_stock.

Top comments (0)