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 pathvalueé o array de retorno padrão da nossa API[0]seleciona o primeiro item do array.Namedefine 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 muitosexpands.
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.