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.

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.

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

Comparaison des API

Versions de Magento

Démarrage : Configuration de l'authentification

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

Avant d'accéder à l'API :

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

É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

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"

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

Créez une intégration via le panneau d'administration :

Allez à Système > Extensions > Intégrations

Cliquez sur Ajouter une nouvelle intégration

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)

Définissez les permissions API :

• Ressources : Sélectionnez les permissions nécessaires
• Recommandé : Produits, Commandes, Clients, Inventaire

Cliquez sur Enregistrer

Cliquez sur Activer sur la nouvelle intégration

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');

É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`);

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}`);
});

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}`);

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}`);

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
    }
  }
});

Suppression d'un produit

Supprimez un produit :

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

  console.log(`Produit ${sku} supprimé`);
};

Types de produits

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}`);
});

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}`);
});

Flux des statuts de commande

pending → processing → complete
        → canceled
        → on_hold
        → payment_review

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'
  });
};

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}`);

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}`);

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}`);
});

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}`);

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}`);

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);

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

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;
      }
    }
  }
};

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.