Relatórios de produtividade por usuário

Objetivo

Consultar os 4 endpoints do grupo Reports (v1) para montar um painel mensal de produtividade: quem executou quais atividades preventivas, quem resolveu quais ocorrências corretivas, com filtros por período, unidade, usuário e geografia.

Endpoints disponíveis

Endpoint	Descrição
`GET /v1/reports/useractivitysummary`	Resumo de atividades por usuário
`GET /v1/reports/useractivitysummary/occurrences`	Resumo de ocorrências por usuário
`GET /v1/reports/summary/activities`	Totais agregados de atividades
`GET /v1/reports/summary/occurrences`	Totais agregados de ocorrências

Parâmetros

Contexto de empresa via header HTTP

EmpresaId e UnidadeId são enviados como headers HTTP, não como query params. Garanta que seu cliente HTTP os inclua em todas as chamadas. Ver a tabela canônica de contexto de empresa para os demais padrões usados pela API.

Headers

Header	Tipo	Obrigatório	Descrição
`EmpresaId`	integer	✅ sim	ID da empresa — resolve o contexto da requisição
`UnidadeId`	integer	não	Restringe a uma unidade específica — também vai no header (como `EmpresaId`); testado: enviado na query, é ignorado silenciosamente.

Query params — período

Parâmetro	Tipo	Descrição
`Month`	integer	Mês (1–12)
`Year`	integer	Ano (ex.: 2026)

Month e Year são obrigatórios na prática

O spec não os marca como required, mas testado: omitir Month e/ou Year retorna 500 Internal Server Error, não um resultado sem filtro de período. Envie sempre os dois. O FiltroReports não tem DataInicio/DataTermino (diferente dos filtros de ocorrências) — o recorte temporal destes 4 endpoints é sempre mês/ano inteiro, não um intervalo de datas.

Query params — filtros de usuário

Parâmetro	Tipo	Descrição
`UsuarioId`	integer	Qualquer usuário associado ao registro
`ExecutorId`	integer	Usuário que executou a tarefa/ocorrência
`EmitenteId`	integer	Usuário que emitiu/abriu o registro

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

Sem UsuarioId/ExecutorId/EmitenteId, os endpoints useractivitysummary e useractivitysummary/occurrences retornam os dados do usuário autenticado no token — não o agregado da empresa. O número volta real e plausível (os seus próprios dados), então é fácil confundir com o total da equipe.

Agregado da empresa → summary/activities e summary/occurrences.
Por técnico → sempre informe o ExecutorId/EmitenteId explícito de cada pessoa; nunca omita esperando um totalizador.

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.

Query params — filtros geográficos e de agrupamento

Parâmetro	Tipo	Descrição
`GrupoUnidadeId`	integer	Grupo de unidades
`SubGrupoUnidadeId`	integer	Sub-grupo de unidades
`CidadeId`	integer	Cidade
`EstadoId`	integer	Estado
`ListaUnidades`	integer[]	Lista de IDs de unidades (aceita múltiplos valores)

Passo 1 — Resumo de atividades preventivas do mês

Retorna a consolidação de tarefas executadas por usuário em maio de 2026 na empresa 100:

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

Filtrando por executor específico:

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

Passo 2 — Resumo de ocorrências corretivas do mesmo período

Mesma assinatura, rota diferente:

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

Filtrando por emitente (quem abriu as ocorrências):

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

Passo 3 — Filtrar por múltiplas unidades

ListaUnidades aceita repetição do parâmetro para múltiplos IDs:

curl "https://lighthousev2.lkp.app.br/v1/reports/useractivitysummary?Month=5&Year=2026&ListaUnidades=10&ListaUnidades=11&ListaUnidades=12" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 100"

Passo 4 — Totais agregados (sem quebra por usuário)

Para totais gerais do mês — útil para comparativos entre períodos:

# Atividades — total agregado
curl "https://lighthousev2.lkp.app.br/v1/reports/summary/activities?Month=5&Year=2026" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 100"

# Ocorrências — total agregado
curl "https://lighthousev2.lkp.app.br/v1/reports/summary/occurrences?Month=5&Year=2026" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 100"

Interpretando o resultado de atividades

A resposta de summary/activities (ResumoAtividadeUsuario) agrupa em 3 blocos:

Campo	Shape	Descrição
`qtdAtividadesPrevistasRealizadas`	`{ previstas, realizadas }`	Total previsto vs. realmente executado no período
`tempoExecucaoOcorrenciasAtividades`	`{ ocorrencias, atividades }`	Tempo de execução em minutos, separado por tipo de registro
`qtdAtividadesPorStatus`	`{ realizada, aguardandoAprovacao, naoRealizada, pendente }`	Quebra por status de execução da tarefa

useractivitysummary usa o mesmo shape (ResumoAtividadeUsuario), só filtrado por pessoa.

Interpretando o resultado de ocorrências

A resposta de summary/occurrences (e useractivitysummary/occurrences) quebra o total por status, usando os nomes de EStatusOcorrencia (ver Glossário → status de ocorrência (v3)):

Campo da resposta	Status (`EStatusOcorrencia`)
`solucionada`	`2` — Solucionada
`analisada`	`1` — Analisada (em aberto)
`naoAnalisada`	`3` — NaoAnalisada
`expirada`	`5` — Expirada

Não há campo para o status 4 (Inativa) nessa resposta — ocorrências inativadas não entram nesse recorte.

Combinando os 4 endpoints — painel completo

Chamada	Responde
`useractivitysummary`	Quem executou quais atividades preventivas
`useractivitysummary/occurrences`	Quem resolveu quais ocorrências corretivas
`summary/activities`	Total de atividades do mês (sem quebra por usuário)
`summary/occurrences`	Total de ocorrências do mês (sem quebra por usuário)

Filtros geográficos

GrupoUnidadeId, SubGrupoUnidadeId, CidadeId e EstadoId são especialmente úteis para empresas com operações distribuídas regionalmente. Combine-os com Month/Year para relatórios por regional.

Dicas para IA / integração

EmpresaId vai no header HTTP, não na query — omiti-lo retorna erro de autorização.
Os IDs de UsuarioId, ExecutorId e EmitenteId são obtidos via GET /v1/usuarios.
Consulte o Glossário de IDs e enums para entender os campos de código usados nos filtros e nos commands relacionados.

Endpoints disponíveis​

Parâmetros​

Headers​

Query params — período​

Query params — filtros de usuário​

Query params — filtros geográficos e de agrupamento​

Passo 1 — Resumo de atividades preventivas do mês​

Passo 2 — Resumo de ocorrências corretivas do mesmo período​

Passo 3 — Filtrar por múltiplas unidades​

Passo 4 — Totais agregados (sem quebra por usuário)​

Interpretando o resultado de atividades​

Interpretando o resultado de ocorrências​

Combinando os 4 endpoints — painel completo​

Dicas para IA / integração​