Resmi geliştirici merkezi

DZN Soft Developers

DZN Soft altyapısıyla entegre uygulamalar geliştirin.

Kargo, ERP, muhasebe, CRM, pazarlama ve pazaryeri uygulamanızı binlerce mağazanın kullandığı panele bağlayın; App Store üzerinden tek tıkla kurulsun.

Dokümantasyonu İncele Developer Hesabı Oluştur

API adresihttps://api.dznsoft.com/v1

GET /v1/orders

curl https://api.dznsoft.com/v1/orders?status=new \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN"

{
  "data": [
    {
      "id": 5521,
      "number": "DZN-20260925-5521",
      "status": "new",
      "grand_total": 749.7
    }
  ],
  "meta": { "page": 1, "total": 1 }
}

OAuth 2.0
Mağaza sahibinin açık onayıyla, scope bazlı erişim.
REST API
Ürün, sipariş, müşteri ve stok uç noktaları.
Webhooks
HMAC-SHA256 imzalı, anlık olay bildirimleri.
Güvenli yalıtım
Kodunuz kendi sunucunuzda; her mağaza ayrı.

Başlangıç

DZN Soft Developers, mağazalara kargo, ERP, muhasebe, CRM, WhatsApp/SMS, pazaryeri, SEO, analiz ve fatura gibi yetenekler ekleyen üçüncü taraf uygulamalar için resmi geliştirici merkezidir.

Uygulamanız DZN Soft sunucularında çalışmaz. Kendi sunucunuzda durur ve mağazayla yalnızca dört kontrollü kanaldan konuşur: OAuth 2.0, REST API, Webhook ve kontrollü UI Extension. Veritabanına, sunucu dosyalarına ya da başka mağazaların verisine erişim yoktur.

1
Developer hesabı açın
Portalda hesabınızı oluşturun ve iki adımlı doğrulamayı açın.
2
Uygulama oluşturun
Client ID ve Client Secret otomatik üretilir; ihtiyaç duyduğunuz scope'ları seçin.
3
Test mağazasında deneyin
Demo verili sandbox mağazaya uygulamanızı kurup erişim anahtarı alın.
4
İncelemeye gönderin
DZN Soft ekibi güvenlik ve kaliteyi inceler; onaylanan uygulama App Store'da yayınlanır.

Developer Hesabı Oluşturma

Hesap açmak için developer kayıt sayfasını kullanın. Developer hesabı, mağaza (müşteri) hesabınızdan tamamen ayrıdır; aynı e-postayla ikisini birden açabilirsiniz.

Parola en az 10 karakter olmalı, harf ve rakam içermelidir.
Ayarlar › İki adımlı doğrulama ekranından Google Authenticator, Microsoft Authenticator ya da 1Password ile 2FA açın. Kurtarma kodlarınızı güvenli bir yerde saklayın.
Portal: Dashboard, Applications, API Credentials, Webhooks, Test Stores, API Logs, Documentation ve Settings alanlarından oluşur.

Uygulama Oluşturma

Portalda Uygulamalar › Yeni uygulama ile ad, kategori (Kargo, ERP, Muhasebe, CRM, Pazarlama, SEO, Yapay Zeka, Stok, Pazaryeri, Müşteri Hizmetleri), açıklama, simge ve adresleri girin.

