Passar para o conteúdo principal

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

Descubra como obter chaves de campos (field key) na API Ploomes para desenvolver integrações, automações e inserções de dados.

João Pedro Ledo avatar
Escrito por João Pedro Ledo
Atualizado essa semana

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.

Confira a documentação completa da nossa API neste link.

Confira como obter uma chave de acesso neste artigo.

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

Entidade

EntityId

Cliente

1

Negócio

2

Venda

4

Bloco de Venda

5

Proposta

7

Bloco de Proposta

8

Produto

10

Tarefa

12

Produto da Proposta

14

Produto da Venda

20

Registro de Contato

36

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.

Respondeu à sua pergunta?