Busca Avançada de Instâncias

POST /process-instances/search é o endpoint de consulta mais rico da API — filtros por definição, chave de negócio, tenant, status, variáveis exatas, intervalo de datas, relação pai/filho, paginação e ordenação, todos combináveis e todos opcionais. Este documento é a referência completa do seu contrato; para os outros endpoints de instância (iniciar, snapshot, variáveis), veja Instâncias de Processo.

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

Exemplo de payload

Nenhum campo é obrigatório — envie só os filtros que quiser. Os filtros informados são combinados com AND (nunca OR entre eles):

{
  "processDefinitionKeys": ["intermediacao-veiculos"],
  "activeNodeId": "AGUARDANDO_CONTATO",
  "tenantIds": ["empresa-abc-123", "empresa-xyz-789"],
  "statuses": ["ACTIVE"],
  "startedAfter": "2026-07-01T00:00:00.000Z",
  "startedBefore": "2026-07-31T23:59:59.999Z",
  "variables": {
    "prospectType": "VENDA",
    "marcaVeiculo": "Toyota"
  },
  "variablesExist": ["telefoneContato"],
  "orderBy": "startedAt",
  "ascending": false,
  "page": 0,
  "size": 20
}

Dicionário de parâmetros

Definição e estado

Parâmetro	Tipo	Descrição
processDefinitionId	string	Busca pelo id exato de uma versão específica.
processDefinitionIds	string[]	Lista de ids de versões específicas.
processDefinitionKeys	string[]	Recomendado. Busca por key (ex.: ["intermediacao-veiculos"]), abrangendo todas as versões daquela key — não precisa saber qual versão está ativa.
activeNodeId	string	Só instâncias com uma tarefa ativa/aguardando exatamente nesse nó (ex.: "EM_ESTOQUE").
parentInstanceId	string	Só as instâncias filhas diretas de um CALL_ACTIVITY_COORDINATOR (subprocesso) da instância informada — ver Listando os subprocessos de uma instância.
statuses	string[]	ACTIVE, COMPLETED, CANCELLED.

Negócio e organização

Parâmetro	Tipo	Descrição
tenantId	string	Um único tenant.
tenantIds	string[]	Vários tenants de uma vez.
businessKey	string	Chave de negócio exata (ex.: número de pedido).
businessKeys	string[]	Várias chaves de negócio.

Datas

Sempre ISO-8601 UTC com sufixo Z.

Parâmetro	Tipo	Descrição
startedAfter	string	Instâncias iniciadas a partir desta data/hora, inclusive.
startedBefore	string	Instâncias iniciadas até esta data/hora, inclusive.

Variáveis

Consulta dinâmica sobre variáveis de processo, sem coluna dedicada por variável.

Parâmetro	Tipo	Descrição
variables	object	Mapa chave→valor — casamento exato com o valor gravado na instância. Ex.: { "prospectType": "VENDA", "statusCredito": "APROVADO" }. Implementação Mongo só faz variables.<key>.value exato — não é busca parcial/substring.
variablesExist	string[]	Instâncias onde a variável está presente (com qualquer valor). Ex.: ["cpfComprador"].

Ordenação e paginação

Parâmetro	Tipo	Padrão	Descrição
orderBy	string	"startedAt"	Whitelist: id, businessKey, status, processDefinitionId, startedAt, endedAt. Qualquer outro valor → 400 BAD_REQUEST, não é ignorado silenciosamente.
ascending	boolean	false	true = crescente; false = decrescente (mais recente primeiro).
page	number	0	Baseado em zero.
size	number	20	Teto de 100 — valores maiores são reduzidos a 100, não rejeitados.

Formato de resposta

Um PageResult<ProcessInstanceSummary> (ver Convenções):

{
  "content": [
    {
      "id": "ae8fd836-c6a8-4dd1-af8d-0e6ec3530657",
      "businessKey": "100234",
      "status": "ACTIVE",
      "processDefinitionId": "fc451f6f-a944-4dbb-b2ba-b5fb6433f40a",
      "startedAt": "2026-07-24T17:10:31.460Z",
      "endedAt": null,
      "activeNodes": { "AGUARDANDO_CONTATO": 1 },
      "parentInstanceId": null,
      "callerTaskId": null,
      "callerBranchId": null
    }
  ],
  "totalElements": 45,
  "totalPages": 3,
  "page": 0,
  "size": 20
}

ProcessInstanceSummary é uma projeção — não traz variables nem o mapa completo de tarefas. Para o conteúdo completo de uma instância específica, siga com GET /process-instances/{id} ou GET /process-instances/{id}/snapshot.

Listando os subprocessos de uma instância

Quando uma instância está parada num CALL_ACTIVITY_COORDINATOR, o snapshot dela não traz o status dos filhos embutido — cada filho é uma ProcessInstance própria, com seu próprio ciclo de vida, e o número de filhos é dirigido por uma variável de coleção (pode ser grande). Para listá-los, use o filtro parentInstanceId:

POST /process-instances/search
{ "parentInstanceId": "ae8fd836-c6a8-4dd1-af8d-0e6ec3530657", "size": 100 }

{
  "content": [
    { "id": "child-1", "businessKey": "100234#0", "status": "COMPLETED", "parentInstanceId": "ae8fd836-...", "callerTaskId": "coord-task-id", "callerBranchId": "coord-task-id:0" },
    { "id": "child-2", "businessKey": "100234#1", "status": "ACTIVE", "activeNodes": { "AGUARDA_ATIVACAO": 1 }, "parentInstanceId": "ae8fd836-...", "callerTaskId": "coord-task-id", "callerBranchId": "coord-task-id:1" }
  ],
  "totalElements": 2
}

"N de M subprocessos concluídos" é a contagem de status: COMPLETED sobre totalElements. Para um filho ainda ativo, o activeNodes do próprio item diz onde ele está parado — e um filho pode, por sua vez, ser pai de outro subprocesso. Para saber se uma instância é filha de outra sem ir ao /search, os campos parentInstanceId/callerTaskId/callerBranchId já vêm na própria instância: null numa instância raiz, preenchidos numa filha.