carsimerkezi.com

Geliştiriciler

Çarşı Merkezi Satıcı API'si

Mağazanızın ürünlerini, stok ve fiyatlarını, siparişlerini kendi yazılımınızdan (ERP, stok programı, kendi siteniz) yönetin; yeni sipariş olduğunda anında haber alın. API REST/JSON'dur, belgesi OpenAPI 3 biçimindedir.

Başlarken

  1. Mağazanızı açın ve onaylanmasını bekleyin.
  2. Mağaza paneli → API ve bildirimler → Yeni anahtar. Yalnızca ihtiyacınız olan yetkileri seçin. Anahtar bir kez gösterilir; güvenli bir yerde saklayın.
  3. Temel adres: https://www.carsimerkezi.com/api/v1/partner

Kimlik doğrulama

Her istekte anahtarı X-Api-Key başlığında gönderin (Authorization: Bearer cm_live_… da kabul edilir). Anahtar yalnızca bir mağazaya bağlıdır ve o mağazanın verisine erişir.

curl https://www.carsimerkezi.com/api/v1/partner/me \
  -H "X-Api-Key: cm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
YetkiNe sağlar
products:readÜrünleri ve varyantları okuma
products:writeÜrün oluşturma/güncelleme, görsel, stok ve fiyat
orders:readSiparişleri okuma
orders:writeSipariş durumunu değiştirme, kargo bildirme, iptal

Uç noktalar

YöntemYolYetkiAçıklama
GET/me—Anahtarın mağazası ve yetkileri
GET/categories—Kategori ağacı (ürün yaprak kategoriye bağlanır)
GET/products?page=&pageSize=&status=&updatedSince=products:readÜrünler (sayfalı)
GET/products/{id}products:readÜrün
POST/productsproducts:writeÜrün oluştur (varyantlarıyla)
PUT/products/{id}products:writeÜrünü güncelle; listede olmayan varyant silinir
DELETE/products/{id}products:writeÜrünü yayından kaldır
POST/products/{id}/imagesproducts:writeGörsel yükle (multipart, alan: files)
PUT/inventoryproducts:writeSKU ile toplu stok/fiyat (en çok 500 satır)
GET/orders?status=&since=&page=orders:readSiparişler (eskiden yeniye)
GET/orders/{number}orders:readSipariş
POST/orders/{number}/prepareorders:writeHazırlanıyor
POST/orders/{number}/shiporders:writeKargoya verildi (firma + takip no)
POST/orders/{number}/deliverorders:writeTeslim edildi
POST/orders/{number}/cancelorders:writeİptal (stok geri döner)

Ürün oluşturma

Fiyat ve stok varyanttadır; tek seçenekli ürün de bir varyant taşır. Stok kodu (SKU) mağazanız içinde tekildir ve stok/fiyat güncellemeleri SKU ile yapılır. Fiyatlar KDV dahildir. categoryId için GET /categories yanıtında isLeaf: true olan bir kategori seçin. Aynı barkodu (GTIN) taşıyan ürünler pazaryerinde “Bu ürünü satan diğer mağazalar” bölümünde birlikte görünür.

curl -X POST https://www.carsimerkezi.com/api/v1/partner/products \
  -H "X-Api-Key: $CM_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "PLA+ Filament 1.75 mm 1 kg",
    "categoryId": "…",
    "brand": "eSun",
    "barcode": "8690000000011",
    "descriptionHtml": "<p>Dayanıklı PLA+ filament.</p>",
    "vatRate": 20,
    "status": "Active",
    "attributes": { "Çap": "1.75 mm", "Ağırlık": "1 kg" },
    "tags": ["pla", "3d baskı"],
    "variants": [
      { "sku": "PLA-BLK", "options": { "Renk": "Siyah" }, "price": 549, "compareAtPrice": 649, "stock": 40 },
      { "sku": "PLA-WHT", "options": { "Renk": "Beyaz" }, "price": 549, "stock": 25 }
    ]
  }'

Doğrulama hataları birlikte döner (400, details listesi). Görseller ürün oluşturulduktan sonra yüklenir:

curl -X POST https://www.carsimerkezi.com/api/v1/partner/products/{id}/images -H "X-Api-Key: $CM_KEY" \
  -F "files=@on.jpg" -F "files=@yan.jpg"

Stok ve fiyat

En sık kullanılan uç: tek istekte 500 satıra kadar stok ve/veya fiyat. Her satırın sonucu ayrı döner; bulunamayan SKU diğerlerini engellemez.

