Borkol Docs ana sayfası

Nesneler

Kayıtlar

Bir nesne türünün kayıtlarını sıralama, arama ve filtrelerle listeleyin; tekil kayıtları id veya adresle getirin.

Markdown olarak görüntüle

Kayıtlar, Objects modülünün içerik yarısıdır. Listeleme endpoint'i, Objects yüzeyindeki tek sayfalanmış endpoint'tir ve kayıt değerleri üzerinde sıralama, serbest metin araması ve özellik bazlı filtreleme destekler. Üç endpoint de objects:read scope'unu gerektirir ve kayıtların values alanı yalnızca aktif (arşivlenmemiş) özellik anahtarlarını içerir. Yalnızca yayınlanmış içeriği sunarlar: yayınlanabilir bir türde taslaklar ve gelecek için zamanlanmış kayıtlar listeden çıkarılır, doğrudan istendiğinde 404 döndürür (bkz. Yayınlama ve görünürlük). Yerelleştirilmiş değerler mağazada etkin dillere indirgenmiş locale haritalarıdır ve media değerleri medya nesneleridir (bkz. Medya değerleri).

GET /v1/api/objects/types/{key}/records

Bir nesne türünün kayıtlarının, türün anahtarıyla (GET /v1/api/objects/types çağrısından) adreslenen sayfalanmış listesi.

Yol parametreleri

AdTürZorunluAçıklama
keystringEvetNesne türü anahtarı, örneğin faq.

Sorgu parametreleri

