Pular para o conteúdo principal

Fluxo de ocorrências (manutenção corretiva)

Objetivo

Percorrer o ciclo de vida completo de uma ocorrência corretiva — configuração, criação, acompanhamento, resolução e aprovação — mapeando cada passo aos endpoints reais da API.

Este guia percorre o ciclo de vida de uma ocorrência — do registro à resolução — mapeando cada passo aos endpoints reais.

No código, "ocorrência" e "anomalia" são o mesmo conceito. Os endpoints usam ocorrencias.

Visão do ciclo​

1. Consultar configuração   →  GET /v{N}/ocorrencias/config/{empresaId}
2. (Opcional) Listar típicas →  GET /v{N}/ocorrencias/tipicas/{empresaId}
3. Criar a ocorrência        →  POST /v{N}/ocorrencias
4. Acompanhar / listar       →  GET /v{N}/ocorrencias
5. Aplicar correções         →  POST /v{N}/correcoes
6. Aprovar / autorizar        →  PUT /v{N}/ocorrencias/aprovacao
                                 PUT /v{N}/ocorrencias/autorizacao

1. Consultar a configuração da empresa​

Antes de criar, descubra como a empresa configura ocorrências (tipos, prioridades, se é auditoria):

curl "https://lighthousev2.lkp.app.br/v3/ocorrencias/config/123" \
  -H "Authorization: Bearer SEU_TOKEN"

2. Criar uma ocorrência​

Use a versão mais recente disponível (v3 concentra a evolução de ocorrências). Uma ocorrência precisa de pelo menos um Emitente (Solicitante).

Os exemplos -d '{...}' abaixo são bash/POSIX. No PowerShell, use o padrão de arquivo — ver Primeiros passos → PowerShell.

Campos obrigatórios de SaveOcorrenciaCommand: empresaId, siteId, plataforma.

O campo do emitente é emitenteId, não usuarioId

Testado: emitentes espera { "emitenteId": <int> }. Um campo desconhecido como usuarioId é silenciosamente ignorado — a API não valida nem retorna erro nessa hora, mas EmitenteId fica 0 internamente e a criação falha com 500 Internal Server Error mais adiante. Valide o emitenteId antes com GET /v1/usuarios?EmpresaId={id} (o campo retornado é usuario). Campos opcionais do objeto emitente: emailCadastro (bool), emailCorrecao (bool).

curl -X POST "https://lighthousev2.lkp.app.br/v3/ocorrencias" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "empresaId": 123,
    "siteId": 456,
    "plataforma": 6,
    "descricao": "Vazamento no equipamento de climatização",
    "areaId": 4567,
    "equipamentoId": 8901,
    "emitentes": [{ "emitenteId": 59064 }],
    "anomaliaTipicaId": 15
  }'

Correlacionando o retorno com as listagens​

O POST de criação retorna o campo anomaliaId com o GUID da ocorrência criada — é esse valor que os próximos passos (correção, aprovação) esperam em anomaliaId. Nas listagens (GET /v3/ocorrencias), porém, anomaliaId é um inteiro e o GUID aparece no campo anomaliaGid. Para correlacionar uma ocorrência recém-criada com um item de listagem: GUID retornado pelo POST == anomaliaGid do GET.

O mesmo GUID (não o inteiro) é usado em DELETE /v{N}/ocorrencias/{id} e DELETE /v{N}/correcoes/{id} — confirmado no spec: id é type: string (GUID) nas 6 rotas de exclusão (v1, v2 e v3 de ambos os recursos). Como regra geral, rotas com {id} do tipo string em ocorrências/correções esperam o GUID, não o inteiro das listagens.

Validação de ocorrência típica​

Se você informar anomaliaTipicaId, a API valida que a típica existe (ativa) e pertence à mesma empresa do contexto. Caso contrário, retorna:

400 Bad Request — "Ocorrência típica inválida"

Essa validação vale para criação e edição, em v1, v2 e v3 (a regra vive no service, compartilhada entre versões).

3. Listar e acompanhar​

EmpresaId vai no header HTTP, não na query — ver tabela canônica de contexto de empresa.

# PageIndex começa em 1 — PageIndex=0 retorna [] silenciosamente
curl "https://lighthousev2.lkp.app.br/v3/ocorrencias?PageIndex=1&PageSize=100&StatusIds=1" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

StatusIds=1 filtra ocorrências em aberto — ver Glossário → status de ocorrência (v3) para os demais valores confirmados e a limitação de usar um único valor por vez. Não existe o parâmetro status (ex.: ?status=aberta).

A contagem para dashboards:

curl "https://lighthousev2.lkp.app.br/v3/ocorrencias/count?StatusIds=1" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

4. Resolver: ações corretivas​

