TABLA DE CONTENIDOS

Este documento tiene la funcionalidad de poder indicar como funciona y como poder trabajar con la API de EBavel, mostrando sus virtudes y añadiendo las limitaciones que se tiene al aplicarla en una proyecto de desarrollo, para la ejemplificación del mismo se utilizara un ejemplo programado en lenguaje PHP que puede ser tomado de base para la creación de alguna herramienta en el mismo lenguaje o adaptar el código al lenguaje de su preferencia.

¿Qué es una API?


Una API como tal es a interfaz de programación de aplicaciones, conocida también por la sigla API, en inglés, application programming interface y es un conjunto de subrutinas, funciones y procedimientos que ofrece la plataforma de EBavel para poder ser utilizado por terceros como una forma para consultar, añadir, modificar o eliminar algún registro en su cuenta de Ebavel.

Limitaciones de la API


Como se menciona anteriormente, la API solamente es un conjunto de procedimientos, por ello estos ya están definidos para los procesos de Insertar, Buscar, Modificar y Eliminar, esto en procesos estáticos, por ello el intentar crear consultas añadiendo procesos como Inner Join, Left Join, etc, no son posibles, esto debido a que no se tiene acceso a la base de datos.


Estructura de archivos PHP.


En este ejemplo se manejarán 2 archivos en lenguaje PHP los cuales llamaremos Conexión y Consultas, adicional a ello deberemos crear un archivo que llamaremos “wsServer” y que tendrá la extensión .log.


Conexión: En el archivo Conexión.php se deberá tener la información de la base de datos, usuario y contraseña que manejaremos en la API de EBavel, adicional en este se encontraran las funciones necesarias para realizar las consultas, inserciones, modificaciones o forma de eliminar la base de datos.


Primeramente, añadiremos las variables globales para la url, el usuario, la contraseña y el tipo de ambiente en el que trabajaremos


global $EBavelURL;
global $EBavelUser;
global $EBavelPwd;
global $environment;
$EBavelURL = '';
$EBavelUser = ''; 
$EBavelPwd = '';
$environment = '';



$EBavelURL = deberá ser conformado por la dirección del servidor de EBavel que se utiliza https : // kpionline (Numero del servidor utilizado) .bitam.com/Versión de EBavel/api/v1/Nombre de base de datos/.

$EBavelUser= Usuario de EBavel.

$EBavelPwd= Contraseña del usuario EBavel.

Nota: El usuario que se utilice en la API no debe ser utilizado al miso tiempo en una sesión, esto debido a que si se utiliza para operaciones normales y en la API, desconectara a uno cuando el otro intente realizar alguna acción, esto puede provocar que desde nuestra aplicación no pueda trabajar correctamente o que la API marque algún error de desconexión, por ello recomendamos tener un usuario independiente para usarlo con la API

$enviroment= en este se coloca "production" o "development" dependiendo de con qué ambiente trabajen.

En este mismo archivo deberás colocar unas funciones que servirán para rellenar el archivo wsServer con errores o valores correcto de lo que se genere y otro que interpretara todas las peticiones que se realicen y las envíen al servidor y devuelva en Json.

 

La función para enviar y recibir información mediante json se llamara curlRequest y recibirá una url, un método, una arreglo con los datos necesarios y si se pasa un archivo, el dato de archivo.


