Documentación API

API 1 comentario

Elementos necesarios para el manejo del API

  • Url servidor myGESTIÓN. 
  • Autenticación. Deberá programar su cliente API con autenticación BASICA.
    Como alternativa a la autenticación, puede pasar su usuario y password como parámetros en la URL del servidor myGESTIÓN, siendo esto nada recomendable.
Es importante que programe su cliente API de tal forma que pueda guardar sesión con el servidor API. De no ser así, en cada una de las peticiones el servidor se verá obligado a autenticar la petición, crear usuario y sesión nueva cada vez, perdiendo eficiencia y dandose un retraso de 30 segundos entre peticiones.

Recomendamos el uso de alguno de los clientes API REST existentes para familiarizarse con el uso de la API. Un ejemplo es ARC. Advanced REST Client, el cual es gratuito y puede instalarse como extensión de google chrome o como aplicación de escritorio. Con el podrá testar la API realizando las operaciones que desee y ver los resultados obtenidos antes de programar una sola línea de código.

Para ver el listado de las tablas, existe un índice en:
https://app05.mygestion.com/appMg/api/?user=usuario&password=password

Para acceder al API es necesario un usuario de myGESTIÓN, la URL del servidor y la tabla a la que se quiere acceder.Todas las tablas siguen la misma dinámica. A continuación, veremos unos ejemplos con la tabla de clientes:

Para hacer uso de la API es necesario un usuario de myGESTIÓN. Los usuarios se traducen en las personas o sesiones que podemos tener abiertas de forma simultánea en myGESTIÓN. Por ello, recomendamos la contratación de un usuario extra para conectar con la API ya que, en caso contrario, las procesos llevados a cabo por el usuario de la API se podrían interrumpir con los accesos al programa por parte de otro usuario o viceversa.

https://app05.mygestion.com/appMg/api/ApiClientes/?user=usuario&password=password

Con esta llamada al método GET se nos devolverá un documento XML con la lista de clientes registrados en la base de datos.

Aquí tienes un ejemplo práctico.

 

 

ApiClientes.get con un código

Si añadimos a la URL el código del cliente que queremos seleccionar, nos devolverá un nuevo documento con los datos del cliente seleccionado:
https://app05.mygestion.com/appMg/api/ApiClientes/710173?user=usuario&password=password

Ir al ejemplo.

 

ApiClientes.get ?schema=blank

Podemos añadir el parámetro «schema=blank» para que se nos devuelva un XML con la estructura de esa tabla para usar en los métodos POST (Insercion), PUT(Modificacion):
https://app05.mygestion.com/appMg/api/ApiClientes/?user=usuario&password=password&schema=blank

Ir al ejemplo.

 

ApiClientes.get ?schema=psynopsis

Podemos añadir el parámetro «schema=psynopsis» para que se nos devuelva un XML con el tipo de dato de cada uno de los campos y el valor por defecto que se insertará en la BBDD si uno de estos campos se envía vacío:
https://app05.mygestion.com/appMg/api/ApiClientes/?user=usuario&password=password&schema=psynopsis

Ir al ejemplo.

 

Parámetros adicionales

«display»

display=[nombreCampo1,nombreCampo2,…]

El parámetro «display» junto con una enumeración de campos de esa tabla nos permite modificar los campos que se devuelven en el listado.

Ir al ejemplo.

 

«filter»

Replica la claúsula where de SQL:
filter=[campo]=[1]           =>where campo=1
filter=[campo]=[1|10]      =>where campo>=1 and campo <=10 solo 2 valores
filter=[campo]=[1,10,11] =>where campo=1 and campo =10 and campo =11 multiples valores

Se puede utilizar «%» para campos de tipo texto en los que sólo tengamos un indicio del dato a buscar
filter=[campo]=[asd%] =>where campo like ‘asd%’.

Ir al ejemplo.

En una URL el caracter ‘%’ se ha de codificar como ‘%25’.

«sort»

Permite ordenar los registros del resultado:
sort=[campo]=[DESC]/sort=[campo]=[ASC]

Campo: nombre del campo a ordenar.

Ir al ejemplo.

 

«limit»

Limita el número de registros:

limit=4    =>limit 4
limit=4,3 =>limit 4 offset 3

Ir al ejemplo.

ApiClientes.post (INSERT)

La funcionalidad y gestión de errores es igual a la de UPDATE.

Ir al ejemplo.

ApiClientes.put (UPDATE)

Seleccionamos un cliente con GET, o usamos el schema BLANK o creamos el XML por otros medios. Tras tener la información necesaria en el XML, enviamos este documento en una llamada PUT. El cliente es modificado.
Es obligatorio que en el documento XML que se envía vaya la clave primaria del registro que queremos modificar. De lo contrario un error devuelto por el servidor le informará de este requerimiento.

Ir al ejemplo.

Cada tabla tiene una lista de campos que el XML debe incluir. En caso de que no coincidan el servidor devuelve un error.

Código de error 460

 

Si la base de datos devolviera un error, se captura y se envía en el response con el código 461.

Los códigos de error están sujetos a modificaciones.

ApiClientes.post (DELETE)

La funcionalidad y gestión de errores es igual a la de UPDATE.

Ir al ejemplo.

Recuerde que importante que programe su cliente API de tal forma que pueda guardar sesión con el servidor API. De no ser así, en cada una de las peticiones el servidor se verá obligado a autenticar la petición, crear usuario y sesión nueva cada vez, perdiendo eficiencia y dandose un retraso de 30 segundos entre peticiones.

Tablas de maestros. Ejemplo: ApiGrupos

En este apartado se incluyen todas las tablas necesarias para insertar, por ejemplo, un cliente.
La funcionalidad es idéntica, salvo en el método UPDATE, para aquellas tablas que no tienen un campo ID/código, ya que en el caso de querer cambiar este no tendríamos una referencia para la cláusula where de SQL. Por tanto, se incluye en los XML un campo ‘newNombreDelCampoIndice’.

 

 

Otros

Verificación de usuario y contraseña, mensajes de error:

https://app05.mygestion.com/appMg/api/ApiClientes/0?user=usuario&password=ContraseñaIncorrecta

 

 

https://app05.mygestion.com/appMg/api/ApiClientes/0?user=usuarioIncorrecto&password=ContraseñaIncorrecta

 

 

Historial de cambios

Podemos ver un historial con todos la cambios y actualizaciones realizadas en la API con la siguiente consulta:
https://app05.mygestion.com/appMg/api/ApiChangelog/?user=usuario&password=password

Guías relacionadas

En la siguiente guía sobre la API de myGESTIÓN tienes una serie de ejemplos prácticos sobre su funcionamiento:

Una respuesta a “Documentación API”

Deja un comentario

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.