المرجع، وبيئة اختبار تلتزم به.

المصادقة

مفتاح واحد لكل تكامل، ينشئه مسؤول، ولا يحمل إلا الصلاحيات التي يحتاجها. توضع المفاتيح في الترويسة، وأي مفتاح يظهر في URL يعد مسربا ويلغى.

curl https://api.nml.sa/fleet/v1/vehicles \
  -H "Authorization: Bearer $SAQR_KEY"

الصلاحيات

• read:fleet
• write:drivers
• write:jobs
• write:geofences
• write:webhooks
• read:exports

يمكن منح صلاحيات الكتابة في أي باقة، لكنها لا تعمل إلا في Command؛ وفي غيرها تعيد plan_required.

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

مؤشرات cursor، لا أرقام صفحات. المؤشر يحدد موضعا في التدفق، فالصفوف التي تصل أثناء تنقلك بين الصفحات، كتعبئة لاحقة بعد منطقة بلا تغطية، تأتي بعد المؤشر بدلا من أن تزيح كل صفحة صفا واحدا.

let since = localStorage.cursor;          // or wherever you keep it
let page;
do {
  const r = await fetch(`https://api.nml.sa/fleet/v1/positions?limit=1000${since ? "&since=" + since : ""}`,
    { headers: { Authorization: `Bearer ${key}` } });
  if (r.status === 429) { await sleep(Number(r.headers.get("Retry-After")) * 1000); continue; }
  page = await r.json();
  await save(page.data);                   // save first…
  since = localStorage.cursor = page.next; // …then move the cursor
} while (page.has_more);

احفظ الصفوف قبل أن تحفظ المؤشر. العكس يضيع صفحة كلما توقفت العملية بين الخطوتين.