Magento 2 API Kullanımı: Kapsamlı E-Ticaret Entegrasyon Rehberi (2026)

Kısaca

Magento 2 (Adobe Commerce) API'si, geliştiricilerin e-ticaret mağazalarıyla programatik olarak entegre olmasını sağlar. OAuth 1.0a ve belirteç tabanlı kimlik doğrulama ile REST, SOAP ve GraphQL uç noktalarını kullanarak ürünlere, siparişlere, müşterilere, envantere ve daha fazlasına yapılandırılabilir hız sınırlarıyla erişim sağlar. Bu kılavuz, kimlik doğrulama kurulumunu, CRUD işlemlerini, web kancalarını, özel uç noktaları ve üretim entegrasyon stratejilerini kapsar.

Giriş

Adobe Commerce (Magento), yıllık 155 milyar doların üzerinde brüt mal değeriyle 250.000'den fazla e-ticaret mağazasına güç veriyor. E-ticaret entegrasyonları, ERP bağlayıcıları veya mobil uygulamalar geliştiren geliştiriciler için Magento API entegrasyonu isteğe bağlı değil; bu devasa satıcı tabanına ulaşmak için zorunludur.

Gerçek şu ki: birden fazla satış kanalını yöneten satıcılar, Magento ile diğer sistemler arasında manuel veri girişiyle haftada 20-30 saat kaybediyor. Sağlam bir Magento API entegrasyonu, ürün senkronizasyonunu, sipariş işlemeyi, envanter güncellemelerini ve müşteri veri yönetimini otomatikleştirir.

Bu kılavuz, eksiksiz Magento 2 API entegrasyon sürecinde size yol gösterecektir. OAuth 1.0a ve belirteç kimlik doğrulamayı, REST/SOAP/GraphQL uç noktalarını, ürün ve sipariş yönetimini, web kancalarını, özel API geliştirmeyi ve üretim dağıtım stratejilerini öğreneceksiniz. Sonunda, üretime hazır bir Magento entegrasyonunuz olacak.

Magento 2 API'si Nedir?

Magento 2, e-ticaret verilerine erişmek için üç API türü sunar:

• REST API: Web ve mobil uygulamalar için JSON tabanlı
• SOAP API: Kurumsal entegrasyonlar için XML tabanlı
• GraphQL: Verimli ön uç uygulamaları için sorgu tabanlı

API şunları işler:

• Ürünler, kategoriler ve envanter
• Siparişler, faturalar ve gönderimler
• Müşteriler ve müşteri grupları
• Alışveriş sepeti ve ödeme
• Promosyonlar ve fiyatlandırma kuralları
• CMS sayfaları ve blokları
• Mağaza yapılandırması

Temel Özellikler

API Karşılaştırması

Magento Sürümleri

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: Yönetici Hesabı veya Entegrasyon Oluşturun

API'ye erişmeden önce:

1. Magento Yönetici Paneline giriş yapın
2. Sistem > İzinler > Tüm Kullanıcılar konumuna gidin
3. Yönetici kullanıcı oluşturun (yönetici belirteci için) VEYA
4. Sistem > Uzantılar > Entegrasyonlar konumuna gidin
5. Yeni entegrasyon oluşturun (OAuth için)

Adım 2: Kimlik Doğrulama Yöntemini Seçin

Adım 3: Yönetici Belirtecini Alın (En Basit Yöntem)

Dahili entegrasyonlar için yönetici belirteci oluşturun:

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('Geçersiz yönetici kimlik bilgileri');
  }

  // Yanıt düz bir dize (belirteç), JSON değil
  const token = await response.text();
  return token;
};

// Kullanım
const token = await getAdminToken();
console.log(`Yönetici belirteci: ${token}`);
// Güvenli bir şekilde saklayın - sonraki API çağrıları için kullanın

Güvenlik notu: Belirteçleri güvenli bir şekilde saklayın:

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

Adım 4: Entegrasyon Oluşturun (Üçüncü Taraflar İçin Önerilir)

Yönetici Paneli aracılığıyla entegrasyon oluşturun:

Sistem > Uzantılar > Entegrasyonlar konumuna gidin

Yeni Entegrasyon Ekle'ye tıklayın

Detayları doldurun:

• Ad: “Entegrasyonum”
• E-posta: your-email@example.com
• Geri Çağırma URL'si: (OAuth için)
• Kimlik Bağlantı URL'si: (OAuth için)

API İzinlerini ayarlayın:

• Kaynaklar: Gerekli izinleri seçin
• Önerilen: Ürünler, Siparişler, Müşteriler, Envanter

Kaydet'e tıklayın

Yeni entegrasyon üzerinde Etkinleştir'e tıklayın

Erişim Belirteci ve Belirteç Sırrı'nı kopyalayın

Adım 5: Müşteri Belirtecini Alın

Müşteri odaklı uygulamalar için:

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('Geçersiz müşteri kimlik bilgileri');
  }

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

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

Adım 6: Kimliği Doğrulanmış API Çağrıları Yapın

