Manual del API Genérica de eFactory ERP v1.0 (Versión 18.02.10)

Factory Soft
Manual del API Generica de eFactory
Versión 1.0
03 de febrero de 2018

Factory Soft 2
https://efactoryerp.com
Historial de Cambios
Versión Fecha Observaciones Responsable
V1.0 03/02/2018 Creación del Manual RJG

Factory Soft 3
Contenido
Historial de Cambios......................................................................................................................2
Información General del API Genérica de eFactory ..........................................................................4
Procedimiento para Configurar el API Key....................................................................................4
Funcionalidad Expuesta..................................................................................................................5
Uso del API General de eFactory.....................................................................................................6
Método: seleccionar...................................................................................................................6
Ejemplo con resultado=json ....................................................................................................6
Ejemplo con resultado=json2 ..................................................................................................7
Ejemplo con resultado=xml.....................................................................................................7
Limitaciones:..........................................................................................................................8
Método: actualizar.....................................................................................................................8
Método: insertar........................................................................................................................8
Método:eliminar.......................................................................................................................9
ConsideracionesAdicionales.......................................................................................................9
Servidor no Configurado .........................................................................................................9
Empresa no Configurada.......................................................................................................10
Operaciones no Permitidas ...................................................................................................10

Factory Soft 4
Información General del API Genérica de eFactory
El API Genérica de eFactory provee un conjuntolimitado de servicios web de propósito general,que
permiten ejecutar operaciones genérales de base de datos, principalmente seleccionar, insertar,
actualizar, o eliminar registros, todo esto bajo ciertas restricciones.
Para utilizar el API Genérica de eFactory, es necesario primero configurar el API Key, que se debe
presentar junto con los parámetros de las funciones del API.
Procedimiento para Configurar el API Key
El API de eFactory requiere configurar en cada empresa, mediante opciones del sistema, un API Key
privada y un código de usuario con permisos de acceso a la empresa.
1. Ingresar a uno de los sistemas de eFactory donde pueda acceder al formulario de Opciones,
en el módulo de Sistemas: Administrativo, Nómina, Contabilidad, Project, MP…
2. En la pantallade Ingreso,seleccionarlaempresaparala cual se deseaconfigurarel APIKey,e
ingresar en ella.
3. Abrir el formulario de Opciones (Sistemas >> Operaciones >> Opciones). Este mostrará las
opciones y valores configurados para la empresa actual.
4. Seleccionar la empresa donde se desea configurar el API Key.
5. Buscar la Propiedad“APIKEYAPI –APIKeyparaaccesoal APIde eFactory”,yasignarle unvalor
de al menos20 caracteres.Debenserletras,números,ocaracteresimprimibles(nose permite
ningún tipo de carácter de espacio o de control).
6. Buscar la Propiedad“USUBDAPI – Usuario de Base de Datos del API de eFactory”,y asignarle
un código de usuario de base de datos válido, que tenga acceso a la base de datos de la
empresa actual.
7. Buscar la Propiedad“CLABDAPI –Clave parael usuariode Base de Datos del APIde eFactory”,
y asignarle la clave del usuario de base de datos definido en la propiedad “USUBDAPI”.
Los tres valores deben permanecer privados: el usuario y clave de base de datos solo deben ser
conocidospor personal de sistemasque requierenconfigurar el API,yadicionalmenteel ApiKeydebe
ser conocido por quienes accederán al API. En particular, al consumir el API Genérica de eFactory,el
API Key debe permanecer oculto de terceros; esto se puede lograr accediendo con el API Key
únicamente desde código de servidor.

Factory Soft 5
Funcionalidad Expuesta
El API Genérica de eFactory permite ejecutar las siguientes operaciones:
Operación Descripción Observaciones
Seleccionar Permite obtener uno o más conjuntos
de datos (tablas)
El número de tablas, registros, y campos devuelto
por las operaciones de selección es limitado, tanto
en número como en tamaño en bytes. Otras
operaciones solo sepermiten en tablas temporales.
Actualizar Permite ejecutar sentencias de
actualización (UPDATE)
Otras operaciones solo se permiten en tablas
temporales.
Insertar Permite ejecutar sentencias de
inserción (INSERT)
temporales.
Eliminar Permite ejecutar sentencias de
eliminación (DELETE)
temporales.

Factory Soft 6
Uso del API General de eFactory
Para usar el API General de eFactory en una empresa, debe tener:
 Un API Key configurado en la empresa.
 Un código de usuario válido y activo con acceso a la empresa.
 El código de la empresa.
