O objetivo deste artigo é esclarecer as diferenças e o uso de web services e do projeto de API do HEFLO. Isso ajudará você a automatizar melhor seu processo BPMN, extraindo o máximo dele sem complicar demais ou alocar recursos incorretamente.

Antes de introduzir os recursos específicos do HEFLO, é importante entender a diferença entre integrações tradicionais de web services e customizações de API.

Um web service é um mecanismo de comunicação, geralmente baseado nos protocolos REST ou SOAP, usado para trocar dados entre sistemas. Na prática, ele permite que uma aplicação envie ou receba informações de outra aplicação por meio de endpoints predefinidos e requisições e respostas estruturadas. Essas integrações podem conectar o HEFLO a sistemas de terceiros desenvolvidos interna ou externamente. No HEFLO, uma configuração de web service normalmente requer uma URL do serviço, parâmetros opcionais de caminho ou consulta, configurações de autenticação e o mapeamento de dados de requisição ou resposta usado durante a automação do processo.

As customizações de API, por outro lado, são projetadas para implementar lógica de negócios personalizada e cenários de automação avançados. Em vez de simplesmente trocar dados, uma customização de API permite que os desenvolvedores criem projetos que manipulam informações do processo programaticamente, aplicam validações e cálculos, integram múltiplos serviços, transformam dados ou executam lógicas de decisão complexas. Esses projetos podem ser desenvolvidos pela equipe do cliente ou pela equipe do HEFLO e usam funções predefinidas e APIs fornecidas pela plataforma para se comunicar diretamente com os processos automatizados por meio de objetos de contexto, parâmetros de requisição e payloads de resposta. Além disso, as customizações de API podem ser executadas e depuradas localmente durante o desenvolvimento e, posteriormente, implantadas em servidores externos ou ambientes serverless para uso em produção.

Em resumo, os web services focam principalmente na comunicação de sistema para sistema e na troca de dados, enquanto as customizações de API fornecem uma camada programável que permite um comportamento de automação avançado, lógica de processamento personalizada e recursos de integração mais profundos.

O que são Web Services no HEFLO?

No HEFLO, os web services funcionam com base no protocolo REST e na transferência de dados via JSON. Seu principal objetivo é permitir a troca de dados entre aplicações desenvolvidas por terceiros e/ou pelo usuário. Elementos BPMN como Tarefas e Eventos, Campos de Dados Externos ou Botões de Ação também podem ser usados por web services para Buscar, Enviar e Receber dados com configurações ligeiramente diferentes.

Os usos típicos para essa configuração incluem APIs de terceiros para obter registros públicos, como código postal (CEP), informações de empresas ou taxas de câmbio; automações de terceiros, como o Zapier, que podem usar webhooks; e APIs personalizadas da empresa ou integração com ERPs, entre outros.

O que são customizações de API?

Por outro lado, o HEFLO oferece um projeto de API baseado em Node.js que possui funções nativas que permitem ao usuário executar regras de negócios ou lógicas complexas para manipular dados. Além de elementos BPMN, Campos de Dados Externos e botões de Ação, também podemos usar o projeto para trabalhar em Campos de Formulário por meio das operações de Inicialização, Adição, Alteração e Remoção; chamar a API durante o fluxo de execução, definir participantes e trabalhar com registros personalizados – criação, atualização e remoção. Uma lista completa de funções nativas e gatilhos pode ser encontrada em nossa documentação da API: Link

Vantagens e limitações

A partir do resumo acima, já podemos ver as vantagens e desvantagens de cada abordagem. Os web services são normalmente usados quando nenhuma lógica de negócios complexa é necessária e o foco é apenas a transferência de dados. Os parâmetros de entrada e saída são definidos pela documentação e geralmente são fixos; estes devem ser recuperados do JSON usando acesso a propriedades de objetos (ou navegação por JSON Path), como data[0].parameters.name, e mapeados para um campo de destino. Outros cenários incluem APIs genéricas da empresa que implementam a lógica de negócios, mas são consumidas por diferentes serviços e, portanto, funcionam com dados JSON e aplicações intermediárias para permitir a comunicação entre o HEFLO e outros sistemas. Tudo isso é “estático” no sentido de que o usuário final é apenas um consumidor, mas não exige habilidades de programação, manutenção e/ou capacidade de hospedagem.

