المفاهيم

الصفحات والمزامنة

تأتي القوائم صفحة بعد صفحة، الأحدث أولًا. وupdatedSince يُبقي نظامًا آخر متزامنًا.

الصفحات

تجيب القائمة بـ { "data": [...], "next": "<cursor>" }. أرسل ?cursor=<next> للصفحة التالية، حتى تصبح next قيمة null. و?limit= من 1 إلى 200، و50 افتراضيًا. والمؤشّر الذي لم تعطه الواجهة يُرفض 400 CURSOR_INVALID.

عوامل التصفية

تقبل كل قائمة التصفية بـ updatedSince وcreatedFrom وcreatedTo وexternalId، وبحقولها الخاصة — قائمة المستندات بـ status وpartnerId وissueFrom وissueTo وnumber، وجهات الاتصال بـ type وsearch وactive.

مزامنة نظام آخر

لا ترسل KWN التغييرات إلى نظامك من تلقاء نفسها: اقرأها أنت. احفظ لحظة بدء آخر مزامنة، ثم اعرض القائمة مع updatedSince قبلها بدقيقة أو اثنتين — فالتداخل الصغير يكلّف بضعة صفوف مكررة ولا يفوّت أيًا منها. حدّث أو أضف بحسب id.

let cursor = null;
do {
  const url = new URL('https://app.kwn.tax/api/v1/invoices');
  url.searchParams.set('limit', '200');
  url.searchParams.set('updatedSince', lastSync);   // an instant, UTC
  if (cursor) url.searchParams.set('cursor', cursor);
  const res = await fetch(url, { headers: { 'X-Api-Key': process.env.KWN_API_KEY } });
  const { data, next } = await res.json();
  for (const invoice of data) upsert(invoice);
  cursor = next;
} while (cursor);

القراءة كل بضع دقائق تكفي لمعظم الأنظمة، وتبقى ضمن حدود المعدل بسهولة.