Mağaza API'si ve Webhook'lar

Başlangıç

API ve webhook erişimi Platinum paketinde açıktır. Diğer paketlerde her istek 403 döner.

1. Mağaza yönetim panelinde API & Webhook sayfasını açın (/admin/api).
2. Yeni API Anahtarı kartında bir ad verin, ihtiyacınız olan yetki kapsamlarını işaretleyin ve Anahtar Oluştur'a basın.
3. Anahtar yalnızca bir kez gösterilir. Hemen kopyalayıp güvenli bir yerde saklayın.
4. İlk isteğinizi gönderin:

curl https://magazaniz.com/api/v1/products?per_page=5 \
  -H "X-API-KEY: 3f9c0e…(48 karakter)"

$ch = curl_init('https://magazaniz.com/api/v1/products?per_page=5');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-KEY: ' . $apiKey],
]);
$yanit = json_decode(curl_exec($ch), true);

const yanit = await fetch('https://magazaniz.com/api/v1/products?per_page=5', {
  headers: { 'X-API-KEY': process.env.API_KEY }
});
const veri = await yanit.json();

Örneklerdeki magazaniz.com yerine mağazanızın alan adını yazın. Alan adı bağlı değilse mağazanızın SUSOFTECH alt alan adını kullanın.

Kimlik doğrulama

Her istekte anahtarınızı X-API-KEY başlığında gönderin. Authorization: Bearer ve adres satırında (query string) anahtar desteklenmez.

Anahtarı tarayıcıda kullanmayın. API, tarayıcıdan yapılan çapraz alan isteklerine (CORS) izin vermez. Çağrıları kendi sunucunuzdan yapın; anahtarı ön yüz koduna koymayın.

Yetki kapsamları

Her anahtar yalnız kendisine verilen kapsamlardaki uçları çağırabilir. Hiç kapsam seçilmezse anahtar tüm okuma izinlerini alır, hiçbir yazma izni almaz.

Kapsamı olmayan bir uç çağrılırsa 403 döner ve gereken kapsam errors.required_scope alanında belirtilir.

İstek ve yanıt biçimi

Yanıtlar her zaman JSON'dur (Content-Type: application/json; charset=utf-8). Yazma isteklerinde gövdeyi JSON olarak gönderin ve Content-Type: application/json başlığını ekleyin. Gövde boşsa form verisi (application/x-www-form-urlencoded) de okunur.

Başarılı yanıt

{
  "success": true,
  "message": "OK",
  "data": { … }
}

Sayfalı liste

Liste uçları page (varsayılan 1) ve per_page (varsayılan 20, en fazla 100) parametrelerini alır. 100'ün üzerindeki değerler 100'e indirilir.

{
  "success": true,
  "message": "OK",
  "data": [ … ],
  "meta": { "page": 1, "per_page": 20, "total": 143, "total_pages": 8 }
}

Hata yanıtı

{
  "success": false,
  "message": "Validation failed",
  "errors": { "price": "Geçerli bir fiyat gerekli." }
}

Tutarlar ondalık sayıdır (TRY, iki basamak). Tarihler sunucu saatine (Türkiye, UTC+3) göre YYYY-MM-DD HH:MM:SS biçimindedir.

Hatalar

Var olmayan bir adres (ör. yazım hatalı uç) JSON yerine HTML hata sayfası döndürür. İstemcinizde yanıt gövdesini çözmeden önce Content-Type başlığını kontrol edin.

Hız limiti

Her anahtarın dakikalık istek limiti vardır (varsayılan 120; yönetim ekranından 0–100.000 arası ayarlanır, 0 = sınırsız). Pencere kayan 60 saniyedir.

Reddedilen (429) istekler de pencereye sayılır. Limite takıldığınızda yeniden denemeden önce Retry-After kadar bekleyin; aralıksız tekrar denemek bekleme süresini uzatır.

Ürünler

curl "https://magazaniz.com/api/v1/products?in_stock=1&sort=price_asc&per_page=50" \
  -H "X-API-KEY: $API_KEY"

$url = 'https://magazaniz.com/api/v1/products'
     . '?' . http_build_query(['in_stock' => 1, 'sort' => 'price_asc', 'per_page' => 50]);

$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-KEY: ' . $apiKey]]);
$urunler = json_decode(curl_exec($ch), true)['data'];

const q = new URLSearchParams({ in_stock: '1', sort: 'price_asc', per_page: '50' });
const r = await fetch(`https://magazaniz.com/api/v1/products?${q}`, {
  headers: { 'X-API-KEY': process.env.API_KEY }
});
const { data, meta } = await r.json();

curl -X PUT https://magazaniz.com/api/v1/products/128/price \
  -H "X-API-KEY: $API_KEY" -H "Content-Type: application/json" \
  -d '{"price": 449.90, "compare_price": 599.90}'

$ch = curl_init('https://magazaniz.com/api/v1/products/128/price');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-KEY: ' . $apiKey, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['price' => 449.90, 'compare_price' => 599.90]),
]);
$sonuc = json_decode(curl_exec($ch), true);

await fetch('https://magazaniz.com/api/v1/products/128/price', {
  method: 'PUT',
  headers: { 'X-API-KEY': process.env.API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ price: 449.90, compare_price: 599.90 })
});

Kategoriler ve markalar

Siparişler

curl -X PATCH https://magazaniz.com/api/v1/orders/5021 \
  -H "X-API-KEY: $API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "shipped", "cargo_company": "Aras Kargo", "tracking_number": "3450012345"}'

$ch = curl_init('https://magazaniz.com/api/v1/orders/5021');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-KEY: ' . $apiKey, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'status'          => 'shipped',
        'cargo_company'   => 'Aras Kargo',
        'tracking_number' => '3450012345',
    ]),
]);
curl_exec($ch);

