API de Integração GET e POST Para a documentação de programação em C# nas APIs de POST, clique aqui Para Informações sobre o Timezone das Apis (fuso horário), clique aqui O termo API vem da abreviação do termo em inglês Application Programming Interface ou Interface de Programação de Aplicativos, o que resumidamente, significa uma forma de dois sistemas se conectarem entre si. O agilityflow possui API Rest para que outros sistemas e aplicativos se conectem e interajam com o agilityflow. Essa interação ocorre usando dois métodos: GET : para outros sistema consumirem os dados do Agilityflow (Buscar informações) POST : para inserir e atualizar dados de outros sistemas no Agilityflow (Input de informações)   Como posso configurar uma API no agilityflow? Um pré-requisito para configurar uma API no agilityflow, é criar um usuário que tenha permissão para executar essa API remotamente. Usuário da API Para criar um usuário da API, basta acessar o devcenter, e no quadro da API, criar em ' Usuários da Api ': Ao clicar nessa tela, é apresentada a lista de usuários, onde é possível filtrar e interagir como em qualquer formulário. No topo, clique em 'Novo' e informe os seguintes dados: Nome: um nome para identificar o usuário. Sugestão : caso seja um sistema legado que irá chamar essa api, crie esse usuário com o nome do sistema legado. Login: nome do usuário; Chave de segurança:  chave de acesso do usuário. Essa chave, ficará visível para que possa ser consultada e informada ao outro sistema que irá fazer uso da API; API: caso já exista uma API configurada, pode ser adicionada permissão a ela nesse momento; Configurar uma API Acesse API de integração no devcenter e clique em  e em seguida clique em "Novo". Preencha os dados que seguem: Nome: identifica a configuração da API; Método: Post ou Get. Mais informações no próximo capítulo; Tipo de execução: selecione síncrona. A opção assíncrona ainda não está implementada; Ativo: marque para deixar habilitada, ou desmarque para desabilitar a API; Usuário API: selecione os usuários de API com acesso à essa configuração, e clique em . Listar (Get) - Buscar de um formulário (versão sem uso de código) Com esse método, você pode buscar qualquer tipo de informação de um determinado formulário. No cadastro de API, marque o método como "Get" e clique na opção "Configurar API para Listagem" Agora associe o usuário que você criou no passo anterior, para que ele tenha acesso de execução nessa API. Na opção configurar API para listagem, selecione o formulário que você deseja recuperar os dados. Filtros da API de GET pelo Id do formulário Além da lista completa e paginada, v ocê pode filtrar por ID ou por IDs. Todos os Ids do agilityflow são no formato de GUID, exemplo de um id: "43837013-be24-4bc9-81c1-b4cdcb6eb3dc" Você pode filtrar por um ou mais ids em uma mesma chamada de API, para isso, basta  enviar o parâmetro id ou ids colocando os ids, divididos por virgula, exemplo: id=43837013-be24-4bc9-81c1-b4cdcb6eb3dc,59a26b8b-6c32-4756-acb7-c1539baf65de,b9199893-7021-1446-f407-942c97d70b74 ou apenas 1 id id = b9199893-7021-1446-f407-942c97d70b74   Filtros por campos do formulario Você pode filtrar por qualquer campo do formulário, os comandos de filtro são similares aos comandos  de consulta do sql server e devem estar entre chaves { } filter={campo_de_numero>2 and campo_de_numero<20 and ( campo_texto='jose' or campo_texto like '%sei%' ) } Lembre-se: que a url da API deve estar com os caracteres especiais com enconded, exemplo da query acima na url: filter={(campo_de_numero%3E2%20and%20campo_de_numero%3C20)%20and%20(%20campo_texto=%27jose%27%20or%20campo_texto%20like%20%27%sei%%27%20)%20}   Paginação da API de GET A paginação da API é feita a cada 10 registros, para buscar a próxima página é só enviar o parâmetro nextPage  colocando o número da página que você deseja buscar, exemplo:  nextPage=2 Ordenação da API de GET É possível ordernar os dados de retorno da API usando os 2 parâmetros abaixo, exemplo:  sortBy =id_do_campo sortDirection =ASC   ou sortDirection =DESC Estrutura de retorno da API de GET * por uma questão de performance da API. O campo TotalRecords não será mais retornado desde Jan/2024 { "paging": { "pageSize": 10, //tamanho da paginação, considere sempre 10 "pageNumber": 1 //página atual "nextPage": 2 //próxima página a ser chamada }, "result": [ { "formId": "43837013-be24-4bc9-81c1-b4cdcb6eb3dc", //Campo Padrão: Id do formulário "createdDate": "2020-03-10 22:41:28", //Campo Padrão: Data de criação do formulário "createdBy": "59a26b8b-6c32-4756-acb7-c1539baf65de", //Campo Padrão: Id do Usuário responsável pela criação do formulário "modifiedDate": "2020-03-10 22:47:58", //Campo Padrão: Data da última alteração do formulário "modifiedBy": "59a26b8b-6c32-4756-acb7-c1539baf65de", //Campo Padrão: Id do Usuário responsável pela última alteração do formulário "workflow": { "currentSteps": [ { "id": "ede6740b-b4b8-21f7-e9c3-4f765620a213", //Campo Padrão: Id da Etapa atual do fluxo "name": "Tax Payment " //Campo Padrão: Nome da Etapa atual do fluxo }, { "id": "9c334289-47e8-49da-93a9-c2e4871e4c3d", //Campo Padrão: Id da Etapa atual do fluxo "name": "Payment deal" //Campo Padrão: Nome da Etapa atual do fluxo } ], "status": "P", //Campo Padrão: Status do fluxo, será "A", "X" ou "P" "statusName": "In progress", //Campo Padrão: Status Name será, "Approved", "Rejected", "In progress" }, "data": { //Dados e campos do formulário: Muda de acordo com os campos do formulário "name": "john", "email": "john@example.com", "age": "35", } } ] } Pronto! Agora é só executar.     Cadastrar (Post) Com esse método, você pode inserir e atualizar dados nos formulários do seu Agilityflow, aqui você deve definir o mapeamento dos dados (DE - PARA) em C#, explicitando como será feito o cadastro dos dados, quando essa API for acionada. No cadastro de API, marque o método como "Post" e clique na opção "Configurar API para Cadastro (Post)" Agora associe o usuário que você criou no passo anterior, para que ele tenha acesso de execução nessa API. Na opção configurar API, selecione o formulário que você deseja recuperar os dados. O código abaixo exemplifica como configurar uma API de Cadastro Para a documentação de programação em C# nas APIs de POST, clique aqui public async Task RunAsync(){ //converte o conteúdo enviado no body da API para JSON var json = Newtonsoft.Json.JsonConvert.DeserializeObject(content); //guarda em uma variável o ID da estrutura do formulário Cliente var idEstruturaFormulario_CLIENTE = Guid.Parse("0b56b66a-4f6f-4ded-ad04-016d7c0724e1"); await ApiContext.LogAsync("Log Message", "logtype"); if (json != null) { //verifica se o JSON recebido contém a propriedade "nome", "email" e "cel" que são necessários p cadastro if (JsonHelper.HasProperty(json, "nome") && JsonHelper.HasProperty(json, "email") && JsonHelper.HasProperty(json, "cel")){ var values = new DataDictionary(); values.Add("nome", json["nome"].ToString()); values.Add("email", json["email"].ToString()); values.Add("cel", json["cel"].ToString()); //salva a informação no banco de dados var id = await ApiContext.SaveEntityAsync(idEstruturaFormulario_CLIENTE, values); } } await ApiContext.LogAsync("Log Message", "logtype"); } Status Header de retorno de uma API Cod. Mensagem Descrição 400 BadRequest Houve algum erro inesperado pela API, verifica se em alguma programação existe um erro de sintaxe ou algo parecido. 401 Unauthorized Possíveis causas:   Provavelmente o usuário API que você está tentando executar não tem permissão para essa execução. O Accesstoken que você está usando para executar a API está vencido. O AccessToken  tem uma duração máxima de 1 hora, após esse período é necessário cria-lo novamente. Ou você estar tentando executar uma API que não está configurada 404 Not Found Api não encontrada 405 Method Not Allowed Possíveis causas:   Provavelmente o usuário API que você está tentando executar não tem permissão para essa execução. O Accesstoken que você está usando para executar a API está vencido. O AccessToken  tem uma duração máxima de 1 hora, após esse período é necessário cria-lo novamente. Ou você estar tentando executar uma API que não está configurada 200 Ok Deu tudo certo. Exemplos de execução da API   Exemplo GET via o software "POSTMAN" Importe o JSON abaixo no seu Postman para executar os exemplos abaixo. { "info": { "_postman_id": "bd36812d-37c9-4e08-9bc0-bdc28a073fcc", "name": "Agilityflow API GET", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "1. Obter AccessToken", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"username\": \"NOME_DO_USUARIO_API__COM_PERMISSAO_NESSA_API\",\"key\": \"CHAVE_DE_SEGURANÇA_DO_USUARIO_API__COM_PERMISSAO_NESSA_API\"}" }, "url": { "raw": "https://XXXXXXXXXXXXXXXXX.agilityflow.io/api/accesstoken?", "protocol": "https", "host": [ "XXXXXXXXXXXXXXXXX", "agilityflow", "io" ], "path": [ "api", "accesstoken" ], "query": [ { "key": "", "value": "", "disabled": true }, { "key": "", "value": "", "disabled": true } ] } }, "response": [] }, { "name": "2. Get API", "protocolProfileBehavior": { "disableBodyPruning": true }, "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoiOTdmZTM1NmItMDA5OC00ZTlhLTkwNTUtODMwMTA3YzM5NjA1IiwibmFtZWlkIjoibG9jYWxob3N0IiwibmJmIjoxNTY0NDI4NTk5LCJleHAiOjE1NjQ0Mjg2NTksImlhdCI6MTU2NDQyODU5OX0.ul7Emi7KDepfmRwWO91RQcTZQrc8r3xlMKJnLYcduEKeNRDGC7F15_-YojHfm1ogM32LjUV76MWxNXTLeJTrLw" }, { "key": "Content-Type", "name": "Content-Type", "type": "text", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n\n}" }, "url": { "raw": "https://XXXXXXXXXXXXXXXXX.agilityflow.io/api/data/g5e262bd-912a-4b1f-91cb-58815cfc5556?nextPage=1", "protocol": "https", "host": [ "XXXXXXXXXXXXXXXXX", "agilityflow", "io" ], "path": [ "api", "data", "g5e262bd-912a-4b1f-91cb-58815cfc5556" ], "query": [ { "key": "nextPage", "value": "1" } ] } }, "response": [] } ] }   Após a importação no Postman você precisará seguir alguns passos:   Passo 1 No Postman, abra o exemplo "1. Obter Accesstoken" Passo 2 Você precisará fazer algumas mudanças.  (1)  Troque o XXXXXX .agilityflow.io pelo seu subdomínio no agilityflow; (2)  Na aba "body", Troque o usuário e a chave de segurança da API que você criou. como na imagem abaixo: Passo 3 - Obter Access token para execução da API Por segurança, antes de cada execução de API é necessário que você gere um token para validação do usuário. Então, agora execute essa API. Copie o código retornado no JSON na propriedade "accessToken", usaremos esse código a seguir.   Passo 4 No Postman, abra o exemplo "2. Get API" Passo 5 Você precisará fazer algumas mudanças.  (1)  Troque o XXXXXX .agilityflow.io pelo seu subdomínio no agilityflow; (2)  Na aba "headers", clique no VALUE da Key "Authorization" e cole o código "accessToken" que geramos nos passos acima, após a palavra "Bearer ". Então o valor deverá ficar  " Bearer Accesstoken_que_você_colou ". (3) Troque o Id da API "/data/ g5e262bd-912a-4b1f-91cb-58815cfc5556" de exemplo pelo id da API que você acabou de criar no Agilityflow.   Então, agora execute a API para visualizar os dados retornados, você pode também consultar o Log de API do agilityflow para acompanhar todas as requisições     Exemplo em NODE de POST Suponhamos que temos uma API no agilityflow que cadastra um cliente, as informações que a API espera é "NOME", "EMAIL" e "CEL" (celular). O código abaixo demonstra como é feita a chamada da API através do NODE. Para executar, é necessário ter o NODE instalado. O pacote utilizado é o "https". Para rodar o script basta copia-lo, salvar em um arquivo com extensão .JS (exemplo: script.js)  abrir o prompt de comando e executar o script da seguinte forma: node "C:\teste\script.js" Abaixo o script NODE: Para configura só troque as 4 variáveis de configuração com as seguintes informações: hostname:  substitua pela sua URL do seu agilityflow accessToken_Credential:  aqui você coloca as credenciais (usuário da API) para execução  apiID:  id da api apiParameterBODY: json com as informações que você deseja enviar para API var http = require("https"); //config var hostname = 'demo123.agilityflow.io'; //substitua pela sua URL do seu agilityflow var accessToken_Credential = { username: 'teste', key: 'teste' }; //aqui você coloca as credenciais (usuário da API) para execução var apiID = 'e8b5b751-774d-4283-855c-fafb8e11236d'; //id da api var apiParameterBODY = { nome: 'JOSE DA SILVA', email: 'josedasilva@email.com.br', cel: '1199887766' } //body json com as informações que você deseja enviar para API //recuperar o access token function ExecuteRecuperarAccessToken(){ var options = { hostname: hostname, // port: 443, path: '/api/accesstoken', method: 'POST', headers: { "Content-Type": "application/json", "cache-control": "no-cache" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); var obj = JSON.parse(body); if(obj.success){ console.log("Recuperou o Access Token",obj.accessToken); ExecuteAPI(obj.accessToken) }else LogErro("execução do access token", body.toString()); }); }); req.write(JSON.stringify(accessToken_Credential)); req.end(); } //execute a API function ExecuteAPI(accessToken){ var options = { hostname: hostname, // port: 443, path: '/api/data/'+apiID, method: 'POST', headers: { "Authorization": "Bearer " + accessToken, "Content-Type": "application/json", "cache-control": "no-cache" } }; var req_api = http.request(options, function (res_api) { var chunks_api = []; res_api.on("data", function (chunk) { chunks_api.push(chunk); }); res_api.on("end", function () { var body = Buffer.concat(chunks_api); var obj = JSON.parse(body); if(obj.success){ console.log("Execução realizada com sucesso:" + body.toString()); }else LogErro("execução da api", body.toString()); }); }); req_api.write(JSON.stringify(apiParameterBODY)); req_api.end(); } function LogErro(local,log){ console.log('==================================================================================') console.log('E R R O - ' + local) console.log('----------------------') console.log(log); console.log('==================================================================================') } ExecuteRecuperarAccessToken(); Exemplo em PHP de POST Suponhamos que temos uma API no agilityflow que cadastra um cliente, as informações que a API espera é "NOME", "EMAIL" e "CEL" (celular). O código abaixo demonstra como é feita a chamada da API através do PHP. nome = $nome ; $novoLead->email = $email ; $novoLead->cel = $_POST['cel']; $novoLead_string = json_encode($novoLead); //////////////////////////////////// 01. BUSCAR O ACCESS TOKEN $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://XXXXXXXXXXXXXXX.agilityflow.io/api/accesstoken", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, //------------- SLL CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0, //-------------------------- CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "{\"username\": \"cadastrar_teste_1\",\"key\": \"cadastrar_teste_1\"}", CURLOPT_HTTPHEADER => array( "Content-Type: application/json", "cache-control: no-cache" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo '{"success": "false", "msg": "Não conseguimos finalizar seu cadastro. Por favor tente novamente. (0)" }'; exit(0); } $json_RESPONSE_ACCESS_TOKEN = json_decode($response); if (!isset($json_RESPONSE_ACCESS_TOKEN->accessToken)){ echo '{"success": "false", "msg": "Não conseguimos finalizar seu cadastro. Por favor tente novamente. (1)" }'; exit(0); } //////////////////////////////////// 02. EXECUTA O POST $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://XXXXXXXXXXXXXXX.agilityflow.io/api/data/b3bf7ce3-f226-4500-83cd-2873b050c742", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, //------------- SLL CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0, //-------------------------- CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => $novoLead_string, CURLOPT_HTTPHEADER => array( "Authorization: bearer ".$json_RESPONSE_ACCESS_TOKEN->accessToken, "Cache-Control: no-cache", "Content-Type: application/json" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo '{"success": "false", "msg": "Não conseguimos finalizar seu cadastro. Por favor tente novamente. (2)" }'; exit(0); } $json_RESPONSE_SUCCESS = json_decode($response); if (!isset($json_RESPONSE_SUCCESS->success)){ echo '{"success": "false", "msg": "Não conseguimos finalizar seu cadastro. Por favor tente novamente. (3)" }'; exit(0); } if ($json_RESPONSE_SUCCESS->success == false){ echo '{"success": "false", "msg": "Não conseguimos finalizar seu cadastro. Por favor tente novamente. (4)" }'; exit(0); } echo '{"success": "true", "msg": "Obrigado, recebemos seus dados aqui e já já nos falamos..." }';   Exemplo POST via o software "POSTMAN" Importe o JSON abaixo no seu Postman para executar os exemplos abaixo. { "info": { "_postman_id": "39445fe2-1bea-46b2-9045-b32337b10030", "name": "Agilityflow API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "1. Obter Accesstoken", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"username\": \"NOME_DO_USUARIO_API__COM_PERMISSAO_NESSA_API\",\"key\": \"CHAVE_DE_SEGURANÇA_DO_USUARIO_API__COM_PERMISSAO_NESSA_API\"}" }, "url": { "raw": "https://XXXXXXXXXXXXXXXXX.agilityflow.io/api/accesstoken?", "protocol": "https", "host": [ "XXXXXXXXXXXXXXXXX", "agilityflow", "io" ], "path": [ "api", "accesstoken" ], "query": [ { "key": "", "value": "", "disabled": true }, { "key": "", "value": "", "disabled": true } ] } }, "response": [] }, { "name": "2. Post API", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoiOTdmZTM1NmItMDA5OC00ZTlhLTkwNTUtODMwMTA3YzM5NjA1IiwibmFtZWlkIjoibG9jYWxob3N0IiwibmJmIjoxNTY0NDI4NTk5LCJleHAiOjE1NjQ0Mjg2NTksImlhdCI6MTU2NDQyODU5OX0.ul7Emi7KDepfmRwWO91RQcTZQrc8r3xlMKJnLYcduEKeNRDGC7F15_-YojHfm1ogM32LjUV76MWxNXTLeJTrLw" }, { "key": "Content-Type", "name": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n\n\t\t\t\"id\": \"345b65d7-4c99-426c-95fc-1dd8de76cc9d\",\n\t\t\t\"nome\": \"_123458910Cargo LEGALLLLL \"\n\t\n}" }, "url": { "raw": "https://XXXXXXXXXXXXXXXXX.agilityflow.io/api/data/b3bf7ce3-f226-4500-83cd-2873b050c742", "protocol": "https", "host": [ "XXXXXXXXXXXXXXXXX", "agilityflow", "io" ], "path": [ "api", "data", "b3bf7ce3-f226-4500-83cd-2873b050c742" ] } }, "response": [] } ] }   Após a importação no Postman você precisará seguir alguns passos:   Passo 1 No Postman, abra o exemplo "1. Obter Accesstoken" Passo 2 Você precisará fazer algumas mudanças.  (1)  Troque o XXXXXX .agilityflow.io pelo seu subdomínio no agilityflow; (2)  Na aba "body", Troque o usuário e chave de segurança da API que você criou. como na imagem abaixo: Passo 3 - Obter Access token para execução da API Por segurança, antes de cada execução de API é necessário que você gere um token para validação do usuário. Então, agora execute essa API. Copie o código retornado no JSON na propriedade "accessToken", usaremos esse código a seguir.   Passo 4 No Postman, abra o exemplo "2. Post API" Passo 5 Você precisará fazer algumas mudanças.  (1)  Troque o XXXXXX .agilityflow.io pelo seu subdomínio no agilityflow; (2)  Na aba "headers", clique no VALUE da Key "Authorization" e cole o código "accessToken" que geramos nos passos acima, após a palavra "Bearer ". Então o valor deverá ficar  " Bearer Accesstoken_que_você_colou ". (3) Troque o Id da API "/data/ b3bf7ce3-f226-4500-83cd-2873b050c742" de exemplo pelo id da API que você acabou de criar no Agilityflow.   (4) Na aba "body" você pode trocar os valores que você deseja inserir ou atualizar: Então, agora execute essa API e entre no seu log de API do agilityflow para acompanhar e verificar se deu certo