Borkol Docs ana sayfası

Katalog

Ürünler

Varyantlar, görseller, kategoriler, stok durumu ve müşteri bağlamına göre fiyatlandırma dahil aktif ürünleri listeleyin ve getirin.

Markdown olarak görüntüle

Ürün endpoint'leri, kimliği doğrulanmış tenant'ın aktif ürünlerini döndürür. Her iki endpoint de Authorization: Bearer {api_key} olarak gönderilen, catalog:read veya commerce:read scope'una sahip bir tenant API anahtarı ve mağaza için etkinleştirilmiş catalog modülü gerektirir. Tenancy anahtardan türetildiği için X-Tenant-Id header'ına gerek yoktur. İstekler, dakikada 120 istek olan ortak tenant rate limit'inden düşer; limiti aşmak, Retry-After ve X-RateLimit-* header'larıyla birlikte 429 {"message":"Too Many Attempts."} döndürür.

Yalnızca durumu active olan ürünler döndürülür. Taslak, arşivlenmiş ve soft-delete edilmiş ürünler listeden filtrelenir ve detay endpoint'inde 404 döndürür.

Ürün nesnesi

Tüm ID'ler UUID'dir. Tüm para tutarları, ürünün ISO para birimi koduyla eşleştirilmiş küçük birim (kuruş/cent) cinsinden integer'lardır (örneğin "EUR" ile 18900, 189,00 EUR demektir). Zaman damgaları ISO 8601 UTC'dir.

