Magenty Public API

Giriş

Magenty Public API, panelinizdeki verilere programatik erişim sağlar. Tüm istekler REST + JSON üzerinden, tek temel adrese gider:

https://v3apibeta.magenty.com/api/v1

Bir API anahtarına ihtiyacınız var — panelinizde Ayarlar → API & Webhook bölümünden oluşturabilirsiniz. Anahtar yalnız oluşturulduğu anda gösterilir, sonra tekrar görüntülenemez.

Kimlik doğrulama

Her isteğe anahtarınızı Authorization başlığında Bearer olarak ekleyin:

curl "https://v3apibeta.magenty.com/api/v1/me" \
  -H "Authorization: Bearer mgk_live_..."

X-Api-Key: mgk_live_... başlığı da eşdeğer bir alternatiftir.

Başarılı bir çağrı panel ve anahtar bilgisini döner:

{
  "panel": { "id": "1000006", "name": "Mağazanız" },
  "key": { "name": "ERP Entegrasyonu", "scopes": ["products:read", "stock:read"] }
}

Kapsamlar

Her anahtar oluşturulurken hangi kapsamlara sahip olacağı seçilir. Bir uç, gerektirdiği kapsam anahtarda yoksa 403 forbidden_scope döner.

Hız limiti

Anahtar başına dakikada 120 istek. Limit aşıldığında 429 döner;Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler. Toplu senkronlarda istekleri kuyruklayıp bu başlığa göre yeniden deneyin.

Sayfalama & filtreleme

Liste uçları page (1'den başlar) ve size (en fazla 100, varsayılan 50) parametrelerini kabul eder. Yalnız belirli bir tarihten sonra değişenleri çekmek için updatedSince (ISO 8601) kullanın — düzenli senkronlarda tüm listeyi her seferinde çekmek yerine bunu tercih edin.

GET https://v3apibeta.magenty.com/api/v1/products?page=1&size=50&updatedSince=2026-09-01T00:00:00Z

Yanıt zarfı:

{
  "data": [ /* ... */ ],
  "meta": { "page": 1, "size": 50, "total": 812 }
}

Hata formatı

Hatalar HTTP durum koduna ek olarak makine-okur bir code taşır:

{
  "statusCode": 403,
  "code": "forbidden_scope",
  "message": "Bu anahtarın 'stock:write' kapsamı yok."
}

Ürünler

GET /products — katalogdaki ürünleri varyantlarıyla listeler. GET /products/:id tek ürünü döner. Barkod veya SKU ile doğrudan varyant aramak için GET /variants?barcode=... ya da ?sku=... kullanın.

{
  "id": "cmt...",
  "title": "Organik Bitki Gübresi 5 LT",
  "brand": "Diğer",
  "totalStock": 997,
  "variants": [
    { "id": "cmt...", "barcode": "8690...", "sku": "SKU-001", "price": 399.9, "stock": 997 }
  ]
}

Stok

GET /stock depo × firma bazında stok satırlarını listeler. PUT /stock ile toplu güncelleme yapılır — her satır bağımsız işlenir, biri hata verse diğerleri devam eder:

curl -X PUT "https://v3apibeta.magenty.com/api/v1/stock" \
  -H "Authorization: Bearer mgk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "barcode": "8690...", "quantity": 42 },
      { "sku": "SKU-002", "quantity": 0 }
    ]
  }'

{
  "results": [
    { "index": 0, "ok": true, "variantId": "cmt...", "total": 42 },
    { "index": 1, "ok": false, "error": { "code": "not_found", "message": "Varyant bulunamadı." } }
  ]
}

warehouseId/companyId belirtmezseniz panelinizin varsayılan deposu ve firması kullanılır (bunları GET /warehouses ve GET /companies ile öğrenebilirsiniz). Güncellediğiniz stok, panelinizde o varyant için pazaryerine gönderim açıksa otomatik olarak pazaryerlerinize de gider — ayrıca bir "yayınla" çağrısı gerekmez. FIFO/ortalama maliyet modundaki bir üründe stok API'den değiştirilemez; giriş panelden yapılmalıdır.

Siparişler

GET /orders — mağazalarınızdaki siparişleri listeler (status, marketplace, storeId, dateFrom/dateTo ile filtrelenebilir). GET /orders/:id kalemleri ve teslimat/fatura adresini de döner.

{
  "orderNumber": "1234567890",
  "marketplace": "trendyol",
  "statusCanonical": "shipped",
  "grossRevenue": 249.9,
  "shipping": { "fullName": "Ayşe Yılmaz", "city": "İstanbul", "district": "Kadıköy" },
  "items": [ { "barcode": "8690...", "quantity": 1, "unitPrice": 249.9 } ]
}

Mağaza / depo / firma

GET /stores, GET /warehouses, GET /companies — stok yazarken veya sipariş filtrelerken ihtiyaç duyacağınız kimlikleri (id, ad, varsayılan olup olmadığı) listeler.

Sürümleme

API adresi /v1 ile sürümlenir. Geriye dönük uyumsuz bir değişiklik yapmamız gerekirse yeni bir sürüm (/v2) açılır, /v1 makul bir süre daha çalışmaya devam eder. Alan eklemek (yeni bir JSON anahtarı) sürüm artışı SAYILMAZ — entegrasyonunuzun bilmediği alanları yok saymasını önerelim.