Hướng dẫn sử dụng Magento 2 API: Tích hợp E-commerce toàn diện (2026)

Tóm tắt

API Magento 2 (Adobe Commerce) cho phép các nhà phát triển tích hợp với các cửa hàng thương mại điện tử theo lập trình. Nó sử dụng các điểm cuối REST, SOAP và GraphQL với xác thực OAuth 1.0a và xác thực dựa trên token, cung cấp quyền truy cập vào sản phẩm, đơn hàng, khách hàng, kho hàng và nhiều hơn nữa, với giới hạn tốc độ có thể cấu hình. Hướng dẫn này bao gồm thiết lập xác thực, các hoạt động CRUD, webhooks, điểm cuối tùy chỉnh và các chiến lược tích hợp sản xuất.

Giới thiệu

Adobe Commerce (Magento) cung cấp năng lượng cho hơn 250.000 cửa hàng thương mại điện tử với tổng giá trị hàng hóa hàng năm hơn 155 tỷ USD. Đối với các nhà phát triển xây dựng tích hợp thương mại điện tử, trình kết nối ERP hoặc ứng dụng di động, tích hợp API Magento không phải là tùy chọn—nó rất cần thiết để tiếp cận lượng lớn nhà bán lẻ này.

Đây là thực tế: các nhà bán lẻ quản lý nhiều kênh bán hàng mất 20-30 giờ hàng tuần để nhập dữ liệu thủ công giữa Magento và các hệ thống khác. Một tích hợp API Magento vững chắc sẽ tự động hóa đồng bộ hóa sản phẩm, xử lý đơn hàng, cập nhật kho hàng và quản lý dữ liệu khách hàng.

Hướng dẫn này sẽ trình bày toàn bộ quá trình tích hợp API Magento 2. Bạn sẽ tìm hiểu về xác thực OAuth 1.0a và token, các điểm cuối REST/SOAP/GraphQL, quản lý sản phẩm và đơn hàng, webhooks, phát triển API tùy chỉnh và các chiến lược triển khai sản xuất. Cuối cùng, bạn sẽ có một tích hợp Magento sẵn sàng cho sản xuất.

API Magento 2 là gì?

Magento 2 cung cấp ba loại API để truy cập dữ liệu thương mại điện tử:

• REST API: Dựa trên JSON cho ứng dụng web và di động
• SOAP API: Dựa trên XML cho tích hợp doanh nghiệp
• GraphQL: Dựa trên truy vấn cho các ứng dụng frontend hiệu quả

API xử lý:

• Sản phẩm, danh mục và kho hàng
• Đơn hàng, hóa đơn và lô hàng
• Khách hàng và nhóm khách hàng
• Giỏ hàng và thanh toán
• Khuyến mãi và quy tắc giá
• Trang và khối CMS
• Cấu hình cửa hàng

Các tính năng chính

So sánh API

Các phiên bản Magento

Bắt đầu: Thiết lập xác thực

Bước 1: Tạo tài khoản quản trị hoặc tích hợp

Trước khi truy cập API:

1. Đăng nhập vào Bảng quản trị Magento
2. Điều hướng đến System > Permissions > All Users (Hệ thống > Quyền > Tất cả người dùng)
3. Tạo người dùng quản trị (cho token quản trị) HOẶC
4. Điều hướng đến System > Extensions > Integrations (Hệ thống > Tiện ích mở rộng > Tích hợp)
5. Tạo tích hợp mới (cho OAuth)

Bước 2: Chọn phương thức xác thực

Bước 3: Lấy token quản trị (Phương pháp đơn giản nhất)

Tạo token quản trị cho tích hợp nội bộ:

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'); // Thông tin đăng nhập quản trị không hợp lệ
  }

  // Phản hồi là một chuỗi đơn thuần (token), không phải JSON
  const token = await response.text();
  return token;
};

// Cách sử dụng
const token = await getAdminToken();
console.log(`Admin token: ${token}`);
// Lưu trữ an toàn - sử dụng cho các cuộc gọi API tiếp theo

Lưu ý bảo mật: Lưu trữ token một cách an toàn:

# .env file
MAGENTO_BASE_URL="https://store.example.com"
MAGENTO_ADMIN_USERNAME="api_user"
MAGENTO_ADMIN_PASSWORD="secure_password_here"
MAGENTO_ACCESS_TOKEN="obtained_via_auth"