curl -X PUT https://www.carsimerkezi.com/api/v1/partner/inventory -H "X-Api-Key: $CM_KEY" -H "Content-Type: application/json" \
  -d '[{ "sku": "PLA-BLK", "stock": 12 }, { "sku": "PLA-WHT", "price": 529.90, "compareAtPrice": 649 }]'

[{ "sku": "PLA-BLK", "ok": true, "error": null }, { "sku": "PLA-WHT", "ok": true, "error": null }]

Siparişler

Ödemesi alınan sipariş New durumunda gelir. Akış: New → Preparing → Shipped → Delivered → Completed; teslimden 14 gün sonra sipariş kendiliğinden tamamlanır ve hakediş kesinleşir. channel alanı siparişin nereden geldiğini söyler: Marketplace (carsimerkezi.com), Storefront (mağazanızın kendi alan adı), External (bağlı pazaryerleri). Komisyon yalnızca Marketplace siparişlerinde kesilir; commissionTotal, commissionVat ve payoutAmount siparişte hazır gelir.

curl "https://www.carsimerkezi.com/api/v1/partner/orders?status=New" -H "X-Api-Key: $CM_KEY"

curl -X POST https://www.carsimerkezi.com/api/v1/partner/orders/CM100123-1/ship -H "X-Api-Key: $CM_KEY" -H "Content-Type: application/json" \
  -d '{ "cargoCompany": "Yurtiçi Kargo", "trackingNumber": "123456789", "trackingUrl": "https://…" }'

Olay bildirimleri (webhook)

Siparişleri sürekli sorgulamak yerine panelden bir https adresi tanımlayın; olay olduğunda POST ile JSON gönderilir. Başarısız gönderim 1 dk, 5 dk, 30 dk, 2 sa, 6 sa ve 24 sa sonra yeniden denenir; 20 kez art arda başarısız olan adres kapatılır.

OlayNe zaman
order.createdSipariş ödendi, hazırlamaya başlayabilirsiniz
order.status_changedDurum değişti (müşteri “teslim aldım” dedi, kargo girildi…)
order.cancelledSipariş iptal edildi (stok geri döndü)
product.stock_lowBir satıştan sonra varyantın stoğu 3 ya da altına indi
POST https://sizin-sunucunuz/carsimerkezi
X-CarsiMerkezi-Event: order.created
X-CarsiMerkezi-Delivery: 0b7c…            (tekrarlanan teslimleri ayıklamak için)
X-CarsiMerkezi-Signature: t=1791200000,v1=5f2a…

{ "id": "0b7c…", "event": "order.created", "createdAt": "2026-10-05T12:00:00Z", "storeId": "…", "data": { "number": "CM100123-1", … } }

İmza: v1 = hex(HMAC-SHA256(sır, t + "." + gövde)). Sır bildirim adresi oluşturulurken bir kez gösterilir (whsec_…). Gövdeyi ham hâliyle doğrulayın ve 5 dakikadan eski t değerlerini reddedin.

// Node.js
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
// C#
static bool Verify(string rawBody, string header, string secret)
{
    var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(parts["t"])) > 300) return false;
    var hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{parts["t"]}.{rawBody}"));
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(Convert.ToHexStringLower(hash)), Encoding.UTF8.GetBytes(parts["v1"]));
}
// PHP
function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $p);
    if (abs(time() - (int)$p['t']) > 300) return false;
    return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret), $p['v1']);
}

Ürün beslemesi

Her mağazanın Google Merchant Center biçiminde (RSS 2.0, g: alanları) bir ürün beslemesi vardır; Meta (Facebook/Instagram) katalogları da aynı biçimi okur. Adres mağaza paneli → Entegrasyonlar'dadır ve gizli bir belirteç taşır; yenilerseniz eski adres çalışmaz. ?hedef=magaza eklenirse ürün bağlantıları mağazanızın kendi alan adına gider.

Pazaryeri entegrasyonları

Ürünlerinizi Trendyol, Hepsiburada, n11, Amazon, Çiçeksepeti, Pazarama, PttAVM ve idefix'e Çarşı Merkezi'nden göndermek, stok ve fiyatı tek yerden eşitlemek ve oradaki siparişleri buraya çekmek için kanal bağlantıları hazırlanıyor. Bağlantılar mağaza panelinden kurulacak; o kanallardaki satışlardan Çarşı Merkezi komisyon almaz.

Hatalar ve sınırlar

Hatalar Türkçe açıklamayla döner: { "error": "…", "details": ["…"] }. 401 anahtar yok/geçersiz, 403 yetki eksik ya da mağaza etkin değil, 404 kayıt yok, 409 durum uygun değil (ör. kargodaki sipariş iptal edilemez), 429 hız sınırı. Sınır anahtar başına dakikada 600 istektir.

Entegrasyon desteği için yazın