Toda conexiónconel APIdebe serrealizadaatravésde SSL para evitarexponeratercerostantoel API
Key como la información enviada y recibida por el API.
Método: seleccionar
Sintaxis:
GET https://host-efactory/api/generica/seleccionar?consulta=[CONSULTA]&respuesta=[json|json2|xml]
Content-Type: application/json; charset=utf-8
Custom-Header: apikey=[API-KEY]
Custom-Header: usuario=[CÓDIGO-DE-USUARIO]
Custom-Header: empresa=[CÓDIGO-DE-EMPRESA]
Parámetros:
 consulta: Debe contener una consulta SQL que seleccione una o más tablas de datos. Las
sentenciasINSERT,DELETE,o UPDATE solose permitensobre tablastemporalescreadasenla
misma consulta. No se permiten sentencias que cambien el contexto de la base de datos, se
conectena otras basesde datos,alterenlaestructura de tablas no temporales,omodifiquen
de algún modo la configuración de seguridad.
 resultado: debe tener uno de los tres valores “json”, “json2” o “xml”.
Respuesta:
Retorna un objeto JSON que contiene las tablas seleccionadas, con sus registros y campos.
Ejemplo con resultado=json
Si “data”esel objeto JavaScriptgeneradoapartirdel JSON devuelto: Paraaccederal primercampode
la primerafilade laprimeratabla usar “data.laTablas[0].laFilas[0][0]”;losnombresde loscampos
de la primera tabla se obtienen mediante “data.laTablas[0].laFilas”. Estructura:
{laTablas : [
{laCampos: ["campo_1", "campo_2", … "campo_M"],
laTipos: ["tipo_1", "tipo_2", … "tipo_M"],
laFilas: [
[valor, valor, … valor],
…
[valor, valor, … valor]
]
},
{laCampos: ["campo_1", "campo_2", … "campo_N"],
laTipos: ["tipo_1", "tipo_2", … "tipo_M"],
laFilas: [
…
[valor, valor, … valor]
]
}]
}

