İşletme API Dokümantasyonu

İşletmeler siparişleri kendi kasa/adisyon yazılımlarından yönetebilir, menü ve ürün güncellemelerini gönderebilir, sipariş olaylarını webhook ile alabilir. Tüm istekler işletmeye özel x-api-key başlığıyla doğrulanır.

Kimlik doğrulama

Anahtar, yönetim panelindeki “Market API Anahtarları” ekranından işletme adına oluşturulur ve yalnızca o işletmenin verisine erişir. Anahtar her isteğe başlık olarak eklenir; gövdeye veya adres satırına yazılmaz.

x-api-key: ppk_1a2b3c4d5e6f...

Uç noktalar

Yöntem	Adres	Açıklama
GET	/api/isletme/menu	Menü detayı: kategoriler, ürünler, seçenekler
POST	/api/isletme/urun	Tek ürün ekleme, düzenleme, satışa açma/kapama
GET	/api/isletme/kategoriler	Kategori listesi ve ürün adetleri
POST	/api/isletme/kategoriler	Kategori ekleme, adı değiştirme, açma/kapama, sıralama
GET	/api/isletme/siparisler	Tarih aralıklı sipariş listesi ve özet (rapor)
GET	/api/isletme/siparis?no=	Tek siparişin tam detayı
POST	/api/isletme/siparis	Sipariş durumu değiştirme ve iptal bildirimi
GET	/api/isletme/durum	Mağazanın açık/kapalı durumu
POST	/api/isletme/durum	Mağazayı açma/kapama
GET	/api/isletme/teslimat	Tanımlı teslimat bölgeleri
POST	/api/isletme/teslimat	Teslimat bölgelerini ve alanı bildirme
POST	/api/isletme/test-siparis	Test siparişi oluşturma / test durumu değiştirme
GET	/api/isletme/test-siparis?no=	Test siparişi detayı

Toplu ürün aktarımı için mevcut şablon ayrı sayfada: Market API Entegrasyon Şablonu.

Sipariş durumu değiştirme

durum	Sonuç	Açıklama
kabul	preparing	Sipariş kabul edildi; hazırlık süresi başlar (hazirlik_dakika)
hazir	-	Paket hazır; kurye hemen çağrılır (siparis.hazir olayı)
yolda	on_the_way	Sipariş yola çıktı
teslim	delivered	Sipariş teslim edildi
iptal	cancelled	Sipariş iptal edildi; sebep opsiyonel (sebep)

# Durum değiştirme curl -X POST https://paketpaket.base44.app/api/isletme/siparis \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "siparis_no": "PK8K2M4Q", "durum": "kabul", "hazirlik_dakika": 20 }' # İptal (sebep müşteriye iletilir) curl -X POST https://paketpaket.base44.app/api/isletme/siparis \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "siparis_no": "PK8K2M4Q", "durum": "iptal", "sebep": "Ürün tükendi" }' # Tarih aralıklı liste ve özet curl "https://paketpaket.base44.app/api/isletme/siparisler?baslangic=2026-11-01&bitis=2026-11-09&limit=200" \ -H "x-api-key: <ANAHTARINIZ>"

Her durum değişikliğinde müşteriye bildirim gider ve işletmenin webhook adresine olay gönderilir. Online ödemeli ve ödemesi tamamlanmamış sipariş kabul edilemez; teslim edilen sipariş iptal edilemez.

Menü, ürün, kategori, teslimat ve mağaza durumu

# Ürün düzenleme (menüdeki id ile) curl -X POST https://paketpaket.base44.app/api/isletme/urun \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "id": "<urun-id>", "fiyat": 32.5, "stok": 40, "aktif": true }' # Kategori kapatma (ürünleri vitrinden kalkar) curl -X POST https://paketpaket.base44.app/api/isletme/kategoriler \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "islem": "durum", "ad": "Tatlılar", "aktif": false }' # Mağazayı kapatma / açma curl -X POST https://paketpaket.base44.app/api/isletme/durum \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "acik": false }'

Menüdeki her ürünün id değeri ürün uçlarında kullanılır; marketler ayrıca kendi ref kodunu gönderebilir.
Fiyat veya görsel değişimi ürünü yeniden yönetici onayına alır.
Kapatılan kategorinin ürünleri vitrinde görünmez, kayıtları korunur.
{ "acik": false } mağazayı kapatır: vitrinde kapalı görünür ve yeni sipariş alınmaz; { "manuel_durum": "auto" } çalışma saatlerine döndürür.
Teslimat bölgeleri ilçe adları listesi ve hizmet alanı (km²) olarak bildirilir.

