REST API
ERP, muhasebe ve diğer harici sistemlerin mağazayla konuşması için. Tüm adresler
https://sizin-domaininiz.com/api/v1/... biçimindedir; istek ve yanıtlar JSON'dur.
Anahtar
Yönetim paneli → Yönetim → API Anahtarları → Yeni anahtar. Anahtar yalnız bir kez gösterilir; kaybederseniz yenisini üretip eskisini İptal et ile kapatın. Yalnız gereken yetkileri verin:
| Yetki | Ne sağlar |
|---|---|
products:read |
Ürün ve kategorileri okuma |
products:write |
Ürün ekleme/güncelleme, toplu stok ve fiyat |
orders:read |
Siparişleri okuma |
orders:write |
Sipariş durumu ve kargo bilgisi güncelleme |
Her istekte başlık:
Authorization: Bearer tic_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
- Geçersiz/iptal edilmiş/süresi dolmuş anahtar →
401; yetki yok →403. - Hız sınırı: anahtar başına dakikada 120 istek (aşılırsa
429,Retry-Afterbaşlığına bakın). - API ile yapılan her değişiklik panelde İşlem Kaydı'na "API · anahtar adı" olarak düşer.
Ürünler
Listeleme — GET /api/v1/products
| Parametre | Açıklama |
|---|---|
updated_since |
ISO-8601 tarih; yalnız bu andan sonra değişenler (senkron için) |
sku, barcode |
Tek ürün arama |
per_page |
Sayfa boyu (en çok 200, varsayılan 50); page ile sayfalanır |
Yanıt data (ürünler, varyantlarıyla), links, meta (toplam, sayfa) içerir. Fiyatlar KDV dahil ₺ ve
perakende fiyattır: bayi (B2B) indirimi API'ye yansımaz, yalnız giriş yapmış bayiye vitrinde uygulanır.
Siparişlerde unit_price müşterinin gerçekten ödediği fiyattır (bayi siparişinde bayi fiyatı).
Tek ürün — GET /api/v1/products/{id}
Ekleme — POST /api/v1/products (products:write)
{ "name": "Meşe Masa", "price": 1500, "stock": 3, "category_id": 4, "barcode": "8690000000001", "brand": "Atölye" }
slug verilmezse addan üretilir (aynısı varsa -2, -3 eklenir). Diğer alanlar: name_en, sku,
description, description_en, compare_at_price, cost_price, tax_rate, dimensional_weight,
is_active, is_featured. Görseller panelden yüklenir. Lisans etkin değilse (demo modu) ürün sınırı API'de de
geçerlidir (403).
Güncelleme — PATCH /api/v1/products/{id} — yalnız gönderilen alanlar değişir.
Toplu stok ve fiyat
POST /api/v1/stock (products:write) — en çok 500 kalem. Kalem barcode ya da sku ile bulunur:
önce varyantta, sonra üründe.
{ "items": [
{ "sku": "MASA-1", "stock": 12, "price": 1499.90 },
{ "barcode": "8690000000002", "stock": 0 }
] }
Yanıt kalem sırasıyla: {"results": [{"index": 0, "sku": "MASA-1", "status": "updated", "type": "product", "id": 15}, ...]}.
status: updated, not_found (bulunamadı; istek yine başarılı) ya da invalid (kimlik ya da değer eksik).
Pazar yerlerindeki stok/fiyat bir sonraki senkronda (en geç 15 dk) kendiliğinden güncellenir.
Kategoriler
GET /api/v1/categories (products:read) — tümü, parent_id ile ağaç kurulabilir.
Siparişler
Listeleme — GET /api/v1/orders (orders:read): updated_since, created_since, status
(pending, confirmed, shipped, delivered, cancelled), payment_status (unpaid, paid, failed,
refunded, partially_refunded), per_page.
Tek sipariş — GET /api/v1/orders/{sipariş no} (ör. SIP-20261024-AB12CD).
totals indirimleri ayrık verir: campaign_discount, coupon_discount, loyalty_discount ve bunların toplamı
discount_total; total = subtotal − discount_total + shipping_total + payment_fee (kapıda ödeme hizmet bedeli, yoksa 0). Pazar yeri siparişlerinde
source: "marketplace" ve marketplace alanı (hesap, pazar yeri sipariş no, durum) dolu gelir.
Güncelleme — PATCH /api/v1/orders/{sipariş no} (orders:write): yalnız status, shipping_carrier,
tracking_number. "Kargoya verildi" (shipped) müşteriye e-posta gönderir. Ödeme durumu ve tutarlar API'den
değiştirilemez (para hareketi ödeme sağlayıcısında ya da paneldeki iade akışındadır).
Hatalar
Doğrulama hatası 422: {"message": "...", "errors": {"alan": ["..."]}}. Bulunamadı 404. Tüm hatalar JSON döner.