Uso de Fórmulas Integradas no Ploomes

As fórmulas integradas são utilizadas para automatizar o preenchimento de campos no Ploomes a partir de informações internas (via nossa API) ou externas (via API do cliente). Essa funcionalidade é essencial para buscar dados fora do escopo padrão entre entidades ou quando é necessário integrar sistemas diferentes.

Essa aba de configuração foi feita justamente para isso: permitir que você monte requisições usando URLs (de qualquer API, não só da Ploomes), escolha o método adequado (como GET ou POST), defina autenticação, envie dados e receba respostas que vão preencher os campos automaticamente.

Estrutura da Fórmula Integrada

1. URL

É o endereço da requisição que será feita.

Importante: só podemos fazer requisições em URLs que utilizam o protocolo HTTPS

Exemplo:

https://api2.ploomes.com/Contacts?$filter=Id+eq+412923217

2. Método

Define a ação que será executada na URL. Pode ser GET, POST, PATCH, entre outros.

Exemplo:

Método: GET

Busca as informações do contato com ID 412923217.

3. Headers

Onde se define a autenticação. Para a API Ploomes, é usada a User-Key:

Exemplo:

{"user-key":"inserir user-key"}

4. JSONPath

Responsável por definir qual valor será retornado da requisição para preencher o campo.

Exemplo:

$.value[0].Name

Explicação:

• $. Início do path

• value é o array de retorno padrão da nossa API

• [0] seleciona o primeiro item do array

• .Name define qual campo daquele objeto deve ser retornado

Obs: O path pode variar de acordo com a estrutura da API usada. Recomendamos o uso do JSON Path Evaluator para facilitar a localização do FieldPath

5. Body da Requisição

Necessário apenas para métodos como POST e PATCH. Aqui será definido o que será enviado para a URL.

Pode ser preenchido com um JSON fixo ou com campos dinâmicos do Ploomes.

Conforme o print acima você pôde identificar aonde estaria localizado cada um, fora isso temos também o Mapeamento de Campos que define os campos que vão receber o resultado da fórmula (pode ser o próprio campo)

Exemplos de Uso

• Buscar dados do produto do cliente vinculado à proposta

• Filtrar opções de campos com base em atributos do cliente

• Puxar informações de sistemas externos usando dados preenchidos no Ploomes

• Retornar apenas contatos de determinada empresa em campos do tipo cliente

Erros comuns e como corrigi-los

Consulte a referência completa de códigos HTTP aqui.

403 Forbidden

• A URL está incorreta ou possui parâmetros com erro.

• Revisar a URL usada e, se necessário, pedir apoio técnico.

401 Unauthorized

• User-Key incorreta ou mal configurada nos headers.

• Em APIs externas, validar com o cliente a forma correta de autenticação.

408/504 Timeout

• A requisição demorou mais de 20 segundos.

• Otimize filtros, use TOP/SKIP, e evite muitos expands.

405 Method Not Allowed

• O método usado não é aceito pela API de destino.

• Verifique a documentação da API utilizada.

Qualquer dúvida pontual sobre esse tipo de fórmula pode ser direcionada à nossa equipe de suporte que estará à disposição para te apoiar.