Alan	Açıklama
`redirect_uri`	Yetki kodunun gönderileceği adres. https zorunlu (yerel test için http://localhost). Birebir eşleşme aranır.
`app_url`	Mağaza sahibi App Store'da "Kur" ya da panelde "Aç" dediğinde yönlendirilen adres. ?store_id= parametresi eklenir.
`scopes`	Uygulamanın istediği izinler ve her birinin gerekçesi (izin ekranında gösterilir).
`privacy_url`	Gizlilik politikası; incelemeye göndermek için zorunlu.

Client Secret bir kez gösterilir

Uygulama oluşturulduğunda Client Secret yalnızca bir kez görüntülenir; DZN Soft onu yalnızca özet (hash) olarak saklar. Kaybederseniz API Credentials ekranından yenileyin.

API Kullanımı

Tüm istekler https://api.dznsoft.com/v1 altına, HTTPS üzerinden, JSON olarak yapılır. Her istek bir mağazaya (tenant) bağlı erişim anahtarıyla doğrulanır; hangi mağazanın verisine dokunulacağını anahtar belirler, istekteki hiçbir parametre bunu değiştiremez.

Konu	Kural
Biçim	İstek ve yanıt gövdesi `application/json`; tarihler ISO 8601.
Sayfalama	`page`, `per_page` (1–100). Yanıtta `meta.total`, `meta.last_page`.
Eşitleme	Artımlı çekim için `updated_since` kullanın; tam listeyi tekrar tekrar çekmeyin.
Hata biçimi	`{"error": {"code": "...", "message": "..."}}`
Para birimi	Tutarlar mağazanın ana para biriminde (TRY), ondalık sayı olarak.

Authentication

API istekleri Authorization: Bearer <access_token> başlığıyla doğrulanır. Erişim anahtarları dzn_at_ ile başlar, 1 saat geçerlidir ve yalnızca OAuth akışıyla (ya da test mağazanızda portaldan) alınır.

Her istekte sırasıyla şu kontroller yapılır:

Kontrol	Başarısızlıkta
HTTPS	403 https_required
Authentication — anahtar geçerli, süresi dolmamış, iptal edilmemiş	401 invalid_token / token_expired
Application — uygulama onaylı ve askıda değil	403 app_disabled
Store / Tenant — uygulama bu mağazada kurulu	403 app_not_installed
Scope — izin hem anahtarda hem mağaza sahibinin güncel onayında	403 insufficient_scope
Rate limit — dakikalık ve günlük sınır	429 rate_limited
Authorization — kayıt anahtarın mağazasına ait	404 not_found

OAuth 2.0

Uygulamalar mağazalara OAuth 2.0 yetkilendirme kodu (authorization code) akışıyla bağlanır. PKCE (S256) desteklenir ve önerilir.

1
Mağaza sahibini izin ekranına yönlendirin
state değerini oturumda saklayın; geri dönüşte karşılaştırın (CSRF koruması).
2
Mağaza sahibi izinleri görür ve onaylar
İzin ekranında istenen her scope açıklamasıyla listelenir. Onayla uygulama kurulur.
3
Kodu anahtarla değiştirin
Kod tek kullanımlıktır ve 10 dakika geçerlidir. İstek sunucudan sunucuya yapılmalıdır.

1. Yetkilendirme adresi

https://panel.dznsoft.com/oauth/authorize
  ?client_id=dzn_ci_xxxxxxxxxxxxxxxxxxxxxxxx
  &redirect_uri=https://uygulamaniz.com/oauth/callback
  &scope=products.read orders.read
  &state=RASTGELE_TEK_KULLANIMLIK_DEGER
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

2. Geri dönüş

https://uygulamaniz.com/oauth/callback?code=AbC123...&state=RASTGELE_TEK_KULLANIMLIK_DEGER&store_id=812

3. Token isteği — POST https://api.dznsoft.com/oauth/token

curl -X POST "https://api.dznsoft.com/oauth/token" \
  -u "$DZN_CLIENT_ID:$DZN_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://uygulamaniz.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"

Yanıt

{
  "token_type": "Bearer",
  "access_token": "dzn_at_…",
  "expires_in": 3600,
  "refresh_token": "dzn_rt_…",
  "scope": "products.read orders.read",
  "store_id": 812
}

Yenileme: Erişim anahtarının süresi dolunca grant_type=refresh_token ile yenileyin. Yenileme anahtarı tek kullanımlıktır (rotation): her yenilemede yeni bir çift gelir. Kullanılmış bir yenileme anahtarı tekrar gönderilirse bu sızıntı sayılır ve aynı yetkilendirmeden türeyen tüm anahtarlar iptal edilir.

Anahtar yenileme

curl -X POST "https://api.dznsoft.com/oauth/token" \
  -u "$DZN_CLIENT_ID:$DZN_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$DZN_REFRESH_TOKEN"

İptal: POST https://api.dznsoft.com/oauth/revoke gövdesinde token ile erişim ya da yenileme anahtarını iptal edin (RFC 7009).

API Keys

Anahtar	Biçim	Ömür	Nerede saklanır
Client ID	`dzn_ci_…`	Kalıcı	Gizli değildir; yetkilendirme adresinde görünür.
Client Secret	`dzn_cs_…`	Yenilenene kadar	Yalnızca sunucunuzda; asla tarayıcı veya mobil uygulamada değil.
Access token	`dzn_at_…`	1 saat	Mağaza (store_id) bazında, şifreli.
Refresh token	`dzn_rt_…`	60 gün, tek kullanımlık	Mağaza bazında, şifreli.
Webhook secret	`whsec_…`	Yenilenene kadar	İmza doğrulaması için sunucunuzda.

Token rotation: API Credentials ekranından Client Secret'ı yenilediğinizde eski anahtar 24 saat daha kabul edilir; bu sürede sunucunuzu güncelleyin. Sızıntıdan şüpheleniyorsanız hemen yenileyin ve destek ekibine bildirin.

Permissions / Scopes

Uygulama yalnızca ihtiyaç duyduğu izinleri istemelidir. write izni aynı kaynağın read iznini kapsamaz; ikisine de ihtiyacınız varsa ikisini de isteyin.

Scope	Mağaza sahibinin gördüğü	Kapsam
`products.read`	Ürünleri görüntüleme	Ürün adı, fiyatı, stok kodu, görselleri ve kategori bilgisi.
`products.write`	Ürün oluşturma ve düzenleme	Yeni ürün ekleme, ürün bilgisi ve fiyat güncelleme.
`orders.read`	Siparişleri görüntüleme	Sipariş kalemleri, tutarlar, teslimat adresi, alıcı iletişim bilgisi. Kart bilgisi asla paylaşılmaz.
`orders.write`	Sipariş durumunu güncelleme	Sipariş durumu, kargo firması ve takip numarası.
`customers.read`	Müşterileri görüntüleme	Üye adı, e-posta, telefon ve adres bilgisi.
`inventory.read`	Stokları görüntüleme	Ürün ve beden bazında stok adetleri.
`inventory.write`	Stok güncelleme	Stok adedini artırma, azaltma ya da doğrudan belirleme.

Yeni scope = yeniden izin

Yayındaki uygulamanıza yeni bir scope eklerseniz mevcut mağazalarda bu izin otomatik verilmez. Mağaza sahibi "Yüklü Uygulamalar" ekranında "Yeni izin istiyor" uyarısını görür; OAuth akışını yeniden başlatıp onay aldığınızda yeni anahtar yeni izni taşır. GET /shop yanıtındaki pending_scopes onay bekleyen izinleri gösterir.

Products API

Mağazanın ürün kataloğunu okuyun, yeni ürün ekleyin ve mevcut ürünleri güncelleyin. Yanıttaki alanlar sabit bir izin listesidir; mağazaya özel iç alanlar dışarı verilmez.

Ürünleri listele

GEThttps://api.dznsoft.com/v1/products

Ürünleri kimlik sırasıyla, sayfalı döndürür.

Gerekli scope: products.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
page	query	integer	Sayfa numarası (varsayılan 1).
per_page	query	integer	Sayfa başına kayıt, 1–100 (varsayılan 25).
sku	query	string	Stok koduyla tam eşleşme.
q	query	string	Ürün adında arama.
is_active	query	boolean	Yalnızca yayındaki (true) ya da pasif (false) ürünler.
updated_since	query	ISO 8601	Bu tarihten sonra değişen ürünler (eşitleme için).

Request Example

curl -X GET "https://api.dznsoft.com/v1/products" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": [
    {
      "id": 1042,
      "name": "Pamuklu Basic Tişört",
      "slug": "pamuklu-basic-tisort",
      "sku": "TS-001",
      "barcode": "8690000000012",
      "brand": "DZN",
      "category_id": 12,
      "description": "Yumuşak dokulu, %100 pamuk tişört.",
      "price": 349.9,
      "compare_at_price": 449.9,
      "vat_rate": 20,
      "is_active": true,
      "images": [
        "https://panel.dznsoft.com/storage/store/ts-001.webp"
      ],
      "inventory": {
        "product_id": 1042,
        "sku": "TS-001",
        "track_stock": true,
        "stock": 58,
        "in_stock": true,
        "variants": [
          {
            "label": "M",
            "stock": 20
          },
          {
            "label": "L",
            "stock": 38
          }
        ]
      },
      "created_at": "2026-09-20T10:15:00+03:00",
      "updated_at": "2026-09-25T08:40:00+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.

Ürün getir

GEThttps://api.dznsoft.com/v1/products/{id}

Tek bir ürünün ayrıntısı. Başka mağazanın ürün kimliği gönderilirse 404 döner.

Gerekli scope: products.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
idzorunlu	path	integer	Ürün kimliği.

Request Example

curl -X GET "https://api.dznsoft.com/v1/products/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": {
    "id": 1042,
    "name": "Pamuklu Basic Tişört",
    "slug": "pamuklu-basic-tisort",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Yumuşak dokulu, %100 pamuk tişört.",
    "price": 349.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Ürün bu mağazada yok.

Ürün oluştur

POSThttps://api.dznsoft.com/v1/products

Yeni ürün ekler. Ürün varsayılan olarak pasif oluşur; is_active: true gönderirseniz hemen yayına girer.

Gerekli scope: products.write
Başarılı yanıt: 201

Parameters

Ad	Konum	Tür	Açıklama
namezorunlu	body	string	Ürün adı (en fazla 255).
pricezorunlu	body	number	Satış fiyatı (TL).
sku	body	string	Stok kodu; mağaza içinde benzersiz.
compare_at_price	body	number	İndirim öncesi (üstü çizili) fiyat.
stock	body	integer	Başlangıç stoğu.
category_id	body	integer	Aynı mağazaya ait kategori.
vat_rate	body	integer	KDV oranı: 0, 1, 8, 10, 18, 20.
is_active	body	boolean	Yayında mı.

Request Example

curl -X POST "https://api.dznsoft.com/v1/products" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pamuklu Basic Tişört","sku":"TS-001","price":349.9,"stock":58,"vat_rate":20,"is_active":true}'

Response Example

HTTP 201

{
  "data": {
    "id": 1042,
    "name": "Pamuklu Basic Tişört",
    "slug": "pamuklu-basic-tisort",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Yumuşak dokulu, %100 pamuk tişört.",
    "price": 349.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
422	validation_failed	Alan hatası; ayrıntı fields içinde.

Ürün güncelle

PATCHhttps://api.dznsoft.com/v1/products/{id}

Yalnızca gönderdiğiniz alanlar değişir. Fiyat ve içerik değişikliği product.updated webhook'unu tetikler.

Gerekli scope: products.write
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
idzorunlu	path	integer	Ürün kimliği.
price	body	number	Yeni fiyat.
compare_at_price	body	number	Üstü çizili fiyat.
is_active	body	boolean	Yayın durumu.

Request Example

curl -X PATCH "https://api.dznsoft.com/v1/products/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"price":329.9,"compare_at_price":449.9}'

Response Example

HTTP 200

{
  "data": {
    "id": 1042,
    "name": "Pamuklu Basic Tişört",
    "slug": "pamuklu-basic-tisort",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Yumuşak dokulu, %100 pamuk tişört.",
    "price": 329.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Ürün bu mağazada yok.
422	validation_failed	Alan hatası.

Orders API

Siparişleri okuyun ve operasyon alanlarını (durum, kargo firması, takip numarası) güncelleyin. Tutarlar, ödeme durumu ve alıcı bilgisi API ile değiştirilemez. Kart numarası ve CVV sistemde saklanmaz, hiçbir yanıtta yer almaz.

Siparişleri listele

GEThttps://api.dznsoft.com/v1/orders

En yeni sipariş önce gelecek şekilde sayfalı döndürür.

Gerekli scope: orders.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
page	query	integer	Sayfa numarası (varsayılan 1).
per_page	query	integer	Sayfa başına kayıt, 1–100 (varsayılan 25).
status	query	string	new, processing, shipped, completed, cancelled.
payment_status	query	string	pending, paid, refunded…
created_since	query	ISO 8601	Bu tarihten sonra oluşturulanlar.
updated_since	query	ISO 8601	Bu tarihten sonra değişenler.

Request Example

curl -X GET "https://api.dznsoft.com/v1/orders" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": [
    {
      "id": 5521,
      "number": "DZN-20260925-5521",
      "status": "processing",
      "payment_status": "paid",
      "payment_method": "Kredi kartı",
      "currency": "TRY",
      "subtotal": 699.8,
      "discount_total": 0,
      "shipping_total": 49.9,
      "grand_total": 749.7,
      "customer_id": 311,
      "customer": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com",
        "phone": "0555 000 00 00"
      },
      "shipping_address": {
        "address": "Örnek Mah. Deneme Sok. No:4",
        "city": "İstanbul",
        "district": "Kadıköy"
      },
      "lines": [
        {
          "product_id": 1042,
          "name": "Pamuklu Basic Tişört",
          "sku": "TS-001",
          "quantity": 2,
          "price": 349.9,
          "variants": [
            "Beden: M"
          ]
        }
      ],
      "carrier": null,
      "tracking_number": null,
      "created_at": "2026-09-25T09:12:44+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.

Sipariş getir

GEThttps://api.dznsoft.com/v1/orders/{id}

Tek bir siparişin ayrıntısı.

Gerekli scope: orders.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
idzorunlu	path	integer	Sipariş kimliği.

Request Example

curl -X GET "https://api.dznsoft.com/v1/orders/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "processing",
    "payment_status": "paid",
    "payment_method": "Kredi kartı",
    "currency": "TRY",
    "subtotal": 699.8,
    "discount_total": 0,
    "shipping_total": 49.9,
    "grand_total": 749.7,
    "customer_id": 311,
    "customer": {
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com",
      "phone": "0555 000 00 00"
    },
    "shipping_address": {
      "address": "Örnek Mah. Deneme Sok. No:4",
      "city": "İstanbul",
      "district": "Kadıköy"
    },
    "lines": [
      {
        "product_id": 1042,
        "name": "Pamuklu Basic Tişört",
        "sku": "TS-001",
        "quantity": 2,
        "price": 349.9,
        "variants": [
          "Beden: M"
        ]
      }
    ],
    "carrier": null,
    "tracking_number": null,
    "created_at": "2026-09-25T09:12:44+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Sipariş bu mağazada yok.

Sipariş durumunu güncelle

PATCHhttps://api.dznsoft.com/v1/orders/{id}

Kargo uygulamaları gönderi oluşturunca takip bilgisini buradan yazar. shipped durumuna geçen siparişte alıcıya kargo e-postası gider.

Gerekli scope: orders.write
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
idzorunlu	path	integer	Sipariş kimliği.
status	body	string	new, processing, shipped, completed, cancelled.
carrier	body	string	Kargo firması adı.
tracking_number	body	string	Takip numarası.
tracking_url	body	https URL	Takip sayfası adresi.

Request Example

curl -X PATCH "https://api.dznsoft.com/v1/orders/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"shipped","carrier":"Yurtiçi Kargo","tracking_number":"YK123456789","tracking_url":"https://kargo.example.com/YK123456789"}'

Response Example

HTTP 200

{
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "shipped",
    "payment_status": "paid",
    "payment_method": "Kredi kartı",
    "currency": "TRY",
    "subtotal": 699.8,
    "discount_total": 0,
    "shipping_total": 49.9,
    "grand_total": 749.7,
    "customer_id": 311,
    "customer": {
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com",
      "phone": "0555 000 00 00"
    },
    "shipping_address": {
      "address": "Örnek Mah. Deneme Sok. No:4",
      "city": "İstanbul",
      "district": "Kadıköy"
    },
    "lines": [
      {
        "product_id": 1042,
        "name": "Pamuklu Basic Tişört",
        "sku": "TS-001",
        "quantity": 2,
        "price": 349.9,
        "variants": [
          "Beden: M"
        ]
      }
    ],
    "carrier": "Yurtiçi Kargo",
    "tracking_number": "YK123456789",
    "created_at": "2026-09-25T09:12:44+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Sipariş bu mağazada yok.
422	validation_failed	Geçersiz durum ya da adres.

Customers API

Mağazaya üye olmuş müşterileri okuyun. Parola, oturum ve sosyal giriş kimlikleri hiçbir yanıtta bulunmaz.

Müşterileri listele

GEThttps://api.dznsoft.com/v1/customers

Üyeleri kayıt sırasıyla sayfalı döndürür.

Gerekli scope: customers.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
page	query	integer	Sayfa numarası (varsayılan 1).
per_page	query	integer	Sayfa başına kayıt, 1–100 (varsayılan 25).
email	query	string	E-posta ile tam eşleşme.
created_since	query	ISO 8601	Bu tarihten sonra kaydolanlar.

Request Example

curl -X GET "https://api.dznsoft.com/v1/customers" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": [
    {
      "id": 311,
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com",
      "phone": "0555 000 00 00",
      "address": "Örnek Mah. Deneme Sok. No:4",
      "city": "İstanbul",
      "district": "Kadıköy",
      "accepts_marketing": true,
      "is_active": true,
      "created_at": "2026-08-02T14:01:10+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.

Müşteri getir

GEThttps://api.dznsoft.com/v1/customers/{id}

Tek bir üyenin ayrıntısı.

Gerekli scope: customers.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
idzorunlu	path	integer	Müşteri kimliği.

Request Example

curl -X GET "https://api.dznsoft.com/v1/customers/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": {
    "id": 311,
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "0555 000 00 00",
    "address": "Örnek Mah. Deneme Sok. No:4",
    "city": "İstanbul",
    "district": "Kadıköy",
    "accepts_marketing": true,
    "is_active": true,
    "created_at": "2026-08-02T14:01:10+03:00"
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Müşteri bu mağazada yok.

Inventory API

Stok adetlerini okuyun ve güncelleyin. Bedene göre stok izlenen ürünlerde işlem beden (variant) bazında yapılır. Güncelleme satır kilidiyle yapılır; aynı anda gelen iki düzeltme birbirini ezmez.

Stokları listele

GEThttps://api.dznsoft.com/v1/inventory

Her ürün için toplam stok ve beden kırılımı.

Gerekli scope: inventory.read
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
page	query	integer	Sayfa numarası (varsayılan 1).
per_page	query	integer	Sayfa başına kayıt, 1–100 (varsayılan 25).
sku	query	string	Stok koduyla tam eşleşme.
low_stock	query	boolean	Yalnızca kritik stok eşiğinin altındakiler.

Request Example

curl -X GET "https://api.dznsoft.com/v1/inventory" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200

{
  "data": [
    {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.

Stok ayarla

POSThttps://api.dznsoft.com/v1/inventory/adjust

adjust göreli değişimdir (+5, −2); set mutlak değerdir. Stok sıfırın altına düşmez. Değişiklik inventory.updated webhook'unu tetikler.

Gerekli scope: inventory.write
Başarılı yanıt: 200

Parameters

Ad	Konum	Tür	Açıklama
product_id	body	integer	Ürün kimliği (ya da sku).
sku	body	string	Stok kodu (ya da product_id).
variant	body	string	Beden adı; bedene göre stok izlenen üründe zorunlu.
adjust	body	integer	Göreli değişim (set ile birlikte gönderilmez).
set	body	integer	Mutlak stok değeri.
reason	body	string	Denetim kaydına yazılan açıklama.

Request Example

curl -X POST "https://api.dznsoft.com/v1/inventory/adjust" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"sku":"TS-001","variant":"M","adjust":-2,"reason":"ERP senkronu"}'

Response Example

HTTP 200

{
  "data": {
    "product_id": 1042,
    "sku": "TS-001",
    "track_stock": true,
    "stock": 56,
    "in_stock": true,
    "variants": [
      {
        "label": "M",
        "stock": 18
      },
      {
        "label": "L",
        "stock": 38
      }
    ]
  }
}

Error Codes

HTTP	Kod	Açıklama
401	invalid_token	Anahtar yok, geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi dolmuş; refresh_token ile yenileyin.
403	insufficient_scope	Anahtarda ya da mağaza sahibinin onayında gerekli izin yok.
429	rate_limited	Dakikalık istek sınırı aşıldı.
404	not_found	Ürün bu mağazada yok.
404	variant_not_found	Beden bulunamadı.
422	variant_required	Ürünün stoğu bedene göre izleniyor.

Webhooks

Mağazada olay gerçekleştiğinde abone olduğunuz adrese imzalı bir POST isteği gönderilir. Webhook'lar kuyruktan gönderilir; 2xx dönmeyen istekler artan aralıklarla (1 dk, 5 dk, 30 dk, 2 sa, 6 sa) toplam 6 kez denenir.

Olay	Gerekli scope	Ne zaman
`order.created`	orders.read	Yeni sipariş oluştu (vitrin, panel ya da pazaryeri).
`order.paid`	orders.read	Siparişin ödemesi doğrulandı.
`order.cancelled`	orders.read	Sipariş iptal edildi.
`product.created`	products.read	Yeni ürün eklendi.
`product.updated`	products.read	Ürün bilgisi ya da fiyatı değişti.
`customer.created`	customers.read	Mağazaya yeni üye kaydoldu.
`inventory.updated`	inventory.read	Ürün ya da beden stoğu değişti.
`app.uninstalled`	—	Mağaza sahibi uygulamayı kaldırdı; anahtarlar iptal edildi.

Olayı alabilmek için uygulamanın o olayın scope'una mağazada sahip olması gerekir.

İstek başlıkları

POST /webhooks/dznsoft HTTP/1.1
Content-Type: application/json
User-Agent: DZNSoft-Webhooks/1.0
X-DZN-Event: order.created
X-DZN-Delivery: 7f2c1d7e-2a8b-4a55-9d0e-2f1d3c4b5a69
X-DZN-Store-Id: 812
X-DZN-Timestamp: 1790409600
X-DZN-Signature: t=1790409600,v1=5f8a…c21e

Gövde

{
  "id": "7f2c1d7e-2a8b-4a55-9d0e-2f1d3c4b5a69",
  "event": "order.created",
  "created_at": "2026-09-25T09:12:45+03:00",
  "store_id": 812,
  "sandbox": false,
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "new",
    "grand_total": 749.7
  }
}

İmza doğrulama (HMAC-SHA256)

v1 = HMAC_SHA256(webhook_secret, "<t>.<ham gövde>"). Karşılaştırmayı sabit zamanlı yapın ve 5 dakikadan eski zaman damgalarını reddedin.

import crypto from "node:crypto";

// Gövdeyi ham (raw) metin olarak alın; JSON.parse sonrası imza tutmaz.
export function verifyDznWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);

  // 5 dakikadan eski istekleri reddedin (tekrar oynatma koruması).
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Adres kuralları

Webhook adresi herkese açık bir HTTPS adresi olmalıdır (443 ya da 8443). localhost, özel ağ (10.x, 192.168.x, 172.16–31.x), bulut metadata (169.254.x) ve yönlendirme yapan adresler reddedilir. Aynı X-DZN-Delivery iki kez gelebilir; işleminizi idempotent yapın.

App Installation

1
Mağaza sahibi App Store'da "Uygulamayı kur" der
Panel, sahibi uygulamanızın app_url adresine ?store_id=812&source=dznsoft_app_store ile gönderir.
2
Uygulamanız OAuth akışını başlatır
Kendi state değerinizle https://panel.dznsoft.com/oauth/authorize adresine yönlendirin (store_id iletilirse o mağaza seçili gelir).
3
Sahip izinleri onaylar, kurulum tamamlanır
Kod gelir, anahtarla değiştirirsiniz. Mağaza "Yüklü Uygulamalar" ekranında uygulamanızı görür.
4
Kaldırma
Sahip uygulamayı kaldırdığında anahtarlar anında iptal edilir ve app.uninstalled webhook'u gönderilir. Bu mağazaya ait verileri silin.

App Store Kuralları

Uygulamanız doğrudan yayınlanamaz. Durumlar:

Durum	Anlamı
`draft`	Taslak; yalnızca kendi test mağazalarınızda çalışır.
`submitted`	İncelemeye gönderildi.
`review`	DZN Soft ekibi inceliyor.
`approved`	Onaylandı; App Store'da yayında.
`rejected`	Reddedildi; inceleme notunu düzeltip yeniden gönderin.
`suspended`	Askıya alındı; API erişimi, anahtarlar ve webhook'lar kapalı.

Yalnızca gerçekten kullandığınız scope'ları isteyin ve gerekçesini yazın.
Gizlilik politikası, destek e-postası ve çalışan bir yönlendirme adresi zorunludur.
Kart numarası, CVV ya da panel parolası istemeyin; mağaza sahibini DZN Soft dışı ödeme sayfasına yönlendirmeyin.
Mağaza verisini yalnızca uygulamanın amacı için kullanın, üçüncü taraflarla paylaşmayın; kaldırılınca silin.
Yayındaki uygulamada yapılan değişiklikler yeniden incelemeye girer; bu sırada mevcut kurulumlar çalışmaya devam eder.
Güvenlik ihlalinde DZN Soft uygulamayı tek adımda devre dışı bırakabilir: API erişimi kapanır, tüm anahtarlar iptal edilir, webhook'lar durur ve uygulama App Store'dan kalkar.

Test / Sandbox

Gerçek müşteri verisi üzerinde test yapmayın. Portalda Test Mağazaları › Test mağazası oluştur ile demo ürün, üye ve siparişlerle dolu, yalnızca size ait bir mağaza açılır (en fazla 3). Örnek vitrin adresi: demo-a1b2c.sandbox.dznsoft.com.

"Uygulama kur + anahtar al" ile taslak uygulamanız incelemeyi beklemeden test mağazasına kurulur ve erişim anahtarı üretilir.
Test mağazasından gelen webhook gövdelerinde "sandbox": true bulunur.
Test mağazası ödeme almaz, faturalanmaz ve silindiğinde tüm test verisi kalkar.

UI Extensions

Uygulamalar ana Next.js veya Laravel koduna müdahale edemez. Yalnızca aşağıdaki sabit alanlara, izole (sandbox) iframe içinde çalışan widget ekleyebilir. Widget adresi herkese açık HTTPS olmalıdır ve uygulama incelemesinde ayrıca denetlenir.

Alan	Konum
`product.after_price`	Ürün sayfası — fiyatın altı
`product.after_description`	Ürün sayfası — açıklamanın altı
`cart.before_checkout`	Sepet — ödeme butonunun üstü
`admin.order.sidebar`	Panel — sipariş detayı yan alanı

iframe sandbox="allow-scripts allow-forms allow-popups" ile yüklenir: sayfanın çerezlerine, DOM'una ve oturumuna erişemez. Widget adresine store_id ve bağlama göre product_id/order_id parametreleri eklenir; veri gerekiyorsa kendi sunucunuzdan API ile çekin.

Aşamalı yayın

Extension alanları uygulama formunda tanımlanır ve incelemede denetlenir; vitrin ve panelde görüntülenmesi aşamalı olarak açılmaktadır. Duyurular için Changelog bölümünü izleyin.

Hata Kodları

API hataları {"error": {"code", "message"}} biçimindedir; OAuth uçları standart gereği {"error", "error_description"} döndürür.

HTTP	Kod	Açıklama
400	invalid_request / invalid_grant	OAuth isteği eksik ya da kod/yenileme anahtarı geçersiz.
401	unauthenticated	Authorization başlığı yok.
401	invalid_token	Anahtar geçersiz ya da iptal edilmiş.
401	token_expired	Erişim anahtarının süresi doldu.
401	invalid_client	client_id ya da client_secret hatalı.
403	insufficient_scope	Gerekli izin yok (required_scope alanına bakın).
403	app_not_installed	Uygulama bu mağazadan kaldırılmış.
403	app_disabled	Uygulama henüz onaylanmadı ya da DZN Soft tarafından durduruldu.
403	https_required	İstek HTTPS üzerinden yapılmalı.
404	not_found	Kayıt bu mağazada yok.
422	validation_failed	Girdi doğrulaması başarısız; fields alanı hatalı alanları listeler.
429	rate_limited / daily_limit_exceeded	İstek sınırı aşıldı; Retry-After kadar bekleyin.
503	unavailable	Servis geçici olarak kullanılamıyor.

Rate Limits

Sınır	Değer	Kapsam
Dakikalık	120 istek	Uygulama × mağaza (kurulum) başına
Günlük	50.000 istek	Uygulama × mağaza başına
Token ucu	30 istek / dakika	IP başına

Her yanıtta X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur. Sınır aşıldığında 429 ve Retry-After (saniye) döner; bu süre kadar bekleyip üstel geri çekilme ile tekrar deneyin.

Security

Önlem	Nasıl uygulanır
Kod izolasyonu	Üçüncü taraf kod DZN Soft sunucularında çalıştırılmaz; PHP/Node/Shell yürütme, veritabanı, .env ve dosya erişimi yoktur.
Tenant isolation	Mağaza yalnızca erişim anahtarından belirlenir; her sorgu o mağazayla sınırlıdır.
IDOR koruması	Başka mağazaya ait kimlikler 404 döner; varlıkları bile doğrulanmaz.
OAuth 2.0 + PKCE	Birebir redirect_uri eşleşmesi, zorunlu state, tek kullanımlık 10 dakikalık kod.
Token güvenliği	Anahtarlar yalnızca SHA-256 özetiyle saklanır; kısa ömür, rotation, anında revoke.
HMAC webhook	Zaman damgalı SHA-256 imza, tekrar oynatma koruması.
SSRF koruması	Webhook/widget adresleri özel ağlara çözümlenemez; bağlantı doğrulanan IP'ye sabitlenir, yönlendirme izlenmez.
Kart verisi	Kart numarası ve CVV sistemde saklanmaz, API'de hiçbir yanıtta yer almaz.
Denetim kaydı	Kurulum, izin, anahtar, inceleme ve API yazma işlemleri audit log'a yazılır.
Hesap güvenliği	Developer hesaplarında 2FA (TOTP) ve kurtarma kodları.
Tarayıcı güvenliği	CSP, X-Frame-Options, HSTS; izin ekranı başka sitelerin çerçevesine gömülemez.

Güvenlik açığı bildirimi

Bir güvenlik açığı bulduysanız herkese açık paylaşmadan önce info@dznsoft.com adresine bildirin.

Changelog

v1.026 Eylül 2026
- Public API v1: Products, Orders, Customers, Inventory uç noktaları.
- OAuth 2.0 yetkilendirme kodu akışı, PKCE (S256), yenileme anahtarı rotasyonu.
- HMAC-SHA256 imzalı webhook'lar ve otomatik yeniden deneme.
- Developer portalı, test mağazaları (sandbox) ve App Store incelemesi.

Portal: panel.dznsoft.com/developer