Pular para o conteúdo principal

Receita: relatório de produtividade da equipe

Objetivo

Levantar quanto cada técnico produziu (atividades baixadas e ocorrências) em um período, e comparar a equipe ou períodos entre si.

Esta receita estende a Produtividade de usuário para o nível de equipe.

Pré-requisitos​

  • Token JWT válido (ver Autenticação).
  • EmpresaId (vai no header HTTP, não na query — atenção a este detalhe. Ver a tabela canônica de contexto de empresa).
  • Mês e ano de referência.
  • Base URL produção: https://lighthousev2.lkp.app.br · sandbox: https://lighthouse.lkp.dev.br.

Parâmetros (confirmados no spec)​

  • Header (obrigatório): EmpresaId. Opcional, também via header: UnidadeId (na query é ignorado silenciosamente).
  • Query — período: Month, Year — sem required no spec, mas testado: obrigatórios na prática (omitir qualquer um retorna 500, não um recorte sem filtro). Não existe DataInicio/DataTermino nesses endpoints. Ver Produtividade de usuário para detalhes.
  • Query — recorte por pessoa: UsuarioId, ExecutorId, EmitenteId.
  • Query — recorte geográfico: GrupoUnidadeId, SubGrupoUnidadeId, CidadeId, EstadoId, ListaUnidades (array).

Passo 1 — Resumo de atividades da empresa no mês​

Sem filtrar por usuário, traz o agregado da empresa (todos os técnicos):

curl "https://lighthousev2.lkp.app.br/v1/reports/summary/activities?Month=6&Year=2026" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

Passo 2 — Resumo de ocorrências da empresa no mês​

curl "https://lighthousev2.lkp.app.br/v1/reports/summary/occurrences?Month=6&Year=2026" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

Passo 3 — Detalhar por técnico​

Default do relatório por usuário (validado 07/2026)

Sem ExecutorId/EmitenteId, useractivitysummary e useractivitysummary/occurrences retornam os dados do usuário autenticado no token — não o agregado da equipe. O número volta real e plausível (os seus próprios dados), então é fácil confundir com o total do time. Nunca omita esse filtro esperando um totalizador — para o agregado da empresa, use summary/activities/summary/occurrences (Passos 1-2).

Report de atividades por técnico com defeito conhecido (07/2026)

Atualmente GET /v1/reports/useractivitysummary filtrado por ExecutorId pode retornar zero mesmo para técnicos com execução no período (defeito de backend em correção). O report de ocorrências por usuário (useractivitysummary/occurrences + EmitenteId) funciona. Para o total de atividades da empresa, use summary/activities.

Para cada técnico, filtre por ExecutorId (quem executou a atividade) ou EmitenteId (quem registrou a ocorrência):

curl "https://lighthousev2.lkp.app.br/v1/reports/useractivitysummary?Month=6&Year=2026&ExecutorId=42" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

curl "https://lighthousev2.lkp.app.br/v1/reports/useractivitysummary/occurrences?Month=6&Year=2026&EmitenteId=42" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

Repita para cada ExecutorId/EmitenteId da equipe (obtenha os IDs em GET /v1/usuarios).

Passo 4 — Comparar com o mês anterior​

Refaça os passos com Month=5 e calcule a variação:

variação % = (mês_atual − mês_anterior) / mês_anterior × 100

Exemplo de conclusão que a IA pode gerar:

"Em junho a equipe baixou 214 atividades (vs 188 em maio, +14%). O técnico 42 liderou com 38 baixas; o técnico 17 caiu de 25 para 12 (−52%) — vale investigar."

Resumo do fluxo​

agregado empresa (activities + occurrences) → por técnico (ExecutorId/EmitenteId) → comparar períodos

Dicas para IA / integração​

  • Atenção: EmpresaId vai no header, não na query string — diferente do padrão REST. Errar isso retorna erro de autorização/escopo.
  • ExecutorId = quem executou a tarefa preventiva; EmitenteId = quem registrou a ocorrência corretiva. Use o recorte certo conforme a métrica.
  • Para listar os técnicos da empresa e seus IDs: GET /v1/usuarios.
  • Respeite o rate limit (1200 req/h): uma equipe de 10 técnicos × 2 endpoints × 2 períodos = 40 chamadas, dentro do limite.
  • Os quatro endpoints de relatório: summary/activities, summary/occurrences, useractivitysummary, useractivitysummary/occurrences.
  • Consulte o Glossário de IDs e enums para referência dos campos de código usados em outras partes da integração (statusId, tipoAnomalia, plataforma, etc.).