Campos — Visão geral

Os campos de fase são os campos customizados exibidos e preenchidos pelos usuários enquanto um card permanece em uma fase do flow — complementares aos campos nativos do card e aos campos do formulário inicial (start-form), que pertencem a um domínio diferente.

Campos de fase são configurados por fase: cada fase tem seu próprio conjunto de campos, ordenação (index) e agrupamento em seções. Um mesmo nome de campo pode existir em fases diferentes sem qualquer relação entre as instâncias.

Endpoints deste domínio

Método	Caminho	Descrição
`GET`	`/v1/flows/{id}/phases/{phaseId}/fields`	Lista os campos configurados na fase
`PUT`	`/v1/flows/{id}/phases/{phaseId}/fields`	Substitui integralmente os campos da fase
`PUT`	`/v1/flows/{id}/phases/{phaseId}/fields/rules`	Configura regras condicionais entre os campos

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}.

Catálogo de tipos de campo

Tipo	Descrição
`shortText`	Texto em linha única
`longText`	Texto livre multi-linha
`select`	Lista de opções, seleção única — `options` como array de strings
`radio`	Opções em botões de escolha única — `options` como array de strings
`checkList`	Múltipla escolha — `options` como array de strings
`attachment`	Upload de arquivo
`document`	Upload de documento
`date`	Data
`number`	Numérico
`currency`	Valor monetário
`email`	E-mail
`phone`	Telefone
`year`	Ano
`percentage`	Percentual
`cropYear`	Safra/ano agrícola
`float`	Numérico com casas decimais
`hour`	Horário
`currencyWithSelect`	Valor monetário com seleção de unidade/moeda
`cep`	Código postal

O valor money, aceito em outros domínios da API AgFlow (parecer técnico, mensageria), não é aceito em campos de fase — utilize currency para valores monetários.

Comportamentos importantes

A atualização de campos (PUT .../fields) é full-replace: o array enviado substitui a configuração inteira da fase. Para manter um campo existente, inclua o seu id; para remover, basta omiti-lo.

Omitir o id de um campo existente não apaga o campo — a API marca active:false e index:null, preservando o histórico de valores já preenchidos pelos cards.

O campo description é gerado automaticamente pela API; o texto de orientação exibido ao usuário deve ser enviado em help.

options é sempre um array de strings simples — nunca um array de objetos {label, value}.

Os campos uiComponent e rules não são aceitos no payload de atualização de campos: uiComponent é derivado automaticamente do type, e as regras condicionais são configuradas separadamente, via PUT .../fields/rules.

Regras condicionais (PUT .../fields/rules) só podem referenciar campos que já existem — configure os campos primeiro, depois as regras, sempre em chamadas separadas.

Regras do tipo onChange reagem a mudanças de valor (mostrar, ocultar, tornar obrigatório/opcional, limpar ou definir o valor de outro campo). Regras do tipo onCalculate calculam automaticamente o valor de um campo a partir de uma expressão envolvendo outros campos.

Para campos select, radio e checkList, o valor é sempre armazenado como array — use o operador in (com valor em array) nas condições de regra, em vez de = com uma string simples.

Recomendamos incluir sectionMetadata em todo campo, mesmo quando a fase tiver uma única seção, para manter a exibição consistente na interface.

Campos — Visão Geral

Campos — Visão geral#

Endpoints deste domínio#

Catálogo de tipos de campo#

Comportamentos importantes#

Campos — Visão geral

Endpoints deste domínio

Catálogo de tipos de campo

Comportamentos importantes