A customização de API do HEFLO permite o acesso a todos os recursos de um web service, mas com acesso a funções nativas que permitem operações específicas de dados, manipulação de dados via alias e muito mais, porém tem a desvantagem da necessidade de programação em Node.js, manutenção e hospedagem. Vale ressaltar que o HEFLO oferece um serviço de consultoria ou serviço de implementação para tais situações – fale com nossa equipe de Vendas para saber mais.

Casos de uso típicos de integração e automação

Independentemente da escolha do método de integração, primeiro precisamos definir a configuração do serviço. Para isso:

1. No seu ambiente do HEFLO, acesse o editor de processos.
   
2. No menu superior, clique nas ferramentas de visualização do editor (ícone de olho).
   
3. Selecione a opção de Web Services.
   
4. Na aba de Web Services, clique em criar um novo registro (ícone de mais).
   
5. Na página de configuração de Web service, preencha os campos obrigatórios, com base na sua configuração.
   
   1. Nome – Usado para identificar facilmente o serviço utilizado.
   2. URL de Produção – A URL usada para chamar o serviço; não insira o caminho da função aqui, isso será usado mais tarde.
      E.g.: A API de Código Postal, como o Zippopotam, requer a seguinte URL para executar uma busca:
      https://api.zippopotam.us/us/90210
      Nesta etapa, inserimos apenas a parte inicial da URL, sem os parâmetros:
      https://api.zippopotam.us/us/
   3. URL de Teste (Opcional) – Normalmente é a mesma que a URL de produção.
   4. Método – Define se a chamada é para “leitura” ou “escrita”.
   5. Tipo de autenticação – Tipo de autenticação usado pelo serviço.
      

Para serviços ou aplicações que realizam operações específicas, como consultas de banco de dados em ambientes HEFLO, ou onde uma camada adicional de proteção é necessária, podemos definir uma chave de API (API Key) e usá-la para impor a validação antes de cada chamada. Para gerar uma nova Chave de API, vá para a aba de chaves de API na página do Web service e:

1. Na aba de Chaves de API, clique em Adicionar Nova Chave (ícone de mais).
2. Se o MFA estiver configurado, será solicitado que você insira o seu Código do Autenticador.
3. Na tela de configuração, você pode definir um nome amigável para ela.
4. Feche a janela para iniciar automaticamente o download do arquivo da chave.

Assim que a chave é gerada, ela é mantida em nosso servidor com uma chave irreversível. Isso significa que não é possível lembrar a senha e, se você perder essa senha, precisará regenerar a chave e realizar a manutenção em todos os programas de chamada mantidos por você.

Observe que este não é o único método para criar a configuração ou a chave; ambos podem ser definidos diretamente no elemento BPMN, campo de formulário ou ação, e na definição do participante.

Configurações de web services

Nesta seção, demonstraremos como configurar uma chamada de web service para dois cenários diferentes: o uso de um serviço de terceiros e um projeto de API personalizado. Observe, no entanto, que documentações adicionais para outros cenários de caso podem ser encontradas em nossa Base de Conhecimento: Link.

Caso 1: Serviço de terceiros – Código postal dos EUA usando Zippopotam

O objetivo desta configuração é extrair algumas informações de código postal (país, estado, cidade) com base em um código postal fornecido. Este é um uso típico da configuração de web service, onde o usuário conhece as entradas (requisições) e saídas (respostas) esperadas.