await fetch('https://magazaniz.com/api/v1/orders/5021', {
  method: 'PATCH',
  headers: { 'X-API-KEY': process.env.API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'shipped', cargo_company: 'Aras Kargo', tracking_number: '3450012345' })
});

Kargo gönderisi

Stok

curl -X PUT https://magazaniz.com/api/v1/stock/128 \
  -H "X-API-KEY: $API_KEY" -H "Content-Type: application/json" \
  -d '{"variant_id": 904, "stock": 25}'

$ch = curl_init('https://magazaniz.com/api/v1/stock/128');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-KEY: ' . $apiKey, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['variant_id' => 904, 'stock' => 25]),
]);
curl_exec($ch);

await fetch('https://magazaniz.com/api/v1/stock/128', {
  method: 'PUT',
  headers: { 'X-API-KEY': process.env.API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ variant_id: 904, stock: 25 })
});

Webhook'lar

Webhook, seçtiğiniz olay gerçekleştiğinde mağazanın sizin adresinize gönderdiği HTTPS POST isteğidir. Yönetim panelinde API & Webhook › Webhook'lar sekmesinden HTTPS adresinizi ve olayları seçerek eklenir. Oluştururken gösterilen imza anahtarını (secret) kopyalayın; bir daha gösterilmez.

Olaylar

stock.changed içindeki reason: order_sale (satış), admin (ürün düzenleme), api, order_cancel (iptal iadesi), order_return (iade), ya da stok hareketi türü (ör. manual_in, manual_out). Olaylar yalnız değer gerçekten değiştiğinde gönderilir.

İstek

POST /sizin/webhook/adresiniz HTTP/1.1
Content-Type: application/json
User-Agent: SUSOFTECH-Webhook/1.0
X-Webhook-Event: stock.changed
X-Webhook-Delivery: 3f9a1c7e2b8d4a60b1e5c9d7a2f4e816
X-Webhook-Signature: sha256=5d1c9e…

{"id":"3f9a1c7e2b8d4a60b1e5c9d7a2f4e816","event":"stock.changed","data":{"product_id":128,"variant_id":904,"old":5,"new":25,"reason":"api"},"timestamp":1760443200}

İmza doğrulama

X-Webhook-Signature değeri, ham istek gövdesinin imza anahtarınızla HMAC-SHA256 özetidir (küçük harf onaltılık, başında sha256=). Gövdeyi çözmeden önce ham baytlar üzerinden doğrulayın ve sabit zamanlı karşılaştırma kullanın.

$raw    = file_get_contents('php://input');
$secret = getenv('SUSOFTECH_WEBHOOK_SECRET');
$beklen = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$gelen  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($beklen, $gelen)) { http_response_code(401); exit; }

$olay = json_decode($raw, true);
if (abs(time() - (int) $olay['timestamp']) > 300) { http_response_code(400); exit; } // 5 dk'dan eski
// işi kuyruğa al …
http_response_code(200);

const crypto = require('crypto');
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const beklenen = 'sha256=' + crypto.createHmac('sha256', process.env.SUSOFTECH_WEBHOOK_SECRET)
                                   .update(req.body).digest('hex');
  const gelen = req.get('X-Webhook-Signature') || '';
  if (gelen.length !== beklenen.length ||
      !crypto.timingSafeEqual(Buffer.from(gelen), Buffer.from(beklenen))) return res.sendStatus(401);
  const olay = JSON.parse(req.body);
  res.sendStatus(200);   // sonra olay.event / olay.data ile işleyin
});

import hmac, hashlib
def imza_dogru(ham: bytes, gelen: str, secret: str) -> bool:
    beklenen = "sha256=" + hmac.new(secret.encode(), ham, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, gelen or "")

Mağaza panelindeki API ekranı

Mağaza yönetim panelinde API & Webhook sayfası (/admin/api, Platinum) üç sekmeden oluşur:

Sınırlar ve öneriler

• Sunucudan çağırın. CORS desteği yoktur; anahtarı tarayıcıya, mobil uygulamaya veya herkese açık depoya koymayın.
• Her entegrasyona ayrı anahtar. ERP, depo, muhasebe gibi her sisteme yalnız gereken kapsamlarla ayrı anahtar açın; biri sızarsa yalnız onu iptal edersiniz.
• Sabit IP'niz varsa İzinli IP'ler listesini doldurun.
• Kargo gönderisi ücretlidir. POST …/shipment gerçek barkod oluşturur ve mağaza cüzdanından ücret çeker; testleri dikkatle yapın.
• Stok mutlak değerdir. Eşzamanlı satışlarda üzerine yazmamak için güncellemeden hemen önce okuyun ya da tek yönlü senkron (ERP → mağaza) kurun.
• Webhook'u tek kaynak yapmayın. Tekrar denemeler olsa da adresiniz uzun süre kapalı kalırsa olay kaybolabilir; kritik verileri belirli aralıklarla API ile karşılaştırın.
• Hız limiti için toplu senkronlarda per_page=100 kullanın ve X-RateLimit-Remaining başlığını izleyin.
• Bu sürümde ürün oluşturma/silme, kategori/marka yazma, müşteri verisi ve sipariş oluşturma uçları yoktur.

Değişiklik günlüğü

14.10.2026

order.created tüm kaynaklardan gönderiliyor; teslim kuyruğu ve 6 tekrar deneme; X-Webhook-Delivery başlığı; panelde Test gönder.

Bu doküman Ekim 2026 itibarıyla API'nin çalışan davranışını anlatır. Soru ve talepler için destek kanalımızı kullanın.