T-SOFT/Admin API/Metafield'lar

Metafield'lar

Uygulamanız ürüne, siparişe, üyeye, kategoriye, içerik sayfasına ve blog yazısına kendi verisini metafield olarak yazabilir. Mağazaya özgü ayarlarınızı da kurulum metafield'ı olarak saklayabilirsiniz. Eşlemeyi kendi veritabanınızda tutmanız gerekmez; veri mağazada, ilgili kaydın yanında durur.

Bir kayda bağlı olmayan kendi verinizi (SSS, beden tablosu, mağaza listesi gibi) metaobject olarak tutarsınız: alanlarını siz tanımlarsınız, kayıtlarını oluşturur, okur, günceller ve silersiniz.

Metafield ve metaobject uç noktaları ayrı bir kapsam istemez; uygulamanın kurulu olması yeterlidir. Uygulamanız yalnız kendi tanımlarını ve değerlerini görür; mağazanın ve başka uygulamaların metafield ve metaobject'lerini hiçbir uç noktadan okuyamaz.

Kavramlar

  • Tanım (metafield-definitions): hangi kayıt türüne, hangi anahtarla, hangi tipte değer yazılacağı. Tanımı oluşturan uygulama tanımın sahibidir; tanımı yalnız o değiştirir ve siler.
  • Değer (metafields): bir tanımın tek bir kayıttaki karşılığı (ör. 42 numaralı ürünün garanti_suresi değeri).
  • Metaobject tanımı (metaobject-definitions): kendi nesne türünüz ve alanları (ör. sss: soru, yanit).
  • Metaobject (metaobjects): bir metaobject tanımının tek bir kaydı (ör. bir SSS maddesi).
Sahip kaynak (ownerResource)Gereken kapsam
productread_products
categoryread_products
orderread_orders
customerread_customers
contentread_content
blogread_content
installation—

Metafield için ayrı bir okuma ya da yazma kapsamı yoktur; tanım oluşturmak da kapsam istemez. Bir kayda değer yazmak ya da kaydın değerini okumak için o kaydı görebilmeniz yeterlidir: ürün değeri için read_products, sipariş için read_orders. Değer yazmak kaydın kendisini değiştirmediği için write_ kapsamı gerekmez. Kaydı görme kapsamınız yoksa 403 alırsınız.

Sınırlar

SınırDeğer
Tanım sayısıUygulama başına, sahip kaynak başına 10 (ör. üründe 10, siparişte 10)
Metaobject tanımı sayısıUygulama başına 10
Metaobject alan sayısıTanım başına 20
Değer boyutu16 KB (metafield değeri ve metaobject alan değeri)
AnahtarKüçük harfle başlar; a-z, 0-9, _; en fazla 64 karakter
Anahtar tekilliğiMetafield anahtarı aynı sahip kaynakta, metaobject tanımı anahtarı mağazanın bütün nesnelerinde tekildir; mağaza ya da başka bir uygulama aynı anahtarı kullanıyorsa 422 döner, farklı bir anahtar seçin. installation tanımlarında anahtar yalnız sizin tanımlarınız arasında tekildir.

Daha büyük veri için kendi veritabanınızı kullanın ve metafield'a yalnız kimliğini yazın.

Tanımlar

Uç noktaMetotKapsam
/config/metafield-definitionsGET, POST—
/config/metafield-definitions/{id}GET, PATCH, DELETE—
POST /config/metafield-definitions
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafield-definitions \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "metafield-definitions",
      "attributes": {
        "ownerResource": "product",
        "key": "garanti_suresi",
        "name": "Garanti süresi (ay)",
        "fieldType": "number",
        "adminAccess": "read",
        "retention": "delete"
      }
    }
  }'
