LicenceDevs API

Başlangıç

Tüm istekler HTTPS üzerinden yapılır ve JSON döner. Sandbox ortamı canlı ortamla aynı şemayı kullanır; sandbox siparişleri gerçek lisans tüketmez ve bakiye düşmez.

Canlı     https://api.licencedevs.com/v1
Sandbox   https://sandbox.api.licencedevs.com/v1

• Sürüm yolun içindedir. Kırıcı değişiklikler yeni bir sürüm yolu ile yayınlanır, mevcut sürüm en az 12 ay çalışmaya devam eder.
• Tüm zaman damgaları ISO 8601 ve UTC biçimindedir.
• Para birimi alanları ISO 4217 kodu ile birlikte, en küçük birim (kuruş/cent) cinsinden tam sayı olarak döner.

Kimlik doğrulama

Her istek bayi paneli üzerinden üretilen bir API anahtarı ile yetkilendirilir. Anahtar yalnızca sunucu tarafında saklanmalı, tarayıcıya gönderilmemelidir.

GET /v1/products?limit=20 HTTP/1.1Host: api.licencedevs.comAuthorization: Bearer ld_live_••••••••••••••••Accept: application/json

• Anahtarlar salt-okunur (catalog:read) veya sipariş yetkili (orders:write) olarak üretilebilir.
• IP kısıtlaması tanımlandığında, listede olmayan adreslerden gelen istekler 403 döner.
• Anahtar sızıntısı durumunda panelden iptal edilen anahtar anında geçersiz olur.

Ürün kataloğu

Katalog uç noktaları ürün ağacını, sürüm bilgisini ve bayi fiyatını döner. Kendi mağazandaki ürün listesini bu uç noktadan senkronize edebilirsin.

GET /v1/products?category=windows-os&stock=in_stock&limit=2

{
  "data": [
    {
      "sku": "MS-WIN11-PRO-RET",
      "name": "Windows 11 Pro",
      "brand": "Microsoft",
      "category": "windows-os",
      "access_type": "license",
      "delivery": "instant_key",
      "stock": { "state": "in_stock", "available": 412 },
      "price": { "amount": 249000, "currency": "TRY" },
      "updated_at": "2026-08-21T09:14:02Z"
    },
    {
      "sku": "MS-WIN11-HOME-RET",
      "name": "Windows 11 Home",
      "brand": "Microsoft",
      "category": "windows-os",
      "access_type": "license",
      "delivery": "instant_key",
      "stock": { "state": "low_stock", "available": 6 },
      "price": { "amount": 179000, "currency": "TRY" },
      "updated_at": "2026-08-21T08:52:41Z"
    }
  ],
  "next_cursor": "eyJvIjoyfQ",
  "has_more": true
}

{
  "sku": "MS-WIN11-PRO-RET",
  "name": "Windows 11 Pro",
  "brand": "Microsoft",
  "category": "windows-os",
  "access_type": "license",
  "delivery": "instant_key",
  "region": "global",
  "language": "multi",
  "stock": { "state": "in_stock", "available": 412, "eta_minutes": 0 },
  "price": { "amount": 249000, "currency": "TRY", "tier": "reseller" },
  "min_quantity": 1,
  "max_quantity": 100,
  "updated_at": "2026-08-21T09:14:02Z"
}

Stok durumu

Stok, sipariş anında yeniden doğrulanır. Mağazanda "stokta var/yok" bilgisini doğru göstermek için toplu stok uç noktasını periyodik olarak, stock.changed webhook bildirimini ise anlık güncelleme için kullan.

GET /v1/stock?sku=MS-WIN11-PRO-RET,MS-O365-BP,JB-ALL-PACK

{
  "data": [
    { "sku": "MS-WIN11-PRO-RET", "state": "in_stock", "available": 412 },
    { "sku": "MS-O365-BP", "state": "on_demand", "available": 0, "eta_minutes": 30 },
    { "sku": "JB-ALL-PACK", "state": "out_of_stock", "available": 0 }
  ],
  "checked_at": "2026-08-21T09:20:11Z"
}

Sipariş ve teslimat

Sipariş oluşturmak bakiyeden düşer ve teslim edilebilir ürünlerde lisans anahtarını aynı yanıtta döner. Her sipariş isteği Idempotency-Key başlığı ile gönderilmelidir; ağ hatasında aynı anahtarla tekrar denemek ikinci bir sipariş oluşturmaz.

POST /v1/ordersAuthorization: Bearer ld_live_••••••••••••••••Idempotency-Key: 8f1c2d40-6b1e-4d5a-9c31-0a2f7e5b1d90Content-Type: application/json{  "sku": "MS-WIN11-PRO-RET",  "quantity": 2,  "reference": "SHOP-2026-104877"}