Bước 4: Tạo tích hợp (Khuyến nghị cho bên thứ ba)

Tạo tích hợp qua Bảng quản trị:

Đi tới System > Extensions > Integrations (Hệ thống > Tiện ích mở rộng > Tích hợp)

Nhấp vào Add New Integration (Thêm tích hợp mới)

Điền thông tin chi tiết:

• Tên: “My Integration”
• Email: your-email@example.com
• Callback URL: (cho OAuth)
• Identity Link URL: (cho OAuth)

Đặt API Permissions (Quyền API):

• Tài nguyên: Chọn các quyền cần thiết
• Khuyến nghị: Sản phẩm, Đơn hàng, Khách hàng, Kho hàng

Nhấp vào Save (Lưu)

Nhấp vào Activate (Kích hoạt) trên tích hợp mới

Sao chép Access Token và Token Secret

Bước 5: Lấy token khách hàng

Dành cho các ứng dụng hướng tới khách hàng:

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'); // Thông tin đăng nhập khách hàng không hợp lệ
  }

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

// Cách sử dụng
const customerToken = await getCustomerToken('customer@example.com', 'password123');

Bước 6: Thực hiện các cuộc gọi API đã xác thực

Tạo client API có thể tái sử dụng:

const magentoRequest = async (endpoint, options = {}) => {
  const token = await getAdminToken(); // Hoặc lấy token đã lưu trữ

  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}`); // Lỗi API Magento
  }

  return response.json();
};

// Cách sử dụng
const products = await magentoRequest('/V1/products');
console.log(`Found ${products.items.length} products`); // Đã tìm thấy ${products.items.length} sản phẩm

Quản lý sản phẩm

Lấy sản phẩm

Lấy sản phẩm với bộ lọc:

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

  // Xây dựng tiêu chí tìm kiếm
  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;
};

// Cách sử dụng
const products = await getProducts({ search: 'shirt', priceFrom: 20, limit: 50 });

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

Lấy một sản phẩm

Lấy sản phẩm bằng SKU:

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

// Cách sử dụng
const product = await getProduct('TSHIRT-001');
console.log(`Name: ${product.name}`); // Tên
console.log(`Price: $${product.price}`); // Giá
console.log(`Stock: ${product.extension_attributes?.stock_item?.qty}`); // Kho hàng

Tạo sản phẩm

Tạo sản phẩm đơn giản:

const createProduct = async (productData) => {
  const product = {
    product: {
      sku: productData.sku,
      name: productData.name,
      attribute_set_id: productData.attributeSetId || 4, // Bộ mặc định
      type_id: 'simple',
      price: productData.price,
      status: productData.status || 1, // 1=đã bật, 2=đã tắt
      visibility: productData.visibility || 4, // 4=Danh mục & Tìm kiếm
      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;
};

// Cách sử dụng
const newProduct = await createProduct({
  sku: 'TSHIRT-NEW-001',
  name: 'Premium Cotton T-Shirt',
  price: 29.99,
  qty: 100,
  description: 'High-quality cotton t-shirt', // Áo thun cotton chất lượng cao
  shortDescription: 'Premium cotton tee', // Áo thun cotton cao cấp
  color: 'Blue',
  size: 'M'
});

console.log(`Product created: ${newProduct.id}`); // Sản phẩm đã được tạo

Cập nhật sản phẩm

Cập nhật thông tin sản phẩm:

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

// Cách sử dụng - Cập nhật giá và kho hàng
await updateProduct('TSHIRT-001', {
  price: 24.99,
  extension_attributes: {
    stock_item: {
      qty: 150,
      is_in_stock: true
    }
  }
});

Xóa sản phẩm

Xóa sản phẩm:

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

  console.log(`Product ${sku} deleted`); // Sản phẩm ${sku} đã bị xóa
};

Các loại sản phẩm

Quản lý đơn hàng

Lấy đơn hàng

Lấy đơn hàng với bộ lọc:

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

// Cách sử dụng - Lấy các đơn hàng đang chờ xử lý từ 7 ngày trước
const orders = await getOrders({
  status: 'pending',
  dateFrom: '2026-03-18 00:00:00',
  limit: 50
});

orders.items.forEach(order => {
  console.log(`Order #${order.increment_id}: ${order.customer_email} - $${order.grand_total}`);
});

Lấy một đơn hàng

Lấy đơn hàng bằng ID:

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