AlanAçıklama
ownerResourceproduct, category, order, customer, content, blog, installation. Oluşturduktan sonra değişmez.
keyAnahtar. Oluşturduktan sonra değişmez.
namePanelde görünen ad.
fieldTypeDeğer tipi (aşağıdaki tablo). Oluşturduktan sonra değişmez.
settingsTipe özgü ayarlar; seçim tiplerinde seçenekler (options).
hasLocaleDeğer dile göre ayrı tutulsun mu.
adminAccessMağaza panelinde görünürlük: hidden (görünmez), read (salt-okur, varsayılan), write (mağaza düzenleyebilir).
retentionUygulama kaldırılınca: delete (tanım ve tüm değerleri silinir, varsayılan) ya da keep (tanım ve değerler 90 gün saklanır; uygulama geri kurulursa size döner, kurulmazsa mağazaya devredilir).
storefrontAccessnone (varsayılan) ya da read. Vitrin ve tema okuması henüz açık değildir; değer saklanır.
appPrefixSalt-okur; tanımın sahibi olan uygulama.

Filtreler: id, ownerResource, key. Silinen tanımın bütün değerleri de silinir.

Değerler

Uç noktaMetotKapsam
/config/metafieldsGET, POSTSahip kaydın okuma kapsamı
/config/metafields/{id}GET, PATCH, DELETESahip kaydın okuma kapsamı

POST upsert'tür: aynı kayıt, tanım ve dil için değer varsa güncellenir, yoksa oluşturulur. İki durumda da 201 ve güncel kayıt döner.

POST /config/metafields
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafields \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "metafields",
      "attributes": {
        "ownerResource": "product",
        "ownerId": 42,
        "definitionId": 318,
        "value": 24
      }
    }
  }'
AlanAçıklama
ownerResource, ownerIdDeğerin yazıldığı kayıt.
definitionIdTanımın kimliği.
valueDeğer; metin, sayı ya da mantıksal. multiselect ve checkbox liste alır. Her zaman metin olarak döner (liste JSON metni olarak).
langCodeİsteğe bağlı dil; verilmezse mağazanın varsayılan dili.
key, fieldType, appPrefixSalt-okur; tanımdan gelir.

Bir kaydın bütün değerleri:

GET /config/metafields
curl 'https://<domain>/api/v3/admin/2026-01/config/metafields?filter[ownerResource]=product&filter[ownerId]=42' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Filtreler: id, ownerResource, ownerId (virgülle birden çok), definitionId (virgülle birden çok), key, langCode.

Değer tipleri

fieldTypeKabul edilen değer
text, textarea, editor, hidden, telMetin
number, rangeSayı
emailE-posta adresi
urlURL
dateYYYY-AA-GG
time, datetime-localMetin
colorOnaltılık renk (#1a2b3c)
checkbox, radio, selectTek değer; checkbox liste de alır
multiselectListe

Tipe uymayan değer 422 döner.

Kurulum metafield'ları

Kurulum metafield'ı bir kayda değil, uygulamanızın bu mağazadaki kurulumuna aittir. Mağazaya özgü ayarları, eşitleme durumunu ya da dış sistemdeki hesap kimliğini burada saklayın.

  • Tanımı ownerResource: "installation" ile oluşturun. adminAccess her zaman hidden, storefrontAccess her zaman none olur; başka değer 422 döner.
  • Değer yazarken ownerId göndermeyin; gönderirseniz 422 döner. Değer, isteği yapan uygulamanın kurulumuna yazılır ve yanıtta ownerId her zaman 0'dır.
  • Değerleri yalnız siz görürsünüz. Mağaza panelinde, mağazanın kendi istemcisinde ve vitrinde görünmez; başka uygulamalar okuyamaz.
  • Kapsam gerekmez. Tanım sayısı (10) ve değer boyutu (16 KB) sınırları burada da geçerlidir.
POST /config/metafields
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafields \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "metafields",
      "attributes": {
        "ownerResource": "installation",
        "definitionId": 325,
        "value": "{\"syncEnabled\":true,\"warehouseId\":3}"
      }
    }
  }'

Kurulumunuzun bütün değerleri:

GET /config/metafields
curl 'https://<domain>/api/v3/admin/2026-01/config/metafields?filter[ownerResource]=installation' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Metaobject tanımları

Uç noktaMetotKapsam
/config/metaobject-definitionsGET, POST—
/config/metaobject-definitions/{id}GET, PATCH, DELETE—

Tanımı alanlarıyla birlikte tek istekte oluşturun:

