الترقيم (Pagination)

تُعيد نقاط نهاية القوائم في API البيانات بالصفحات. تاريخياً تتوفر في المنصة مخططان للترقيم؛ المخطط المحدد موضح في كل نقطة نهاية ضمن المرجع التفاعلي.

المخطط 1 — الإزاحة وX-Total-Count

ترقيم كلاسيكي بالإزاحة. يقبل الطلب معاملَي query: limit (حجم الصفحة) وoffset (عدد السجلات المتخطاة):

curl -H "Authorization: Bearer mbp_رمزك" "https://نطاقك/api/bots/BOT_ID/subscribers?limit=50&offset=100"

يُعاد العدد الإجمالي للسجلات في ترويسة الاستجابة X-Total-Count. يُحسَب عدد الصفحات منها: تصفح بزيادة offset بمقدار limit ما دام offset أصغر من قيمة X-Total-Count. جسم الاستجابة هو مصفوفة عناصر الصفحة الحالية.

المخطط 2 — المؤشر before وhas_more

ترقيم بالمؤشر للتدفقات المرتبة زمنياً (مثلاً رسائل المحادثة). يقبل الطلب limit ومؤشراً اختيارياً before — معرّف أو علامة العنصر الأخير المستلَم:

curl -H "Authorization: Bearer mbp_رمزك" "https://نطاقك/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

تحتوي الاستجابة على صفحة من العناصر وعلامة has_more. طالما has_more تساوي true، كرّر الطلب ممرراً في before مؤشر آخر عنصر مستلَم. حين تصبح has_more تساوي false — هذه هي الصفحة الأخيرة.

اختيار المخطط

لا تختار المخطط — تحدده نقطة النهاية. القوائم المرجعية عادةً تستخدم الإزاحة وX-Total-Count؛ التدفقات الزمنية تستخدم المؤشر before وhas_more. راجع دائماً صفحة نقطة النهاية في المرجع.

الخطوات التالية