Campos Dinâmicos (fields / fieldData)
Como ler, gravar e filtrar dados de campos dinâmicos customizados associados a cards no Perpetuus CRM.
Os Boards do Perpetuus CRM permitem a criação de campos dinâmicos por fase (ex: CNPJ, Valor da Proposta, Data de Fechamento). Para simplificar o consumo desses dados, a API expõe os campos em dois formatos: Escrita facilitada e Leitura dupla.
Escrita (POST e PUT)
Ao criar ou atualizar um card, envie as informações em formato de objeto plano contendo os pares slug: valor dentro da propriedade fields. O backend descobre automaticamente em qual fase o campo reside e realiza a validação de tipo e obrigatoriedade.
{
"data": {
"title": "Empresa ACME",
"fields": {
"cnpj": "00.000.000/0001-00",
"valor_estimado": 45000.50,
"urgencia": "ALTA"
}
}
}Atualização Parcial (PUT): Não é necessário enviar todos os campos dinâmicos no PUT. Envie apenas os slugs que deseja alterar. Os campos não declarados manterão seus valores intactos.
Leitura (GET)
Nas requisições de leitura (GET), os dados são retornados em duas chaves distintas para acomodar necessidades simples e avançadas:
1. Objeto Plano fields (Recomendado)
O objeto fields traz todos os campos dinâmicos preenchidos do card em um formato direto e desembrulhado. Ideal para integrações rápidas, Make, Zapier e envio de e-mails/templates.
{
"documentId": "card_abc123",
"title": "Empresa ACME",
"fields": {
"cnpj": "00.000.000/0001-00",
"valor_estimado": 45000.50,
"urgencia": "ALTA"
}
}2. Array Estruturado fieldData (Avançado)
Para sistemas que precisam de metadados ricos (como o tipo do campo, label cadastrado ou a fase original em que o dado foi preenchido), inclua fieldData no parâmetro populate.
{
"documentId": "card_abc123",
"fieldData": [
{
"documentId": "data_record_01",
"value": {
"val": "00.000.000/0001-00"
},
"field": {
"documentId": "field_cnpj",
"name": "CNPJ da Empresa",
"slug": "cnpj",
"type": "text"
},
"phase": {
"documentId": "phase_inbound",
"name": "Entrada"
}
}
]
}Atenção ao Storage: No array fieldData, o valor real está encapsulado sob a chave value.val. Certifique-se de navegar até esta propriedade ao ler o array cru.
Filtrar por Campos Dinâmicos na API
Para filtrar a listagem de cards com base em um campo dinâmico customizado, filtre navegando pelo array fieldData:
# Filtrar cards cujo CNPJ seja exatamente '00.000.000/0001-00'
curl -G "https://api.perpetuus.com.br/api/boards/BOARD_ID/cards" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "x-tenant-id: acme" \
--data-urlencode "filters[fieldData][field][slug]=cnpj" \
--data-urlencode "filters[fieldData][value][val]=00.000.000/0001-00"