Fase — Visão geral

Uma fase representa uma etapa do kanban dentro de um flow — por exemplo, Triagem, Análise, Aprovação, Ganho ou Perda. Cada card do flow permanece em exatamente uma fase por vez.

Fase é um recurso estrutural do flow. Não deve ser confundida com ação de fase (phase-action), que é o módulo habilitado dentro de uma fase — como aprovação, parecer, motores de decisão ou mensageria.

Endpoints deste domínio

Método	Caminho	Descrição
`POST`	`/v1/flows/{id}/phases`	Cria uma fase
`GET`	`/v1/flows/{id}/phases`	Lista as fases do flow
`PATCH`	`/v1/flows/{id}/phases/{phaseId}`	Atualiza uma fase (parcial)
`DELETE`	`/v1/flows/{id}/phases/{phaseId}`	Remove uma fase
`GET`	`/v1/flows/{id}/phases/{phaseId}/phase-actions`	Lista os módulos habilitados na fase
`POST`	`/v1/flows/{id}/phases/{phaseId}/actions`	Habilita um módulo na fase
`PUT`	`/v1/flows/{id}/phases/{phaseId}/actions/{actionId}`	Atualiza um módulo habilitado
`DELETE`	`/v1/flows/{id}/phases/{phaseId}/actions/{actionId}`	Desabilita um módulo

Nota sobre nomenclatura: neste domínio, o parâmetro de flow no caminho é literalmente {id} — diferente de outros domínios da API AgFlow, que utilizam {flowId}.

Padrão de ativação de um módulo

Para habilitar um módulo em uma fase, recomendamos seguir sempre esta ordem:

Configurar o módulo correspondente (approval-config, opinion-config, credit-engine-config, decision-engine-config, messaging-config, entre outros).

Criar a ação de fase (POST .../actions), informando o tipo de módulo em action: approval, opinion, credit-engine, decision-engine, messaging, conversation, agrisk, create-document-enable, create-document-auto, financial-report ou income-tax.

Pular a segunda etapa não gera erro na API — porém o botão ou widget correspondente simplesmente não aparece para os usuários na fase.

Regra do campo `blocksMovement`

Tipo de ação	blocksMovement
`opinion` / `approval`	sempre `true`
`messaging`	sempre `false`
`credit-engine` / `decision-engine`	`false` por padrão (exceções pontuais podem usar `true`)

Comportamentos importantes

O campo start é obrigatório na criação de uma fase — sua ausência retorna erro 400.

O campo latenessTime também é obrigatório na criação — sua ausência pode comprometer operações futuras sobre os cards da fase, retornando um erro 500. O valor padrão recomendado é 2880 (48 horas).

O campo sortingPreference.field não aceita o valor createdAt; utilize enteredCurrentPhaseAt.

Reordenar fases pelo campo index via PATCH retorna 422 caso o novo valor já esteja em uso por outra fase — recomendamos reordenar de forma sequencial, nunca em paralelo.

Remover uma fase não atualiza automaticamente o campo cardsCanBeMovedToPhase de outras fases que faziam referência a ela — recomendamos revisar e atualizar essas referências manualmente.

O campo cardsCanBeMovedToPhase é uma orientação de interface exibida no editor do flow; não é validado pela API nem pelas automações de trigger.

O caminho correto para listar os módulos habilitados é /v1/flows/{id}/phases/{phaseId}/phase-actions.

Dentro de conditions[].rule[], a chave que identifica o campo avaliado é field — o uso de path retorna erro 400.

O campo action aceita exatamente 11 valores; consultas de bureau/AgRisk utilizam o valor agrisk.

Configurar approval-config ou opinion-config sem criar a ação de fase correspondente não gera erro na API, mas o botão de voto ou parecer não aparece para o usuário.

Fase — Visão Geral

Fase — Visão geral#

Endpoints deste domínio#

Padrão de ativação de um módulo#

Regra do campo blocksMovement#

Comportamentos importantes#

Fase — Visão geral

Endpoints deste domínio

Padrão de ativação de um módulo

Regra do campo `blocksMovement`

Comportamentos importantes