AdTürZorunluAçıklama
idstring (uuid)her zamanÜrün ID'si.
capabilitystringher zamanÜrünün nasıl satıldığı: standard (sepete product_id ve varyantı varsa variant_id ile eklenen düz veya varyantlı ürün) ya da made_to_measure (configurator ile fiyatlanır, sepete bir configuration ile eklenir). Enum'u açık kabul edin ve bilinmeyen bir değeri nötr gösterin.
capability_activebooleanher zamanÜrünün capability'sinin şu anda satılıp satılamayacağı: standard için commerce modülü, made_to_measure için configurator modülü gerekir. false olduğunda sepete ekleme ürünü CAPABILITY_INACTIVE ile reddeder; satın al düğmesini gizleyin.
purchasabilitystringher zamanŞunlardan biri: direct, quote, both; merchant hiçbir şey ayarlamadıysa direct. quote, ürünün doğrudan satın alınamayacağı anlamına gelir; alıcıyı bir teklif talebine yönlendirin. Alan, mağazada sales modülü devre dışı olsa bile raporlanır; ancak ödemeyi yalnızca sales modülü etkin (ve teklif talepleri açık) bir mağaza reddeder.
unitstringher zamanÜrünün satıldığı birim: piece, kg, g, l, m, m2, m3 veya hour. piece ürünü yalnızca tam sayı sepet miktarı kabul eder; diğer tüm birimler en fazla üç ondalık basamak kabul eder (örneğin 0.75 kg).
skustring or nullher zamanÜrün düzeyinde SKU.
slugstringher zamanURL slug'ı, tenant başına benzersiz.
namestringher zamanÜrün adı.
descriptionstring or nullher zamanÜrün açıklaması.
statusstringher zamanBu API'de her zaman active.
meta_titlestring or nullher zamanSEO başlığı.
meta_descriptionstring or nullher zamanSEO açıklaması.
compare_at_amountinteger or nullher zamanMerchant'ın belirlediği karşılaştırma (eski) fiyatı, küçük birim cinsinden; her zaman ürün fiyatından yüksektir. Ayarlanmamışsa null. Müşteri grubu veya kademe fiyatlandırmasından önceki fiyatı bildiren list_price_amount alanından bağımsızdır.
barcodestring or nullher zamanBarkod (EAN, UPC veya merchant'a ait herhangi bir kod).
weight_gramsinteger or nullher zamanGram cinsinden gönderim ağırlığı.
requires_shippingbooleanher zamanÜrünün fiziksel olarak gönderilip gönderilmediği. Bir sepet, ödemede yalnızca ürünü gönderim gerektiren en az bir satır içerdiğinde gönderim yöntemine ihtiyaç duyar.
track_stockbooleanher zamanMağazanın bu ürün için stok takibi yapıp yapmadığı. false olduğunda stock_status untracked olur ve ürün hiçbir zaman tükenmez.
returnablebooleanher zamanMerchant'ın iadeyi kabul edip etmediği. made_to_measure ürünler siparişe göre üretilir ve bu bayrak ne derse desin sipariş verildikten sonra asla iade edilemez (sipariş satırındaki attributes.returnable alanına bakın).
lead_time_daysinteger or nullher zamanGün cinsinden üretim veya teslim süresi, 0 ile 365 arası. Ayarlanmamışsa null.
tagsarray of stringher zamanMerchant etiketleri. Yoksa boş array.
social_imageobject or nullher zamanSosyal paylaşım (Open Graph) görseli; aşağıdaki görsel nesnesine ek olarak id alanını içerir. Ayarlanmamışsa null; bu durumda image alanını kullanın.
priceobjecther zaman{amount, currency}. amount, isteğin müşteri bağlamı için (herhangi bir X-Customer-Token header'ı gönderilmediğinde misafir) miktar 1'deki çözümlenmiş birim fiyattır. Tenant fiyatları misafirlerden gizliyorsa ve istek bir misafir isteğiyse amount null olur.
list_price_amountintegerkoşulluKüçük birim cinsinden orijinal (liste) fiyatı. Yalnızca çözümlenen fiyattan farklı olduğunda ve tenant orijinal fiyatları gösterdiğinde bulunur.
quantity_tiersarraykoşullu[{min_quantity, price_amount}] satırları; yalnızca tenant kademe tablolarını gösterdiğinde ve min_quantity > 1 olan ürün kapsamlı kademeler mevcut olduğunda bulunur. Müşteri grubu satırları, aynı min_quantity değerindeki herkese açık satırları gölgeler.
price_displayobjectkoşullu{mode}; mode inc veya ex'tir (KDV dahil veya KDV hariç gösterim). Tenant'ın vat_display ayarından çözümlenir (inc, ex veya auto; auto, X-Customer-Token ile tanımlanan B2B müşteriler için ex, diğer durumlarda inc olarak çözümlenir).
attributesobject or arrayher zamanMerchant tarafından belirlenen serbest biçimli öznitelik haritası. Boşken [] olarak serileştirilir.
optionsarrayyalnızca detay[{name, values}], ürünün seçenek tanımları (örneğin {"name":"Color","values":["Natural","Black"]}). Yalnızca GET /v1/api/commerce/products/{id} yanıtında yer alır.
categoriesarrayher zamanÜrünün ait olduğu aktif kategoriler: [{id, name, slug, is_active}].
variantsarrayher zamanAktif varyantlar, aşağıdaki varyant nesnesine bakın. Ürünün varyantı yoksa boş dizi.
has_variantsbooleanher zamanvariants dizisinin boş olup olmadığı.
price_fromobjecther zaman{amount, currency}. Çözümlenmiş en düşük varyant fiyatı veya varyant yoksa ürün fiyatı. Tenant misafir fiyatlarını gizliyorsa misafirler için amount null olur.
imageobject or nullher zamanBirincil görsel (primary olarak işaretlenmiş medya öğesi, yoksa ilki), aşağıdaki görsel nesnesine bakın. Ürünün medyası yoksa null.
imagesarrayyalnızca detayTam galeri; her öğe bir görsel nesnesi artı id, is_primary (boolean) ve sort_order (integer) içerir. Yalnızca GET /v1/api/commerce/products/{id} yanıtında yer alır.
stock_statusstringkoşulluŞunlardan biri: in_stock, low_stock, out_of_stock, backorder, untracked. untracked, mağazanın bu ürünü saymadığı anlamına gelir: track_stock false, stok satırı yok veya mağazada stock modülü devre dışı. Stock modülü platformda kayıtlı değilse tamamen atlanır.
created_atstring (ISO 8601)her zamanOluşturulma zaman damgası.
updated_atstring (ISO 8601)her zamanSon güncelleme zaman damgası.

Client panelindeki stock_available alanı bu API'de asla yer almaz.

Varyant nesnesi

AdTürZorunluAçıklama
idstring (uuid)her zamanVaryant ID'si.
option_valuesobjecther zamanSeçenek adından seçilen değere eşleme, örneğin {"Color":"Natural"}.
skustring or nullher zamanVaryant SKU'su.
barcodestring or nullher zamanVaryant barkodu.
weight_gramsinteger or nullher zamanGram cinsinden varyant gönderim ağırlığı; null, ürünün weight_grams değerinin geçerli olduğu anlamına gelir.
priceobjecther zaman{amount, currency}. Varyantın kendi fiyatı yoksa ürün fiyatına döner. Tenant misafir fiyatlarını gizliyorsa misafirler için amount null olur.
is_activebooleanher zamanBu API'de her zaman true (pasif varyantlar filtrelenir).
image_idstring (uuid) veya nullher zamanVaryantın kendi görseli: ürünün medya öğelerinden birinin id değeri; bu nedenle detay endpoint'indeki images içindeki bir öğeyle eşleşir. Müşteri bu varyantı seçtiğinde gösterin. Varyantın kendi görseli yoksa null; bu durumda ürünün image alanını kullanın.
imageobject veya nullher zamanVaryantın kendi görseli, id olmadan bir görsel nesnesi olarak (aşağıya bakın). Varyantın kendi görseli yoksa null.
stock_statusstringkoşulluÜrün düzeyindeki stock_status ile aynı enum; track_stock değeri false olan bir ürünün tüm varyantları untracked olur. Yalnızca stock modülü kayıtlıyken bulunur.

Görsel nesnesi

AdTürZorunluAçıklama
urlstringher zamanOrijinal görsel URL'i.
variantsobjecther zamanwsrv.nl üzerinden sunulan, thumb (160px genişlik), card (480px genişlik), detail (1200px genişlik) anahtarlı, anında oluşturulan webp yeniden boyutlandırma URL'leri.
altstring or nullher zamanAlt metni.

GET /v1/api/commerce/products

Tenant'ın aktif ürünlerinin sayfalanmış bir listesini, en yeniden başlayarak döndürür (created_at azalan, yapılandırılamaz). Her ürün; birincil görselini, aktif varyantlarını, aktif kategorilerini, stok durumunu (stock modülü kayıtlıyken) ve müşteri bağlamına göre fiyatlandırmayı içerir. Liste, options dizisini ve images galerisini içermez; bunlar için detay endpoint'ini çağırın. Sayfa boyutu 20'de sabittir; per_page, sıralama veya arama parametresi yoktur.

Query parametreleri

AdTürZorunluAçıklama
filter[category]stringHayırKategori slug'ı. O aktif kategorideki veya aktif alt kategorilerinin herhangi birindeki ürünleri eşleştirir. Bilinmeyen veya pasif bir slug boş bir sonuç kümesi verir (200, 404 değil).
pageintegerHayırSayfa numarası, varsayılan 1. Sayfa boyutu 20'de sabittir.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringHayırStorefront müşteri oturum token'ı. Fiyatlandırmayı o müşterinin bağlamına geçirir (grup fiyatlandırması, B2B KDV hariç gösterim, kademe tabloları). Onsuz fiyatlandırma misafir için hesaplanır.
Request
curl "https://api.borkol.com/v1/api/commerce/products?filter%5Bcategory%5D=tables&page=1" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
Request (JS)
const res = await fetch(
  "https://api.borkol.com/v1/api/commerce/products?" +
    new URLSearchParams({ "filter[category]": "tables", page: "1" }),
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  }
);
const { data, links, meta } = await res.json();
Response
{
  "data": [
    {
      "id": "9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21",
      "capability": "standard",
      "capability_active": true,
      "purchasability": "direct",
      "unit": "piece",
      "sku": "TABLE-OAK",
      "slug": "oak-table",
      "name": "Oak Table",
      "description": "Solid oak table.",
      "status": "active",
      "meta_title": null,
      "meta_description": null,
      "compare_at_amount": null,
      "barcode": null,
      "weight_grams": 32000,
      "requires_shipping": true,
      "track_stock": true,
      "returnable": true,
      "lead_time_days": null,
      "tags": [],
      "social_image": null,
      "price": { "amount": 54900, "currency": "EUR" },
      "price_display": { "mode": "inc" },
      "attributes": [],
      "categories": [
        {
          "id": "7a1b3c5d-2e4f-4a6b-8c0d-1e2f3a4b5c6d",
          "name": "Tables",
          "slug": "tables",
          "is_active": true
        }
      ],
      "variants": [],
      "has_variants": false,
      "price_from": { "amount": 54900, "currency": "EUR" },
      "image": {
        "url": "https://cdn.borkol.com/t/9c2f/table.jpg",
        "variants": {
          "thumb": "https://wsrv.nl/?url=...&w=160&we=1&output=webp&q=80",
          "card": "https://wsrv.nl/?url=...&w=480&we=1&output=webp&q=80",
          "detail": "https://wsrv.nl/?url=...&w=1200&we=1&output=webp&q=80"
        },
        "alt": "Oak table"
      },
      "stock_status": "in_stock",
      "created_at": "2026-07-02T09:14:33.000000Z",
      "updated_at": "2026-08-01T15:20:11.000000Z"
    }
  ],
  "links": {
    "first": "https://api.borkol.com/v1/api/commerce/products?page=1",
    "last": "https://api.borkol.com/v1/api/commerce/products?page=3",
    "prev": null,
    "next": "https://api.borkol.com/v1/api/commerce/products?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": [
      { "url": null, "label": "« Previous", "active": false },
      {
        "url": "https://api.borkol.com/v1/api/commerce/products?page=1",
        "label": "1",
        "active": true
      }
    ],
    "path": "https://api.borkol.com/v1/api/commerce/products",
    "per_page": 20,
    "to": 20,
    "total": 47
  }
}

Zarf, standart Laravel resource paginator'ıdır: üst düzey bir data dizisi artı links (first, last, prev, next, mutlak URL'ler veya null) ve meta (current_page, from, last_page, links, path, per_page, to, total). per_page her zaman 20'dir.

