Aktivitätserfassung: die Agent-API (für Entwickler)

Diese Anleitung ist für Entwickler. Die Kaam360-Desktop-Agenten sprechen über eine kleine Web-API unter /api/agent/v1 mit Kaam360. Ihre vollständige Beschreibung für Werkzeuge wie Postman liegt unter /api/agent/v1/openapi.json. Wie Sie die Erfassung in Kaam360 einrichten, steht in der Anleitung zur Aktivitätserfassung.

Regeln für jeden Aufruf

• Nur über HTTPS. Einfaches HTTP wird abgelehnt.
• Senden Sie JSON (Content-Type: application/json), außer Screenshots, die als Formular hochgeladen werden.
• Senden Sie nach der Anmeldung bei jedem Aufruf den Geräteschlüssel als Authorization: Bearer, gefolgt vom Schlüssel (er beginnt mit kad_). Bewahren Sie ihn im sicheren Speicher des Systems auf (Windows DPAPI, macOS-Schlüsselbund). Kaam360 speichert nur einen Fingerabdruck davon.
• Antworten sind { "data": ... }. Eine Ablehnung ist { "error": { "code", "message" } } mit einem HTTP-Status: 401 für einen falschen oder widerrufenen Schlüssel (neu anmelden), 403 für einen pausierten Computer oder eine ausgeschaltete Funktion, 413 für zu viel auf einmal, 422 für ein falsches Feld, 429 für zu viele Aufrufe (warten Sie die Sekunden aus Retry-After).
• Senden Sie nie Tastenanschläge, getippten Text, Passwörter oder den Inhalt von Nachrichten und Dokumenten. Senden Sie von einer Website nur die Domain.

1. Anmelden: POST /register

Senden Sie den Anmeldecode aus Geräte, Ihre eigene ID für diese Installation (installId, einmal erzeugt und behalten), den Namen des Computers, os (windows oder macos), osVersion, agentVersion und, falls bekannt, die geschäftliche E-Mail der Person. Die Antwort enthält den Geräteschlüssel (nur dieses eine Mal angezeigt) und die Regeln. Von einer Adresse kommen höchstens 20 Anmeldungen pro Stunde.

2. Melden: POST /heartbeat

Senden Sie alle heartbeatSeconds (standardmäßig fünf Minuten) agentVersion, die Uhr des Computers (sentAtUtc) und wie viele Abschnitte warten. Die Antwort enthält die aktuellen Regeln (policy) und ob der Computer pausiert ist oder noch keine Person hat. Mit GET /policy lesen Sie nur die Regeln.

Die Regeln sagen dem Agenten: trackingEnabled (bei false nichts erfassen), workHoursOnly mit workStart, workEnd, workDays und der Zeitzone, neverRecord (zu überspringende Programme und Domains), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (beim ersten Start und über das Symbol anzeigen) und minAgentVersion.

3. Aktivität senden: POST /activity

Senden Sie eine eigene batchId, sentAtUtc und bis zu 1000 Abschnitte (höchstens 1 MB). Jeder Abschnitt hat start und end (UTC), app (das Programm), title (nur wenn recordTitles an ist), domain und idle. Dieselbe batchId noch einmal zu senden bewirkt nichts, wiederholen Sie also ruhig nach einer verlorenen Verbindung. Die Antwort sagt, wie viele gespeichert wurden und warum andere verworfen wurden: tracking_off, no_person, invalid, too_long (mehr als 4 Stunden), future, too_old (älter als 14 Tage), never_record oder outside_hours. Eine Computeruhr, die mehr als eine Minute falsch geht, wird korrigiert; mehr als einen Tag wird abgelehnt.

4. Einen Screenshot senden: POST /screenshots

Nur wenn Screenshots eingeschaltet sind. Ein Formular-Upload mit file (JPEG, PNG oder WebP, höchstens 1 MB), takenAtUtc, app, domain und blurred. Machen Sie das Bild zuerst unscharf, wenn blur an ist: Ein scharfes wird abgelehnt. Nicht öfter als das Intervall. Ein Screenshot eines Nie-erfassen-Programms oder außerhalb der Arbeitszeit wird nicht gespeichert.

Offline

Bewahren Sie Abschnitte ohne Verbindung auf dem Computer auf (verschlüsselt, höchstens maxBufferDays lang) und senden Sie sie in Stapeln, sobald die Verbindung wieder da ist.

5. Updates: GET /update

Rufen Sie einmal am Tag GET /update mit os (windows oder macos) und der Version des Agenten auf. Die Antwort enthält latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable und updateRequired (der Agent ist älter als die niedrigste Version, die die Organisation zulässt). Laden Sie nur von der downloadUrl unter derselben Kaam360-Adresse herunter, prüfen Sie Größe und SHA-256-Fingerabdruck der Datei und ihre Codesignatur, bevor Sie sie ausführen. Das neueste Installationsprogramm liegt für alle auch unter /download/agent/windows (es ist ein Programm, keine Daten: Erst ein Anmeldecode verbindet einen Computer). Das Mac-Paket (.pkg) liegt unter /download/agent/macos; prüfen Sie beim Mac, dass die Datei mit xar! beginnt und, wenn Ihre App mit einer Apple Developer ID signiert ist, dass pkgutil --check-signature dasselbe Team zeigt.

Der von Kaam360 gebaute Windows-Agent hält sich an all das; sein Code liegt im Ordner agents des Kaam360-Quellcodes, und docs/activity-agent.md beschreibt ihn.