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 Bloco de Venda
7 Proposta
8 Bloco de Proposta
10 Produto
12 Tarefa
14 Produto da Proposta
20 Produto da Venda
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.