Cara Menggunakan Magento 2 API: Panduan Integrasi E-commerce Lengkap (2026)

TL;DR

API Magento 2 (Adobe Commerce) memungkinkan pengembang untuk berintegrasi dengan toko e-commerce secara terprogram. API ini menggunakan endpoint REST, SOAP, dan GraphQL dengan otentikasi OAuth 1.0a dan berbasis token, menyediakan akses ke produk, pesanan, pelanggan, inventaris, dan lainnya, dengan batas kecepatan (rate limits) yang dapat dikonfigurasi. Panduan ini mencakup pengaturan otentikasi, operasi CRUD, webhook, endpoint kustom, dan strategi integrasi produksi.

Pendahuluan

Adobe Commerce (Magento) mendukung lebih dari 250.000 toko e-commerce dengan nilai barang dagangan kotor tahunan lebih dari $155 miliar. Bagi pengembang yang membangun integrasi e-commerce, konektor ERP, atau aplikasi seluler, integrasi API Magento bukanlah pilihan—tetapi penting untuk menjangkau basis pedagang yang masif ini.

Inilah kenyataannya: pedagang yang mengelola banyak saluran penjualan kehilangan 20-30 jam setiap minggu untuk entri data manual antara Magento dan sistem lainnya. Integrasi API Magento yang solid mengotomatiskan sinkronisasi produk, pemrosesan pesanan, pembaruan inventaris, dan manajemen data pelanggan.

Panduan ini akan membahas seluruh proses integrasi API Magento 2. Anda akan mempelajari otentikasi OAuth 1.0a dan token, endpoint REST/SOAP/GraphQL, manajemen produk dan pesanan, webhook, pengembangan API kustom, dan strategi penerapan produksi. Pada akhirnya, Anda akan memiliki integrasi Magento yang siap produksi.

Apa Itu API Magento 2?

Magento 2 menyediakan tiga jenis API untuk mengakses data e-commerce:

• REST API: Berbasis JSON untuk aplikasi web dan seluler
• SOAP API: Berbasis XML untuk integrasi perusahaan
• GraphQL: Berbasis kueri untuk aplikasi frontend yang efisien

API menangani:

• Produk, kategori, dan inventaris
• Pesanan, faktur, dan pengiriman
• Pelanggan dan grup pelanggan
• Keranjang belanja dan checkout
• Promosi dan aturan harga
• Halaman dan blok CMS
• Konfigurasi toko

Fitur Utama

Perbandingan API

Versi Magento

Memulai: Pengaturan Otentikasi

Langkah 1: Buat Akun Admin atau Integrasi

Sebelum mengakses API:

1. Masuk ke Panel Admin Magento
2. Navigasi ke Sistem > Izin > Semua Pengguna
3. Buat pengguna admin (untuk token admin) ATAU
4. Navigasi ke Sistem > Ekstensi > Integrasi
5. Buat integrasi baru (untuk OAuth)

Langkah 2: Pilih Metode Otentikasi

Langkah 3: Dapatkan Token Admin (Metode Paling Sederhana)

Hasilkan token admin untuk integrasi internal:

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('Kredensial admin tidak valid');
  }

  // Respons adalah string biasa (token), bukan JSON
  const token = await response.text();
  return token;
};

// Penggunaan
const token = await getAdminToken();
console.log(`Token admin: ${token}`);
// Simpan dengan aman - gunakan untuk panggilan API berikutnya

Catatan keamanan: Simpan token dengan aman:

# file .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"

Langkah 4: Buat Integrasi (Direkomendasikan untuk Pihak Ketiga)

Buat integrasi melalui Panel Admin:

Buka Sistem > Ekstensi > Integrasi

Klik Tambah Integrasi Baru

Isi detail:

• Nama: “Integrasi Saya”
• Email: email-anda@example.com
• URL Panggilan Balik (Callback URL): (untuk OAuth)
• URL Tautan Identitas (Identity Link URL): (untuk OAuth)

Atur Izin API:

• Sumber Daya (Resources): Pilih izin yang dibutuhkan
• Direkomendasikan: Produk, Pesanan, Pelanggan, Inventaris

Klik Simpan

Klik Aktifkan pada integrasi baru

Salin Token Akses dan Rahasia Token

Langkah 5: Dapatkan Token Pelanggan

Untuk aplikasi yang menghadap pelanggan:

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('Kredensial pelanggan tidak valid');
  }

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

// Penggunaan
const customerToken = await getCustomerToken('customer@example.com', 'password123');

Langkah 6: Lakukan Panggilan API yang Diautentikasi

Buat klien API yang dapat digunakan kembali:

