Meta veriler

metadata, bir nesne üzerindeki kendi anahtar-değer çiftlerinizden oluşan bir kümedir: CRM’inizdeki kaydın kimliği, nesneden sorumlu ekip, nesneyi yazan senkronizasyon çalıştırması. Sursa bu verileri saklar, nesneyle birlikte ve olaylarda döndürür ve kart, koleksiyon ve klasör listelerini bunlara göre filtrelemenizi sağlar. Bu verileri hiçbir şekilde yorumlamaz.

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

metadata alanı olan nesneler: kartlar, koleksiyonlar ve klasörler. Bir özel kaynağın belgesi de metadata taşır; bu değer belgenin kartının metadata alanı olur.

Sınırlar

Bir sınırı aşan istek api.metadata_invalid koduyla 400 döndürür. error.details.key anahtarı belirtir, error.details.reason ise neyin yanlış olduğunu söyler: too_many_keys, key_invalid, value_too_long, too_large ya da value_invalid (değer bir dize değil).

Değerler dizedir. Sayıları ve tarihleri de dize olarak saklayın, örneğin "2026-10-24".

Meta verileri ayarlama

Bir nesneyi oluşturduğunuzda ya da değiştirdiğinizde (POST, PUT) metadata bir bütün olarak ayarlanır:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

Dosya yükleme gibi bir multipart/form-data isteğinde metadata değerini, değeri JSON nesnesi olan bir form alanı olarak gönderin: metadata={"crm_id":"A-1042"}.

Meta verileri güncelleme

PATCH, gönderdiğiniz anahtarları mevcut anahtarlarla birleştirir. Değeri "" ya da null olan bir anahtar kaldırılır; göndermediğiniz anahtarlar olduğu gibi kalır:

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {} hiçbir şeyi değiştirmez. Tüm çiftleri kaldırmak için her anahtarı null değeriyle gönderin.

Meta verilere göre filtreleme

Şu listeler metadata[<key>]=<value> parametresini kabul eder:

• kartlar: GET /v1/cards ve GET /v1/cards/count;
• koleksiyonlar: GET /v1/collections;
• klasörler: GET /v1/folders ve GET /v1/collections/{name}/folders.

Bu parametre değerle tam olarak eşleşir. En fazla 3 koşulu birleştirebilirsiniz; bir nesnenin hepsini karşılaması gerekir:

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

Filtre kullanıldığında klasör ağacı düz bir liste olarak gelir: her koleksiyonun folders alanı, eşleşen klasörleri boş children ile içerir; her klasörün nerede durduğunu parent_id gösterir. Bu durumda GET /v1/folders, eşleşen klasörü olmayan koleksiyonları yanıta almaz. 3’ten fazla koşul ya da geçersiz bir anahtar api.metadata_invalid koduyla 400 döndürür.

Meta veriler ne değildir

• İçerik değildir. Arama ve asistanın yanıtları meta verileri kullanmaz. İnsanların bulması gerekenleri kartın metnine, başlığına ya da etiketlerine yazın.
• Erişimi kısıtlı değildir. Nesneyi görebilen herkes meta verilerini de görebilir. Nesnenin okurlarının görmemesi gereken gizli değerleri, belirteçleri ya da kişisel verileri hiçbir zaman burada saklamayın.
• external_id alanının yerini tutmaz. Bir kartı kaydınızın kimliğiyle bulmak için karta bir external_id verin; bu değer benzersizdir, meta veri değerleri ise değildir.