Ana içeriğe geç

Urunler

Urunlerin CRUD islemleri, ozellik deger atama ve Media Manager referanslariyla kapak/galeri yonetimi.

Base URL: /api/tenant/product-catalog/products Yetkilendirme: Bearer Token + X-Api-Key Modul: Product Catalog modulu musteriye atanmis olmalidir.

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-Api-Key: customer-api-key

POST /​

Yeni urun olusturur. Ceviriler, kategori atamalari ve ozellik degerleri tek istekte gonderilebilir.

Request Body:

{
  "code": "iphone-16-pro",
  "sku": "IP16PRO-256-BLK",
  "coverImageMediaFileId": "media-cover-id-...",
  "status": "Draft",
  "isActive": true,
  "categoryIds": ["3fa85f64-..."],
  "translations": [
    {
      "languageId": "9cd14a82-...",
      "name": "iPhone 16 Pro",
      "slug": "iphone-16-pro",
      "shortDescription": "Apple iPhone 16 Pro 256GB",
      "description": "<p>Detayli urun aciklamasi...</p>",
      "metaTitle": "iPhone 16 Pro | Magazamiz",
      "metaDescription": "iPhone 16 Pro 256GB en uygun fiyatla"
    }
  ],
  "images": [
    {
      "mediaFileId": "media-gallery-1-id-...",
      "sortOrder": 1,
      "altText": "iPhone 16 Pro on gorunum"
    }
  ],
  "attributeValues": [
    {
      "attributeDefinitionId": "attr-renk-id-...",
      "attributeOptionId": "opt-siyah-id-..."
    },
    {
      "attributeDefinitionId": "attr-agirlik-id-...",
      "decimalValue": 0.199
    },
    {
      "attributeDefinitionId": "attr-garantili-id-...",
      "booleanValue": true
    }
  ]
}
AlanTipZorunluAciklama
codestringEvetBenzersiz urun kodu
skustringHayirBenzersiz stok birimi kodu
coverImageMediaFileIdGuid?HayirKapak gorseli icin Media Manager dosya ID
statusstringEvetDraft, Published veya Archived
isActiveboolHayirAktiflik durumu (varsayilan: true)
categoryIdsGuid[]HayirKategori ID listesi
translationsProductTranslationRequest[]EvetDil cevirileri
imagesProductImageRequest[]HayirGaleri gorselleri
attributeValuesProductAttributeValueRequest[]HayirOzellik degerleri

ProductTranslationRequest​

AlanTipZorunluAciklama
languageIdGuidEvetDil ID
namestringEvetUrun adi
slugstringHayirURL slug (bos ise otomatik olusturulur)
shortDescriptionstringHayirKisa aciklama
descriptionstringHayirDetayli aciklama (HTML)
metaTitlestringHayirSEO basligi
metaDescriptionstringHayirSEO aciklamasi

ProductAttributeValueRequest​

Ozelligin dataType degerine gore ilgili alan doldurulur:

AlanTipAciklama
attributeDefinitionIdGuidOzellik tanimi ID (zorunlu)
textValuestring?Text tipi deger
numberValueint?Number tipi deger
decimalValuedecimal?Decimal tipi deger
booleanValuebool?Boolean tipi deger
dateValueDateTime?Date tipi deger
attributeOptionIdGuid?Select tipi secenek ID

ProductImageRequest​

AlanTipZorunluAciklama
mediaFileIdGuidEvetMedia Manager'da yuklenmis gorsel ID
sortOrderintHayirSiralama degeri
altTextstring?HayirAlternatif metin

Response — 201 Created:

{
  "success": true,
  "data": {
    "id": "3fa85f64-...",
    "code": "iphone-16-pro",
    "sku": "IP16PRO-256-BLK",
    "status": "Draft",
    "isActive": true,
    "coverImageUrl": null,
    "createdAt": "2026-03-28T14:00:00Z",
    "updatedAt": null,
    "translations": [
      {
        "languageId": "9cd14a82-...",
        "languageCode": "tr",
        "name": "iPhone 16 Pro",
        "slug": "iphone-16-pro",
        "shortDescription": "Apple iPhone 16 Pro 256GB",
        "description": "<p>Detayli urun aciklamasi...</p>",
        "metaTitle": "iPhone 16 Pro | Magazamiz",
        "metaDescription": "iPhone 16 Pro 256GB en uygun fiyatla"
      }
    ]
  }
}

