البيانات الوصفية

الحقل metadata هو أزواج مفتاح وقيمة خاصة بك على الكائن: معرّف السجل في نظام CRM لديك، والفريق المسؤول عنه، وتشغيل المزامنة الذي كتبه. يحفظها Sursa ويعيدها مع الكائن وفي الأحداث، ويتيح لك تصفية قوائم البطاقات والمجموعات والمجلدات بها، ولا يفسّرها بأي شكل.

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

الكائنات التي لها metadata: البطاقات والمجموعات والمجلدات. ويحمل مستند المصدر المخصص الحقل metadata أيضًا، فيصبح الحقل metadata لبطاقة المستند.

الحدود

الطلب الذي يتجاوز حدًا يعيد الحالة 400 مع الرمز api.metadata_invalid. يذكر الحقل error.details.key المفتاح، ويبيّن الحقل error.details.reason الخطأ: too_many_keys، أو key_invalid، أو value_too_long، أو too_large، أو value_invalid (القيمة ليست سلسلة نصية).

القيم سلاسل نصية. احفظ الأرقام والتواريخ أيضًا سلاسلَ نصية، مثل "2026-10-24".

تعيين البيانات الوصفية

حين تنشئ كائنًا أو تستبدله (POST أو PUT)، يُعيَّن الحقل metadata كاملًا:

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"}
  }'

في الطلب multipart/form-data، مثل رفع ملف، أرسل metadata حقلًا في الاستمارة قيمته كائن JSON: metadata={"crm_id":"A-1042"}.

تحديث البيانات الوصفية

يدمج الطلب PATCH المفاتيح التي ترسلها في المفاتيح الموجودة. والمفتاح بالقيمة "" أو null يُحذف، والمفاتيح التي لا ترسلها تبقى كما هي:

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": {} لا تغيّر شيئًا. ولحذف كل الأزواج، أرسل كل مفتاح بالقيمة null.

التصفية بالبيانات الوصفية

تقبل هذه القوائم المعامل metadata[<key>]=<value>:

• البطاقات: GET /v1/cards وGET /v1/cards/count؛
• المجموعات: GET /v1/collections؛
• المجلدات: GET /v1/folders وGET /v1/collections/{name}/folders.

وهو يطابق القيمة تمامًا. يمكنك جمع ما يصل إلى 3 شروط، ويجب أن يطابقها الكائن كلها:

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"

مع عامل التصفية، تصل شجرة المجلدات قائمةً مسطحة: يحمل الحقل folders لكل مجموعة المجلداتِ المطابقة بحقل children فارغ، ويبيّن الحقل parent_id موضع كل منها. وعندها لا تعيد العملية GET /v1/folders المجموعات التي لا مجلدات مطابقة فيها. ويعيد أكثر من 3 شروط، أو مفتاح غير صالح، الحالة 400 مع الرمز api.metadata_invalid.

ما لا تصلح له البيانات الوصفية

• ليست محتوى. لا يستخدمها البحث ولا إجابات المساعد. ضع ما ينبغي أن يجده الناس في نص البطاقة أو عنوانها أو وسومها.
• ليست خاصة. كل من يرى الكائن يرى بياناته الوصفية. لا تحفظ فيها أبدًا أسرارًا أو رموز وصول أو بيانات شخصية لا ينبغي أن يراها قرّاء الكائن.
• ليست بديلًا عن external_id. للعثور على بطاقة بمعرّف سجلك، أعطِ البطاقة قيمة external_id، فهي فريدة، بخلاف قيم البيانات الوصفية.