POST /config/metaobject-definitions
curl -X POST 'https://<domain>/api/v3/admin/2026-01/config/metaobject-definitions' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "metaobject-definitions",
      "attributes": {
        "key": "sss",
        "name": "Sıkça sorulan sorular",
        "fields": [
          { "key": "soru", "name": "Soru", "fieldType": "text" },
          { "key": "yanit", "name": "Yanıt", "fieldType": "textarea" },
          { "key": "sira", "name": "Sıra", "fieldType": "number" }
        ],
        "adminAccess": "read",
        "retention": "delete"
      }
    }
  }'

201 ile tanım döner:

{
  "data": {
    "type": "metaobject-definitions",
    "id": "57",
    "attributes": {
      "key": "sss",
      "name": "Sıkça sorulan sorular",
      "fields": [
        { "key": "soru", "name": "Soru", "fieldType": "text" },
        { "key": "yanit", "name": "Yanıt", "fieldType": "textarea" },
        { "key": "sira", "name": "Sıra", "fieldType": "number" }
      ],
      "appPrefix": "app.ornek-sss",
      "retention": "delete",
      "adminAccess": "read",
      "storefrontAccess": "none",
      "releasedAt": null,
      "createdAt": "2026-11-12T09:30:00.000000Z",
      "updatedAt": "2026-11-12T09:30:00.000000Z"
    }
  }
}
AlanTipAçıklama
keystringZorunlu. Tanımın anahtarı; küçük harfle başlar, a-z, 0-9, _, en fazla 64 karakter. Oluşturduktan sonra değişmez.
namestringZorunlu. Panelde görünen ad. En fazla 255 karakter.
fieldsarrayZorunlu. Alanlar; en az 1, en fazla 20. Her eleman key (anahtar kuralıyla, tanımda tekil), name ve fieldType taşır. fieldType değerleri değer tipleri tablosundakilerdir. Liste sırası alan sırasıdır.
adminAccessstringhidden, read (varsayılan) ya da write. Metafield'daki anlamıyla; write ise mağaza kayıtları panelden düzenleyebilir.
retentionstringdelete (varsayılan) ya da keep; Uygulama kaldırılınca bölümündeki gibi.
storefrontAccessstringnone (varsayılan) ya da read. Vitrin ve tema okuması henüz açık değildir; değer saklanır.
appPrefixstringSalt okunur; tanımın sahibi olan uygulama.
releasedAtdatetimeSalt okunur; uygulama kaldırılıp tanım beklemedeyse kaldırma zamanı, değilse null.

PATCH ile name, adminAccess, retention, storefrontAccess ve fields güncellenir. fields gönderirseniz liste alanların tam halidir: yeni anahtarlar eklenir, var olanların adı ve sırası güncellenir, listede olmayan alanlar kayıtlardaki değerleriyle birlikte silinir. Var olan alanın fieldType'ı değişmez; değiştirmek için alanı yeni anahtarla ekleyin.

Silinen tanımın bütün kayıtları ve değerleri de silinir. Filtreler: id, key.

fields listesini eksik gönderirseniz listede olmayan alanların değerleri geri alınamaz şekilde silinir. Alan eklerken önce tanımı GET ile okuyun, yeni alanı listenin sonuna ekleyip gönderin.

Metaobject kayıtları

Uç noktaMetotKapsam
/config/metaobjectsGET, POST—
/config/metaobjects/{id}GET, PATCH, DELETE—
POST /config/metaobjects
curl -X POST 'https://<domain>/api/v3/admin/2026-01/config/metaobjects' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "metaobjects",
      "attributes": {
        "definitionId": 57,
        "name": "Kargo süresi",
        "fields": {
          "soru": "Siparişim ne zaman kargoya verilir?",
          "yanit": "Hafta içi 14.00'e kadar verilen siparişler aynı gün kargoya verilir.",
          "sira": 1
        }
      }
    }
  }'

201 ile kayıt döner:

