Todas as coleções
Integrações e fórmulas externas
Como identificar todos os campos (padrões e customizados) e suas chaves no Ploomes para desenvolvimento através da API
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 na API Ploomes para desenvolver integrações, automações e inserções de dados.

Lucca Leão avatar
Escrito por Lucca Leão
Atualizado há mais de uma semana

Desenvolver integrações e automações no Ploomes com a API é comum no processo de personalização do sistema. No entanto, entender quais campos estão disponíveis, especialmente os personalizados criados sob demanda, é crucial para o sucesso dessas integrações.

Este artigo visa explicar como realizar o procedimento.

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

Confira como obter uma chave de acesso neste artigo.

Obtendo a lista de todos os campos

Para simplificar esse processo, basta realizar uma chamada GET no endpoint de Fields, acessível através do link: ​https://public-api2.ploomes.com/Fields.

Isso retornará todos os campos da conta, mas é possível filtrar por critérios específicos para tornar a pesquisa mais prática. Veja a seguir.

Filtrando por critérios

Para exemplificar, suponhamos que você precise dos campos customizados de Clientes.

Para isso, pode filtrar usando o parâmetro $filter da seguinte maneira: EntityId = 1 (Clientes), Dynamic = true e TypeId = 7.

Na imagem acima vemos o resultado da pesquisa.

Exemplo

Com a FieldKey, podemos aplicar alterações diretamente na API. Seguindo o exemplo anterior, se quisermos inserir um cliente informando o "E-mail de cobrança", basta criar um objeto no seguinte padrão:

{
"FieldKey" : "contact_A51DFABF-56CA-4F03-AABB-F89AF0E7D354",
"StringValue": "cobranca@ploomes.com"
}

Essa informação deve ser adicionada a um Array de Fields, com a chave "OtherProperties".

Exemplo

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

Informações complementares:
Note que o tipo do campo "E-mail de cobrança" é String e o valor deve ser passado em um atributo chamado StringValue.

O mesmo padrão se aplica a outros tipos de campos, basta adicionar a palavra "Value" ao tipo do campo.

Por exemplo, "Integer" ficaria "IntegerValue".

Solicitando 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:


Lista das principais entidades disponíveis

1 Cliente
2 Negócio
3 Lead
4 Venda
5 Tabela da venda
6 Cotação
7 Revisão da Cotação
8 Tabela de Revisão da Cotação
10 Produto
12 Tarefa
14 Produto da Proposta
36 Registro de contato

55 Mural de Publicação

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

Para campos desse tipo, existe um endpoint específico que retorna a lista de opções disponíveis.

Primeiro, identifique o "OptionsTableId" do campo retornado no GET de Fields e faça uma chamada em OptionsTable para descobrir as opções válidas.

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

Na imagem acima vemos o resultado.

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:

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

"FieldKey" : "contact_94F9848B-7F0A-4BC4-9BC6-E1E9D846563B",
"IntegerValue": 18653

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

Na imagem acima vemos o resultado.


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

Respondeu à sua pergunta?