{
  "id": "ord_3Kd91mQpZ",
  "status": "completed",
  "reference": "SHOP-2026-104877",
  "sku": "MS-WIN11-PRO-RET",
  "quantity": 2,
  "charged": { "amount": 498000, "currency": "TRY" },
  "balance_after": { "amount": 1254300, "currency": "TRY" },
  "items": [
    { "key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "activation_url": "https://licencedevs.com/a/9f2c" },
    { "key": "YYYYY-YYYYY-YYYYY-YYYYY-YYYYY", "activation_url": "https://licencedevs.com/a/4b7e" }
  ],
  "created_at": "2026-08-21T09:21:44Z"
}

{
  "id": "ord_3Kd91mQpZ",
  "status": "pending",
  "reference": "SHOP-2026-104877",
  "sku": "MS-O365-BP",
  "quantity": 1,
  "eta_minutes": 25,
  "items": [],
  "created_at": "2026-08-21T09:21:44Z"
}

• Sipariş durumları: pending, completed, failed, refunded.
• failed ve refunded siparişlerde bakiye otomatik olarak iade edilir; iade işlemi transactions listesinde ayrı bir kayıt olarak görünür.

Bakiye ve otomatik yükleme

Bayi hesabı ön ödemeli bakiye ile çalışır. Otomatik sipariş akışı kuran ekipler için bakiye, tanımlanan eşiğin altına düştüğünde kayıtlı ödeme yöntemi ile otomatik yüklenir; böylece stok ve bakiye kaynaklı sipariş hataları önlenir.

{
  "balance": { "amount": 1254300, "currency": "TRY" },
  "auto_topup": {
    "enabled": true,
    "threshold": { "amount": 500000, "currency": "TRY" },
    "amount": { "amount": 2000000, "currency": "TRY" },
    "daily_limit": { "amount": 6000000, "currency": "TRY" },
    "payment_method": "card_9f31",
    "last_topup_at": "2026-08-19T22:04:10Z"
  }
}

POST /v1/balance/auto-topup{  "enabled": true,  "threshold": 500000,  "amount": 2000000,  "daily_limit": 6000000,  "payment_method": "card_9f31"}

{
  "enabled": true,
  "threshold": { "amount": 500000, "currency": "TRY" },
  "amount": { "amount": 2000000, "currency": "TRY" },
  "daily_limit": { "amount": 6000000, "currency": "TRY" },
  "payment_method": "card_9f31",
  "updated_at": "2026-08-21T09:25:00Z"
}

{
  "data": [
    {
      "id": "txn_71aQ",
      "type": "order",
      "amount": -498000,
      "order_id": "ord_3Kd91mQpZ",
      "created_at": "2026-08-21T09:21:44Z"
    },
    {
      "id": "txn_70zP",
      "type": "topup",
      "amount": 2000000,
      "source": "auto",
      "created_at": "2026-08-19T22:04:10Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Webhook bildirimleri

Stok ve sipariş değişikliklerini beklemeden almak için bayi panelinden bir webhook adresi tanımlanır. Her istek X-LicenceDevs-Signature başlığı ile HMAC-SHA256 imzalanır; gövde doğrulanmadan işlenmemelidir.

{
  "event": "stock.changed",
  "sent_at": "2026-08-21T09:30:00Z",
  "data": {
    "sku": "MS-WIN11-PRO-RET",
    "previous": { "state": "in_stock", "available": 412 },
    "current":  { "state": "low_stock", "available": 8 }
  }
}

{
  "event": "balance.low",
  "sent_at": "2026-08-21T09:31:12Z",
  "data": {
    "balance": { "amount": 480000, "currency": "TRY" },
    "threshold": { "amount": 500000, "currency": "TRY" },
    "auto_topup_enabled": true
  }
}

• Gönderilen olaylar: order.completed, order.failed, order.refunded, stock.changed, balance.low, balance.topup_failed.
• 2xx dışında yanıt alınan bildirimler artan aralıklarla 24 saat boyunca yeniden denenir.
• Aynı olay birden fazla kez ulaşabilir; event ve sent_at ile birlikte gelen data alanları idempotent işlenmelidir.

Hata kodları

Hatalar HTTP durum kodu ile birlikte makine tarafından okunabilir bir code alanı döner. Entegrasyonda dallanma bu alan üzerinden yapılmalıdır.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Bakiye yetersiz ve günlük otomatik yükleme limiti aşıldı.",
    "balance": { "amount": 12400, "currency": "TRY" },
    "required": { "amount": 498000, "currency": "TRY" }
  }
}