Sipariş webhook'u

Webhook adresi işletme panelindeki “API ve Webhook” ekranından tanımlanır. Adres https olmalıdır. Gönderim 8 saniye içinde yanıtlanmazsa başarısız sayılır; sipariş akışı bundan etkilenmez, son gönderim sonucu panelde görünür.

Olay	Ne zaman gönderilir
siparis.yeni	Yeni sipariş oluştu
siparis.durum	Durum değişti: kabul, yolda, teslim
siparis.hazir	Sipariş hazır olarak işaretlendi
siparis.iptal	Sipariş iptal edildi (sebep dahil)
siparis.kurye	Siparişe kurye atandı

POST https://kasa.sirketim.com/paketpaket/siparis Content-Type: application/json x-pp-event: siparis.yeni x-pp-signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 x-pp-delivery: 4f1c1a1e-8f0e-4a3f-9a1f-2c5a1e6b7d10 { "olay": "siparis.yeni", "gonderim_zamani": "2026-11-09T20:41:12.000Z", "veri": { "siparis_no": "PK8K2M4Q", "durum": "pending", "durum_etiketi": "Bekliyor", "olusturma": "2026-11-09T20:41:10.000Z", "musteri": { "ad": "Ayşe Yılmaz", "telefon": "05551112233" }, "adres": "Caferağa Mah. Moda Cad. No: 12 D:3, Kadıköy", "konum": { "enlem": 40.9876, "boylam": 29.0254 }, "tutar": 245.5, "teslimat_ucreti": 15, "odeme": { "yontem": "cash", "durum": "pending" }, "not": "Kapı zilini çalmayın", "kalemler": [ { "urun_kodu": "STK-88123", "ad": "Karışık Pizza", "adet": 1, "birim_fiyat": 230.5, "toplam": 230.5, "secenekler": [{ "grup": "Hamur", "ad": "İnce Hamur", "fiyat_farki": 0 }] } ], "test": false } }

x-pp-signature, gövdenin imza anahtarıyla hesaplanmış HMAC-SHA256 özetidir (hex). Doğrulama örneği:

// Node.js / benzeri ortam const crypto = require("crypto"); // body: ham istek gövdesi (JSON.parse ETMEDEN), secret: panelde ürettiğiniz anahtar const beklenen = crypto .createHmac("sha256", secret) .update(body) .digest("hex"); if (beklenen !== req.headers["x-pp-signature"]) { return res.status(401).end(); // imza uyuşmuyor } const { olay, veri } = JSON.parse(body);

Test ortamı

Test siparişleri canlı sipariş tablosuna hiç yazılmaz: kendi kayıtlarında tutulur, raporlara, kurye akışına ve müşteri bildirimlerine karışmaz. Böylece entegrasyon denemeleri canlı operasyonu etkilemez. Test sipariş numaraları TEST- önekiyle üretilir.

# 1) Test siparişi oluştur (canlı siparişlere karışmaz) curl -X POST https://paketpaket.base44.app/api/isletme/test-siparis \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "musteri_adi": "Test Müşteri", "teslimat_ucreti": 15 }' # Yanıt: { "siparis": { "siparis_no": "TEST-8QK2M4", ... }, "webhook": { "sent": true, "status": 200 } } # 2) Test siparişini kabul et / iptal et curl -X POST https://paketpaket.base44.app/api/isletme/test-siparis \ -H "Content-Type: application/json" \ -H "x-api-key: <ANAHTARINIZ>" \ -d '{ "siparis_no": "TEST-8QK2M4", "durum": "kabul" }'

Test siparişi oluşturulduğunda webhook adresinize gerçek olayla aynı yapıda bir gönderim yapılır ve yanıt kodu döner; adresiniz çalışmıyorsa bunu anında görürsünüz.

Hata yanıtları

200 / 201 işlem alındı
400 şablon veya alan hatası — hata alanında açıklama
401 geçersiz veya pasif x-api-key
404 anahtara bağlı işletme ya da kayıt bulunamadı
409 sipariş bu durumdan istenen duruma geçemiyor