Podemos modelar essa chamada usando uma tarefa de serviço que lê o código postal da tarefa “Coletar dados”, realiza a requisição para coletar as informações do código postal e exibe as informações na tarefa “Exibir dados”. Uma abordagem alternativa é usar um botão de ação dentro do formulário para realizar a requisição; isso elimina a tarefa de web service e pode ser útil em cenários onde as informações devem ser visualizadas pelo usuário imediatamente.

Para configurar este caso de uso, primeiro:

1. Na página principal do ambiente do HEFLO, acesse o editor de processos.
2. Abra um processo BPMN existente ou crie um do zero.
3. Verifique se o processo está com a opção Processo automatizado habilitada.
   
4. Adicione o elemento inicial, as tarefas “Coletar dados” e “Exibir dados”, a tarefa de serviço e o elemento final, conforme mostrado na imagem abaixo.
   
5. Na tarefa “Coletar dados”, vincule uma entrada de dados (formulário).
6. Dê um duplo clique no formulário para acessar a janela de criação de formulários.
7. Dentro dela, crie um campo de texto chamado “Código postal” e defina-o como obrigatório.
   
8. Faça o mesmo para a tarefa “Exibir dados”, criando também os seguintes campos de texto:
   a. País;
   b. Estado;
   c. Cidade.
   
9. Na tarefa de serviço, clique no menu de propriedades (lado direito) e localize a seção Execução.
   
10. Defina o tipo de conector como Web service.
11. Clique no botão Configurar web service para abrir a janela de configurações.
12. Aqui precisamos configurar a chamada do web service e definir os parâmetros de envio e recebimento.
    Para este exemplo, os parâmetros de entrada são enviados diretamente dentro da URL, portanto não usamos a aba “Parâmetros de envio”, apenas copie a configuração abaixo.Para mais detalhes sobre como definir corretamente a “URL de Produção” e o “Recurso”, consulte a documentação do web service.
13. Na aba de resposta, mapeie cada parâmetro recebido para o campo de destino.Observe que esta etapa requer conhecimento de acesso a propriedades de objetos; alternativamente, você pode usar soluções online, como o JSON path finder, para identificar facilmente o caminho correto dos dados.
14. Salve a configuração.
15. No editor, clique com o botão direito no elemento inicial e selecione Testar, depois Iniciar novo item de trabalho.
16. Valide a configuração.

Nota: Às vezes, o JSON de resposta possui um formato diferente do esperado, portanto, alguns ajustes podem ser necessários. Certifique-se de sempre testar antes de publicar o processo.

Caso 2: Projeto de API personalizado

O objetivo desta configuração é simular uma API interna de uma empresa que pode ser usada para executar regras de negócios sem utilizar as funções nativas do HEFLO ou para a transferência de dados entre aplicações — neste caso, calcular o custo total com base no departamento, número de parcelas e custo por mês. Como a ideia aqui é apresentar a configuração do processo BPMN, abordaremos brevemente como criar e implantar um projeto baseado em:

• Node.js + Express API;
• Expor publicamente usando o ngrok.

É necessário um conhecimento mínimo de ambos para realizar ajustes e depuração, no entanto, seguindo as etapas, este guia lhe dará acesso a uma API simples para testar a configuração do web service.

Nota: Todas estas etapas são feitas usando um terminal, como o terminal do VS Code.

1. Crie o diretório do projeto.
   a. Abra o terminal e execute:
   mkdir custom-api
   cd custom-api
2. Inicialize o projeto Node.js.
   a. Execute:
   npm init -y
   Isso cria um arquivo package.json.
3. Instale as dependências:
   npm install express
   
4. Crie o arquivo da API.
   a. Crie um arquivo chamado server.js dentro do diretório.
   b. Cole este conteúdo:
   const express = require(“express”);
   const app = express();
   app.use(express.json());
   app.post(“/computeTotal”, (req, res) => {
       const { code, param } = req.body;
       const [numberStr, decimalStr] = (param || “”).split(“;”);
       const number = parseFloat(numberStr);
       const decimal = parseFloat(decimalStr);
       let constant = 1;
       switch (code) {
           case “HR”:
               constant = 1.25;
               break;
           case “ACC”:
               constant = 1.30;
               break;
           case “IT”:
               constant = 1.15;
               break;
           default:
               constant = 1;
       }
       const total = constant * (number * decimal);
       res.json({
           total
       });
   });
   app.listen(4000, () => {
       console.log(“Server running on port 4000”);
   });
