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

نقاط نهاية قوائم الكتالوغ — /v1/products و/v1/orders و/v1/customers و/v1/customers/{id}/orders و/v1/landing-pages — تستخدم ترقيم المؤشّر. الـ offsets غير مدعومة عمدًا.

الطلب:

GET /v1/products?limit=50&cursor=<opaque>

الاستجابة:

{ "data": {
    "items": [...],
    "next_cursor": "MTIz",
    "has_more": true
  } }

إذا كانت قيمة has_more تساوي false فقد انتهيت من قراءة كل الموارد.

القيمة الافتراضية لـlimit هي 50 وتُقصَر ضمن المجال 1–200: أي قيمة خارج المجال أو غير رقمية تُعدَّل بصمت ولا تُرفض. وتسير الصفحات من الأحدث إلى الأقدم، لذا يشير المؤشّر إلى آخر عنصر استلمته.

المؤشّر التالف يُتجاهَل بصمت

قيمة cursor المبتورة أو التالفة لا تُرجع bad_request — بل تُهمَل وتبدأ القائمة من جديد عند أحدث سجل. تعامل مع الرمز على أنه غير شفاف تمامًا، وأعِده كما هو بايتًا ببايت، وتوقّف عندما تصبح has_more تساوي false؛ وإلا فإن أي عميل يشوّه الرمز سيعيد جلب الصفحة الأولى إلى ما لا نهاية.

نقاط نهاية لا تستخدم ترقيم المؤشّر

• GET /v1/keys وGET /v1/webhooks تُرجعان مصفوفة items كاملة دون next_cursor أو has_more.
• GET /v1/usage/history يعتمد على مجال زمني عبر from وto (90 يومًا كحد أقصى) ويُرجع rows.