AdTürZorunluAçıklama
sortstringHayırSıralama sütunu: created_at veya herhangi bir aktif özellik anahtarı. Azalan sıralama için başına - ekleyin. Varsayılan -created_at. number ve money özellikleri sayısal, date özellikleri tarih olarak sıralanır; ilgili özellik için değeri olmayan kayıtlar en sona sıralanır.
qstringHayırTürün tüm text ve textarea özellikleri üzerinde OR ile birleştirilen, büyük/küçük harfe duyarsız alt dize araması. Yerelleştirilmiş bir özellikte locale ile verilen dil aranır (yoksa mağazanın varsayılan dili). Türün metin özelliği yoksa yok sayılır (her şeyle eşleşir).
filter[{propertyKey}]stringHayırBir özellik üzerinde tam eşleşme filtresi. Boolean'lar true, false, 1, 0 kabul eder. select, seçenek metniyle eşleşir. status ile filtreleme public API'da kullanılamaz, çünkü her kayıt zaten yayınlanmıştır; türde status anahtarlı bir özellik yoksa filter[status] 422 döndürür. Birden fazla özellik için tekrarlanabilir; birden fazla filtre AND ile birleşir. Bir tags özelliğinde filter[{propertyKey}], listesi tam olarak o etiketi içeren kayıtları eşler; record_ref_list özelliğinde listesi o kayıt kimliğini içeren kayıtları; record_ref özelliğinde o kimliğe işaret eden kayıtları. Dizi olan bir değer filter üzerinde 422 döndürür. Bir color özelliği, büyük/küçük harf fark etmeksizin eşitlikle eşleşir (#1a2b3c, #1A2B3C değerini bulur).
filter[{propertyKey}][from]stringHayırAlt sınır (dahil). Yalnızca number, money ve date özellikleri için. Tarihler YYYY-MM-DD, para cent cinsinden.
filter[{propertyKey}][to]stringHayırÜst sınır (dahil). from ile aynı türler ve formatlar. from ve to birlikte veya tek başına kullanılabilir.
per_pageintegerHayırSayfa boyutu. Varsayılan 25, 1 ile 100 aralığına sabitlenir.
pageintegerHayırSayfa numarası, varsayılan 1.
localestringHayırMağazada etkin bir dil etiketi, örneğin tr. Yerelleştirilmiş filter[...], sort ve q bu dili kullanır; yoksa mağazanın varsayılan dili. Etkin olmayan bir dil burada varsayılan dile döner (by-slug endpoint'i bunun yerine 422 yanıtlar).
includestringHayırrefs, kayıt referanslarını açar (Include ile referanslar bölümüne bakın). Virgülle ayrılmış liste veya include[]=refs; diğer token'lar yok sayılır.
Request
curl --globoff "https://api.borkol.com/v1/api/objects/types/faq/records?sort=-created_at&q=delivery&filter[category]=shipping&per_page=10" \
  -H "Authorization: Bearer {api_key}"
Request (JS)
const params = new URLSearchParams({
  sort: "-created_at",
  q: "delivery",
  "filter[category]": "shipping",
  per_page: "10",
});
const res = await fetch(
  `https://api.borkol.com/v1/api/objects/types/faq/records?${params}`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { data, meta } = await res.json();

Durum: 200 OK. Her kayıt {id, values, published_at, created_at} yapısındadır; türün adresleri varsa ayrıca slugs (dil etiketinden adrese) içerir. Response, standart Laravel sayfalama zarfını kullanır: data (kayıtlar), links (first, last, prev, next sayfa URL'leri, mevcut olmayanlar null) ve meta (current_page, from, last_page, links, path, per_page, to, total).

Response
{
  "data": [
    {
      "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "values": {
        "name": "How long does delivery take?",
        "answer": "Orders ship within 2 business days.",
        "category": "shipping"
      },
      "published_at": "2026-08-01T09:15:00.000000Z",
      "created_at": "2026-08-01T09:15:00.000000Z",
      "slugs": { "en": "how-long-does-delivery-take" }
    }
  ],
  "links": {
    "first": "https://api.borkol.com/v1/api/objects/types/faq/records?page=1",
    "last": "https://api.borkol.com/v1/api/objects/types/faq/records?page=3",
    "prev": null,
    "next": "https://api.borkol.com/v1/api/objects/types/faq/records?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/objects/types/faq/records?page=1", "label": "1", "active": true },
      { "url": "https://api.borkol.com/v1/api/objects/types/faq/records?page=2", "label": "2", "active": false },
      { "url": "https://api.borkol.com/v1/api/objects/types/faq/records?page=3", "label": "3", "active": false },
      { "url": "https://api.borkol.com/v1/api/objects/types/faq/records?page=2", "label": "Next »", "active": false }
    ],
    "path": "https://api.borkol.com/v1/api/objects/types/faq/records",
    "per_page": 10,
    "to": 10,
    "total": 25
  }
}

Include ile referanslar

Varsayılan olarak bir record_ref değeri bağlı kaydın id'sidir, bir record_ref_list değeri ise id listesidir. Bağlı kayıtları satır içi almak için include=refs (veya include[]=refs) gönderin. Liste, GET /v1/api/objects/records/{id} ve by-slug endpoint'inde çalışır; üst düzeydeki, tekrarlayıcı satırlarındaki, bölüm verisindeki ve yerelleştirilmiş değerlerdeki referansları kapsar.

Açılmış bir kayıt {id, type_key, values, slugs?, published_at} biçimindedir: slugs yalnızca hedefin türünde adres (slug) ayarları varsa bulunur ve values her genel kayıtla aynı biçimdedir (yerelleştirilmiş haritalar etkin dillere indirilir, media nesne olarak gelir). Açma yalnızca bir düzey ilerler: açılmış bir kaydın içindeki referanslar id olarak kalır. Yalnızca herkese açık görünen hedefler açılır; taslak, zamanlanmış, silinmiş veya bulunmayan bir hedef atlanır, yani bir record_ref null olur ve giriş bir record_ref_list içinden kaybolur. Bilinmeyen include token'ları yok sayılır. Bir sayfanın tüm bağlı kayıtları birlikte yüklenir, bu yüzden isteğin maliyeti kayıt başına artmaz.

Request
curl "https://api.borkol.com/v1/api/objects/types/service/records?include=refs" \
  -H "Authorization: Bearer {api_key}"
Response
{
  "data": [
    {
      "id": "7a8b9c0d-1e2f-4a3b-84c5-d6e7f8a9b0c1",
      "values": {
        "name": "Kitchen fitting",
        "author": {
          "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
          "type_key": "team_member",
          "values": { "name": "Sam Jansen" },
          "slugs": { "en": "sam-jansen" },
          "published_at": "2026-09-01T10:00:00.000000Z"
        },
        "related": []
      },
      "published_at": "2026-10-01T08:00:00.000000Z",
      "created_at": "2026-09-28T13:20:00.000000Z",
      "slugs": { "en": "kitchen-fitting" }
    }
  ]
}

Hatalar

  • 404: bu anahtara sahip bir nesne türü olmadığında.
  • 422, errors.sort ["Cannot sort by {column}."] ile: sort, ne created_at ne de aktif bir özellik anahtarı olan bir şey belirttiğinde.
  • 422, errors.filter ["Cannot filter by {field}."] ile: bir filtre bilinmeyen veya arşivlenmiş bir özelliği (status dahil) belirttiğinde ya da number, money veya date olmayan bir özelliğe dizi (from/to) geçirdiğinde.
  • 422, errors.filter ["Invalid filter value for {field}."] ile: bir number veya money değeri ya da sınırı sayısal olmadığında veya bir date değeri ya da sınırı geçerli bir YYYY-MM-DD tarihi olmadığında.
  • 403 {"error":"Module not enabled: objects"} ve 403 {"message":"Invalid ability provided."}: modül ve scope hataları için.

GET /v1/api/objects/types/{key}/records/by-slug/{slug}

Tek bir kaydı, bir dildeki adresiyle getirir. Bir storefront URL'sini çözmek için kullanın: yoldan türün o dil için önekini çıkarın ve kalanı slug olarak geçin. Yalnızca yayınlanmış ve şu anda görünür kayıtlar eşleşir; adres yalnızca istediğiniz dil içinde eşleştirilir.

Yol parametreleri

AdTürZorunluAçıklama
keystringEvetNesne türü anahtarı, örneğin service.
slugstringEvetKaydın istenen dildeki adresi, örneğin mutfak-montaji.

Sorgu parametreleri

AdTürZorunluAçıklama
localestringHayırMağazada etkin bir dil etiketi, örneğin tr. Varsayılan, mağazanın varsayılan dilidir.
includestringHayırrefs, listedeki gibi kayıt referanslarını açar. Bkz. Include ile referanslar.
Request
curl "https://api.borkol.com/v1/api/objects/types/service/records/by-slug/keukenmontage?locale=nl" \
  -H "Authorization: Bearer {api_key}"

Durum: 200 OK; kayıt, liste öğeleriyle aynı şekildedir.

Response
{
  "data": {
    "id": "7a8b9c0d-1e2f-4a3b-84c5-d6e7f8a9b0c1",
    "values": {
      "name": { "en": "Kitchen fitting", "nl": "Keukenmontage" },
      "cover": {
        "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "url": "https://cdn.borkol.com/t/abc/kitchen.webp",
        "alt": "A fitted oak kitchen",
        "width": 1600,
        "height": 900,
        "mime_type": "image/webp"
      }
    },
    "published_at": "2026-10-01T08:00:00.000000Z",
    "created_at": "2026-09-28T13:20:00.000000Z",
    "slugs": { "en": "kitchen-fitting", "nl": "keukenmontage" }
  }
}

Bir satıcı bir adresi yeniden adlandırırsa eski adres burada artık sunulmaz. Yönlendirme yalnızca türün o dil için boş olmayan bir adres öneki varsa kaydedilir; eski yolu, ziyaretçileri yenisine yönlendirmek için GET /v1/api/redirects ile çözün.

Hatalar

  • 404: bu anahtara sahip bir nesne türü olmadığında veya o dilde bu adrese sahip görünür bir kayıt bulunmadığında (taslak veya zamanlanmış kayıt 404 döndürür).
  • 422, errors.locale ["This language is not enabled."] ile: locale, mağazanın etkin bir içerik dili olmadığında.
  • 403: yukarıdaki gibi modül ve scope hataları.

GET /v1/api/objects/records/{id}

Tek bir kaydı id ile getirir. Bu, tüm nesne türleri genelinde çalışır; tür anahtarını bilmeniz gerekmez. values yalnızca aktif özellik anahtarlarını içerir. Bir sections özelliği section yığınını tutar; yerelleştirilmiş alanlardaki locale haritası değerleri ve medya nesneleri dahil section örneği şekli için Objects kavram sayfasına bakın. Kayıt yalnızca yayınlanmış ve görünür olduğu sürece sunulur.

Yol parametreleri

AdTürZorunluAçıklama
idstring (uuid)EvetKayıt id'si.

Sorgu parametreleri

AdTürZorunluAçıklama
includestringHayırrefs, listedeki gibi kayıt referanslarını açar. Bkz. Include ile referanslar.
Request
curl https://api.borkol.com/v1/api/objects/records/6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0 \
  -H "Authorization: Bearer {api_key}"

Durum: 200 OK.

Response
{
  "data": {
    "id": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0",
    "values": {
      "name": "About us",
      "body": [
        {
          "_key": "sec_a1b2c3d4e5f60718293a4b5c",
          "type": "hero",
          "look": "default",
          "v": 1,
          "visible": true,
          "data": {
            "title": { "en": "Welcome to our shop" },
            "image": {
              "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
              "url": "https://cdn.borkol.com/t/abc/hero.webp",
              "alt": "Our shop front",
              "width": 1600,
              "height": 900,
              "mime_type": "image/webp"
            },
            "cta": { "url": "/products", "label": "Shop now" }
          }
        }
      ]
    },
    "published_at": "2026-07-20T14:05:33.000000Z",
    "created_at": "2026-07-20T14:05:33.000000Z"
  }
}

Hatalar

  • 404: kayıt bu mağazada mevcut olmadığında veya taslak ya da gelecek için zamanlanmış olduğunda.
  • 403: yukarıdaki gibi modül ve scope hataları.