5. Execute a API localmente.
   a. Inicie o servidor.
   node server.js
   b. Saída esperada: Server running on port 4000
6. Após instalar e configurar o seu ngrok, exponha sua API local.
   a. Execute isto em um novo terminal:
   ngrok http 4000
   b. Você verá algo como:
   Forwarding https://abcd-1234.ngrok-free.app -> http://localhost:4000
   c. Seu endpoint se torna:
   https://abcd-1234.ngrok-free.app/computeTotal
7. Mantenha ambos os serviços em execução.

A próxima etapa é criar o processo BPMN e configurar a chamada do web service; para isso, reutilizaremos o diagrama apresentado no Caso 1.

1. Na página principal do ambiente do HEFLO, acesse o editor de processos.
2. Abra um processo BPMN existente ou crie um do zero.
3. Verifique se o processo está com a opção Processo automatizado habilitada.
4. Adicione o elemento inicial, as tarefas “Coletar dados” e “Exibir dados”, a tarefa de serviço e o elemento final, conforme mostrado na imagem abaixo.
   
5. Na tarefa “Coletar dados”, vincule uma entrada de dados (formulário).
6. Dê um duplo clique no formulário para acessar a janela de criação de formulários.
   A partir daqui, o processo se torna um pouco diferente:
7. Na tarefa “Coletar dados”, crie três campos e defina-os como obrigatórios:
   a. Departamento: Campo de texto com as opções “HR”, “ACC”, “IT” e “Outro”.
   b. Parcelas: Campo de número (inteiro);
   c. Custo por mês (US$): Campo de número decimal;
8. Na tarefa “Exibir dados”, crie um campo de número decimal chamado “Total (US$)”.
   
9. Na tarefa de serviço, clique no menu de propriedades (lado direito) e localize a seção Execução.
10. Defina o tipo de conector como Web service.
11. Clique no botão Configurar web service para abrir a janela de configuração.
12. Aqui precisamos configurar a chamada do web service e definir os parâmetros de envio e recebimento. Para isso, crie um novo web service e defina:
    a. URL de Produção: https://abcd-1234.ngrok-free.app/
    b. Recurso: computeTotal
    c. Método: Post
    d. Autenticação: Nenhuma
    onde a URL de produção deve ser a que foi mostrada no terminal do ngrok.
    
13. Nos parâmetros de envio, mapearemos o campo do formulário para as entradas esperadas da API, neste caso, code e param. A ideia aqui é apresentar as duas abordagens possíveis: um único campo ou múltiplos campos por entrada.
    a. Nome do parâmetro: code Valor: Department
    b. Nome do parâmetro: param Valor: :Installments;:Cost per Month (US$)
14. Por fim, a aba de resposta mapeará o total para o campo do formulário “Total (US$)”.
    a. Nome do parâmetro: total Valor: Total (US$)
15. Salve a configuração.
16. No editor, clique com o botão direito no elemento inicial e selecione Testar, depois Iniciar novo item de trabalho.
17. Valide a configuração.

É importante ressaltar que esta abordagem utiliza um projeto local para simular uma API de empresa que já está implantada e disponível online; portanto, esta implementação funcionará apenas enquanto o projeto estiver em execução.

Configurações de API do HEFLO

Esta seção final demonstrará como implantar um projeto local de API do HEFLO e usá-lo em um processo BPMN simples. Para este cenário, implementaremos um projeto de API que, ao alterar o valor no campo “Valor”, calculará um novo total após a aplicação dos impostos.

Documentações adicionais para outros cenários de caso podem ser encontradas em nossa Base de Conhecimento: Link.

