Instâncias de Processo

Uma ProcessInstance é uma execução concreta de uma Definição de Processo. Este documento cobre o ciclo de vida básico (iniciar, consultar, alterar variáveis, encerrar). Para busca com filtros ricos, veja Busca Avançada de Instâncias; para o retrato agregado usado por telas de monitor, veja o Guia de Integração do Monitor.

Operação	Endpoint
Iniciar uma instância	POST /process-instances
Buscar uma instância por id	GET /process-instances/{id}
Listar instâncias (por ids, ou por definição+tenant)	GET /process-instances
Contar instâncias de uma definição	GET /process-instances/count?process-definition-id=
Atualizar (mesclar) variáveis	PUT /process-instances/{id}/variables
Remover variáveis	PUT /process-instances/{id}/variables/unset
Encerrar/remover uma instância	PUT /process-instances/{id}
Incidentes de uma instância	GET /process-instances/{id}/incidents
Snapshot completo de uma instância	GET /process-instances/{id}/snapshot
Listar com paginação (deprecated)	GET /process-instances/summary — use POST /search

Todos requerem QueryRepository no contexto exceto POST /process-instances, PUT .../variables, PUT .../variables/unset e PUT /process-instances/{id}, que requerem KikwiflowEngine.

Iniciar uma instância

POST /process-instances
Content-Type: application/json

{
  "processDefinitionKey": "onboarding-cliente",
  "tenant": "empresa-abc-123",
  "businessKey": "cliente-42",
  "businessValue": 15000.00,
  "origin": "portal-vendas",
  "variables": {
    "email": { "name": "email", "value": "cliente@exemplo.com" }
  }
}

Campo	Obrigatório	Papel
processDefinitionKey	sim	Resolve sempre para a versão mais recente implantada daquela key.
targetFlowNodeId	não	Inicia a instância diretamente num nó específico em vez de defaultStartPoint — uso avançado (retomar/simular a partir de um ponto do fluxo).
tenant	não	Grava em ProcessInstance.tenantId. Ver Segurança e Multi-tenancy — não há validação de que o IdentityContext da requisição tenha direito a esse tenant.
businessKey	não	Identificador de negócio livre (ex.: número de pedido), não único imposto pelo motor.
businessValue	não	BigDecimal livre para a aplicação anexar um valor monetário/numérico à instância (ex.: para dashboards).
origin	não	String livre para rastrear de onde veio o start (nome do sistema chamador).
variables	não	Ver formato de variáveis.

Resposta 201 Created — a ProcessInstance recém-criada, já avançada de forma síncrona até o primeiro ponto de espera (EXTERNAL_TASK, boundary timer, etc.) ou até concluir, caso o processo não tenha nenhum nó assíncrono (ver Execução Síncrona/Assíncrona).

Buscar uma instância por id

GET /process-instances/{id}

200 OK com a ProcessInstance completa, ou 404 (NOT_FOUND).

Listar instâncias

GET /process-instances?ids=id-1&ids=id-2
GET /process-instances?process-definition-id={id}&tenant-id={tenant}

Este endpoint só aceita duas combinações de filtro — qualquer outra combinação (inclusive nenhum parâmetro) lança NotImplementedException → 501:

1. ids (uma ou mais ocorrências) — busca exatamente aquelas instâncias, ignorando os demais parâmetros.
2. process-definition-id e tenant-id juntos — não funciona informar só um dos dois.

Para qualquer outro filtro (status, chave de negócio, intervalo de datas, variáveis...), use POST /process-instances/search — muito mais completo e o caminho recomendado; este GET existe para os dois casos de acesso direto acima.

Resposta 200 OK — ProcessInstance[], não paginado.

Contar instâncias

GET /process-instances/count?process-definition-id={id}

Único filtro suportado hoje — omitir process-definition-id lança NotImplementedException → 501, não devolve uma contagem total. Conta todas as instâncias daquela definição (ACTIVE, COMPLETED e CANCELLED — não só as ativas; para "quantas estão rodando agora" use /pulse/process-definition/{id}/snapshot).

Resposta 200 OK:

{ "total": 1284 }

Atualizar variáveis

PUT /process-instances/{id}/variables
Content-Type: application/json

{ "variables": { "statusCredito": { "name": "statusCredito", "value": "APROVADO" } } }

Mescla (upsert por nome) sobre as variáveis existentes — não substitui o mapa inteiro; variáveis não citadas permanecem intocadas. Resposta 200 OK com a ProcessInstance atualizada.

Remover variáveis

PUT /process-instances/{id}/variables/unset
Content-Type: application/json

{ "variableNames": ["statusCredito", "scoreTemporario"] }

Remove as variáveis citadas por nome. Resposta 200 OK com a ProcessInstance atualizada.

Encerrar/remover uma instância

PUT /process-instances/{id}

Sem corpo. Resposta 204 No Content.

:::warning Nome de operação enganoso e delete físico Apesar do verbo PUT e de não haver corpo, esta operação apaga a instância (e suas ExternalTask/ ExecutableTask associadas) — não é um "encerrar suavemente" nem um soft-delete reversível. Trate como destrutivo: não há confirmação, e não há checagem de tenant/identidade antes de apagar (o IdentityContext recebido não é usado para autorização nesta operação hoje). Eventos de histórico já emitidos para a instância (GET /process-instances/{id}/events) não são apagados — permanecem como rastro de auditoria mesmo depois da instância sumir; incidentes associados também não são removidos, e passam a apontar para um processInstanceId inexistente. :::

Incidentes de uma instância

GET /process-instances/{id}/incidents

200 OK — Incident[] não paginado (tipicamente poucos por instância). Ver Incidentes para o modelo completo e como retentar.

Snapshot completo

GET /process-instances/{id}/snapshot

Agrega, numa única chamada concorrente (ExecutorService de threads virtuais), tudo que uma tela de detalhe de instância normalmente precisaria buscar separadamente:

{
  "instance": { "...": "ProcessInstance completa" },
  "executableTasks": [ "..." ],
  "externalTasks": [ "..." ],
  "incidents": [ "..." ],
  "eventCatcherWaitStatus": [ "..." ]
}

eventCatcherWaitStatus é computado (não persistido) a cada chamada, a partir das externalTasks do próprio snapshot — ver Guia de Integração do Monitor §3.1 para o que cada campo significa e como renderizar "3 de 5 eventos recebidos". 404 (NOT_FOUND) se a instância não existir — as demais listas do snapshot vêm vazias em vez de erro se não houver dados (não é tratado como "instância inexistente", já que tarefas/incidentes zerados são um estado normal).

GET /process-instances/summary (deprecated)

Paginado, com três filtros fixos (processDefinitionId, activeNodeId, tenantId) e sem os demais filtros de /search. Mantido só por compatibilidade com integrações antigas — não use em código novo; veja Busca Avançada de Instâncias para o substituto completo.