تتبع النشاط: واجهة برمجة البرنامج الوكيل (للمطورين)

هذا الدليل للمطورين. تتحدث برامج Kaam360 الوكيلة لسطح المكتب مع Kaam360 عبر واجهة ويب صغيرة على /api/agent/v1. وصفها الكامل لأدوات مثل Postman موجود على /api/agent/v1/openapi.json. طريقة ضبط التتبع في Kaam360 موجودة في دليل تتبع النشاط.

قواعد كل طلب

• عبر HTTPS فقط. يُرفض HTTP العادي.
• أرسل JSON (Content-Type: application/json)، باستثناء لقطات الشاشة التي تُرفع كنموذج.
• بعد التسجيل، أرسل مفتاح الجهاز في كل طلب على شكل Authorization: Bearer متبوعًا بالمفتاح (يبدأ بـ kad_). احفظه في المخزن الآمن للنظام (Windows DPAPI، سلسلة مفاتيح macOS). لا يحتفظ Kaam360 إلا ببصمة له.
• الردود على شكل { "data": ... }. الرفض على شكل { "error": { "code", "message" } } مع حالة HTTP: ‏401 لمفتاح خاطئ أو ملغى (سجّل من جديد)، و403 لجهاز موقوف مؤقتًا أو ميزة متوقفة، و413 لكمية كبيرة دفعة واحدة، و422 لحقل خاطئ، و429 لطلبات كثيرة جدًا (انتظر الثواني في Retry-After).
• لا ترسل أبدًا ضغطات المفاتيح أو النص المكتوب أو كلمات المرور أو محتوى الرسائل والمستندات. ومن المواقع أرسل النطاق فقط.

1. التسجيل: POST /register

أرسل رمز التسجيل من الأجهزة، ومعرّفك الخاص لهذا التثبيت (installId، يُنشأ مرة ويُحفظ)، واسم الجهاز، وos (‏windows أو macos)، وosVersion، وagentVersion، وبريد العمل للشخص إن كنت تعرفه. يحتوي الرد على مفتاح الجهاز (يظهر هذه المرة فقط) والقواعد. يأتي من العنوان الواحد 20 تسجيلًا في الساعة على الأكثر.

2. الاتصال: POST /heartbeat

كل heartbeatSeconds (خمس دقائق افتراضيًا) أرسل agentVersion وساعة الجهاز (sentAtUtc) وعدد الفترات المنتظرة. يحتوي الرد على القواعد الحالية (policy) وهل الجهاز موقوف مؤقتًا أو بلا شخص بعد. استخدم GET /policy لقراءة القواعد فقط.

تخبر القواعد البرنامج الوكيل بـ: trackingEnabled (لا تسجّل شيئًا عندما تكون false)، وworkHoursOnly مع workStart وworkEnd وworkDays والمنطقة الزمنية، وneverRecord (البرامج والنطاقات التي تُتخطى)، وrecordTitles، وscreenshots (‏enabled وintervalMinutes وblur وmaxBytes)، وidleMinutes، وuploadBatchSize، وmaxBatchSlices، وmaxBufferDays، وnoticeText (اعرضه عند أول تشغيل ومن الأيقونة)، وminAgentVersion.

3. إرسال النشاط: POST /activity

أرسل batchId خاصًا بك وsentAtUtc وما يصل إلى 1000 فترة (1 ميغابايت على الأكثر). لكل فترة start وend (‏UTC) وapp (البرنامج) وtitle (فقط عند تشغيل recordTitles) وdomain وidle. إرسال batchId نفسه مرة أخرى لا يفعل شيئًا، فأعد المحاولة بلا قلق بعد انقطاع الاتصال. يقول الرد كم فترة حُفظت ولماذا استُبعدت غيرها: tracking_off أو no_person أو invalid أو too_long (أكثر من 4 ساعات) أو future أو too_old (أقدم من 14 يومًا) أو never_record أو outside_hours. تُصحَّح ساعة الجهاز المنحرفة أكثر من دقيقة؛ وتُرفض إذا انحرفت أكثر من يوم.

4. إرسال لقطة شاشة: POST /screenshots

فقط عند تشغيل لقطات الشاشة. رفع نموذج فيه file (‏JPEG أو PNG أو WebP، 1 ميغابايت على الأكثر) وtakenAtUtc وapp وdomain وblurred. موّه الصورة أولًا عند تشغيل blur: تُرفض الصورة الواضحة. لا تتجاوز التكرار المحدد. لا تُحفظ لقطة لبرنامج في قائمة عدم التسجيل أو خارج ساعات العمل.

دون اتصال

احفظ الفترات على الجهاز ما دام لا يوجد اتصال (مشفّرة، لمدة maxBufferDays على الأكثر) وأرسلها على دفعات عند عودته.

5. التحديثات: GET /update

استدعِ GET /update مرة في اليوم مع os (windows أو macos) وإصدار البرنامج الوكيل. يتضمن الرد latestVersion وdownloadUrl وsha256 وsizeBytes وupdateAvailable وupdateRequired (البرنامج الوكيل أقدم من أدنى إصدار تقبله المؤسسة). نزّل فقط من downloadUrl على عنوان Kaam360 نفسه، وتحقق من حجم الملف وبصمة SHA-256 وتوقيع الشيفرة قبل تشغيله. أحدث مثبّت متاح أيضًا للجميع على /download/agent/windows (إنه برنامج وليس بيانات: ما يربط الجهاز هو رمز التسجيل). حزمة Mac (‏.pkg) على /download/agent/macos؛ على جهاز Mac تحقق من أن الملف يبدأ بـ xar! وأن pkgutil --check-signature يُظهر الفريق نفسه إذا كان تطبيقك موقّعًا بمعرّف Apple Developer ID.

البرنامج الوكيل لنظام Windows الذي بناه Kaam360 يتبع كل ذلك؛ شيفرته في مجلد agents في شيفرة Kaam360 المصدرية، ويصفه الملف docs/activity-agent.md.