Başlarken

Önce deneme ortamında deneyin: ayrı hesap ve spk_test_ anahtarıyla gerçek sipariş ve ödeme oluşturmadan bağlantınızı kurabilirsiniz.

API sipariş, müşteri, ürün, stok, kategori, ürün markası ve kupon bilgilerini okur ve yazar; kargo, iade ve fatura işlemlerini, dış satış bildirimini ve toplu güncellemeyi destekler. Değişiklikleri olay akışı ve webhook ile haber verir. Önce API ile neler yapabilirim? tablosunda yapmak istediğiniz işi bulun.

API temel adresi https://api.siparis.app/v1; belge adresi https://developer.siparis.app. İstekleri kendi sunucunuzdan gönderin.

1. Anahtar oluşturun

İşletme sahibi hesabıyla İşletme › Entegrasyonlar › Geliştirici sayfasını açın. “Anahtar oluştur”a basın; bağlantınıza (anahtarı ve izinlerini tutan kayıt; anahtarı yenileseniz de aynı kalır) bir ad verin, erişilecek markayı ve ilk deneme için orders:read, events:read kapsamlarını seçin. Kapsam, anahtarın hangi bilgilere erişebildiğini belirleyen izindir. Bir kez gösterilen anahtarı sunucunuzda SIPARIS_API_KEY ortam değişkenine kaydedin.

Anahtar yalnız Authorization: Bearer başlığıyla gönderilir; panel oturumu veya çerez API kimliği değildir. Anahtarı tarayıcı koduna, URL’ye, kayıtlara veya AI sohbetine koymayın; AI’a anahtar yerine ortam değişkeninin adını verin. CORS ile tarayıcıdan doğrudan erişim açılmaz.

2. İlk istek: /v1/me

Bu blok SIPARIS_API_KEY tanımlıysa kopyalanıp çalışır. Yerel denemede yalnız SIPARIS_API_URL=http://127.0.0.1:PORT/v1 değişkenini ayarlayın; örnek komut aynı kalır.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/me" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

Yanıtta scopes etkin kapsamları, stores erişilebilen markaları, environment ortamı, api_version sürümü ve api_url bu ortamın API adresini gösterir; anahtar yanıtta bulunmaz. 401 invalid_api_key alırsanız ortam değişkenini ve panelde bağlantının açık olduğunu kontrol edin.

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "api_url": "https://api.siparis.app/v1",
  "api_version": "v1",
  "environment": "live",
  "id": "grt_1234567890abcdef1234567890abcdef",
  "scopes": [
    "orders:read",
    "events:read"
  ],
  "stores": [
    {
      "id": "sto_1234567890abcdef1234567890abcdef",
      "name": "Örnek Marka"
    }
  ]
}

3. İlk sipariş listesini alın

Aşağıdaki istek en fazla 2 sipariş getirir; data=[] başarılı ama henüz görünür sipariş olmadığını, 403 insufficient_scope ise orders:read kapsamının eksik olduğunu gösterir.

curl --fail-with-body --silent --show-error --get \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'limit=2'

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "data": [
    {
      "channel": "whatsapp",
      "created_at": "2026-10-16T09:00:00Z",
      "currency": "TRY",
      "customer": null,
      "delivery_day": "2026-10-17",
      "delivery_method": "shipping",
      "discount_total": "0.00",
      "gift_wrap_fee": "0.00",
      "id": "ord_1234567890abcdef1234567890abcdef",
      "number": "48273910",
      "payment_fee": "0.00",
      "payment_method": "bank_transfer",
      "payment_state": "paid",
      "preorder_from": null,
      "shipping_total": "0.00",
      "source": "panel",
      "status": "confirmed",
      "store": "sto_1234567890abcdef1234567890abcdef",
      "subtotal": "120.00",
      "tax_status": "standard",
      "tax_total": "20.00",
      "total": "120.00",
      "updated_at": "2026-10-16T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

has_more=true ise yanıttaki next_cursor (sonraki sayfanın yer imi) değerini aynı süzgeçlerle cursor parametresinde gönderin. Para alanları ("120.00") ve miktarlar metindir; ondalık sayı kütüphanesi kullanın. Kimlikleri (ord_…) aynen saklayın. Kişisel veri kapsamı verilmediğinde müşteri adı, telefon ve adres gibi alanlar yanıtta yer almaz.

Bağlantı çalışınca Siparişleri listelemek veya Müşterileri bulmak rehberiyle devam edin. Sürekli aktarım için Siparişleri ERP’ye almak, Stoku eşitlemek ve İlk eşitleme rehberleri var. Liste uçları değişen verinin kayıpsız ilk aktarımını garanti etmez; bunun için tutarlı dışa aktarmayı (İlk eşitleme) kullanın.