// Cách sử dụng
const order = await getOrder(12345);
console.log(`Order #${order.increment_id}`); // Đơn hàng
console.log(`Status: ${order.status}`); // Trạng thái
console.log(`Total: $${order.grand_total}`); // Tổng cộng
console.log(`Items:`); // Mặt hàng
order.items.forEach(item => {
  console.log(`  - ${item.name} x ${item.qty_ordered}`);
});

Luồng trạng thái đơn hàng

đang chờ → đang xử lý → hoàn tất
        → đã hủy
        → đang giữ
        → chờ xét duyệt thanh toán

Cập nhật trạng thái đơn hàng

Thay đổi trạng thái đơn hàng:

const updateOrderStatus = async (orderId, newStatus) => {
  // Lưu ý: Cập nhật trạng thái trực tiếp yêu cầu điểm cuối tùy chỉnh
  // Thay vào đó, hãy sử dụng quy trình quản lý đơn hàng:

  // Để hủy:
  await magentoRequest(`/V1/orders/${orderId}/cancel`, {
    method: 'POST'
  });

  // Để giữ:
  await magentoRequest(`/V1/orders/${orderId}/hold`, {
    method: 'POST'
  });

  // Để bỏ giữ:
  await magentoRequest(`/V1/orders/${orderId}/unhold`, {
    method: 'POST'
  });
};

Tạo hóa đơn

Tạo hóa đơn cho đơn hàng:

