Monitoramento de atividade: a API do agente (para desenvolvedores)

Este guia é para desenvolvedores. Os agentes de desktop do Kaam360 conversam com o Kaam360 por uma pequena API web em /api/agent/v1. A descrição completa dela, para ferramentas como o Postman, está em /api/agent/v1/openapi.json. Como configurar o monitoramento no Kaam360 está no guia de monitoramento de atividade.

Regras para todas as chamadas

• Só por HTTPS. HTTP simples é recusado.
• Envie JSON (Content-Type: application/json), exceto capturas de tela, que são um envio de formulário.
• Depois do registro, envie a chave do dispositivo em todas as chamadas como Authorization: Bearer seguido da chave (ela começa com kad_). Guarde-a no armazenamento seguro do sistema (Windows DPAPI, o Keychain do macOS). O Kaam360 guarda só uma impressão digital dela.
• As respostas são { "data": ... }. Uma recusa é { "error": { "code", "message" } } com um status HTTP: 401 para uma chave errada ou revogada (registre de novo), 403 para um computador pausado ou um recurso desligado, 413 para coisa demais de uma vez, 422 para um campo errado, 429 para chamadas demais (espere os segundos indicados em Retry-After).
• Nunca envie teclas digitadas, texto digitado, senhas ou o conteúdo de mensagens e documentos. Envie só o domínio de um site.

1. Registro: POST /register

Envie o código de registro de Dispositivos, o seu próprio id para esta instalação (installId, criado uma vez e guardado), o nome do computador, os (windows ou macos), osVersion, agentVersion e, se souber, o e-mail de trabalho da pessoa. A resposta traz a chave do dispositivo (mostrada só desta vez) e as regras. No máximo 20 registros por hora vêm de um mesmo endereço.

2. Comunicação periódica: POST /heartbeat

A cada heartbeatSeconds (cinco minutos por padrão), envie agentVersion, o relógio do computador (sentAtUtc) e quantas fatias estão esperando. A resposta traz as regras atuais (policy) e se o computador está pausado ou ainda não tem pessoa. Use GET /policy para ler só as regras.

As regras dizem ao agente: trackingEnabled (não registrar nada quando for false), workHoursOnly com workStart, workEnd, workDays e o fuso horário, neverRecord (programas e domínios a ignorar), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (mostre-o na primeira inicialização e pelo ícone da bandeja) e minAgentVersion.

3. Envie a atividade: POST /activity

Envie um batchId seu, sentAtUtc e até 1000 fatias (no máximo 1 MB). Cada fatia tem start e end (UTC), app (o programa), title (só quando recordTitles está ligado), domain e idle. Enviar o mesmo batchId de novo não faz nada, então repita à vontade depois de uma conexão perdida. A resposta diz quantas foram guardadas e por que as outras foram descartadas: tracking_off, no_person, invalid, too_long (mais de 4 horas), future, too_old (mais de 14 dias), never_record ou outside_hours. Um relógio de computador com mais de um minuto de diferença é corrigido; com mais de um dia, é recusado.

4. Envie uma captura de tela: POST /screenshots

Só quando as capturas de tela estão ligadas. Um envio de formulário com file (JPEG, PNG ou WebP, no máximo 1 MB), takenAtUtc, app, domain e blurred. Desfoque a imagem antes quando blur estiver ligado: uma imagem nítida é recusada. Não com mais frequência que o intervalo. Uma captura de um programa que nunca deve ser registrado, ou fora do horário de trabalho, não é guardada.

Offline

Guarde as fatias no computador enquanto não houver conexão (criptografadas, por no máximo maxBufferDays) e envie-as em lotes quando ela voltar.

5. Atualizações: GET /update

Chame GET /update com os (windows ou macos) e a versão do agente uma vez por dia. A resposta traz latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable e updateRequired (o agente é mais antigo que a versão mínima que a organização aceita). Baixe só do downloadUrl no mesmo endereço do Kaam360, confira o tamanho e a impressão digital SHA-256 do arquivo, e confira a assinatura de código antes de executá-lo. O instalador mais recente também está em /download/agent/windows, e o pacote para Mac (.pkg) em /download/agent/macos, para qualquer pessoa (é um programa, não dados: é um código de registro que conecta um computador). No Mac, confira se o pacote começa com xar! e, quando o seu aplicativo for assinado com um Apple Developer ID, se pkgutil --check-signature mostra a mesma equipe.

Os agentes para Windows e Mac feitos pelo Kaam360 seguem tudo isso; o código deles está na pasta agents do código-fonte do Kaam360, e docs/activity-agent.md os descreve.