GET /​

Urunleri filtreli ve sayfalanmis olarak listeler. Ozellik degerlerine gore filtreleme destekler.

Query Parametreleri:

ParametreTipVarsayilanAciklama
pageint1Sayfa numarasi
pageSizeint10Sayfa basina kayit
statusstring—Draft, Published veya Archived filtresi
categoryIdGuid (tekrarli)—Kategori filtresi. Birden fazla categoryId gonderilebilir
searchstring—Urun adinda arama
langstring—Dil kodu filtresi (ornek: tr)
attrs[code]string (tekrarli)—Ozellik degerine gore filtreleme. Ayni code birden fazla kez gonderilebilir
attrs[code_min]string—Sayisal ozellik alt sinir
attrs[code_max]string—Sayisal ozellik ust sinir

Ozellik Filtreleme Ornekleri​

# Rengi "Kirmizi" olan urunler
GET /api/tenant/product-catalog/products?attrs[renk]=Kirmizi

# Agirligi 0.5 ile 2.0 kg arasi urunler
GET /api/tenant/product-catalog/products?attrs[agirlik_min]=0.5&attrs[agirlik_max]=2.0

# Garantili urunler
GET /api/tenant/product-catalog/products?attrs[garantili]=true

# Coklu kategori filtresi (OR)
GET /api/tenant/product-catalog/products?categoryId=cat-a&categoryId=cat-b

# Ayni attribute icinde coklu secim (OR)
GET /api/tenant/product-catalog/products?attrs[brand]=Veda&attrs[brand]=Apicenna&attrs[brand]=GigiVet

# Birden fazla filtre birlikte
GET /api/tenant/product-catalog/products?categoryId=xxx&attrs[renk]=Mavi&attrs[agirlik_max]=1.5

Filtre Semantigi​

  • Ayni attribute icindeki tekrarli secimler OR mantigiyla uygulanir.
  • categoryId parametresi tekrarli gonderilirse kategoriler OR mantigiyla uygulanir.
  • Farkli attribute gruplari birbiriyle AND mantigiyla birlestirilir.

Ornek:

GET /api/tenant/product-catalog/products?attrs[brand]=Veda&attrs[brand]=Apicenna&attrs[form]=Tablet&attrs[form]=Toz

Yukaridaki ifade:

(brand IN [Veda, Apicenna]) AND (form IN [Tablet, Toz])

Response — 200 OK:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "3fa85f64-...",
        "code": "iphone-16-pro",
        "sku": "IP16PRO-256-BLK",
        "status": "Published",
        "isActive": true,
        "coverImageUrl": "https://api.example.com/media/acme/cc4d4a1df9894a8da60f0a5e8cb8583d.webp",
        "createdAt": "2026-03-28T14:00:00Z",
        "name": "iPhone 16 Pro",
        "slug": "iphone-16-pro"
      }
    ],
    "page": 1,
    "pageSize": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

GET /export/xlsx​

Filtrelenmis urun listesini Excel (.xlsx) olarak indirir. Liste endpoint'i ile ayni filtre semantigini kullanir, ancak sayfalama uygulanmaz.

Query Parametreleri:

ParametreTipVarsayilanAciklama
statusstring—Draft, Published veya Archived filtresi
categoryIdGuid (tekrarli)—Kategori filtresi. Birden fazla categoryId gonderilebilir
searchstring—Urun kodu, SKU veya ceviri alanlarinda arama
langstring—Listeleme ve baslik alanlari icin tercih edilen dil kodu
attrs[code]string (tekrarli)—Ozellik degerine gore filtreleme. Ayni code birden fazla kez gonderilebilir
attrs[code_min]string—Sayisal ozellik alt sinir
attrs[code_max]string—Sayisal ozellik ust sinir

Davranis:

  • page ve pageSize dikkate alinmaz; tum eslesen urunler export edilir.
  • Mevcut liste filtreleriyle ayni categoryId, search, lang ve attrs[...] mantigi kullanilir.
  • Cikti .xlsx dosyasi olarak indirilir.

Response:

  • 200 OK
  • Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • Content-Disposition: attachment; filename=products-YYYYMMDD-HHmmss.xlsx