const createInvoice = async (orderId, items = [], notify = true, appendComment = false, comment = null) => {
  const invoice = {
    capture: true, // true = thu tiền thanh toán
    last: true,
    items: items // Mảng gồm {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;
};

// Cách sử dụng - Lập hóa đơn và thu toàn bộ đơn hàng
const invoiceId = await createInvoice(12345, [], true, false, 'Thank you for your order!'); // Cảm ơn quý khách đã đặt hàng!
console.log(`Invoice created: ${invoiceId}`); // Hóa đơn đã được tạo

Tạo lô hàng

Vận chuyển đơn hàng:

const createShipment = async (orderId, items = [], notify = true, appendComment = false, comment = null, tracks = []) => {
  const shipment = {
    items: items, // Mảng gồm {order_item_id, qty}
    notify: notify ? 1 : 0,
    append_comment: appendComment ? 1 : 0,
    comment: comment,
    tracks: tracks // Mảng gồm {track_number, title, carrier_code}
  };

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

  return response;
};

// Cách sử dụng - Vận chuyển có theo dõi
const shipmentId = await createShipment(12345, [], true, false, 'Your order has shipped!', [ // Đơn hàng của bạn đã được vận chuyển!
  {
    track_number: '1Z999AA10123456784',
    title: 'Tracking Number', // Mã theo dõi
    carrier_code: 'ups'
  }
]);
console.log(`Shipment created: ${shipmentId}`); // Lô hàng đã được tạo

Quản lý khách hàng

Lấy khách hàng

Lấy khách hàng:

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

// Cách sử dụng
const customers = await getCustomers({ email: 'customer@example.com' });
customers.items.forEach(customer => {
  console.log(`${customer.firstname} ${customer.lastname} - ${customer.email}`);
});

Tạo khách hàng

Đăng ký khách hàng mới:

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

// Cách sử dụng
const newCustomer = await createCustomer({
  email: 'newcustomer@example.com',
  firstname: 'John',
  lastname: 'Doe',
  password: 'SecurePass123!',
  subscribed: true
});

console.log(`Customer created: ID ${newCustomer.id}`); // Khách hàng đã được tạo: ID ${newCustomer.id}

Quản lý kho hàng (MSI)

Lấy trạng thái kho hàng

Kiểm tra kho hàng của sản phẩm:

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

// Cách sử dụng
const stock = await getStockStatus('TSHIRT-001');
console.log(`Qty: ${stock.qty}`); // Số lượng
console.log(`In Stock: ${stock.is_in_stock}`); // Trong kho
console.log(`Min Qty: ${stock.min_qty}`); // Số lượng tối thiểu

Cập nhật kho hàng

Cập nhật số lượng sản phẩm:

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

// Cách sử dụng
await updateStock('TSHIRT-001', 100, true);

Webhooks và các hoạt động bất đồng bộ

Thiết lập Webhooks

Magento sử dụng hàng đợi tin nhắn cho các thông báo bất đồng bộ:

// Magento không có webhooks gốc
// Thay vào đó, hãy sử dụng các phương pháp này:

// 1. Thăm dò điểm cuối đơn hàng định kỳ
const pollNewOrders = async (lastOrderId) => {
  const orders = await getOrders({
    dateFrom: new Date().toISOString()
  });

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

// 2. Sử dụng Sự kiện Adobe I/O (chỉ dành cho Adobe Commerce)
// Cấu hình sự kiện trong Adobe Developer Console

// 3. Tạo mô-đun webhook tùy chỉnh
// Xem: https://devdocs.magento.com/guides/v2.4/extension-dev-guide/message-queues/message-queues.html

Giới hạn tốc độ

Hiểu về giới hạn tốc độ

Giới hạn tốc độ của Magento có thể cấu hình được:

• Mặc định: Không giới hạn (cấu hình trong Admin)
• Khuyến nghị: 100-1000 yêu cầu/phút

Cấu hình trong Admin: Stores > Configuration > Services > Web API > Security (Cửa hàng > Cấu hình > Dịch vụ > Web API > Bảo mật)

Thực hiện xử lý giới hạn tốc độ

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

Danh sách kiểm tra triển khai sản xuất

Trước khi ra mắt:

• [ ] Sử dụng token tích hợp (không phải thông tin đăng nhập quản trị) trong môi trường sản xuất
• [ ] Lưu trữ token an toàn (cơ sở dữ liệu được mã hóa)
• [ ] Thực hiện giới hạn tốc độ và xếp hàng yêu cầu
• [ ] Thêm xử lý lỗi toàn diện
• [ ] Thiết lập ghi nhật ký cho tất cả các cuộc gọi API
• [ ] Tạo giải pháp thay thế webhook (thăm dò hoặc Adobe I/O)
• [ ] Kiểm tra với khối lượng dữ liệu sản xuất
• [ ] Thực hiện logic thử lại cho các yêu cầu không thành công

Các trường hợp sử dụng trong thực tế

Tích hợp ERP

Một nhà sản xuất đồng bộ hóa kho hàng:

• Thách thức: Cập nhật kho hàng thủ công giữa ERP và Magento
• Giải pháp: Đồng bộ hóa API hai chiều mỗi 15 phút
• Kết quả: Kho hàng thời gian thực, không bán quá mức

Ứng dụng di động

Một nhà bán lẻ xây dựng ứng dụng mua sắm:

• Thách thức: Cần trải nghiệm di động gốc
• Giải pháp: API GraphQL để duyệt sản phẩm, REST để thanh toán
• Kết quả: Tăng 40% tỷ lệ chuyển đổi trên thiết bị di động

Kết luận

API Magento 2 cung cấp chức năng thương mại điện tử toàn diện. Các điểm chính:

• Có sẵn các API REST, SOAP và GraphQL
• Xác thực dựa trên token cho các tích hợp
• CRUD đầy đủ cho sản phẩm, đơn hàng, khách hàng
• MSI để quản lý kho hàng nâng cao
• Giới hạn tốc độ có thể cấu hình cho từng cài đặt
• Apidog hợp lý hóa việc kiểm thử API và cộng tác nhóm

Phần hỏi đáp

Làm cách nào để xác thực với API Magento?

Sử dụng token quản trị cho tích hợp nội bộ hoặc tạo Tích hợp trong System > Extensions (Hệ thống > Tiện ích mở rộng) cho OAuth. Token khách hàng cho ứng dụng hướng tới khách hàng.

Sự khác biệt giữa REST và GraphQL trong Magento là gì?

REST cung cấp các hoạt động CRUD đầy đủ. GraphQL được tối ưu hóa cho các truy vấn frontend với việc tìm nạp dữ liệu hiệu quả.

Làm cách nào để tạo sản phẩm qua API?

Gửi POST tới /V1/products với dữ liệu sản phẩm bao gồm SKU, tên, giá và stock_item trong extension_attributes.

Tôi có thể nhận webhooks cho các đơn hàng mới không?

Magento không có webhooks gốc. Sử dụng thăm dò, Sự kiện Adobe I/O (Adobe Commerce) hoặc tạo mô-đun tùy chỉnh.

Làm cách nào để cập nhật số lượng kho hàng?

Gửi PUT tới /V1/products/{sku}/stockItems/1 với các giá trị qty và is_in_stock.