# Kayıtlar 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](./index#yaynlama-ve-grnrlk)). Yerelleştirilmiş değerler mağazada etkin dillere indirgenmiş locale haritalarıdır ve `media` değerleri medya nesneleridir (bkz. [Medya değerleri](./index#medya-deerleri)). ## 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 | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `key` | string | Evet | Nesne türü anahtarı, örneğin `faq`. | ### Sorgu parametreleri | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `sort` | string | Hayır | Sı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. | | `q` | string | Hayır | Tü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}]` | string | Hayır | Bir ö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]` | string | Hayır | Alt sınır (dahil). Yalnızca `number`, `money` ve `date` özellikleri için. Tarihler `YYYY-MM-DD`, para cent cinsinden. | | `filter[{propertyKey}][to]` | string | Hayır | Üst sınır (dahil). `from` ile aynı türler ve formatlar. `from` ve `to` birlikte veya tek başına kullanılabilir. | | `per_page` | integer | Hayır | Sayfa boyutu. Varsayılan 25, 1 ile 100 aralığına sabitlenir. | | `page` | integer | Hayır | Sayfa numarası, varsayılan 1. | | `locale` | string | Hayır | Mağ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). | | `include` | string | Hayır | `refs`, kayıt referanslarını açar ([Include ile referanslar](#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. | ```bash title="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}" ``` ```javascript title="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`). ```json title="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. ```bash title="Request" curl "https://api.borkol.com/v1/api/objects/types/service/records?include=refs" \ -H "Authorization: Bearer {api_key}" ``` ```json title="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 | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `key` | string | Evet | Nesne türü anahtarı, örneğin `service`. | | `slug` | string | Evet | Kaydın istenen dildeki adresi, örneğin `mutfak-montaji`. | ### Sorgu parametreleri | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `locale` | string | Hayır | Mağazada etkin bir dil etiketi, örneğin `tr`. Varsayılan, mağazanın varsayılan dilidir. | | `include` | string | Hayır | `refs`, listedeki gibi kayıt referanslarını açar. Bkz. [Include ile referanslar](#include-ile-referanslar). | ```bash title="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. ```json title="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`](/tr/api/getting-started/seo) 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](./index) bakın. Kayıt yalnızca yayınlanmış ve görünür olduğu sürece sunulur. ### Yol parametreleri | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `id` | string (uuid) | Evet | Kayıt id'si. | ### Sorgu parametreleri | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `include` | string | Hayır | `refs`, listedeki gibi kayıt referanslarını açar. Bkz. [Include ile referanslar](#include-ile-referanslar). | ```bash title="Request" curl https://api.borkol.com/v1/api/objects/records/6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0 \ -H "Authorization: Bearer {api_key}" ``` Durum: `200 OK`. ```json title="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ı.