API de Integração
aO 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:
- POST: para o recebimento de dados de outros sistemas
- GET: para outros sistema consumirem os dados do seu Agilityflow
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;
- Senha: senha para acesso à API. Essa senha, 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)
Com esse método, você pode buscar qualquer tipo de informação de um determinado formulário
Cadastrar (Post)
Com esse método, você pode inserir ou 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.
O código abaixo exemplifica como configurar uma API de Cadastro
public void Execute(){
//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");
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 NameValueCollection();
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
DataBase.SaveEntity(idEstruturaFormulario_CLIENTE, values);
}
}
}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
XPTExemploExecução em NODE para execução da API de POSTOPOST
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', password: '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();Execução em PHP da API 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\",\"password\": \"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..." }';
Execução da API 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\",\"password\": \"SENHA_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 senha 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 agilityflow para verificar se deu certo.