{"openapi":"3.1.0","info":{"title":"Satisla REST API Gateway","version":"1.4.0","description":"# Satisla v1 REST API & Webhook Entegrasyon Portalı\n\nSatisla E-Ticaret Altyapısı; harici web siteleri, mobil uygulamalar, depo ve ERP sistemleri (Logo, Mikro, Nebim, Paraşüt, BizimHesap vb.), B2B yazılımları ve yapay zeka ajanları için tasarlanmış yüksek performanslı, kurumsal bir **Merkezi REST API Gateway** sunar.\n\n---\n\n## 🚀 Temel Özellikler ve Avantajlar\n\n- **Merkezi API Gateway:** Tüm mağaza entegrasyonları tek bir merkezi adres (`https://satisla.com/api/v1`) üzerinden yönetilir.\n- **Otomatik Mağaza Eşleştirme:** Gönderilen her istekte kullanılan API anahtarı (`Bearer ek_...`) sayesinde sistem isteğin hangi mağazaya ait olduğunu otomatik olarak tespit eder; mağaza ID'si göndermenize gerek kalmaz.\n- **Dış Siteden/Programdan Ürün Açma:** Resimleri, varyantları (beden/renk), SKU, barkod, liste ve indirimli fiyatları ile tek istekte eksiksiz ürün yaratımı (`POST /api/v1/products`).\n- **Gerçek Zamanlı Toplu Fiyat ve Stok Eşitleme:** Tek istekte yüzlerce varyantın stok ve fiyatını milisaniyeler içinde güncelleme (`POST /api/v1/stock`).\n- **Sipariş ve Kargo Takip Entegrasyonu:** Mağazaya düşen siparişleri çekme, kargo firması ve takip numarası girerek müşteriye otomatik kargo bildirim e-postası tetikleme (`GET/PATCH /api/v1/orders`).\n- **Çift Yönlü Pazaryeri Uyumu:** Satisla'ya API üzerinden aktardığınız tüm ürün ve stoklar, bağlı olan Trendyol, Hepsiburada ve Amazon mağazalarınıza anında otomatik olarak yansıtılır.\n\n---\n\n## 🔑 Kimlik Doğrulama (Authentication)\n\nTüm API isteklerinde **Satisla Yönetici Paneli > API Anahtarları** sayfasından oluşturduğunuz `ek_` ile başlayan gizli anahtarınızı **HTTP Authorization Header** içerisinde iletmelisiniz:\n\n```http\nAuthorization: Bearer ek_live_9b4e872c1f...\nContent-Type: application/json\n```\n\n> ⚠️ **Güvenlik Notu:** API anahtarlarınızı kesinlikle istemci tarafı (frontend / public JS) kodlarınızda paylaşmayın. Yalnızca güvenli sunucudan sunucuya (backend-to-backend) iletişim için kullanın.\n\n---\n\n## 🌐 Sunucu Adresi (Base URL)\n\n```\nhttps://satisla.com\n```\n\nTüm endpoint'ler bu sunucu adresinin altına `/api/v1/...` ön ekiyle bağlanır.\n\n---\n\n## ⚡ Hız Sınırı (Rate Limiting)\n\nAPI Gateway stabilitesini korumak için mağaza başına varsayılan hız sınırı **dakikada 120 istek**tir. Bu sınır aşıldığında sistem `429 Too Many Requests` HTTP yanıt kodu ve `Retry-After` başlığı döndürür. Toplu işlemler için tek tek istek yerine `/api/v1/stock` toplu güncelleme endpoint'ini kullanınız.\n","x-logo":{"url":"https://satisla.com/satisla-logo.png","altText":"Satisla E-Ticaret Altyapısı","href":"https://satisla.com"},"contact":{"name":"Satisla Developer Destek Ekibi","url":"https://satisla.com/entegrasyonlar","email":"destek@satisla.com"}},"servers":[{"url":"https://satisla.com","description":"Satisla Canlı Üretim Gateway (Production)"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ek_token","description":"Satisla Mağaza Yönetici Panelinden üretilen 'ek_...' formatındaki gizli API anahtarı"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"Yetkisiz erişim: Geçersiz API anahtarı"},"code":{"type":"string","example":"UNAUTHORIZED"}}},"ProductVariant":{"type":"object","properties":{"size":{"type":"string","example":"4 Yaş"},"color":{"type":"string","example":"Beyaz"},"color_hex":{"type":"string","example":"#FFFFFF"},"sku":{"type":"string","example":"KDS-MONT-01-BEYAZ-4YAS"},"barcode":{"type":"string","example":"2955827419234"},"stock":{"type":"integer","example":45},"price_diff":{"type":"number","example":0}}},"StockUpdateItem":{"type":"object","properties":{"sku":{"type":"string","example":"KDS-MONT-01-BEYAZ-4YAS"},"barcode":{"type":"string","example":"2955827419234"},"product_id":{"type":"string","example":"prod_98765"},"stock":{"type":"integer","example":60},"price":{"type":"number","example":899.9},"compare_at_price":{"type":"number","example":1199.9}}}}},"security":[{"BearerAuth":[]}],"tags":[{"name":"Ürünler (Products)","description":"Dış sistemlerden mağazaya yeni ürün açma, varyant yönetimi ve katalog sorgulama."},{"name":"Stok & Fiyat (Inventory)","description":"Depo ve ERP programlarından gerçek zamanlı anlık ve toplu stok/fiyat senkronizasyonu."},{"name":"Siparişler & Kargo (Orders & Logistics)","description":"Gelen siparişleri listeleme, fatura detaylarını çekme ve kargo takip numarası işleme."},{"name":"Webhooks (Events)","description":"Sipariş ve stok hareketlerinde kendi sunucunuza anlık tetiklenen HTTP POST bildirimleri."}],"paths":{"/api/v1/products":{"get":{"tags":["Ürünler (Products)"],"summary":"Ürün Kataloğunu Listele","description":"Mağazanızdaki ürünleri resimleri, renk/beden varyantları, SKU, barkod, fiyat ve stok bilgileriyle birlikte sayfalanmış olarak listeler.","parameters":[{"name":"page","in":"query","required":false,"description":"Sayfa numarası (varsayılan: 1)","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Sayfa başına ürün adedi (varsayılan: 50, maksimum: 100)","schema":{"type":"integer","default":50}},{"name":"active_only","in":"query","required":false,"description":"Yalnızca aktif satışta olan vitrin ürünlerini getirir","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Başarılı ürün listesi yanıtı","content":{"application/json":{"example":{"data":[{"id":"d9e8f7a6-b5c4-4d3e-8f2a-1b0c9d8e7f6a","name":"Unisex Çocuk Kapüşonlu Sweatshirt","slug":"unisex-cocuk-kapusonlu-sweatshirt","description":"100% pamuklu, birinci sınıf 3 iplik şardonlu kumaş.","price":699.9,"compare_at_price":899.9,"is_active":true,"images":[{"url":"https://erayalpkids.com.tr/uploads/sweatshirt-1.webp","is_primary":true}],"variants":[{"id":"var_1","sku":"EYR-SWT-BEYAZ-4YAS","barcode":"2955827419234","size":"4 Yaş","color":"Beyaz","color_hex":"#FFFFFF","stock":24,"price_diff":0},{"id":"var_2","sku":"EYR-SWT-BEYAZ-5YAS","barcode":"2955827419241","size":"5 Yaş","color":"Beyaz","color_hex":"#FFFFFF","stock":18,"price_diff":0}]}],"meta":{"page":1,"limit":50,"total":1,"total_pages":1}}}}},"401":{"description":"Geçersiz veya eksik API anahtarı","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Ürünler (Products)"],"summary":"Dış Siteden / ERP'den Yeni Ürün Aç","description":"Harici platformunuzdaki veya deponuzdaki bir ürünü varyantları (beden, renk), resimleri, SKU, barkod, fiyat ve açıklamasıyla birlikte tek istekte Satisla mağazanıza aktarır.","requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Kız Çocuk Fırfırlı Triko Elbise","description":"Özel dokuma pamuk-akrilik karışımlı kışlık triko elbise.","price":849.9,"compare_at_price":1099.9,"is_active":true,"images":["https://ornek-depo.com/gorseller/elbise-pembe-1.jpg","https://ornek-depo.com/gorseller/elbise-pembe-2.jpg"],"variants":[{"size":"3-4 Yaş","color":"Pudra Pembe","color_hex":"#FFD1DC","sku":"EYR-ELB-PDR-34","barcode":"2955827419800","stock":35,"price_diff":0},{"size":"5-6 Yaş","color":"Pudra Pembe","color_hex":"#FFD1DC","sku":"EYR-ELB-PDR-56","barcode":"2955827419817","stock":40,"price_diff":50}]}}}},"responses":{"201":{"description":"Ürün ve varyantları başarıyla oluşturuldu","content":{"application/json":{"example":{"ok":true,"product_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","slug":"kiz-cocuk-firfirli-triko-elbise","variants_created":2}}}},"400":{"description":"Geçersiz ürün veya varyant verisi"},"401":{"description":"Yetkisiz istek"}}}},"/api/v1/stock":{"get":{"tags":["Stok & Fiyat (Inventory)"],"summary":"Stok Seviyelerini Kontrol Et","description":"Tüm varyantların güncel stok adetlerini listeler. Kritik seviyedeki stoklar (low_stock=true) için filtre uygulanabilir.","parameters":[{"name":"low_stock","in":"query","required":false,"description":"Yalnızca 5 ve altı kritik stokta olan ürünleri filtreler","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Stok listesi yanıtı","content":{"application/json":{"example":{"data":[{"variant_id":"var_1","sku":"EYR-SWT-BEYAZ-4YAS","barcode":"2955827419234","stock":3,"product_name":"Unisex Çocuk Kapüşonlu Sweatshirt"}],"meta":{"page":1,"limit":100,"total":1}}}}}}},"post":{"tags":["Stok & Fiyat (Inventory)"],"summary":"Toplu Stok ve Fiyat Eşitleme (Bulk Stock & Price Sync)","description":"Stok programınızdan veya ERP'den tek istekte yüzlerce varyantın stok adetlerini ve fiyatlarını anında senkronize eder. Eşleşme SKU, Barkod veya Product ID üzerinden yapılır.","requestBody":{"required":true,"content":{"application/json":{"example":{"updates":[{"sku":"EYR-SWT-BEYAZ-4YAS","stock":65,"price":749.9},{"barcode":"2955827419241","stock":40},{"sku":"EYR-ELB-PDR-34","stock":50,"price":899.9,"compare_at_price":1199.9}]}}}},"responses":{"200":{"description":"Stok ve fiyatlar başarıyla güncellendi","content":{"application/json":{"example":{"ok":true,"updated_count":3,"failed_count":0}}}},"400":{"description":"Hatalı güncelleme formatı"}}}},"/api/v1/orders":{"get":{"tags":["Siparişler & Kargo (Orders & Logistics)"],"summary":"Siparişleri Listele & Filtrele","description":"Mağazanıza gelen siparişleri, müşteri bilgilerini, teslimat adreslerini ve satın alınan ürün kalemlerini listeler. Muhasebe veya depo yazılımlarına aktarım için idealdir.","parameters":[{"name":"status","in":"query","required":false,"description":"Sipariş durumu: pending, paid, processing, shipped, delivered, cancelled","schema":{"type":"string","example":"paid"}},{"name":"since","in":"query","required":false,"description":"Belirtilen ISO tarihten sonraki siparişler (ör. 2026-09-01T00:00:00Z)","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Sipariş listesi yanıtı","content":{"application/json":{"example":{"data":[{"id":"9b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e","order_number":"ORD-99124","status":"paid","total_amount":1549.8,"currency":"TRY","payment_method":"Kredi Kartı (PayTR)","customer":{"first_name":"Aytül","last_name":"Yıldız","email":"aytul@example.com","phone":"05415269371"},"shipping_address":{"title":"Ev Adresi","first_name":"Aytül","last_name":"Yıldız","phone":"05415269371","city":"Tekirdağ","district":"Çerkezköy","address_line1":"Fevzi Paşa Mah. Ersöz Sk. No:2"},"items":[{"product_id":"prod_123","name":"Çocuk Unisex Kapüşonlu Eşofman Takımı","variant":"Siyah / 9 Yaş","sku":"P4469-9YAS","quantity":1,"unit_price":959.01,"tax_rate":10}],"cargo_company":null,"cargo_tracking_number":null,"created_at":"2026-09-16T14:15:00Z"}],"meta":{"page":1,"limit":50,"total":1}}}}}}}},"/api/v1/orders/{id}":{"patch":{"tags":["Siparişler & Kargo (Orders & Logistics)"],"summary":"Kargo Takip Numarası & Sipariş Durumu Güncelle","description":"Sipariş durumunu 'shipped' (Kargoya Verildi) yapar, kargo firması ve takip numarasını sisteme kaydeder. Müşteriye otomatik takip e-postası ve SMS gönderimini tetikler.","parameters":[{"name":"id","in":"path","required":true,"description":"Sipariş UUID'si veya Sipariş Numarası (ör. ORD-99124)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"status":"shipped","cargo_company":"Yurtiçi Kargo","cargo_tracking_number":"872049674192","cargo_tracking_url":"https://selfservis.yurticikargo.com/reports/SSWIntegrationReport.aspx?code=872049674192"}}}},"responses":{"200":{"description":"Sipariş kargo bilgisi başarıyla güncellendi","content":{"application/json":{"example":{"ok":true,"id":"9b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e","order_number":"ORD-99124","status":"shipped","customer_notified":true}}}},"404":{"description":"Sipariş bulunamadı"}}}}}}