A abordagem aqui é semelhante ao Caso 2, onde a ideia é apresentar a configuração do processo BPMN. Neste exemplo, abordaremos brevemente como criar e implantar uma API de integração leve baseada em:

• Node.js + Express;
• SDK do HEFLO;
• Exposição pública usando o ngrok para integração com o webhook do HEFLO.

Novamente, é necessário um conhecimento mínimo disso para realizar ajustes e depuração; no entanto, seguindo as etapas, este guia lhe dará acesso a uma API simples para testar a configuração do web service.

Nota: Todas estas etapas são feitas usando um terminal, como o terminal do VS Code.

1. Crie um diretório para o projeto.
   a. Abra o terminal:
   mkdir heflo-api-project
   cd heflo-api-project
2. Inicialize o projeto Node.js.
   a. Execute:
   npm init -y
   Isso cria um arquivo package.json.
   
3. Instale as dependências
   a. Precisamos instalar o Express.js e o SDK da API do HEFLO; para isso, execute:
   npm install express heflo-api
   npm install -D typescript ts-node @types/node @types/express
   O pacote do HEFLO fornece a manipulação do contexto de eventos para customizações de fluxo de trabalho.
4. Crie o tsconfig.json
   {
       “compilerOptions”: {
           “target”: “es2020”,
           “module”: “commonjs”,
           “strict”: false,
           “esModuleInterop”: true
       }
   }
5. Crie o servidor da API.
   a. Crie o arquivo server.ts dentro do diretório.
   b. Cole o seguinte código:
   import express from “express”;
   import * as HEFLOApi from “heflo-api”;
   const app = express();
   app.use(express.json());
   app.get(“/”, (_, res) => { res.json({ status: “HEFLO API running” }); });
   app.post(“/onChanged”, async (req, res) => {
       try {
           const context = new HEFLOApi.Events.WorkItem.OnChanged({ body: req.body });
           const department = context.WorkItem.Get(“department”);
           const amount = parseFloat(context.WorkItem.Get(“amount_uss”) || “0”);
           let tax = 1;
           switch (department) {
               case “HR”:
                   tax = 1.25;
                   break;
               case “ACC”:
                   tax = 1.30;
                   break;
               case “IT”:
                   tax = 1.15;
                   break;
               default:
                   tax = 1;
           }
           const total = amount * tax;
           context.WorkItem.Set(“total_uss”, total);
           res.json(context.GetModifiedData());
       } catch (err: any) {
           console.error(err);
           res.status(500).json({
               error: err.message
           });
       }
   });
   const PORT = 4000;
   app.listen(PORT, () => { console.log(`Server running on port ${PORT}`); });
6. Execute o projeto.
   a. Inicie o servidor:
   npx ts-node server.ts
   Saída esperada: Server running on port 4000
   
7. Após instalar e configurar o seu ngrok, exponha sua API local.
   a. Execute isto no terminal:
   ngrok http 4000
   b. Você verá algo como:
   Forwarding https://abcd-1234.ngrok-free.app -> http://localhost:4000
   Seu endpoint se torna:
   https://abcd-1234.ngrok-free.app/onChanged
8. Mantenha ambos os serviços em execução.

A próxima etapa é criar o processo BPMN e configurar a chamada do web service; para isso, usaremos um diagrama simplificado para exibir apenas o evento de alteração no campo do formulário.

1. Na página principal do ambiente do HEFLO, acesse o editor de processos.
2. Abra um processo BPMN existente ou crie um do zero.
3. Verifique se o processo está com a opção Processo automatizado habilitada.
4. Adicione o elemento inicial, as tarefas “Coletar dados” e “Exibir dados“, o elemento final, conforme mostrado na imagem abaixo.
   
5. Na tarefa “Coletar dados”, vincule uma entrada de dados (formulário).
6. Dê um duplo clique no formulário para acessar a janela de criação de formulários.
7. Na tarefa “Coletar dados”, crie três campos e defina-os da seguinte forma:
   a. Departamento: Campo de texto com as opções “HR”, “ACC”, “IT” e Outro.
   b. Valor (US$): Campo de número decimal;
   c. Total (US$): Campo de número decimal;
   