Kolon Mantigi:

  • Her satir bir urunu temsil eder.
  • Ilk kolonlar temel alanlardir: id, code, sku, status, isActive, coverImageUrl, createdAt, updatedAt.
  • Ardindan cok dilli alanlar duzlestirilir. Ornek kolonlar: Name_tr, Slug_tr, Name_en, Slug_en.
  • Kategoriler tek hucrede birlestirilir; birden fazla kategori | ayiraciyla yazilir.
  • Ozellik degerleri attribute koduna gore kolonlastirilir; Select degerleri secenek etiketiyle, birden fazla deger gerekiyorsa | ile ayrilarak yazilir.
  • Uzun metin alanlari ve HTML iceren ceviri alanlari Excel hucreleri icinde aynen korunur.

Ornek:

GET /api/tenant/product-catalog/products/export/xlsx?status=Published&categoryId=cat-a&lang=tr

Bu istek yayinlanmis urunleri, secili kategori kapsaminda, Excel formatinda indirir.

GET /{id}​

Urun detayini kategoriler, ozellik degerleri ve gorselleriyle birlikte getirir.

Response — 200 OK:

{
  "success": true,
  "data": {
    "id": "3fa85f64-...",
    "code": "iphone-16-pro",
    "sku": "IP16PRO-256-BLK",
    "status": "Published",
    "isActive": true,
    "coverImageUrl": "https://api.example.com/media/acme/cc4d4a1df9894a8da60f0a5e8cb8583d.webp",
    "createdAt": "2026-03-28T14:00:00Z",
    "updatedAt": "2026-03-28T15:00:00Z",
    "translations": [
      {
        "languageId": "9cd14a82-...",
        "languageCode": "tr",
        "name": "iPhone 16 Pro",
        "slug": "iphone-16-pro",
        "shortDescription": "Apple iPhone 16 Pro 256GB",
        "description": "<p>Detayli urun aciklamasi...</p>",
        "metaTitle": "iPhone 16 Pro | Magazamiz",
        "metaDescription": "iPhone 16 Pro 256GB en uygun fiyatla"
      }
    ],
    "categories": [
      {
        "id": "cat-id-...",
        "parentId": null,
        "sortOrder": 1,
        "isActive": true,
        "translations": [
          { "languageId": "...", "languageCode": "tr", "name": "Telefonlar", "slug": "telefonlar" }
        ]
      }
    ],
    "attributeValues": [
      {
        "attributeDefinitionId": "attr-renk-...",
        "attributeCode": "renk",
        "dataType": "Select",
        "unit": null,
        "textValue": null,
        "numberValue": null,
        "decimalValue": null,
        "booleanValue": null,
        "dateValue": null,
        "attributeOptionId": "opt-siyah-...",
        "optionTranslations": [
          { "languageId": "...", "languageCode": "tr", "value": "Siyah" }
        ]
      },
      {
        "attributeDefinitionId": "attr-agirlik-...",
        "attributeCode": "agirlik",
        "dataType": "Decimal",
        "unit": "kg",
        "decimalValue": 0.199,
        "attributeOptionId": null,
        "optionTranslations": null
      }
    ],
    "images": [
      {
        "id": "img-id-...",
        "imageUrl": "https://api.example.com/media/acme/f9cc9bbcc17f4635b4b8766d939e6043.jpg",
        "sortOrder": 1,
        "altText": "iPhone 16 Pro on gorunum"
      }
    ]
  }
}

PUT /{id}​

Urunu gunceller. Kategori atamalari ve ozellik degerleri tamamen yeniden yazilir (replace).

Request Body: CreateProductRequest ile ayni yapidir (code haric).

Response — 200 OK: ProductResponse objesi doner.

DELETE /{id}​

Urunu siler (soft delete).

Response — 204 No Content

Medya Kullanımı​

Kapak ve galeri gorselleri icin akıs:

  1. Dosyalari Media Manager modulu ile yukleyin.
  2. Kapak icin coverImageMediaFileId, galeri icin images[].mediaFileId alanlarini kullanin.
  3. Kapagi kaldirmak icin coverImageMediaFileId: null, galeriyi degistirmek icin images listesini yeniden gonderin.

Olasi Hatalar​

KodDurum
401Token eksik veya gecersiz
403Tenant kullanicisi yetkisi yok veya product-catalog modul erisimi yok
404Urun, kategori, ozellik tanimi veya medya kaydi bulunamadi
409Urun kodu, SKU veya slug cakismasi
400Gecersiz status degeri veya medya referansi hatasi