Suivi d'activité : l'API de l'agent (pour les développeurs)

Ce guide s'adresse aux développeurs. Les agents de bureau Kaam360 communiquent avec Kaam360 par une petite API web à l'adresse /api/agent/v1. Sa description complète, pour des outils comme Postman, se trouve à /api/agent/v1/openapi.json. La configuration du suivi dans Kaam360 est décrite dans le guide du suivi d'activité.

Règles pour chaque appel

• Uniquement en HTTPS. Le HTTP simple est refusé.
• Envoyez du JSON (Content-Type: application/json), sauf pour les captures d'écran, qui sont un envoi de formulaire.
• Après l'inscription, envoyez la clé de l'appareil à chaque appel sous la forme Authorization: Bearer suivi de la clé (elle commence par kad_). Conservez-la dans le magasin sécurisé du système (Windows DPAPI, le trousseau macOS). Kaam360 n'en conserve qu'une empreinte.
• Les réponses sont { "data": ... }. Un refus est { "error": { "code", "message" } } avec un statut HTTP : 401 pour une clé erronée ou révoquée (réinscrivez-vous), 403 pour un ordinateur en pause ou une fonction désactivée, 413 pour un envoi trop volumineux, 422 pour un champ erroné, 429 pour trop d'appels (attendez le nombre de secondes indiqué dans Retry-After).
• N'envoyez jamais de frappes au clavier, de texte saisi, de mots de passe ni le contenu de messages et de documents. N'envoyez que le domaine d'un site web.

1. S'inscrire : POST /register

Envoyez le code d'inscription obtenu sur Appareils, votre propre identifiant pour cette installation (installId, créé une fois et conservé), le nom de l'ordinateur, os (windows ou macos), osVersion, agentVersion et, si vous le connaissez, l'e-mail professionnel de la personne. La réponse contient la clé de l'appareil (affichée cette seule fois) et les règles. Au plus 20 inscriptions par heure peuvent provenir d'une même adresse.

2. Se signaler : POST /heartbeat

Tous les heartbeatSeconds (cinq minutes par défaut), envoyez agentVersion, l'heure de l'ordinateur (sentAtUtc) et le nombre de tranches en attente. La réponse contient les règles en vigueur (policy) et indique si l'ordinateur est en pause ou n'a pas encore de personne. Utilisez GET /policy pour ne lire que les règles.

Les règles indiquent à l'agent : trackingEnabled (ne rien enregistrer si false), workHoursOnly avec workStart, workEnd, workDays et le fuseau horaire, neverRecord (programmes et domaines à ignorer), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (à afficher au premier démarrage et depuis l'icône de la zone de notification) et minAgentVersion.

3. Envoyer l'activité : POST /activity

Envoyez un batchId de votre choix, sentAtUtc et jusqu'à 1000 tranches (1 Mo au maximum). Chaque tranche comporte start et end (UTC), app (le programme), title (uniquement si recordTitles est activé), domain et idle. Renvoyer le même batchId ne fait rien : vous pouvez donc réessayer sans crainte après une perte de connexion. La réponse indique combien de tranches ont été conservées et pourquoi les autres ont été écartées : tracking_off, no_person, invalid, too_long (plus de 4 heures), future, too_old (plus de 14 jours), never_record ou outside_hours. Une horloge d'ordinateur décalée de plus d'une minute est corrigée ; décalée de plus d'un jour, elle est refusée.

4. Envoyer une capture d'écran : POST /screenshots

Uniquement lorsque les captures d'écran sont activées. Un envoi de formulaire avec file (JPEG, PNG ou WebP, 1 Mo au maximum), takenAtUtc, app, domain et blurred. Floutez d'abord l'image lorsque blur est activé : une image nette est refusée. Pas plus souvent que l'intervalle. Une capture d'un programme à ne jamais enregistrer ou prise en dehors des heures de travail n'est pas conservée.

Hors ligne

Conservez les tranches sur l'ordinateur tant qu'il n'y a pas de connexion (chiffrées, pendant maxBufferDays au maximum) et envoyez-les par lots à son retour.

5. Mises à jour : GET /update

Appelez GET /update avec os (windows ou macos) et la version de l'agent une fois par jour. La réponse donne latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable et updateRequired (l'agent est plus ancien que la version minimale acceptée par l'organisation). Ne téléchargez que depuis la downloadUrl à la même adresse Kaam360, vérifiez la taille et l'empreinte SHA-256 du fichier, et vérifiez sa signature de code avant de l'exécuter. Le programme d'installation le plus récent se trouve aussi à /download/agent/windows, et le paquet Mac (.pkg) à /download/agent/macos, accessibles à tous (c'est un programme, pas des données : c'est un code d'inscription qui connecte un ordinateur). Pour le Mac, vérifiez que le paquet commence par xar! et, lorsque votre application est signée avec un Apple Developer ID, que pkgutil --check-signature indique la même équipe.

Les agents Windows et Mac développés par Kaam360 respectent tout cela ; leur code se trouve dans le dossier agents des sources de Kaam360, et docs/activity-agent.md les décrit.