function curlRequest($url, $method = 'GET', $postData = array(), $file = '')
{
  global $EBavelUser;
  global $EBavelPwd;
  global $environment;
  $bPostFile = false;
  if ($method == 'POST')
  {
    if (count($postData) > 0)
      $post = json_encode($postData);
    elseif ($file != '')
    {
      if (function_exists('curl_file_create')) { // php 5.5+
        $cFile = curl_file_create($file);
      } else { // 
        $cFile = '@' . realpath($file);
      }
      $post = array('qqfile' => $cFile);
      $bPostFile = true;
    }
    else
      return array(false, 'Missing POST data');
  }
  
  $response = '';

  writeServerLog('=======EBavel CURL Request Start=======');
  writeServerLog('Method:'.$method);
  writeServerLog('URL:'.$url);
  writeServerLog('PostData:');
  writeServerLog($postData);
  writeServerLog('JSON PostData:');
  writeServerLog(@$post);

  $ch = curl_init();
  if ($method == 'POST')
    curl_setopt($ch, CURLOPT_POST, 1);
  if ($method == 'DELETE')
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  if ($method == 'POST')
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
  $header = array();
  $header[] = 'PHP_AUTH_USER: '.$EBavelUser;
  $header[] = 'PHP_AUTH_PW: '.$EBavelPwd;
  $header[] = 'ENVIRONMENT: '.$environment;
  if (!$bPostFile)
    $header[] = 'Content-Type: application/json';
  curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt( $ch, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36');
  @curl_setopt($ch, CURLOPT_TIMEOUT, 600);
  curl_setopt($ch, CURLOPT_SSLVERSION, 4);
  // grab URL and pass it to the browser
    
  $response = curl_exec($ch);

  if ($response === false)
  {
    writeServerLog('CURL Request Error No='.curl_errno($ch));
    writeServerLog('CURL Request Error Msg='.curl_error($ch));
    return array(false, 'Failed to perform CURL request!');
  }

  curl_close($ch);
  unset($ch);

  $responseData = json_decode($response, true);
  if (isset($responseData['error']))
  {
    if ($responseData['error'] != 0)
    {
      writeServerLog('EBavel Response errorSummary:'.@$responseData['errorSummary']);
      writeServerLog('EBavel Response errorDescription:'.@$responseData['errorDescription']);
      return array(false, 'EBavel Response Error!');
    }
    else
    {
      writeServerLog('EBavel Response:');
      writeServerLog($responseData);
      return array(true, $responseData);
    }
  }
  elseif (isset($responseData['success']))
  {
    if ($responseData['success'])
    {
      writeServerLog('EBavel Response:');
      writeServerLog($responseData);
      return array(true, $responseData);
    }
    else
    {
      writeServerLog('EBavel Response errorSummary:'.@$responseData['errorSummary']);
      writeServerLog('EBavel Response errorDescription:'.@$responseData['errorDescription']);
      return array(false, 'EBavel Response Error!');
    }
  }
  else
  {
    #Crea archivo html con el error.
    $htmlFile = date('YmdHis').'_EbavelErrorRequest.html';
    error_log($response, 3, $htmlFile);
    writeServerLog('EBavel Request error. HTML file response: '.$htmlFile);
    return array(false, 'EBavel Request Error!');
  }
}


Consultas: En el archivo Consultas.php se declaran todos los datos que se pasaran a "Conexion.php" y la respuesta que recibiremos la podemos imprimir en esta misma pantalla pero puede ser pasada a alguna otra.


En este archivo tambien deberemos de añadir la linea que permita conectar con el archivo de Conexion.php esta es la siguiente "require_once('Conexion .php');" esta linea debe estar en la parte superior del documento para que respete la llamada a Conexion.php.


require_once('Conexion .php');


Consultar datos.


Las desde la api podemos realizar consulta de información capturada en Ebavel, desde la misma API podemos realizar 3 tipos de consultas, consulta de toda la información, consulta  de la información aplicando filtros y consulta de un registro buscando por un Id en especifico.


para todas las consultas de datos, sera necesario crear una función dentro del archivo Conexion.php la cual llamaremos eBavelGetFormData la cual tomara los datos que envíen desde Consultas.php y generara una url la cual pasara los valores a la función curlRequest.


function eBavelGetFormData($form, $id = -1, $select = '', $filter = '', $order = '')
{
  global $EBavelURL;
  $url = $EBavelURL.'data/'.$form;
  if ($id != -1)
    $url .= '/'.$id;
  else
    $url .= '?$select='.$select.'&$filter='.urlencode($filter).'&$orderby='.urlencode($order);

  $response = curlRequest($url, 'GET');
  if ($response[0])
    return $response[1];
  else
    return false;
}



Mostrar todos los datos de un formulario.

Desde la API podemos mostrar todos los datos de un formulario en especifico, para ello es necesario que en el archivo de Consultas.php se agregue la siguiente linea.


$response = eBavelGetFormData('FORMULARIO', -1, '', '');


Esta solicita a la función eBavelGetFormData que realice una consulta de un formulario en especifico, la clave del formulario pueden obtenerla en la aplicación de Ebavel, en el url, como se muestra en la pantalla inferior, esta por lo general se conformara de "FRM_" seguido de una combinación de números y letras que genera la miasma aplicación. 




Seguido de la clave del formulario se deberá colocar -1, esto para indicar que requerimos todo lo que la base de datos contiene de ese formulario, seguido de 2 segmentos vacíos entre comillas. Al ejecutar el registro, nos devolverá todos los registros en forma de un arreglo de datos con el que podemos trabajar (ver imagen inferior) en el arreglo podremos ver el nombre del campo y el valor que contiene, esto usando el nombre del campo interno de la aplicación.



Mostrar un registro en especifico.


Desde la API podemos mostrar todos los datos de un registro en especifico, para ello es necesario que la consulta antes colocada, reemplace el -1 por el id del registro, este debe ser el Id interno, no el Id de seguimiento que puede encontrar en el formulario, en el ejemplo anterior se puede observar que en el resultado se muestra un campo llamado "id_FRM_A266DF6C" por lo general, el valor Id que requerimos esta construido por "id_" seguido de la clave del formulario, en este caso, la consulta en el archivo de consultas quedara de la siguiente manera.


$response = eBavelGetFormData('FORMULARIO', ID, '', '');


al momento de ejecutar esta consulta, lo que nos devolverá la aplicación es un arreglo con la información del registro que coincide con el Id colocado.



Utilizar filtros en la búsqueda.


Si se requiere una búsqueda de datos desde la API es posible realizarlo utilizando la misma consulta que ya se ha establecido con anterioridad, realizando pequeñas modificaciones en la consulta. En la información que se envié a la función eBavelGetFormData se deberá añadir en el cuarto segmento la información a filtrar, en este caso deberán añadir el nombre del campo a buscar (debe ser el nombre interno del campo, este lo pueden ver en la consulta de todos los registros, pues en el arreglo se mencionan los nombre de los campos, ejemplo "FFRMS_433AF9BC" ) seguido de un igual y entre comillas lo que se desea buscar, ya sea un valor numérico, alfabético o alfanumérico.


$response = eBavelGetFormData('FORMULARIO', -1, '','CAMPO="busqueda"');


Este ultimo mostrara un resultado como la primera búsqueda, pero solo con los registros que coincidan con el filtro de búsqueda.


Obtener solo ciertos valores en la consulta.


A diferencia de la búsqueda anterior, esta permite realizar una consulta de todos los registros, pero extrayendo solo ciertos valores de cada uno, por ejemplo en lugar de hacer una consulta que traiga  todo de todos los registros, puedo hacer una consulta que solo extraiga el nombre de cada uno de los registros, para ello se utiliza la funcion eBavelGetFormData, pero de la siguiente manera.


$response = eBavelGetFormData('FORMULARIO', -1, 'CAMPO', '');


En este ultimo cambiamos la leyenda FORMULARIO por la clave del formulario,  el "-1" en caso de desear buscar de todo lo capturado en dicho formulario o un ID en especifico, seguido de comillas y entre estas mismas se añaden los campos que desea buscar, esto utilizando el nombre interno del campo, si se requiere mas de un campo, deberá ser añadido en el orden que desea visualizar y separándolos por una coma, pero siempre dentro de las comillas


$response = eBavelGetFormData('FORMULARIO', -1, 'CAMPO1,CAMPO2', '');


Crear/Modificar registro.


Para poder dar de alta un nuevo registro o modificar uno existente en nuestra base de datos realizaremos lo siguiente, en nuestro archivo de Consultas pasaremos los datos que deseamos insertar/modificar, posteriormente en nuestro archivó de Conexión trataremos los datos en una funcion llamada "eBavelSendFormData".


En el archivo Consultas.php se debera agregar la siguiente linea.


$form = 'FORMULARIO';
$appCode = 'CODIGO DE APLICACION';

$data = array();
$data['applicationCodeName'] = $appCode;
$data['environment'] = 'production';
$data['data'] = array();
$data['data'][$form] = array();
$data['data'][$form][-1] = array();
$data['data'][$form][-1]['id_FORMULARIO'] = -1; 
$data['data'][$form][-1]['CAMPO 1'] = 'valor 1';
$data['data'][$form][-1]['CAMPO 2'] = 'valor 2'; 
$response = eBavelSendFormData($form ,$data);


En esta parte lo que debemos realizar es un arreglo de datos, en el cual indicaremos los valores que deseamos pasar a Ebavel, se crea una variable llamada "$form" la cual contiene los valores del formulario y la appCode que es el código de aplicación.



posterior a la appcode se deberá crear un arreglo en el cual se deberá colocar la información de lo que e desea modificar o crear, esto debido a que el primer campo debe ser el ID del formulario y si como valor a pasar se coloca -1 indicamos que se añadirá un nuevo registro, si se coloca un ID ya existente, este modificara el registro con los valores que se agreguen posteriormente.


en la sección "$data['data'][$form][-1]['Campo 1'] = 'valor 1'; " se reemplaza "Campo 1" por la clave interna del campo donde se agregara, y en valor 1 se añade el valor que se deberá añadir en dicha columna, este mismo segmento de arreglo se puede repetir n cantidad de veces dependiendo de la cantidad de campos que desea modificar o agregar.


En el archivo Conexion.php se deberá agregar la siguiente función la cual tomara el valor de la forma y el arreglo con los datos a guardar/ modificar, así la función toma los valores de conexión y genera una url que pasa a la función de curlRequest  para ser procesada.


function eBavelSendFormData($form, $data)
{
  global $EBavelURL;
  $url = $EBavelURL.'data';
  $response = curlRequest($url, 'POST', $data);
  if ($response[0])
    return $response[1];
  else
    return false;
}



Eliminar registro.


Para poder borrar un registro en nuestra base de datos realizaremos lo siguiente, en nuestro archivo de Consultas pasaremos el id del registro a eliminar, posteriormente en nuestro archivó de Conexión pasaremos el dato a una función que llamaremos "eBavelDeleteFormData".


En el archivo Consultas.php se agregara la siguiente linea.


$response = eBavelDeleteFormData('FORMULARIO','ID');


En la linea anterior los valores que se pasan son los siguiente:


* Formulario: el cual pueden consultar en la misma aplicación de Ebavel, esto en la url del formulario en el que se encuentra el registro a eliminar.



por lo general inicia con "FRM_" seguido de datos que genera el mismo Ebavel, este dato debe ir entre comillas.


* Id del registro a eliminar: Esta clave no debe ser confundida con el ID que puede tener el registro (como se ve en la imagen) ya que el ID que se puede mostrar en el formulario es el ID autoincrementado del formulario, pero no el ID del registro, este lo pueden consultar en el mismo url del registro (en el ejemplo se puede observar que el ID del cliente es el 1003 pero el ID del registro es 1026 el cual es el que se requiere para eliminar el registro).


 


En el archivo Conexion.php se deberá agregar la siguiente función la cual tomara el valor de la forma y el Id que se desea eliminar, así la función toma los valores de conexión y genera una url que pasa a la funcion de curlRequest  para ser procesada.


function eBavelDeleteFormData($form, $id)
{
  global $EBavelURL;
  $url = $EBavelURL.'data/'.$form;
  if (is_array($id))
  {
    $url .= '/remove';
    $response = curlRequest($url, 'POST', $id);
  }
  else
  {
    $url .= '/'.$id;
    $response = curlRequest($url, 'DELETE');
  }

  if ($response[0])
    return $response[1];
  else
    return false;
}


Si todo es correcto se elimina el registro, en caso contrario en el documento wsServer.log se añadirá una linea con el error surgido en el.

Agregar documento.


Desde Ebavel es posible añadir documentos, desde la API es posible, pero para ello ya debe existir el registro y posteriormente pasar el documento a un registro en especifico.


En el archivo de Conexión se deberá agregar lo siguiente:


function eBavelPostFile($appCode, $formCode, $rowID, $fieldID, $file)
{
   global $EBavelURL;
   $url = $EBavelURL.$appCode.'/actions/uploaddocument?sectionname='.$formCode.'&rowid='.$rowID.'&fieldid='.$fieldID;
   $response = curlRequest($url, 'POST', array(), $file);
   if ($response[0])
     return $response[1];
   else
    return false;
}


Esto para poder agregar los archivos en json para enviar por la API.


Posterior a ello se deberá de añadir en el archivo de Consultas lo siguiente:


$response = eBavelPostFile('A1','A2', 'A3', 'A4','A5');


Se añadirá una variable response que llamará a la función eBavelPostFile que se agrego en el archivo de Conexión. Pasamos a indicar que debe colocar en cada uno de los valores que se deben pasar a dicha función.

A1.- Es la clave de la forma que se utilizara para cargar el archivo, este puede encontrarse en la dirección del formulario toando como ejemplo el recuadro rojo que se ve en la imagen inferior.

A2.- Esta es la clave del formulario a la que se cargara el archivo, este puede encontrarse en la dirección del formulario tomando como ejemplo el recuadro azul que se ve en la imagen inferior.


A3.- Este es el Id Interno del registro no confundir con el ID que pueda tener consecutivo el formulario, por ejemplo, en la imagen inferior el ID del cliente es el 1003 pero el Id Interno es el 1026 y este es el que se utilizaría en la API.

A4.-Este es el Id del campo que guarda el archivo, este Id por lo general es alfanumérico y es necesario para indicarle a la API a que campo va a introducirse el archivo, esto con la finalidad de que se hagan validaciones correctas.


A5.- En este deberán colocar la ruta del archivo completa, esto con la finalidad de que al leerlo la API encuentre el archivo en el directorio correcto, un ejemplo es el siguiente, si quiero tomar un archivo txt que está en mi escritorio con el nombre de Prueba, la ruta debe ser la siguiente “C:\Users\Usuario\Desktop\Prueba.txt”.


Adicional a lo anterior es necesario indicarle que la carga de documentos desde la API solo soporta archivos con un máximo de 20 Mb si estos exceden dicho peso el archivo no será cargado.