8. Aqui precisamos dar um passo adicional e, para isso, temos duas abordagens possíveis:
   a. A primeira é usar o identificador do campo para mapear o campo do formulário dentro da aplicação; para isso:
   i. Clique no ícone de lápis no lado direito do campo e selecione a opção Editar.
   ii. Na parte inferior da janela, clique no ícone “</>” para acessar o identificador do campo e substitua field_id nas linhas como:
       context.WorkItem.Get(“field_id”);
       context.WorkItem.Set(“field_id”,);
   Para mapear o campo dentro da aplicação.
   b. A segunda é criar um alias personalizado; isso mantém o código da API mais simples e sustentável; para isso:
   i. Clique no ícone de lápis no lado direito do campo e selecione a opção Editar.
   ii. Na parte inferior da janela, clique no ícone “</>” para acessar o identificador do campo.
   iii. Selecione a opção para criar alias e confirme.
   iv. Use-os no lugar de field_id nas linhas como:
       context.WorkItem.Get(“field_id”);
       context.WorkItem.Set(“field_id”,);
   Para mapear o campo dentro da aplicação.
   c. Crie o seguinte alias para cada campo; estes devem ser os mesmos usados no código.
   Campo: Department Alias: department;
   Campo: Amount (US$) Alias: amount_uss;
   Campo: Total (US$) Alias: total_uss.
9. Agora é hora de configurar a chamada da API; selecione o campo do formulário “Valor (US$)” e clique no ícone de lápis.
10. Clique na opção Alteração, isso configurará o evento de chamada cada vez que o campo for alterado.
    
11. No tipo de customização, selecione API usando NodeJS.
12. Aqui precisamos configurar a chamada do web service. Para este exemplo, crie um novo web service e defina:
    a. URL de Produção: https://abcd-1234.ngrok-free.app/
    b. Recurso: onChanged
    c. Método: Post
    d. Autenticação: Nenhuma
    onde a URL de produção deve ser a mesma mostrada no terminal do ngrok.
    
    Observe que, diferentemente de antes, não precisamos configurar nenhum parâmetro de envio e resposta; todas as informações serão manipuladas dentro da aplicação e enviadas para o ambiente do HEFLO dentro de um contexto.
13. Confirme a configuração.
14. Salve a configuração.
15. No editor, clique com o botão direito no elemento inicial e selecione Testar, depois Iniciar novo item de trabalho.
16. Valide a configuração.

Um ponto interessante é que este pequeno projeto pode ser adaptado ainda mais para modelar regras de negócios complexas e servir como ponto de partida para futuros projetos.

É importante notar que esta abordagem usa um projeto local para simular uma API de empresa que normalmente estaria implantada e disponível online. Como resultado, esta implementação funcionará apenas enquanto o projeto local estiver em execução.

Assim que a solução for validada, por favor, coordene com sua equipe de TI para implantar o projeto em um ambiente de produção adequado. Alternativamente, o HEFLO oferece serviços de consultoria e implementação para ajudar as organizações a implantar e gerenciar suas regras de negócios. Para mais informações, entre em contato com a equipe de vendas em:  Link

Conclusão

Em resumo, este artigo explica as abordagens de integração disponíveis no HEFLO e ajuda os usuários a identificar a melhor opção para cada cenário de automação.

Os web services são normalmente usados quando nenhuma lógica de negócios complexa é necessária e o foco é apenas a transferência de dados, enquanto a customização de API do HEFLO permite o acesso a todos os recursos de um web service, mas com acesso a funções nativas que permitem operações específicas de dados, manipulação de dados e muito mais.

Para ambos os casos, foram apresentados exemplos simples de uso e configuração, mas esteja ciente de que também temos documentações adicionais relacionadas a informações ou casos de uso em nossa base de conhecimento e documentação de API.