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, você 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<dynamic>(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:
|
| 404 | Not Found |
Api não encontrada |
| 405 | Method Not Allowed |
Possíveis causas:
|
| 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.
<?php
// header('Content-Type: application/json');
if( !isset($_POST['nome']) || !isset($_POST['email']) || $_POST['nome'] == '' || $_POST['email'] == '')
{
echo '{"success": "false", "msg": "Informe o nome e o e-mail"}';
exit(0);
}
$nome = $_POST['nome'];
$email = $_POST['email'];
$novoLead = new StdClass();
$novoLead->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