const magentoRequest = async (endpoint, options = {}) => {
  const token = await getAdminToken(); // Atau ambil token yang tersimpan

  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(`Kesalahan API Magento: ${error.message}`);
  }

  return response.json();
};

// Penggunaan
const products = await magentoRequest('/V1/products');
console.log(`Ditemukan ${products.items.length} produk`);

Manajemen Produk

Mendapatkan Produk

Ambil produk dengan pemfilteran:

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

  // Bangun kriteria pencarian
  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;
};

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

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

Mendapatkan Satu Produk

Ambil produk berdasarkan SKU:

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

// Penggunaan
const product = await getProduct('TSHIRT-001');
console.log(`Nama: ${product.name}`);
console.log(`Harga: $${product.price}`);
console.log(`Stok: ${product.extension_attributes?.stock_item?.qty}`);

Membuat Produk

Buat produk sederhana:

const createProduct = async (productData) => {
  const product = {
    product: {
      sku: productData.sku,
      name: productData.name,
      attribute_set_id: productData.attributeSetId || 4, // Set default
      type_id: 'simple',
      price: productData.price,
      status: productData.status || 1, // 1=aktif, 2=nonaktif
      visibility: productData.visibility || 4, // 4=Katalog & Pencarian
      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;
};

// Penggunaan
const newProduct = await createProduct({
  sku: 'TSHIRT-BARU-001',
  name: 'Kaos Katun Premium',
  price: 29.99,
  qty: 100,
  description: 'Kaos katun berkualitas tinggi',
  shortDescription: 'Kaos katun premium',
  color: 'Biru',
  size: 'M'
});

console.log(`Produk dibuat: ${newProduct.id}`);

Memperbarui Produk

Perbarui informasi produk:

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

// Penggunaan - Perbarui harga dan stok
await updateProduct('TSHIRT-001', {
  price: 24.99,
  extension_attributes: {
    stock_item: {
      qty: 150,
      is_in_stock: true
    }
  }
});

Menghapus Produk

Hapus produk:

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

  console.log(`Produk ${sku} dihapus`);
};

Jenis Produk

Manajemen Pesanan

Mendapatkan Pesanan

Ambil pesanan dengan pemfilteran:

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

// Penggunaan - Dapatkan pesanan yang tertunda dari 7 hari terakhir
const orders = await getOrders({
  status: 'pending',
  dateFrom: '2026-03-18 00:00:00',
  limit: 50
});

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

Mendapatkan Satu Pesanan

Ambil pesanan berdasarkan ID:

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

// Penggunaan
const order = await getOrder(12345);
console.log(`Pesanan #${order.increment_id}`);
console.log(`Status: ${order.status}`);
console.log(`Total: $${order.grand_total}`);
console.log(`Item:`);
order.items.forEach(item => {
  console.log(`  - ${item.name} x ${item.qty_ordered}`);
});

Alur Status Pesanan

pending → processing → complete
        → canceled
        → on_hold
        → payment_review

Memperbarui Status Pesanan

Ubah status pesanan:

const updateOrderStatus = async (orderId, newStatus) => {
  // Catatan: Pembaruan status langsung memerlukan endpoint kustom
  // Gunakan alur kerja manajemen pesanan sebagai gantinya:

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

  // Untuk ditahan:
  await magentoRequest(`/V1/orders/${orderId}/hold`, {
    method: 'POST'
  });

  // Untuk tidak ditahan:
  await magentoRequest(`/V1/orders/${orderId}/unhold`, {
    method: 'POST'
  });
};

Membuat Faktur

Hasilkan faktur untuk pesanan:

const createInvoice = async (orderId, items = [], notify = true, appendComment = false, comment = null) => {
  const invoice = {
    capture: true, // true = tangkap pembayaran
    last: true,
    items: items // Array of {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;
};

// Penggunaan - Faktur dan tangkap pesanan penuh
const invoiceId = await createInvoice(12345, [], true, false, 'Terima kasih atas pesanan Anda!');
console.log(`Faktur dibuat: ${invoiceId}`);

Membuat Pengiriman

Kirim pesanan:

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

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

  return response;
};

// Penggunaan - Kirim dengan pelacakan
const shipmentId = await createShipment(12345, [], true, false, 'Pesanan Anda telah dikirim!', [
  {
    track_number: '1Z999AA10123456784',
    title: 'Nomor Pelacakan',
    carrier_code: 'ups'
  }
]);
console.log(`Pengiriman dibuat: ${shipmentId}`);

Manajemen Pelanggan

Mendapatkan Pelanggan

Ambil pelanggan:

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

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

Membuat Pelanggan

Daftarkan pelanggan baru:

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

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

console.log(`Pelanggan dibuat: ID ${newCustomer.id}`);

Manajemen Inventaris (MSI)

Mendapatkan Status Stok

Periksa stok produk:

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

// Penggunaan
const stock = await getStockStatus('TSHIRT-001');
console.log(`Jumlah: ${stock.qty}`);
console.log(`Dalam Stok: ${stock.is_in_stock}`);
console.log(`Jumlah Min: ${stock.min_qty}`);

Memperbarui Stok

Perbarui kuantitas produk:

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

// Penggunaan
await updateStock('TSHIRT-001', 100, true);

Webhook dan Operasi Asinkron

Menyiapkan Webhook

Magento menggunakan antrean pesan untuk notifikasi asinkron:

// Magento tidak memiliki webhook bawaan
// Gunakan pendekatan ini sebagai gantinya:

// 1. Ambil endpoint pesanan secara berkala
const pollNewOrders = async (lastOrderId) => {
  const orders = await getOrders({
    dateFrom: new Date().toISOString()
  });

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

// 2. Gunakan Adobe I/O Events (Hanya Adobe Commerce)
// Konfigurasi event di Adobe Developer Console

// 3. Buat modul webhook kustom
// Lihat: https://devdocs.magento.com/guides/v2.4/extension-dev-guide/message-queues/message-queues.html

Pembatasan Tingkat (Rate Limiting)

Memahami Pembatasan Tingkat

Pembatasan tingkat Magento dapat dikonfigurasi:

• Default: Tidak ada batasan (konfigurasi di Admin)
• Direkomendasikan: 100-1000 permintaan/menit

Konfigurasi di Admin: Toko > Konfigurasi > Layanan > API Web > Keamanan

Menerapkan Penanganan Pembatasan Tingkat

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

Daftar Periksa Penerapan Produksi

Sebelum go live:

• [ ] Gunakan token integrasi (bukan kredensial admin) di produksi
• [ ] Simpan token dengan aman (basis data terenkripsi)
• [ ] Terapkan pembatasan tingkat dan antrean permintaan
• [ ] Tambahkan penanganan kesalahan yang komprehensif
• [ ] Siapkan pencatatan untuk semua panggilan API
• [ ] Buat alternatif webhook (polling atau Adobe I/O)
• [ ] Uji dengan volume data produksi
• [ ] Terapkan logika coba ulang untuk permintaan yang gagal

Kasus Penggunaan Dunia Nyata

Integrasi ERP

Produsen menyinkronkan inventaris:

• Tantangan: Pembaruan stok manual antara ERP dan Magento
• Solusi: Sinkronisasi API dua arah setiap 15 menit
• Hasil: Inventaris real-time, nol overselling

Aplikasi Seluler

Pengecer membangun aplikasi belanja:

• Tantangan: Dibutuhkan pengalaman seluler asli
• Solusi: API GraphQL untuk penjelajahan produk, REST untuk checkout
• Hasil: Peningkatan konversi seluler sebesar 40%

Kesimpulan

API Magento 2 menyediakan fungsionalitas e-commerce yang komprehensif. Poin-poin penting:

• Tersedia API REST, SOAP, dan GraphQL
• Otentikasi berbasis token untuk integrasi
• Operasi CRUD penuh untuk produk, pesanan, pelanggan
• MSI untuk manajemen inventaris lanjutan
• Pembatasan tingkat dapat dikonfigurasi per instalasi
• Apidog menyederhanakan pengujian API dan kolaborasi tim

Bagian FAQ

Bagaimana cara melakukan otentikasi dengan API Magento?

Gunakan token admin untuk integrasi internal atau buat Integrasi di Sistem > Ekstensi untuk OAuth. Token pelanggan untuk aplikasi yang menghadap pelanggan.

Apa perbedaan antara REST dan GraphQL di Magento?

REST menyediakan operasi CRUD penuh. GraphQL dioptimalkan untuk kueri frontend dengan pengambilan data yang efisien.

Bagaimana cara membuat produk melalui API?

POST ke /V1/products dengan data produk termasuk SKU, nama, harga, dan `stock_item` di `extension_attributes`.

Bisakah saya mendapatkan webhook untuk pesanan baru?

Magento tidak memiliki webhook bawaan. Gunakan polling, Adobe I/O Events (Adobe Commerce), atau buat modul kustom.

Bagaimana cara memperbarui kuantitas stok?

PUT ke /V1/products/{sku}/stockItems/1 dengan nilai `qty` dan `is_in_stock`.