Yeniden kullanılabilir API istemcisi oluşturun:

const magentoRequest = async (endpoint, options = {}) => {
  const token = await getAdminToken(); // Veya depolanmış belirteci alın

  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 Hatası: ${error.message}`);
  }

  return response.json();
};

// Kullanım
const products = await magentoRequest('/V1/products');
console.log(`Bulunan ${products.items.length} ürün`);

Ürün Yönetimi

Ürünleri Alma

Filtreleme ile ürünleri getirin:

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

  // Arama kriterleri oluştur
  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;
};

// Kullanım
const products = await getProducts({ search: 'gömlek', priceFrom: 20, limit: 50 });

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

Tek Ürün Alma

SKU ile ürün getirin:

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

// Kullanım
const product = await getProduct('TSHIRT-001');
console.log(`Ad: ${product.name}`);
console.log(`Fiyat: $${product.price}`);
console.log(`Stok: ${product.extension_attributes?.stock_item?.qty}`);

Ürün Oluşturma

Basit ürün oluşturun:

const createProduct = async (productData) => {
  const product = {
    product: {
      sku: productData.sku,
      name: productData.name,
      attribute_set_id: productData.attributeSetId || 4, // Varsayılan küme
      type_id: 'simple',
      price: productData.price,
      status: productData.status || 1, // 1=etkin, 2=devre dışı
      visibility: productData.visibility || 4, // 4=Katalog ve Arama
      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;
};

// Kullanım
const newProduct = await createProduct({
  sku: 'TSHIRT-NEW-001',
  name: 'Birinci Sınıf Pamuklu Tişört',
  price: 29.99,
  qty: 100,
  description: 'Yüksek kaliteli pamuklu tişört',
  shortDescription: 'Birinci sınıf pamuklu tişört',
  color: 'Mavi',
  size: 'M'
});

console.log(`Ürün oluşturuldu: ${newProduct.id}`);

Ürün Güncelleme

Ürün bilgilerini güncelleyin:

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

// Kullanım - Fiyat ve stok güncelle
await updateProduct('TSHIRT-001', {
  price: 24.99,
  extension_attributes: {
    stock_item: {
      qty: 150,
      is_in_stock: true
    }
  }
});

Ürün Silme

Ürünü kaldırın:

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

  console.log(`Ürün ${sku} silindi`);
};

Ürün Türleri

Sipariş Yönetimi

Siparişleri Alma

Filtreleme ile siparişleri getirin:

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

// Kullanım - Son 7 günün bekleyen siparişlerini al
const orders = await getOrders({
  status: 'pending',
  dateFrom: '2026-03-18 00:00:00',
  limit: 50
});

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

Tek Sipariş Alma

ID ile sipariş getirin:

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

// Kullanım
const order = await getOrder(12345);
console.log(`Sipariş #${order.increment_id}`);
console.log(`Durum: ${order.status}`);
console.log(`Toplam: $${order.grand_total}`);
console.log(`Ürünler:`);
order.items.forEach(item => {
  console.log(`  - ${item.name} x ${item.qty_ordered}`);
});

Sipariş Durumu Akışı

beklemede → işleniyor → tamamlandı
        → iptal edildi
        → beklemede
        → ödeme_inceleniyor

Sipariş Durumunu Güncelleme

Sipariş durumunu değiştirin:

const updateOrderStatus = async (orderId, newStatus) => {
  // Not: Doğrudan durum güncelleme özel uç nokta gerektirir
  // Bunun yerine sipariş yönetimi iş akışını kullanın:

  // İptal için:
  await magentoRequest(`/V1/orders/${orderId}/cancel`, {
    method: 'POST'
  });

  // Bekletmek için:
  await magentoRequest(`/V1/orders/${orderId}/hold`, {
    method: 'POST'
  });

  // Bekletmeyi kaldırmak için:
  await magentoRequest(`/V1/orders/${orderId}/unhold`, {
    method: 'POST'
  });
};

Fatura Oluşturma

Sipariş için fatura oluşturun:

const createInvoice = async (orderId, items = [], notify = true, appendComment = false, comment = null) => {
  const invoice = {
    capture: true, // true = ödemeyi yakala
    last: true,
    items: items // {order_item_id, qty} dizisi
  };

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

// Kullanım - Tam sipariş faturası ve yakalama
const invoiceId = await createInvoice(12345, [], true, false, 'Siparişiniz için teşekkür ederiz!');
console.log(`Fatura oluşturuldu: ${invoiceId}`);

Gönderi Oluşturma

Siparişi gönderin:

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

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

  return response;
};

// Kullanım - Takiple gönder
const shipmentId = await createShipment(12345, [], true, false, 'Siparişiniz kargoya verildi!', [
  {
    track_number: '1Z999AA10123456784',
    title: 'Takip Numarası',
    carrier_code: 'ups'
  }
]);
console.log(`Gönderi oluşturuldu: ${shipmentId}`);

Müşteri Yönetimi

Müşterileri Alma

Müşterileri getirin:

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

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

Müşteri Oluşturma

Yeni müşteri kaydı yapın:

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

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

console.log(`Müşteri oluşturuldu: ID ${newCustomer.id}`);

Envanter Yönetimi (MSI)

Stok Durumunu Alma

Ürün stoğunu kontrol edin:

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

// Kullanım
const stock = await getStockStatus('TSHIRT-001');
console.log(`Miktar: ${stock.qty}`);
console.log(`Stokta: ${stock.is_in_stock}`);
console.log(`Minimum Miktar: ${stock.min_qty}`);

Stok Güncelleme

Ürün miktarını güncelleyin:

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

// Kullanım
await updateStock('TSHIRT-001', 100, true);

Web Kancaları ve Eşzamansız İşlemler

Web Kancalarını Kurma

Magento, eşzamansız bildirimler için mesaj kuyruklarını kullanır:

// Magento'nun yerel web kancaları yoktur
// Bunun yerine şu yaklaşımları kullanın:

// 1. Sipariş uç noktasını periyodik olarak sorgulayın
const pollNewOrders = async (lastOrderId) => {
  const orders = await getOrders({
    dateFrom: new Date().toISOString()
  });

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

// 2. Adobe I/O Etkinliklerini kullanın (Yalnızca Adobe Commerce)
// Adobe Developer Console'da etkinlikleri yapılandırın

// 3. Özel web kancası modülü oluşturun
// Bkz: https://devdocs.magento.com/guides/v2.4/extension-dev-guide/message-queues/message-queues.html

Hız Sınırlaması

Hız Sınırlarını Anlama

Magento hız sınırları yapılandırılabilir:

• Varsayılan: Sınır yok (Yönetici'de yapılandırın)
• Önerilen: 100-1000 istek/dakika

Yönetici'de yapılandırın: Mağazalar > Yapılandırma > Hizmetler > Web API > Güvenlik

Hız Sınırı İşlemeyi Uygulama

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

Üretim Dağıtım Kontrol Listesi

Yayına almadan önce:

• [ ] Üretimde entegrasyon belirteçlerini kullanın (yönetici kimlik bilgilerini değil)
• [ ] Belirteçleri güvenli bir şekilde saklayın (şifreli veritabanı)
• [ ] Hız sınırlaması ve istek kuyruğu uygulayın
• [ ] Kapsamlı hata işlemeyi ekleyin
• [ ] Tüm API çağrıları için günlük kaydı ayarlayın
• [ ] Web kancası alternatifi oluşturun (sorgulama veya Adobe I/O)
• [ ] Üretim veri hacmiyle test edin
• [ ] Başarısız istekler için yeniden deneme mantığı uygulayın

Gerçek Dünya Kullanım Durumları

ERP Entegrasyonu

Bir üretici envanteri senkronize eder:

• Zorluk: ERP ile Magento arasında manuel stok güncellemeleri
• Çözüm: Her 15 dakikada bir çift yönlü API senkronizasyonu
• Sonuç: Gerçek zamanlı envanter, sıfır fazla satış

Mobil Uygulama

Bir perakendeci alışveriş uygulaması geliştirir:

• Zorluk: Yerel mobil deneyim gerekliliği
• Çözüm: Ürün göz atma için GraphQL API, ödeme için REST
• Sonuç: Mobil dönüşümde %40 artış

Sonuç

Magento 2 API'si kapsamlı e-ticaret işlevselliği sağlar. Temel çıkarımlar:

• REST, SOAP ve GraphQL API'leri mevcut
• Entegrasyonlar için belirteç tabanlı kimlik doğrulama
• Ürünler, siparişler, müşteriler için tam CRUD
• Gelişmiş envanter yönetimi için MSI
• Kurulum başına yapılandırılabilir hız sınırları
• Apidog, API testini ve ekip işbirliğini kolaylaştırır

SSS Bölümü

Magento API'si ile nasıl kimlik doğrularım?

Dahili entegrasyonlar için yönetici belirteci kullanın veya OAuth için Sistem > Uzantılar'da bir Entegrasyon oluşturun. Müşteri odaklı uygulamalar için müşteri belirteci kullanın.

Magento'da REST ve GraphQL arasındaki fark nedir?

REST, tam CRUD işlemleri sağlar. GraphQL, verimli veri getirme ile ön uç sorguları için optimize edilmiştir.

API aracılığıyla nasıl ürün oluştururum?

SKU, ad, fiyat ve `extension_attributes` içindeki `stock_item` dahil olmak üzere ürün verileriyle `/V1/products` adresine POST isteği gönderin.

Yeni siparişler için web kancaları alabilir miyim?

Magento'nun yerel web kancaları yoktur. Sorgulama, Adobe I/O Etkinlikleri (Adobe Commerce) kullanın veya özel bir modül oluşturun.

Stok miktarlarını nasıl güncellerim?

miktar ve `is_in_stock` değerleriyle `/V1/products/{sku}/stockItems/1` adresine PUT isteği gönderin.