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

للتنقل بين النتائج، كرر الطلب مع cursor=<next_cursor> والمرشحات نفسها حتى تصبح has_more هي false. المؤشر معتم ومبني على مجموعة المفاتيح، لذا لا تسبب المعاملات الجديدة الواصلة أثناء المزامنة أي تخطٍّ أو تكرار.

تستخدم نقطة نهاية المعاملات ترقيم صفحات بالمؤشر (keyset). تتضمن كل استجابة كائن pagination:

{
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "eyJ0IjoiMjAyNi0wOS0yMFQwODo1OTozNi4zNDBaIiwiaWQiOjE4NTQzMn0"
  }
}

كيف أتنقل بين الصفحات؟Copy Anchor Link

1. نفّذ الطلب الأول بمرشحاتك دون cursor.
2. طالما has_more هي true، كرر الطلب بالمرشحات نفسها وcursor=<next_cursor>.
3. توقف عندما تصبح has_more هي false.

تُرتَّب النتائج الأحدث أولًا حسب created_at ثم id. ولأن المؤشر يشفّر موضع آخر سجل لا إزاحة رقمية، فإن المعاملات الواصلة أثناء التنقل لا تسبب تخطي سجلات أو تكرارها.

القواعدCopy Anchor Link

• تعامل مع المؤشر كقيمة معتمة. قد تتغير صيغته؛ لا تحلّله ولا تبنِه.
• مرر دائمًا قيم from وto وcorporate_id وcorporate_group_id وstatus نفسها مع كل صفحة. المؤشر لا معنى له إلا للاستعلام الذي أنتجه.
• استخدم limit=100 للمزامنات الكبيرة لتقليل عدد الطلبات مقابل حد المعدل.

مثال: جلب نطاق كاملCopy Anchor Link

async function* transactions(apiKey, filters) {
  const base = 'https://prod-app.octanetech-api.com/api/v1/integration/transactions';
  let cursor;

  do {
    const url = new URL(base);
    for (const [k, v] of Object.entries(filters)) url.searchParams.set(k, String(v));
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });
    if (!res.ok) throw new Error(`Octane API ${res.status}: ${await res.text()}`);

    const { data, pagination } = await res.json();
    yield* data;
    cursor = pagination.has_more ? pagination.next_cursor : undefined;
  } while (cursor);
}

for await (const tx of transactions(process.env.OCTANE_API_KEY, {
  from: '2026-09-01T00:00:00Z',
  to: '2026-09-30T23:59:59Z',
})) {
  console.log(tx.id, tx.status, tx.fees.total_amount);
}

كيف أجلب أكثر من 31 يومًا؟Copy Anchor Link

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

function* windows(from, to, days = 31) {
  let start = new Date(from);
  const end = new Date(to);
  while (start < end) {
    const next = new Date(Math.min(start.getTime() + days * 86_400_000, end.getTime()));
    yield [start.toISOString(), next.toISOString()];
    start = next;
  }
}