Operando via API REST

O Kikwiflow Monitor cobre a operação do dia a dia pela interface — iniciar instâncias, completar tarefas, editar variáveis, retentar incidentes. Este capítulo é para quando você precisa fazer isso de código ou em automação: um sistema parceiro que completa uma tarefa por webhook, um job que dispara instâncias em lote, um pipeline que implanta uma definição, um teste de carga.

Com kikwi-management-rest-spring-boot-starter (e kikwi-runtime-query-spring-boot-starter para os endpoints de busca) no classpath, o Kikwiflow expõe uma API REST para tudo isso sem escrever código Java. Este documento é um tour da superfície disponível — não uma referência exaustiva de cada payload; o contrato completo está na Referência da API REST.

Definições de processo

Operação	Endpoint
Implantar uma definição	POST /process-definitions
Buscar uma definição por key	GET /process-definitions/one-by-key/{process-definition-key}
Buscar uma definição por id	GET /process-definitions/{id}
Limpar cache de definições	DELETE /process-definitions/cache

Instâncias de processo

Operação	Endpoint
Iniciar uma instância	POST /process-instances
Consultar snapshot de uma instância	GET /process-instances/{id}/snapshot
Contar instâncias	GET /process-instances/count
Incidentes de uma instância	GET /process-instances/{id}/incidents
Atualizar variáveis	PUT /process-instances/{id}/variables
Encerrar/remover uma instância	PUT /process-instances/{id}
Buscar instâncias com filtros	POST /process-instances/search

POST /process-instances é o mesmo endpoint que o botão de play do Monitor chama por baixo — útil quando as solicitações de abertura-de-conta chegam de um sistema (o portal do cliente), não de um operador. O endpoint de busca (POST /process-instances/search) é o mais rico da API: filtros por definição, chave de negócio, tenant, status, variáveis exatas, intervalo de datas, paginação. O contrato completo está no guia de integração de busca avançada.

Tarefas externas

Ciclo de vida de uma EXTERNAL_TASK (conceito em Tarefas Externas e Workers):

Operação	Endpoint
Reivindicar	PUT /external-tasks/{id}/claim/{assignee}
Liberar	PUT /external-tasks/{id}/unclaim
Completar	POST /external-tasks/{id}/complete
Consultar	GET /external-tasks/{id}
Contar pendentes	GET /external-tasks/count

Via KikwiflowEngine (dentro da própria aplicação)

Quando quem opera a instância é a própria aplicação — um listener de evento assíncrono, um @Scheduled, um controller REST seu — injete KikwiflowEngine e chame direto, sem passar por HTTP:

// iniciar
kikwiflowEngine.startProcess()
        .byKey("abertura-de-conta")
        .withBusinessKey(cpf)
        .withVariables(Map.of(
                "cpf", new ProcessVariable("cpf", cpf),
                "rendaDeclarada", new ProcessVariable("rendaDeclarada", renda)))
        .execute();

// completar uma tarefa externa a partir de um callback de outro sistema
kikwiflowEngine.completeExternalTask(externalTaskId,
        Map.of("decisao", new ProcessVariable("decisao", "APROVADA")),
        IdentityContext.system());

IdentityContext.system() é um atalho para chamadas internas sem um usuário/tenant real por trás (equivalente a rodar com papel SYSTEM_ADMIN, tenant GLOBAL). Em um endpoint autenticado por usuário, use o IdentityContext real resolvido para aquela requisição. completeExternalTask mescla as variáveis fornecidas e continua a execução de forma síncrona dentro da mesma chamada, até o próximo ponto de commitBefore ou o fim do processo.

Incidentes

Um incidente é aberto quando uma tarefa esgota suas tentativas de retry, ou quando um erro de negócio não tem BOUNDARY_ERROR_HANDLER correspondente (ver Tratando Erros de Negócio).

Operação	Endpoint
Consultar um incidente	GET /incidents/{id}
Retentar um incidente aberto	PUT /incidents/{id}/retry

Retentar reativa a tarefa associada e marca o incidente como resolvido de forma atômica — só incidentes com status OPEN podem ser retentados. O Monitor faz retry por instância; retry em lote (varrer todos os incidentes de uma definição e retentá-los) hoje é feito por script sobre esses endpoints.

Estatísticas e observabilidade em tempo real (Pulse)

Quando kikwiflow.pulse.sse-endpoints.enabled=true, o Kikwiflow expõe endpoints Pulse com um snapshot agregado por definição de processo, disponível como consulta pontual e como stream SSE. É o que alimenta os indicadores LIVE do Monitor sem polling manual. O contrato exato dos endpoints está em Estatísticas (Pulse).

Próximo passo

A maior parte do comportamento operacional acima é regida por propriedades kikwiflow.* — veja Configuração Essencial para as que você provavelmente vai querer ajustar.