Hatalar

DurumBodyNeden
401{"message":"Unauthenticated."}API anahtarı eksik veya geçersiz.
403{"message":"Invalid ability provided."}Anahtar ne catalog:read ne de commerce:read scope'una sahip.
403{"error":"Module not enabled: catalog"}Tenant'ta catalog modülü etkin değil. message yerine error anahtarına dikkat edin.
403{"message":"Tenant suspended.","code":"tenant_suspended"}Tenant hesabı askıya alınmış.
429{"message":"Too Many Attempts."}Dakikada 120 istek rate limit'i aşıldı.

GET /v1/api/commerce/products/{id}

UUID ile tek bir aktif ürünü getirir. Liste endpoint'ine kıyasla detay yanıtı ek olarak options dizisini ve tam images galerisini (is_primary ve sort_order ile birlikte) içerir. Stok durumu ve fiyatlandırma listedeki gibi zenginleştirilir: X-Customer-Token header'ı yoksa misafir fiyatlandırması uygulanır. Taslak, arşivlenmiş, soft-delete edilmiş veya bilinmeyen ürünler için 404 döndürür.

Path parametreleri

AdTürZorunluAçıklama
idstring (uuid)EvetÜrün ID'si.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringHayırStorefront müşteri oturum token'ı. Fiyatlandırmayı o müşterinin grubuna ve B2B bağlamına geçirir.
Request
curl "https://api.borkol.com/v1/api/commerce/products/9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
Response
{
  "data": {
    "id": "9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21",
    "capability": "standard",
    "capability_active": true,
    "purchasability": "direct",
    "unit": "piece",
    "sku": "CHAIR-OAK",
    "slug": "oak-dining-chair",
    "name": "Oak Dining Chair",
    "description": "Solid oak chair with linen seat.",
    "status": "active",
    "meta_title": "Oak Dining Chair",
    "meta_description": "Handmade solid oak dining chair.",
    "compare_at_amount": 22900,
    "barcode": "8712345678906",
    "weight_grams": 6500,
    "requires_shipping": true,
    "track_stock": true,
    "returnable": true,
    "lead_time_days": 5,
    "tags": ["oak", "dining"],
    "social_image": {
      "id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "url": "https://cdn.borkol.com/t/9c2f/chair-social.jpg",
      "variants": {
        "thumb": "https://wsrv.nl/?url=...&w=160&we=1&output=webp&q=80",
        "card": "https://wsrv.nl/?url=...&w=480&we=1&output=webp&q=80",
        "detail": "https://wsrv.nl/?url=...&w=1200&we=1&output=webp&q=80"
      },
      "alt": "Oak dining chair in a dining room"
    },
    "price": { "amount": 18900, "currency": "EUR" },
    "list_price_amount": 21900,
    "quantity_tiers": [
      { "min_quantity": 5, "price_amount": 17900 },
      { "min_quantity": 10, "price_amount": 16900 }
    ],
    "price_display": { "mode": "inc" },
    "attributes": { "material": "oak" },
    "options": [
      { "name": "Color", "values": ["Natural", "Black"] }
    ],
    "categories": [
      {
        "id": "7a1b3c5d-2e4f-4a6b-8c0d-1e2f3a4b5c6d",
        "name": "Chairs",
        "slug": "chairs",
        "is_active": true
      }
    ],
    "variants": [
      {
        "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
        "option_values": { "Color": "Natural" },
        "sku": "CHAIR-OAK-NAT",
        "barcode": "8712345678913",
        "weight_grams": null,
        "price": { "amount": 18900, "currency": "EUR" },
        "is_active": true,
        "image_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "image": {
          "url": "https://cdn.borkol.com/t/9c2f/chair.jpg",
          "variants": {
            "thumb": "https://wsrv.nl/?url=...&w=160&we=1&output=webp&q=80",
            "card": "https://wsrv.nl/?url=...&w=480&we=1&output=webp&q=80",
            "detail": "https://wsrv.nl/?url=...&w=1200&we=1&output=webp&q=80"
          },
          "alt": "Oak dining chair front view"
        },
        "stock_status": "in_stock"
      }
    ],
    "has_variants": true,
    "price_from": { "amount": 18900, "currency": "EUR" },
    "image": {
      "url": "https://cdn.borkol.com/t/9c2f/chair.jpg",
      "variants": {
        "thumb": "https://wsrv.nl/?url=...&w=160&we=1&output=webp&q=80",
        "card": "https://wsrv.nl/?url=...&w=480&we=1&output=webp&q=80",
        "detail": "https://wsrv.nl/?url=...&w=1200&we=1&output=webp&q=80"
      },
      "alt": "Oak dining chair front view"
    },
    "images": [
      {
        "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "url": "https://cdn.borkol.com/t/9c2f/chair.jpg",
        "variants": {
          "thumb": "https://wsrv.nl/?url=...&w=160&we=1&output=webp&q=80",
          "card": "https://wsrv.nl/?url=...&w=480&we=1&output=webp&q=80",
          "detail": "https://wsrv.nl/?url=...&w=1200&we=1&output=webp&q=80"
        },
        "alt": "Oak dining chair front view",
        "is_primary": true,
        "sort_order": 0
      }
    ],
    "stock_status": "in_stock",
    "created_at": "2026-07-02T09:14:33.000000Z",
    "updated_at": "2026-08-01T15:20:11.000000Z"
  }
}

Hatalar

DurumBodyNeden
401{"message":"Unauthenticated."}API anahtarı eksik veya geçersiz.
403{"message":"Invalid ability provided."}Anahtar ne catalog:read ne de commerce:read scope'una sahip.
403{"error":"Module not enabled: catalog"}Tenant'ta catalog modülü etkin değil.
403{"message":"Tenant suspended.","code":"tenant_suspended"}Tenant hesabı askıya alınmış.
404{"message":"..."}Ürün mevcut değil, soft-delete edilmiş veya durumu active değil.
429{"message":"Too Many Attempts."}Dakikada 120 istek rate limit'i aşıldı.