ترقيم الصفحات

تُقسَّم قوائم واجهة Sursa API إلى صفحات باستخدام مؤشر: تطلب ما يصل إلى limit من العناصر، وتخبرك الاستجابة بكيفية الحصول على الصفحة التالية. لا تحسب الإزاحات أبدًا، ولا تتكرر العناصر ولا تضيع بين الصفحات إذا تغيّرت البيانات في أثناء ذلك.

تعيد القائمة مؤشرها التالي بإحدى طريقتين، بحسب شكل استجابتها. وتبيّن صفحة كل نقطة نهاية في مرجع API أيهما تستخدم.

القوائم ذات غلاف data

تعيد القوائم المضافة لواجهة API العامة، مثل سجل الأحداث، كائنًا فيه العناصر داخل data:

curl "https://api.sursa.com/v1/webhook-events?limit=2" \
  -H "Authorization: Bearer $SURSA_API_KEY"

{
  "data": [
    {"id": "evt_8a1f…", "type": "card.published", "created_at": "2026-10-24T10:00:00Z"},
    {"id": "evt_8a20…", "type": "card.updated", "created_at": "2026-10-24T10:00:03Z"}
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbMTA0Ml19",
  "has_more": true
}

حين تكون قيمة has_more هي true، اطلب الصفحة التالية مع cursor بقيمة next_cursor وعوامل التصفية نفسها:

curl "https://api.sursa.com/v1/webhook-events?limit=2&cursor=eyJ2IjoxLCJrIjpbMTA0Ml19" \
  -H "Authorization: Bearer $SURSA_API_KEY"

القوائم التي وُجدت قبل المؤشرات وتعيد كائنًا تحتفظ بغلافها الخاص (مثل {"items": […], "total": 120}). ويُضاف إليها next_cursor وhas_more في الكائن نفسه، وتبقى العناصر في مكانها.

القوائم التي تعيد مصفوفة

قلة من القوائم تعيد مصفوفة JSON مجردة، مثل GET /v1/collections. ولا يمكن تغيير شكل استجابتها، لذا تأتي الصفحة التالية في الترويسات بدلًا من ذلك:

curl -i "https://api.sursa.com/v1/collections?limit=50" \
  -H "Authorization: Bearer $SURSA_API_KEY"

HTTP/1.1 200 OK
Link: <https://api.example.com/v1/collections?limit=50&cursor=eyJ2IjoxLCJrIjpbNTBdfQ>; rel="next"
X-Next-Cursor: eyJ2IjoxLCJrIjpbNTBdfQ

[{"id": 1, "name": "support", …}, …]

• الترويسة Link مع rel="next" هي العنوان الكامل للصفحة التالية؛ وX-Next-Cursor هي المؤشر نفسه وحده.
• غياب Link مع rel="next" وغياب X-Next-Cursor يعنيان أن هذه هي الصفحة الأخيرة.
• بلا limit، تعيد هذه القوائم كل العناصر في استجابة واحدة، كما كانت تفعل دائمًا. مرّر limit لتقسيمها إلى صفحات؛ فالمؤشر يتذكر حجم الصفحة، ويمكن للطلب التالي ألا يرسل limit.
• العملية GET /v1/cards استثناء: فهي تعيد صفحات دائمًا، 200 بطاقة افتراضيًا وحتى 1000 مع limit، لذا اتبع X-Next-Cursor حتى بلا limit.

// Every item of a list that returns an array.
async function* listArray(path) {
  let next = `https://api.sursa.com${path}?limit=200`;
  while (next) {
    const response = await fetch(next, { headers: { Authorization: `Bearer ${process.env.SURSA_API_KEY}` } });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    yield* await response.json();
    const cursor = response.headers.get("X-Next-Cursor");
    next = cursor ? `https://api.sursa.com${path}?cursor=${encodeURIComponent(cursor)}` : null;
  }
}

سجل الأحداث

سجل الأحداث GET /v1/webhook-events قائمة متتابعة زمنيًا، لذا يُقسَّم إلى صفحات بطريقة مختلفة قليلًا:

• الأحداث بترتيب تصاعدي، الأقدم أولًا.
• يُعاد next_cursor في كل صفحة، حتى حين تكون قيمة has_more هي false. احفظه، واطلب لاحقًا بالمؤشر نفسه لتحصل على الأحداث التي وقعت منذ ذلك الحين. فالسجل قائمة انتظار تقرؤها بالوتيرة التي تناسبك.
• يظهر الحدث في السجل خلال ثانية تقريبًا من التغيير الذي يصفه، ولا يظهر أبدًا قبل حدث سبقت قراءته.
• يضم السجل أحداث المؤسسة كلها، لذا تتطلب قراءته مفتاحًا بالدور admin والنطاق webhooks:manage.

يعرض دليل التصدير إلى مستودع البيانات حلقة استطلاع كاملة.

قواعد المؤشرات

• المؤشر سلسلة نصية غير شفافة حتى 512 حرفًا. لا تحلّله ولا تبنِه بنفسك: فصيغته قد تتغيّر.
• يخص المؤشر قائمة واحدة وعوامل تصفية محددة. والمؤشر التالف، أو الآتي من قائمة أخرى، أو المرسَل مع عوامل تصفية مختلفة يعيد الحالة 400 مع الرمز api.cursor_invalid.
• لكل قائمة ترتيب فرز ثابت ينتهي بمفتاح فريد، فيظهر كل عنصر في صفحة واحدة بالضبط.
• القوائم المضافة بالمؤشرات لا تعيد العدد الإجمالي؛ أما القوائم التي كان لها الحقل total من قبل فتحتفظ به. عُدّ العناصر أثناء القراءة إن احتجت إلى الإجمالي.

ترقيم الصفحات بالإزاحة

بعض القوائم كانت تقبل offset قبل إدخال المؤشرات، ولا تزال تقبله، كي تبقى التكاملات القائمة عاملة. فضّل cursor في الشيفرة الجديدة. ولا يمكن الجمع بين offset وcursor: إرسالهما معًا يعيد الحالة 422 مع الرمز validation.failed.