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
- Mağazanızı açın ve onaylanmasını bekleyin.
- 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.
- 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"| Yetki | Ne sağlar |
|---|---|
products:read | Ürünleri ve varyantları okuma |
products:write | Ürün oluşturma/güncelleme, görsel, stok ve fiyat |
orders:read | Siparişleri okuma |
orders:write | Sipariş durumunu değiştirme, kargo bildirme, iptal |
Uç noktalar
| Yöntem | Yol | Yetki | Açı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 | /products | products: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}/images | products:write | Görsel yükle (multipart, alan: files) |
| PUT | /inventory | products:write | SKU ile toplu stok/fiyat (en çok 500 satır) |
| GET | /orders?status=&since=&page= | orders:read | Siparişler (eskiden yeniye) |
| GET | /orders/{number} | orders:read | Sipariş |
| POST | /orders/{number}/prepare | orders:write | Hazırlanıyor |
| POST | /orders/{number}/ship | orders:write | Kargoya verildi (firma + takip no) |
| POST | /orders/{number}/deliver | orders:write | Teslim edildi |
| POST | /orders/{number}/cancel | orders: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.
| Olay | Ne zaman |
|---|---|
order.created | Sipariş ödendi, hazırlamaya başlayabilirsiniz |
order.status_changed | Durum değişti (müşteri “teslim aldım” dedi, kargo girildi…) |
order.cancelled | Sipariş iptal edildi (stok geri döndü) |
product.stock_low | Bir 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.