Para resolver, registram-se Correções (que contêm Emitentes, Executores e Fotos). Campos obrigatórios de SaveCorrecaoCommand: anomaliaId, inicio, plataforma.

Antes de criar a correção, descubra os tipos configurados pela empresa:

curl "https://lighthousev2.lkp.app.br/v3/correcoes/tipos" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"
EmpresaId é necessário aqui — e a resposta tem dois IDs diferentes [F12]

Testado: sem o header EmpresaId, GET /v3/correcoes/tipos retorna [] silenciosamente (sem erro). Além disso, cada item da resposta traz dois identificadores com propósitos distintos — ver Glossário → tipoCorrecaoId:

  • codigo — é este valor que vai em tipoCorrecaoId no POST abaixo.
  • tipoAcaoCorretivaEmpresa — ID único do registro, não é o que o command espera.

Uma empresa pode ter vários tipos configurados com o mesmo codigo — não use codigo como chave de um registro específico, só para decidir o valor de tipoCorrecaoId.

Opcionalmente, consulte os campos obrigatórios daquele tipo específico com GET /v3/correcoes/config?tipoId={codigo} (tipoId é obrigatório) — a config varia por tipo, não é a mesma para todos. Não confundir com GET /v3/correcoes/toadd?ocorrenciaId={guid}, que retorna um template de um tipo default, não a configuração de todos os tipos disponíveis.

curl -X POST "https://lighthousev2.lkp.app.br/v3/correcoes" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anomaliaId": "ANOMALIA_ID_DO_PASSO_3",
    "inicio": "2026-06-29T10:30:00",
    "plataforma": 6,
    "descricao": "Reparo concluído",
    "executores": [{ "executorId": 59064 }]
  }'

5. Aprovação e autorização​

Conforme o workflow da empresa. Campos obrigatórios de AprovarOcorrenciaCommand: anomaliaId, statusAprovacaoId, temAssinatura.

Aprovar exige mais campos do que o mínimo documentado [F13]

Os três campos "obrigatórios" acima bastam para a chamada ser aceita, mas não bastam para aprovar. Ao enviar statusAprovacaoId=2 (Aprovado — ver Glossário → statusAprovacaoId, a tabela foi corrigida em 05/07/2026), a API exige, por validação condicional:

Omitir qualquer um desses retorna um erro estruturado dentro do campo data da resposta (não só uma mensagem solta) — bom exemplo de mensagem de validação, vale inspecionar data sempre que success: false.

curl -X PUT "https://lighthousev2.lkp.app.br/v3/ocorrencias/aprovacao" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anomaliaId": "ANOMALIA_ID_DO_PASSO_3",
    "statusAprovacaoId": 2,
    "statusAvaliacaoId": 1,
    "temAssinatura": true,
    "assinaturaPath": "CAMINHO_DA_ASSINATURA",
    "usuarioAssinaturaId": 59064,
    "descricaoAprovacao": "Reparo verificado e aprovado"
  }'

Máquina de estados da ocorrência​

Verificado empiricamente — o ciclo de vida real de uma ocorrência (quando a empresa tem aprovação habilitada):

NaoAnalisada (3)
   │  POST /v3/correcoes  (registra a 1ª correção)
   ▼
Analisada (1)
   │  statusNome deriva do tipo da correção — com um tipo de código 3
   │  ("Solucionada" no ETipoCorrecao-base), o statusNome fica
   │  "Aguardando Aprovação" e a ocorrência expõe statusAprovacao=1
   │  (AguardandoAprovacao)
   │
   │  PUT /v3/ocorrencias/aprovacao  com statusAprovacaoId=2
   ▼
Solucionada (2)

Duas notas importantes:

  • Registrar a correção não soluciona a ocorrência por si só. Se a empresa tem aprovação habilitada, a ocorrência fica em Analisada (statusAprovacao=1, aguardando decisão) até a aprovação explícita fechar o ciclo. Os campos isAguardandoAprovacao e habilitarAprovacao (na configuração da empresa/ocorrência) indicam se esse workflow está ativo.
  • A configuração de campos obrigatórios da correção é por tipo (GET /v3/correcoes/config?tipoId={codigo}, ver seção 4 acima) — não existe uma config única "de todos os tipos"; GET /v3/correcoes/toadd retorna o template de um tipo default, não a configuração completa.

SLA automático (quando habilitado)​

Empresas com a flag HabilitarModuloSLA recebem auto-atribuição de SLA na criação da ocorrência: prazos de atendimento, solução e assistência são copiados automaticamente. Para empresas sem a flag, o comportamento permanece inalterado.

Os campos obrigatórios de cada comando estão indicados nas seções acima. Para o contrato completo (campos opcionais, tipos, validações), consulte a Referência de API.