Factory Soft 7
Ejemplo con resultado=json2
Si “data” es el objeto JavaScript generado a partir del JSON devuelto: Para acceder al primer campo
“campo_1” de la primera fila en la primera tabla usar “data.laTablas[0].laFilas[0].campo_1”.
Estructura:
{laTablas : [
[
{"campo_1":valor, "campo_2":valor, … "campo_M":valor},
{"campo_1":valor, "campo_2":valor, … "campo_M":valor},
…
{"campo_1":valor, "campo_2":valor, … "campo_M":valor}
],
[
{"campo_1":valor, "campo_2":valor, … "campo_N":valor},
{"campo_1":valor, "campo_2":valor, … "campo_N":valor},
…
{"campo_1":valor, "campo_2":valor, … "campo_N":valor}
]
]}
Ejemplo con resultado=xml
Si “data” es el objeto XMLDocument a partir del JSON devuelto: Para acceder al primer campo
“campo_1” de la primera fila en la primera tabla usar “data.querySelector('tablas>tabla:nth-
child(1)>fila:nth-child(1)>campo_1').textContent”. Estructura:
<?xml version="1.0" encoding="UTF-8"?>
<tablas>
<tabla>
<fila>
<campo_1>valor</campo_1>
…
<campo_M>valor</campo_M>
</fila>
<fila>
…
</fila>
…
<fila>
…
</fila>
</tabla>
<tabla>
<fila>
…
<campo_N>valor</campo_N>
</fila>
<fila>
…
</fila>
…
<fila>
…

Factory Soft 8
</fila>
</tabla>
</tablas>
Limitaciones
El métodoSeleccionar puede devolverhastaun máximode 5 tablas de resultados,cadauna de ellas
con un máximo de 50 columnas de datos, y con un tamaño total de 10MB. Se recomienda que al
seleccionar datos de tipo cadena se eliminen los espacios extra (caracteres en blanco a la derecha)
mediante la función SQL RTRIM().
Método: actualizar
Sintaxis:
POST https://host-efactory/api/generica/actualizar
Body: consulta=[CONSULTA]
Parámetros:
 consulta: Debe contener una consulta SQL que actualice registros de una o más tablas de
datos.Las sentenciasINSERToDELETE solose permitensobretablastemporalescreadasenla
misma consulta. No se permiten sentencias que cambien el contexto de la base de datos, se
conectena otras basesde datos,alterenlaestructura de tablas no temporales,omodifiquen
de algún modo la configuración de seguridad.
Respuesta:
RetornaunobjetoJSON conunapropiedadqueindicael númerodefilasafectadasporlaactualización.
Estructura:
{lnFilasAfectadas : valor}
Método: insertar
Sintaxis:
POST https://host-efactory/api/generica/insertar
Parámetros:
 consulta: Debe contener una consulta SQL que inserte registros una tabla de datos. Las
sentencias UPDATE o DELETE solo se permitensobre tablas temporales creadas en la misma
consulta.Nose permitensentenciasque cambienelcontextode labase de datos,se conecten

Factory Soft 9
a otras basesde datos, alterenla estructurade tablas no temporales,omodifiquende algún
modo la configuración de seguridad.
Respuesta:
Retorna un objeto JSON con una propiedad que indica el número de filas insertadas.
Estructura:
Método: eliminar
Sintaxis:
POST https://host-efactory/api/generica/eliminar
Parámetros:
 consulta: Debe contener una consulta SQL que elimine registros una tabla de datos. Las
sentencias UPDATE o INSERT solo se permiten sobre tablas temporales creadas en la misma
consulta.Nose permitensentenciasque cambienelcontextode labase de datos,se conecten
a otras basesde datos, alterenla estructurade tablas no temporales, omodifiquende algún
modo la configuración de seguridad.
Respuesta:
Retorna un objeto JSON con una propiedad que indica el número de filas eliminadas.
Estructura:
Consideraciones Adicionales
En caso de que no sea posible ejecutar exitosamente la llamada al API, la respuesta de la misma
contendráinformaciónque indiquelarazóndel error.Enespecial,podráreconocerse si lallamadafue
exitosa o no al inspeccionar el estatus de la respuesta.
Servidor no Configurado
Si el servidornoestáconfiguradoparausarel APIGenéricade eFactory,devolveráunode lossiguientes
mensajes de error:
 400 – Bad Request
 404 – Not Found
 501 – Not Implemented

Factory Soft 10
En cualquier caso, es necesario adecuar la configuración del servidor antes de continuar haciendo
llamadas al API.
Empresa no Configurada
Si el servidorestáconfigurado,peronose poseenpermisosparaaccederal APIolaempresade destino
no está correctamente configurada, las llamadas al API devolverán el siguiente mensaje de error:
 401 – Unautorized:típicamente significaque no se suministróunusuario,empresa,oApiKey
válida
Operaciones no Permitidas
Esto puede ocurrir si el servidor y la empresa están correctamente configurados,y se cuenta con los
permisosde accesoapropiados,perose intentaejecutarunaoperaciónnopermitida.Eneste caso,las
llamadas al API devolverán uno de los siguientes mensajes de error:
 403 – Forbiden:típicamente significaque estáintentandoejecutarunaoperaciónnoadmitida.
 405 – Method Not Allowed: está intentando ejecutar el servicio con un verbo no admitido,
como al ejecutar el servicio Eliminar mediante el método PUT.
 413 – PayloadToLarge: ocurre cuandolosparámetros ocabeceras enviadosal servicioesmuy
largo. El tamaño máximo permitido es de aproximadamente 1MB, pero este puede ser
ampliadooreducidoenel futuro. Se recomiendaque losparámetrosenviadosnoexcedande
5KB.
Tambiénesposible querecibaotroscódigosde error,quedependeránde laconfiguracióndelservidor
y/o proxis; por ejemplo “408 - Request Timeout” o “511 - Network Authentication Required”.
Estructura de Respuesta de Error
Adicionalmenteal códigoy descripcióndel errorenviadoenlacabecerade la respuesta,el cuerpode
la misma puede contener un texto largo que explique la causa del error; normalmente devolverá el
mensaje de error generadopor el servidor de base de datos en caso de un error de sintaxis SQL o al
violar alguna restricción (clave primaria, clave foránea…).
Estructura:
{
"lnEstatus": Valor_Entero,
"lcMensaje": "Mensaje descriptivo…"
}

Manual del API Genérica de eFactory ERP v1.0 (Versión 18.02.10)

Recomendados

Recomendados

Mais conteúdo relacionado

Mais de Factory Soft - Software ERP para la Nube Latinoamericano

Mais de Factory Soft - Software ERP para la Nube Latinoamericano (20)

Manual del API Genérica de eFactory ERP v1.0 (Versión 18.02.10)