Perguntas de negócio via IA

Este guia é para quem quer plugar a LightHouse API num GPT Actions (ou agente similar) e fazer perguntas de negócio em português — "quantas ocorrências a Jessica solucionou em maio?" — sem escrever código. Ele documenta o fluxo real testado ponta a ponta, incluindo o que não funcionou de primeira e como contornar.

Packs reduzidos (GPT packs)

O GPT Actions aceita specs de até 1 MB — o spec completo tem ~1,3 MB. Cada pack abaixo cobre um caso de uso e fica bem abaixo do limite. Importe a URL diretamente no GPT Actions:

Pack	URL	Cobre
Reports	https://docs.leankeep.com/openapi/gpt/reports.json	Buscar usuário por nome e consultar os 4 relatórios de produtividade (ocorrências e atividades, resumo e por técnico).
Ocorrências	https://docs.leankeep.com/openapi/gpt/ocorrencias.json	Buscar usuário por nome, listar/contar ocorrências, consultar configuração e tipos, criar ocorrência e correção.
Atividades	https://docs.leankeep.com/openapi/gpt/atividades.json	Buscar usuário por nome, listar atividades, dar baixa em lote e consultar justificativas.

Escolha o pack pelo tipo de pergunta — se a pergunta é sobre "quanto/quantos" produzidos, use Reports; se é sobre abrir/consultar/resolver um problema pontual, use Ocorrências; se é sobre manutenção preventiva/tarefas, use Atividades.

Regra de bolso: ExecutorId, EmitenteId ou UsuarioId?

Quase toda pergunta de negócio envolve filtrar por pessoa. A API tem três IDs de pessoa com significados diferentes — errar aqui é a causa mais comum de resposta errada:

Pergunta é sobre...	Use
Quem solucionou / resolveu / executou	ExecutorId
Quem abriu / criou / emitiu	EmitenteId
Genérico, sem verbo claro	UsuarioId

Resumindo: solucionou → ExecutorId; abriu → EmitenteId.

Fluxo ponta a ponta (exemplo real testado)

Pergunta: "Quantas ocorrências a Jessica Rose solucionou em maio de 2026?"

1. Buscar o ID da pessoa pelo nome:

   GET /v1/usuarios?Search=Jessica Rose

   Resposta contém um array de usuários; o campo que importa é usuario (o ID) — nesse teste, "usuario": 65747.

2. Guardar o ID: 65747.

3. Consultar o relatório, já que "solucionou" → ExecutorId:

   GET /v1/reports/summary/occurrences?Month=5&Year=2026&ExecutorId=65747

   (com o header EmpresaId — veja a nota abaixo sobre esse header no GPT Actions).

4. Ler o campo da resposta: "solucionada": 13.

5. Responder: "Em maio de 2026, Jessica Rose solucionou 13 ocorrências."

Esse é o fluxo canônico — nome → ID → relatório — que qualquer pergunta desse tipo segue.

Mais perguntas modelo

"Quantas ocorrências o João abriu em abril?"

Mesmo fluxo, mas "abriu" → EmitenteId:

1. GET /v1/usuarios?Search=João → pegar usuario.
2. GET /v1/reports/summary/occurrences?Month=4&Year=2026&EmitenteId=<id>.
3. Ler solucionada/analisada/naoAnalisada/expirada conforme a pergunta (aqui, o total de abertas é a soma, ou cada status individualmente se a pergunta especificar).

"Qual foi a produtividade da equipe em junho?"

Não tem uma pessoa específica — é o agregado da empresa:

1. GET /v1/reports/summary/activities?Month=6&Year=2026 (atividades preventivas).
2. GET /v1/reports/summary/occurrences?Month=6&Year=2026 (ocorrências corretivas).
3. Combine os dois números na resposta. Para detalhar por técnico, use GET /v1/reports/useractivitysummary e GET /v1/reports/useractivitysummary/occurrences com ExecutorId/EmitenteId de cada pessoa (repita a busca por nome do fluxo canônico para cada uma).

"Quantas atividades pendentes a Maria tem essa semana?"

Sai do pack de Reports para o de Atividades:

1. GET /v1/usuarios?Search=Maria → pegar usuario.
2. GET /v1/atividades filtrando pelo executor e período (consulte os parâmetros do endpoint no pack atividades.json).

Nota sobre o header EmpresaId

O parâmetro EmpresaId dos endpoints de relatório é declarado no spec como header HTTP, não query param. Isso é um problema conhecido para ferramentas de IA: o GPT Actions, ao importar um spec com parâmetro in: header, historicamente pode simplesmente ignorá-lo (mensagem de log típica: "parameter has location header; ignoring") em vez de deixar você preenchê-lo.

Testado em 04/07/2026: sem o header EmpresaId, os endpoints de Reports retornam 200 OK com todos os campos zerados — não há erro, e não há fallback para o token (mesmo padrão de falha silenciosa das listagens v3 de ocorrências, sem EmpresaId no header). O header é obrigatório na prática.

• Configure o header EmpresaId na ferramenta. Se seu GPT Actions ignora parâmetros in: header na importação do spec, configure-o manualmente pela seção de autenticação/headers customizados da ferramenta — não dá para contar com o token sozinho.
• Sintoma de header ausente: o relatório inteiro vem zerado (0 em todos os campos) mesmo quando você sabe que há dados no período — não um erro, nem números de outra empresa.

Como buscar IDs pelo nome

• Usuários: GET /v1/usuarios?Search=<nome> → campo usuario da resposta é o ID. Está em todos os packs.
• Unidades: GET /v1/unidades/ativas.
• Equipamentos: GET /v1/equipamentos/ativos.
• Planos de atividades: GET /v1/planosatividades/ativos.

Esses três últimos não estão inclusos nos packs reduzidos (são consultas pontuais, não fazem parte dos casos de uso cobertos) — consulte-os direto na Referência de API completa, ou peça para sua IA usar o spec completo (openapi/lighthouse.json) só para descobrir esses IDs, e os packs reduzidos para as chamadas do dia a dia.

Kit de discovery — endpoints de referência

Todos os endpoints abaixo esperam EmpresaId no header (ver Primeiros passos → EmpresaId vai sempre no header):

Objetivo	Endpoint	Filtro
Empresas do token	GET /v1/empresas/ativas	nenhum
Sites/unidades da empresa	GET /v1/unidades/ativas	—
Usuários da empresa	GET /v1/usuarios	—
Sistemas da empresa	GET /v1/sistemas	—
Áreas	GET /v1/areas	siteId (opcional)
Equipamentos	GET /v1/equipamentos	siteId (opcional)

Shapes reais da resposta (campos principais):

• unidades/ativas → { site, empresa, nome, codigo, endereco, statusSite, quantidadeAreas, quantidadeEquipamentos }
• usuarios → { usuario (id), nome, login, tipo, tipoNome } (tipoNome: Administrador/Operacional/Chamado)
• sistemas → { sistemaEmpresa (id), sistema, empresa, nome }

Ver também

• Comece com IA — primeiros passos gerais para usar IA com a API.
• Glossário de IDs e enums — significado de outros campos de código (statusId, plataforma, etc.), incluindo a seção sobre ExecutorId/EmitenteId/UsuarioId.
• Relatório de produtividade da equipe — a receita completa dos 4 endpoints de Reports, sem o recorte de GPT Actions.