معرّفات الكائنات

لكل كائن في واجهة API حقل id. احفظه في نظامك حين تحتاج إلى العودة إلى الكائن: فالأسماء والعناوين قد تتغير، أما المعرّفات فلا تتغير أبدًا.

تعامل مع المعرّفات على أنها غير شفافة. لا تحلّلها، ولا تفترض لها صيغة غير نوعها: المعرّف النصي قد يكون أي سلسلة نصية، بالطول الذي يسمح به حقله.

أنواع الكائنات الجديدة التي يُرجَّح أن تشير إليها من أنظمتك تحصل على معرّفات نصية ببادئة قصيرة تدل على النوع، يليها 32 حرفًا ست عشريًا.

الإشارات بين الكائنات

تشير الكائنات بعضها إلى بعض بالمعرّف، في حقول أسماؤها على النمط <object>_id: collection_id، وowner_id، وfolder_id. وللحصول على الكائن المرتبط في الاستجابة نفسها، استخدم expand[].

ومعاملات المسار التي تأخذ معرّفًا تُسمّى بالطريقة نفسها: {card_id}، و{webhook_id}، و{upload_id}.

المجموعات بالمعرّف

للمجموعات معرّف id واسم فريد name، مثل support. والمسارات التي وُجدت قبل أن تصبح المعرّفات هي المفضلة تأخذ اسم المجموعة:

GET /v1/collections/support/stats

وتقبل المسارات نفسها المعرّف أيضًا، مكتوبًا بالصيغة id:<number>:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

فضّل الصيغة id: في الشيفرة الجديدة: يستطيع المشرف تغيير اسم المجموعة، لكن معرّفها يبقى كما هو. أما جزء المسار المؤلف من أرقام فقط، مثل /v1/collections/3، فلا يزال يعني المجموعة التي اسمها 3. ولا يمكن أن يحتوي اسم المجموعة على :، فلا تختلط الصيغتان أبدًا.

في نصوص الطلبات ومعاملات الاستعلام، يقف الحقل collection_id إلى جانب الحقل الأقدم collection (الاسم). وإذا مرّرت الاثنين، يُعتمد collection_id. والقيمة collection_id غير الموجودة في المؤسسة، أو التي لا يُسمح للمفتاح برؤيتها، تعيد الحالة 404 مع الرمز collections.not_found.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

معرّفاتك الخاصة

يمكن أن تحمل البطاقات في الحقل external_id معرّف السجل الذي جاءت منه في نظامك: حتى 512 حرفًا، وهو فريد بين بطاقات المؤسسة. وبه لن تحتاج أبدًا إلى حفظ معرّف البطاقة في Sursa:

طبّق ترميز URL على external_id حين يكون جزءًا من المسار: تصبح crm/A-1042 بالصيغة crm%2FA-1042.

لمستندات المصدر المخصص قيمة external_id خاصة بها داخل مصدرها. ولا يتعارض الاثنان: تُغيَّر بطاقة المصدر المخصص بإرسال المستند إلى مصدره مرة أخرى، لا بالعملية PUT /v1/cards-by-external-id/…، التي تجيب في هذه الحالة بالحالة 409 مع الرمز cards.managed_by_source.