Pedidos API externos

Os pedidos API externos permitem-lhe definir modelos de pedido e, em seguida, desencadear chamadas de saída para qualquer API a partir de processos empresariais. Com eles, pode ligar o seu projecto a qualquer serviço de terceiros, mesmo que ainda não exista nenhum módulo para ele no mercado.

Definição

Consultar as especificações de como o pedido deve ser estruturado na documentação API do prestador de serviços com o qual se pretende ligar.

1. Para definir um novo modelo de pedido, ir para o separador "Business Logic" na barra lateral (1), mudar para o separador "External API Requests" (2), e clicar em "New API Request" (3).

2. Dar um nome ao novo pedido e, opcionalmente, uma descrição.

3. Seleccione o método HTTP de pedido e o seu URL.

4. Definir parâmetros URL, parâmetros de consulta (apenas para pedidos GET), cabeçalhos, e o corpo do pedido, introduzindo o nome do parâmetro (1), o seu tipo (2), e clicando em "Adicionar Parâmetro" (3).

O valor real destes parâmetros será definido no momento da execução do processo de negócio, onde o pedido é accionado.

Para compreender a diferença entre o URL e os parâmetros de consulta, leia mais aqui. Contudo, independentemente das normas, a documentação API do fornecedor do serviço com o qual se pretende ligar é a melhor fonte de informação sobre como construir o pedido.

Também é possível preencher automaticamente os cabeçalhos e o corpo do pedido introduzindo uma amostra JSON, o sistema criará automaticamente todos os parâmetros necessários.

Não é necessário adicionar novos parâmetros em cada separador. Alguns pedidos podem não conter quaisquer parâmetros URL, cabeçalhos, ou corpo, por exemplo.

Caso o seu pedido contenha objectos (por exemplo, carro -> cor, tamanho, etc.), terá de criar modelos virtuais para processar estes objectos mais tarde nos seus processos empresariais. Faça-o seleccionando "Modelo" no selector de tipo de parâmetro, e introduzindo os elementos de criança que necessitaria. Pode aninhar os objectos tantas vezes quantas precisar (ou seja, objecto dentro do objecto) e criar matrizes de modelos virtuais. Caso tenha utilizado o preenchimento automático, este processo foi concluído automaticamente.

5. Alterar as configurações do pedido, tais como verificação SSL, timeout, e tratamento de erros no separador "Configurações".

6. Teste o pedido clicando em "Pedido de Teste" e introduzindo todos os parâmetros requeridos. Verificar a resposta do servidor e preencher automaticamente os cabeçalhos e corpo da resposta, ou fazê-lo manualmente.

7. Guardar o modelo de pedido, clicando em "Save Request".

Utilizar

Depois de definir e guardar um novo pedido, um novo bloco ficará disponível no Editor de Processos de Negócios para o accionar.

Terá de lhe fornecer todos os componentes que gostaria de adicionar ao pedido (URL e parâmetros de consulta, cabeçalhos, e o corpo) como modelos de dados, que podem ser feitos utilizando estes blocos. Na saída, será capaz de extrair o corpo formatado da resposta, os seus cabeçalhos e o estado da resposta. É possível expandir estes modelos utilizando estes blocos.

Não é necessário ligar todas as entradas de dados para que o pedido seja accionado correctamente. Por exemplo, se tiver um pedido sem parâmetros URL, não tem de criar o seu modelo e ligá-lo.

Para cada modelo virtual que tenha definido, 2 novos blocos serão adicionados ao seu Editor de Processos de Negócios para o fazer e expandir.

Monitorização

Cada vez que acciona um pedido API, o sistema emitirá para os registos o seu tipo e endereço, o corpo do pedido, o código de estado HTTP de resposta, e o corpo de resposta. Pode emitir outras informações, tais como campos específicos do corpo de resposta, ou a latência dos registos utilizando o bloco Write to Log.