{
  "data": {
    "type": "metaobjects",
    "id": "903",
    "attributes": {
      "definitionId": 57,
      "name": "Kargo süresi",
      "fields": {
        "soru": "Siparişim ne zaman kargoya verilir?",
        "yanit": "Hafta içi 14.00'e kadar verilen siparişler aynı gün kargoya verilir.",
        "sira": "1"
      },
      "createdAt": "2026-11-12T09:31:00.000000Z",
      "updatedAt": "2026-11-12T09:31:00.000000Z"
    }
  }
}
AlanTipAçıklama
definitionIdintegerZorunlu. Metaobject tanımının kimliği. Oluşturduktan sonra değişmez.
namestringKaydın adı. null olabilir. En fazla 255 karakter.
fieldsobjectAlan anahtarı → değer. Değer değer tipleri tablosuna göre doğrulanır ve en fazla 16 KB'tır; değerler metin olarak döner (liste tiplerinde liste). Değeri olmayan alan nesnede yer almaz.

PATCH ile name ve fields güncellenir. fields kısmidir: yalnız gönderdiğiniz alanlar değişir, değeri null gönderilen alan silinir.

Bir tanımın bütün kayıtları:

GET /config/metaobjects
curl 'https://<domain>/api/v3/admin/2026-01/config/metaobjects?filter[definitionId]=57' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Filtreler: id (virgülle birden çok), definitionId.

Durum koduSebep
422definitionId sizin bir tanımınız değil; fields içinde tanımda olmayan anahtar; değer tipe uymuyor ya da 16 KB'ı aşıyor

Mağaza panelinde

Metafield tanımınız adminAccess değerine göre ürün, sipariş ve üye ekranlarında, metaobject tanımınız mağazanın özel nesneleri arasında görünür:

  • hidden: mağaza görmez; yalnız uygulamanızın iç verisi.
  • read: mağaza görür, değiştiremez. Panelden gelen değişiklik yok sayılır.
  • write: mağaza değeri ve metaobject kayıtlarını düzenleyebilir. Tanımı (ad, tip, alanlar, ayarlar) yine yalnız siz değiştirirsiniz.

Uygulama kaldırılınca

Bu bölüm metafield ve metaobject tanımları için aynıdır. retention: delete tanımlar bütün değerleri ve kayıtlarıyla hemen silinir. Yeniden kurduğunuzda tanımları baştan oluşturursunuz; eski değerler gelmez.

retention: keep tanımlar ve değerleri 90 gün saklanır:

  • Bu sürede tanım sizin kalır. Mağaza değerleri panelde görür ama değiştiremez; tanımı silemez. Başka uygulamalar yine göremez.
  • Uygulamanız bu sürede aynı mağazaya yeniden kurulursa tanımlar ve değerler olduğu gibi size döner; yeniden oluşturmanız gerekmez, aynı anahtarlarla çalışmaya devam edersiniz. metafield-definitions ve metaobject-definitions listelerinde hazır bulursunuz.
  • 90 gün içinde kurulmazsa tanımlar mağazaya devredilir: mağazanın kendi tanımı olur, uygulamanız artık göremez ve geri alamaz. installation tanımları devredilmez; değerleriyle birlikte silinir.

Tanımın kaldırılıp beklemede olduğu, mağazanın kendi istemcisine releasedAt alanında görünür.

Değişiklik olayı

Değer değiştiğinde metafield.updated olayı gelir. Belge, bu uçta GET ile alacağınız metafields kaydıdır; yalnız kendi tanımlarınızın değerleri için gönderilir. Değer aynı kalan yazımlar olay üretmez. installation değerlerini yalnız uygulamanız yazabildiği için bu değerler olay üretmez.

Mağaza metafield'ları

Uygulamalar mağazanın kendi metafield ve metaobject'lerini ve platformun meta verisini okuyamaz. Meta verisi taşıyan şu yollar uygulama token'ına açık değildir:

  • customer/customer-meta-fields (üye alanı tanımları): 403
  • customer/customers?filter[meta]=…: 400 (read_customers yoksa üye listesinin kendisi 403 döner)
  • order/orders/-actions/meta-fields: 403
  • config/meta-object-entries ve POST config/object-fields (mağazanın özel nesneleri): 403
  • config/objects/{id} (mağazanın özel nesnesi): 403. Bu yolun liste ucu yoktur; mağazada olmayan bir kimlik yetki denetiminden önce 404 döner.
  • cms/contents ve catalog/combines yanıtlarındaki metaFields alanı yer almaz