Hesap
Bağlantınızı doğrulamak için ilk çağıracağınız uç.GET api/v1/me Yetki gerekmez
Anahtar bilgisi
Anahtarın hangi satıcıya ait olduğunu, hangi yetkileri taşıdığını ve istek sınırını döner. Entegrasyonu kurarken ilk bunu çağırın: cevap geliyorsa kimlik doğrulamanız çalışıyor demektir.
Örnek cevap — 200
{
"vendorId": 1042,
"vendorName": "Örnek Kozmetik",
"keyName": "Entegra bağlantısı",
"apiKey": "kzm_7QF3MHKD2NRAX9TB",
"scopes": [
{ "code": "ProductRead", "title": "Ürün okuma" },
{ "code": "OrderRead", "title": "Sipariş okuma" }
],
"rateLimit": { "windowSeconds": 10, "maxRequests": 50 }
}
Ürünler
Kataloğunuzu okuyun. Yazma uçları Faz 2'de eklenecek.GET api/v1/products Yetki: Ürün okuma
Ürünleri listele
Yalnız sizin ürünlerinizi döner. Artımlı senkronizasyon için updatedSince kullanın: her seferinde bütün kataloğu çekmek yerine son çalışmadan bu yana değişenleri alırsınız.
Örnek cevap — 200
{
"page": 0,
"size": 50,
"totalElements": 213,
"totalPages": 5,
"content": [
{
"id": 9412,
"name": "Örnek Yüz Kremi 50 ml",
"sku": "KZM-1001",
"barcode": "8690000000017",
"price": 249.90,
"listPrice": 299.90,
"stockQuantity": 42,
"published": true,
"brand": "Örnek Marka",
"categoryIds": [ 118, 204 ],
"createdOnUtc": "2026-03-11T09:24:00Z",
"updatedOnUtc": "2026-08-14T18:02:11Z"
}
]
}GET api/v1/products/{id} Yetki: Ürün okuma
Tek ürün
Kimliğe göre tek ürün döner. Ürün size ait değilse 404 döner — başkasının ürününü sorgulayarak varlığını öğrenemezsiniz.
Örnek cevap — 200
{
"id": 9412,
"name": "Örnek Yüz Kremi 50 ml",
"sku": "KZM-1001",
"barcode": "8690000000017",
"price": 249.90,
"listPrice": 299.90,
"stockQuantity": 42,
"published": true,
"brand": "Örnek Marka",
"categoryIds": [ 118, 204 ],
"createdOnUtc": "2026-03-11T09:24:00Z",
"updatedOnUtc": "2026-08-14T18:02:11Z"
}
Ürün yazma
Kataloğunuzu kendi sisteminizden yönetin. Gönderim kabul edilir, numara döner; sonucu sorgularsınız.POST api/v1/products Yetki: Ürün yazma
Ürün oluştur (toplu)
Yeni ürünleri kuyruğa alır ve bir toplu istek numarası döner. Ürünler YAYINA KAPALI oluşturulur; satıcı panelinden kontrol edip yayınlarsınız. Görseli ve başlığı görülmeden bir ürünün vitrine düşmemesi için böyle.
Örnek cevap — 200
{
"batchRequestId": "6f2a91c4d38b47e5ac1f7b0e29d5a833",
"itemCount": 250,
"status": "Queued",
"message": "Ürünler kuyruğa alındı. Oluşturulan ürünler yayına kapalı gelir; satıcı panelinden kontrol edip yayınlayabilirsiniz."
}PUT api/v1/products Yetki: Ürün yazma
Ürün güncelle (toplu)
Var olan ürünleri günceller. Ürün barkod veya stok koduyla bulunur; size ait olmayan bir barkod bulunamamış sayılır. Yalnız gönderdiğiniz alanlar değişir, göndermedikleriniz olduğu gibi kalır.
Örnek cevap — 200
{
"batchRequestId": "b81d40f7c9a24e6d95c3e0182fa7d64b",
"itemCount": 40,
"status": "Queued",
"message": "Güncellemeler kuyruğa alındı."
}POST api/v1/products/price-and-stock Yetki: Ürün yazma
Fiyat ve stok güncelle (toplu)
Gün içinde en sık çağıracağınız uç. Yalnız fiyat ve stok değişir; ürün adı, açıklaması ve görselleri hiç dokunulmadan kalır — bu yüzden panelde elle yaptığınız düzeltmeler senkronizasyonla geri alınmaz.
Örnek cevap — 200
{
"batchRequestId": "3c7e18a0b6d54f92ae0d47c8b1539f2a",
"itemCount": 1000,
"status": "Queued",
"message": "Fiyat ve stok güncellemeleri kuyruğa alındı."
}GET api/v1/products/batch-requests/{batchRequestId} Yetki: Ürün yazma
Toplu istek sonucu
Gönderiminizin durumunu ve SATIR BAZINDA sonucunu döner. 1000 satırın 3'ü hatalıysa 997'si işlenir ve yalnız 3'ü için sebep yazar; lineIndex ile kendi kaydınıza eşleştirirsiniz.
Örnek cevap — 200
{
"batchRequestId": "3c7e18a0b6d54f92ae0d47c8b1539f2a",
"type": "PriceAndStock",
"status": "Completed",
"itemCount": 3,
"succeededCount": 2,
"failedCount": 1,
"createdOnUtc": "2026-08-19T08:14:02Z",
"completedOnUtc": "2026-08-19T08:15:07Z",
"items": [
{ "lineIndex": 0, "status": "Succeeded", "productId": 9412 },
{ "lineIndex": 1, "status": "Succeeded", "productId": 9413 },
{
"lineIndex": 2,
"status": "Failed",
"failReason": "Bu barkod veya stok koduna sahip ürününüz bulunamadı."
}
]
}
Kargo
Siparişlerinizi kargolayın. Paketler satıcı bazında ayrı — kendi satırlarınızı yönetirsiniz.GET api/v1/shipment-packages Yetki: Sipariş okuma
Paketleri listele
Kargolanmayı bekleyen ve kargolanmış paketlerinizi döner. Aynı siparişteki başka satıcının satırları ve kargo takip numarası burada GÖRÜNMEZ.
Örnek cevap — 200
{
"page": 0,
"size": 50,
"totalElements": 3,
"totalPages": 1,
"content": [
{
"orderId": 20481,
"orderNumber": "20481",
"orderStatus": "Processing",
"shippingStatus": "NotYetShipped",
"createdOnUtc": "2026-08-17T11:04:22Z",
"vendorTotal": 499.80,
"shipments": [],
"lines": [
{ "id": 55120, "productId": 9412, "productName": "Örnek Yüz Kremi 50 ml", "sku": "KZM-1001", "quantity": 2, "unitPrice": 249.90, "totalPrice": 499.80 }
],
"shipping": {
"recipientName": "Ayşe Yılmaz",
"phone": "05xxxxxxxxx",
"addressLine": "Örnek Mah. Örnek Sk. No:1 D:2",
"district": "Kadıköy",
"city": "İstanbul",
"postalCode": "34700"
}
}
]
}GET api/v1/shipment-packages/{orderId} Yetki: Sipariş okuma
Tek paket
Siparişte size ait satır yoksa 404 döner.
Örnek cevap — 200
{ "orderId": 20481, "orderNumber": "20481", "shippingStatus": "NotYetShipped", "lines": [ ... ] }PUT api/v1/shipment-packages/{orderId}/shipped Yetki: Sipariş yazma
Kargo bilgisi bildir
Sizin bu siparişteki satırlarınız için kargo paketi oluşturur ve takip numarasını kaydeder. Zaten kargolanmış satırlar tekrar paketlenmez. Siparişin kargo durumu kısmi/tam olarak otomatik belirlenir — çok satıcılı bir siparişte yalnız sizin gönderiminiz siparişin tamamını 'kargolandı' yapmaz.
Örnek cevap — 200
{
"id": 3312,
"trackingNumber": "1234567890",
"shippedOnUtc": "2026-08-19T09:21:00Z"
}
İadeler
Kendi ürünlerinize açılan iade taleplerini görün ve sonuçlandırın.GET api/v1/returns Yetki: İade okuma
İadeleri listele
Yalnız sizin ürünlerinize açılmış talepler döner.
Örnek cevap — 200
{
"page": 0,
"size": 50,
"totalElements": 1,
"totalPages": 1,
"content": [
{
"id": 412,
"orderId": 20481,
"productId": 9412,
"productName": "Örnek Yüz Kremi 50 ml",
"quantity": 1,
"status": "Pending",
"reason": "Ürün beklediğim gibi değil",
"requestedAction": "İade",
"customerComment": "Kutusu ezikti.",
"createdOnUtc": "2026-08-18T14:32:10Z"
}
]
}PUT api/v1/returns/{id} Yetki: İade yazma
İadeyi sonuçlandır
Talebin durumunu değiştirir. REDDEDERKEN GEREKÇE ZORUNLU — müşterinin neden reddedildiğini görmesi gerekiyor. Notlar üst üste yazılmaz, geçmiş korunur.
Örnek cevap — 200
{
"id": 412,
"orderId": 20481,
"productId": 9412,
"productName": "Örnek Yüz Kremi 50 ml",
"quantity": 1,
"status": "ReturnAuthorized",
"createdOnUtc": "2026-08-18T14:32:10Z"
}
Siparişler
Siparişleriniz — yalnız size ait satırlarla.GET api/v1/orders Yetki: Sipariş okuma
Siparişleri listele
Bir sipariş birden fazla satıcının ürününü içerebilir. Bu uç yalnız SİZİN satırlarınızı ve onların toplamını döner; siparişin genel toplamı başkalarının tutarını da içereceği için verilmiyor.
Örnek cevap — 200
{
"page": 0,
"size": 50,
"totalElements": 7,
"totalPages": 1,
"content": [
{
"id": 20481,
"orderNumber": "20481",
"status": "Processing",
"paymentStatus": "Paid",
"shippingStatus": "NotYetShipped",
"createdOnUtc": "2026-08-17T11:04:22Z",
"vendorTotal": 499.80,
"lines": [
{
"id": 55120,
"productId": 9412,
"productName": "Örnek Yüz Kremi 50 ml",
"sku": "KZM-1001",
"quantity": 2,
"unitPrice": 249.90,
"totalPrice": 499.80
}
],
"shipping": {
"recipientName": "Ayşe Yılmaz",
"phone": "05xxxxxxxxx",
"addressLine": "Örnek Mah. Örnek Sk. No:1 D:2",
"district": "Kadıköy",
"city": "İstanbul",
"postalCode": "34700"
}
}
]
}GET api/v1/orders/{id} Yetki: Sipariş okuma
Tek sipariş
Siparişte size ait satır yoksa 404 döner. Numarayı artırarak başka siparişleri okumak mümkün değildir.
Örnek cevap — 200
{ "id": 20481, "orderNumber": "20481", "status": "Processing", "vendorTotal": 499.80, "lines": [ ... ] }
Referans veri
Ürün gönderirken ihtiyaç duyacağınız kimlikler.GET api/v1/categories Yetki: Referans veri
Kategoriler
Kategori ağacı. parentId ile üst kategoriye bağlanır, 0 ise kök kategoridir. Bu liste nadiren değişir; kendi tarafınızda önbelleğe alın.
Örnek cevap — 200
{
"page": 0,
"size": 50,
"totalElements": 3911,
"totalPages": 79,
"content": [
{ "id": 118, "name": "Cilt Bakımı", "parentId": 12 }
]
}GET api/v1/brands Yetki: Referans veri
Markalar
Sistemde tanımlı marka listesi.
Örnek cevap — 200
{ "page": 0, "size": 50, "totalElements": 240, "totalPages": 5, "content": [ { "id": 31, "name": "Örnek Marka", "parentId": 0 } ] }
Sağlık
Kimlik doğrulaması istemeyen tek uç.GET api/v1/health Yetki gerekmez
Servis durumu
API'nin ve her bölümün ayakta olup olmadığını döner. Kendi izleme sisteminize bağlayabilirsiniz. Anahtar gerektirmez ve hiçbir iş verisi döndürmez.
Örnek cevap — 200
{
"status": "ok",
"timeUtc": "2026-08-18T20:14:03Z",
"groups": {
"products": true,
"orders": true,
"returns": true,
"reference": true,
"account": true,
"webhooks": true
}
}
Hata kodları
Bütün hatalar aynı zarfla döner. Kodunuzu code alanına göre yazın; message metni zamanla iyileştirilebilir.
404 her zaman "yok" demek değildir. Size ait olmayan bir kayıt da 404 döner. Bu bilinçli: "yetkiniz yok" demek, o kimlikte bir kaydın var olduğunu doğrulamak olurdu ve numara deneyerek başkalarının katalog büyüklüğü öğrenilebilirdi.
