Seguimiento de actividad: la API del agente (para desarrolladores)

Esta guía es para desarrolladores. Los agentes de escritorio de Kaam360 hablan con Kaam360 mediante una pequeña API web en /api/agent/v1. Su descripción completa, para herramientas como Postman, está en /api/agent/v1/openapi.json. Cómo configurar el seguimiento en Kaam360 se explica en la guía de seguimiento de actividad.

Reglas para cada llamada

• Solo por HTTPS. El HTTP sin cifrar se rechaza.
• Envíe JSON (Content-Type: application/json), salvo las capturas, que se suben como formulario.
• Tras la inscripción, envíe en cada llamada la clave del dispositivo como Authorization: Bearer seguido de la clave (empieza por kad_). Guárdela en el almacén seguro del sistema (DPAPI de Windows, el Llavero de macOS). Kaam360 solo guarda una huella de ella.
• Las respuestas son { "data": ... }. Un rechazo es { "error": { "code", "message" } } con un estado HTTP: 401 para una clave incorrecta o revocada (inscríbase de nuevo), 403 para un equipo en pausa o una función desactivada, 413 para demasiado a la vez, 422 para un campo incorrecto, 429 para demasiadas llamadas (espere los segundos de Retry-After).
• Nunca envíe pulsaciones de teclas, texto escrito, contraseñas ni el contenido de mensajes y documentos. De un sitio web envíe solo el dominio.

1. Inscribirse: POST /register

Envíe el código de inscripción de Dispositivos, su propio id para esta instalación (installId, creado una vez y conservado), el nombre del equipo, os (windows o macos), osVersion, agentVersion y, si lo sabe, el correo de trabajo de la persona. La respuesta contiene la clave del dispositivo (mostrada solo esta vez) y las reglas. Desde una misma dirección llegan como mucho 20 inscripciones por hora.

2. Conectarse: POST /heartbeat

Cada heartbeatSeconds (cinco minutos por defecto) envíe agentVersion, el reloj del equipo (sentAtUtc) y cuántos tramos esperan. La respuesta contiene las reglas actuales (policy) y si el equipo está en pausa o aún no tiene persona. Use GET /policy para leer solo las reglas.

Las reglas indican al agente: trackingEnabled (no registrar nada cuando es false), workHoursOnly con workStart, workEnd, workDays y la zona horaria, neverRecord (programas y dominios que omitir), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (mostrarlo al primer inicio y desde el icono) y minAgentVersion.

3. Enviar actividad: POST /activity

Envíe un batchId propio, sentAtUtc y hasta 1000 tramos (como mucho 1 MB). Cada tramo tiene start y end (UTC), app (el programa), title (solo si recordTitles está activado), domain e idle. Enviar de nuevo el mismo batchId no hace nada, así que reintente sin miedo tras perder la conexión. La respuesta dice cuántos se guardaron y por qué se descartaron otros: tracking_off, no_person, invalid, too_long (más de 4 horas), future, too_old (más de 14 días), never_record u outside_hours. Un reloj del equipo desfasado más de un minuto se corrige; más de un día se rechaza.

4. Enviar una captura: POST /screenshots

Solo cuando las capturas están activadas. Una subida de formulario con file (JPEG, PNG o WebP, como mucho 1 MB), takenAtUtc, app, domain y blurred. Difumine primero la imagen cuando blur esté activado: una nítida se rechaza. No más a menudo que el intervalo. Una captura de un programa de la lista de no registrar o fuera del horario laboral no se guarda.

Sin conexión

Guarde los tramos en el equipo mientras no haya conexión (cifrados, como mucho maxBufferDays) y envíelos por lotes cuando vuelva.

5. Actualizaciones: GET /update

Llame a GET /update una vez al día con os (windows o macos) y la versión del agente. La respuesta da latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable y updateRequired (el agente es más antiguo que la versión mínima que acepta la organización). Descargue solo desde la downloadUrl en la misma dirección de Kaam360, compruebe el tamaño y la huella SHA-256 del archivo y su firma de código antes de ejecutarlo. El instalador más reciente también está en /download/agent/windows para cualquiera (es un programa, no datos: lo que conecta un equipo es un código de inscripción). El paquete para Mac (.pkg) está en /download/agent/macos; en el Mac, compruebe que el archivo empieza por xar! y, si su aplicación está firmada con un Apple Developer ID, que pkgutil --check-signature muestra el mismo equipo.

El agente para Windows creado por Kaam360 cumple todo esto; su código está en la carpeta agents del código fuente de Kaam360 y docs/activity-agent.md lo describe.