Como identificar todos os campos (padrões e customizados) e suas chaves no Ploomes para desenvolvimento através da API

Ao desenvolver integrações ou automações utilizando a API da Ploomes, é essencial saber quais campos estão disponíveis em cada entidade - como Clientes, Negócios, Tarefas, etc. Isso inclui tanto os campos nativos quanto os campos personalizados (dinâmicos).

Este artigo explica como identificar esses campos, consultar suas chaves (FieldKeys) e utilizá-las corretamente em suas requisições.

Conceitos introdutórios

Tipos de campos

• Campos nativos: são criados automaticamente pelo sistema e estão presentes em cada entidade (ex: Nome, E-mail, Data de criação).

• Campos dinâmicos: são personalizados por cada empresa e criados sob demanda diretamente na plataforma (ex: "E-mail de cobrança", "Status interno", "Fonte do lead").

O que é a FieldKey?

A FieldKey é a chave única que identifica cada campo dentro da API. É por meio dela que os dados dos campos personalizados podem ser manipulados em requisições, como criação ou atualização de registros.

Ela segue o padrão:

entidade_GUID

Exemplo: contact_A51DFABF-56CA-4F03-AABB-F89AF0E7D354 → campo da entidade Clientes (/Contacts)

Lista das principais entidades disponíveis

Consultando campos via API

Listar todos os campos da conta

Para simplificar esse processo, basta realizar uma chamada GET no endpoint de Fields, dessa forma: ​https://public-api2.ploomes.com/Fields.

Essa chamada retorna todos os campos disponíveis, incluindo os dinâmicos.

Filtrar a busca

Você pode aplicar filtros usando o parâmetro $filter.

Listar apenas campos de uma entidade específica

Para obter todos os campos de uma entidade, como Negócio, basta realizar uma requisição GET neste formato:

https://public-api2.ploomes.com/Fields?$filter=EntityId+eq+2

Listar apenas os campos dinâmicos de Clientes

Para isso, faça uma chamada GET em Fields com o parâmetro de $filter, dessa forma: https://public-api2.ploomes.com/Fields?$filter=EntityId+eq+1+and+Dynamic+eq+true&$expand=Type($select=NativeType)&$select=Name,Key,Type

EntityId = 1 → Clientes

Dynamic = true → Apenas campos personalizados/dinâmicos

$select → Seleciona apenas as propriedades relevantes

Na imagem acima vemos o resultado da pesquisa.

Listar campos do tipo 7 (opções pré-cadastradas)

Para campos com opções pré-cadastradas (como "Origem", "Segmento" etc.), é necessário consultar a tabela de opções vinculada.

Passo 1: Identificar o OptionsTableId do campo

Para isso, consulte os campos usando o endpoint /Fields com um $select que inclua a propriedade OptionsTableId.

No exemplo anterior esta opção não foi mostrada porque omitimos ela ao selecionar apenas o Nome, Chave e Tipo do campo ($select=Name,Key,Type). Mas no exemplo abaixo, esta informação é exibida:

https://public-api2.ploomes.com/Fields@OptionsTables?$filter=Id+eq+1204&$expand=Options

Na imagem acima vemos o resultado.

Passo 2: Consultar as opções disponíveis

Usando o código 1204 retornado, pode-se então realizar uma chamada em OptionsTable para descobrir todas as opções válidas, como mostrado abaixo:

https://public-api2.ploomes.com/Fields@OptionsTables?$filter=Id+eq+1204&$expand=Options

A resposta mostrará todas as opções válidas, com seus respectivos IDs.

Na imagem acima vemos o resultado.

Se a intenção for adicionar uma Empresa e informar que a "Faculdade" relacionada é "Universidade Federal do Rio Grande do Norte", basta dar um POST em "Contacts" e incluir um objeto no Array de OtherProperties.

Exemplo

"OtherProperties": [
  {
    "FieldKey": "contact_94F9848B-7F0A-4BC4-9BC6-E1E9D846563B",
    "IntegerValue": 18653
  }
]

Listar campos específicos como "Telefones"

Para campos como "Telefones", que armazenam conjuntos de números, é necessário expandir o objeto "Phones" no Endpoint "Contacts" durante uma requisição GET.

Exemplo

https://public-api2.ploomes.com/Contacts?$expand=Phones

Na imagem acima vemos o resultado.

Utilizando campos personalizados (dinâmicos) em requisições

Uma vez com a FieldKey em mãos, você pode usá-la em requisições POST ou PATCH dentro do objeto OtherProperties.

Exemplo: criar um Cliente com o campo "E-mail de cobrança" preenchido

POST em /Contacts:

{
  "Name": "Cliente Exemplo",
  "OtherProperties": [
    {
      "FieldKey": "contact_A51DFABF-56CA-4F03-AABB-F89AF0E7D354",
      "StringValue": "cobranca@ploomes.com"
    }
  ]
}

O tipo do campo define o sufixo usado na propriedade de valor:

• String → StringValue

• Inteiro → IntegerValue

• Booleano → BooleanValue

• Decimal → DecimalValue

• Data → DateTimeValue

---

Acesse a Universidade Ploomes para saber mais

A Ploomes disponibiliza uma plataforma de educação digital criada para capacitar seus clientes, oferecendo uma variedade de cursos, shorts e casos de uso.

Abaixo, você confere sugestões de conteúdos disponíveis em nossa plataforma que se relacionam ao tema deste artigo.

---

Dúvidas, comentários ou sugestões? Entre em contato com nosso time de suporte! Nos vemos online.