Documentación API

API 2 comentarios

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.

Referencia a la tabla a la que queremos acceder
Parámetros adicionales
- usuario. Es recomendable no usarlo. Preferiblemente usar el método de autenticación Basic y guardar sesión.
- clave. Es recomendable no usarlo. Preferiblemente usar el método de autenticación Basic y guardar sesión.
- schema (opcional)
  - blank. Proporcionará un xml con todos los nodos en blanco de la tabla indicada. Se puede usar para posterior inserción, modificación o borrado.
  - psynopsis. Proporcionará un xml con información para cada nodo de la tabla indicada.
- filter (opcional. Se usa para establecer condiciones de consulta en métodos GET)
- sort (opcional. Se usa para ordenar la consulta realizadas con GET)
- limit (opcional. Establece un limite de registros a extraer en las consultas con GET)
Métodos
- GET (Selección)
- POST (Inserción)
- PUT (Modificación)
- DELETE (Borrado)
Tablas disponibles

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.

<?xml version="1.0" encoding="UTF-8"?>
<clientes>
    <cliente>
        <codigo>710173</codigo>
        <nombre>TestApi</nombre>
    </cliente>
    <cliente>
        <codigo>710174</codigo>
        <nombre>TestApi2</nombre>
    </cliente>
    <cliente>
        <codigo>710175</codigo>
        <nombre>TestApi3</nombre>
    </cliente>
</clientes>

<?xml version="1.0" encoding="UTF-8"?>

<nombre>TestApi</nombre>

</cliente>

<nombre>TestApi2</nombre>

</cliente>

<nombre>TestApi3</nombre>

</cliente>

</clientes>

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.

<?xml version="1.0" encoding="UTF-8"?>
<clientes>
    <cliente>
        <codigo>710000175</codigo>
        <nombre>TestApi3</nombre>
        <grupo>Cliente</grupo>
        <nombre_comercial/>
        <direccion/>
        <poblacion/>
        <provincia/>
        <pais>España</pais>
        <cod_postal/>
        <nif/>
        <tlf1/>
        <tlf2/>
        <fax/>
        <email/>
        <persona_contacto/>
        <observaciones/>
        <agente/>
        <nombre_agente/>
        <forma_pago>CONTADO</forma_pago>
        <dia_pago_1/>
        <dia_pago_2/>
        <dia_pago_3/>
        <dto_especial>0.00</dto_especial>
        <dto_pronto_pago>0.00</dto_pronto_pago>
        <tipo_dto>0</tipo_dto>
        <divisa>EUR</divisa>
        <riesgo_maximo>0.000</riesgo_maximo>
        <riesgo_alcanzado>0.000</riesgo_alcanzado>
        <euros_impagados>0.000</euros_impagados>
        <num_copias_factura>1</num_copias_factura>
        <serie_facturas>B</serie_facturas>
        <tipo_rappel/>
        <cuenta_remesas/>
        <regimen_iva>General</regimen_iva>
        <transportista/>
        <check_recargo_equiv>N</check_recargo_equiv>
        <check_fac_iva_incluido>N</check_fac_iva_incluido>
        <check_precio_mayorista>N</check_precio_mayorista>
        <subcuenta/>
        <cuenta_ventas>7000000</cuenta_ventas>
        <cuenta_ventas_servicios/>
        <responsable/>
        <zona/>
        <ruta/>
        <franquicia/>
        <valoracion/>
        <activo>SI</activo>
        <intranet_acceso>SI</intranet_acceso>
        <intranet_password/>
        <notas/>
        <api_codigo_cliente/>
        <api_origen_cliente/>
        <fecha_alta>2018-12-12</fecha_alta>
        <mandato/>
        <mandato_fecha>0000-00-00</mandato_fecha>
    </cliente>
</clientes>

<?xml version="1.0" encoding="UTF-8"?>

<nombre>TestApi3</nombre>

<grupo>Cliente</grupo>

<nombre_comercial/>

<pais>España</pais>

<cod_postal/>

<nif/>

<tlf1/>

<tlf2/>

<fax/>

<persona_contacto/>

<nombre_agente/>

<forma_pago>CONTADO</forma_pago>

<dia_pago_1/>

<dia_pago_2/>

<dia_pago_3/>

<dto_especial>0.00</dto_especial>

<dto_pronto_pago>0.00</dto_pronto_pago>

<tipo_dto>0</tipo_dto>

<riesgo_maximo>0.000</riesgo_maximo>

<riesgo_alcanzado>0.000</riesgo_alcanzado>

<euros_impagados>0.000</euros_impagados>

<num_copias_factura>1</num_copias_factura>

<serie_facturas>B</serie_facturas>

<tipo_rappel/>

<cuenta_remesas/>

<regimen_iva>General</regimen_iva>

<check_recargo_equiv>N</check_recargo_equiv>

<check_fac_iva_incluido>N</check_fac_iva_incluido>

<check_precio_mayorista>N</check_precio_mayorista>

<cuenta_ventas>7000000</cuenta_ventas>

<cuenta_ventas_servicios/>

<zona/>

<ruta/>

<intranet_acceso>SI</intranet_acceso>

<intranet_password/>

<api_codigo_cliente/>

<api_origen_cliente/>

<fecha_alta>2018-12-12</fecha_alta>

<mandato_fecha>0000-00-00</mandato_fecha>

</cliente>

</clientes>

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.

<?xml version="1.0" encoding="UTF-8"?>
<clientes>
    <cliente>
        <codigo/>
        <nombre/>
        <grupo/>
        <nombre_comercial/>
        <direccion/>
        <poblacion/>
        <provincia/>
        <pais/>
        <cod_postal/>
        <nif/>
        <tlf1/>
        <tlf2/>
        <fax/>
        <email/>
        <persona_contacto/>
        <observaciones/>
        <agente/>
        <nombre_agente/>
        <forma_pago/>
        <dia_pago_1/>
        <dia_pago_2/>
        <dia_pago_3/>
        <dto_especial/>
        <dto_pronto_pago/>
        <tipo_dto/>
        <divisa/>
        <riesgo_maximo/>
        <riesgo_alcanzado/>
        <euros_impagados/>
        <num_copias_factura/>
        <serie_facturas/>
        <tipo_rappel/>
        <cuenta_remesas/>
        <regimen_iva/>
        <transportista/>
        <check_recargo_equiv/>
        <check_fac_iva_incluido/>
        <check_precio_mayorista/>
        <subcuenta/>
        <cuenta_ventas/>
        <cuenta_ventas_servicios/>
        <responsable/>
        <zona/>
        <ruta/>
        <franquicia/>
        <valoracion/>
        <activo/>
        <intranet_acceso/>
        <intranet_password/>
        <notas/>
        <api_codigo_cliente/>
        <api_origen_cliente/>
        <fecha_alta/>
        <mandato/>
        <mandato_fecha/>
    </cliente>
</clientes>

<?xml version="1.0" encoding="UTF-8"?>

<nombre_comercial/>

<pais/>

<cod_postal/>

<nif/>

<tlf1/>

<tlf2/>

<fax/>

<persona_contacto/>

<nombre_agente/>

<forma_pago/>

<dia_pago_1/>

<dia_pago_2/>

<dia_pago_3/>

<dto_especial/>

<dto_pronto_pago/>

<tipo_dto/>

<riesgo_maximo/>

<riesgo_alcanzado/>

<euros_impagados/>

<num_copias_factura/>

<serie_facturas/>

<tipo_rappel/>

<cuenta_remesas/>

<regimen_iva/>

<check_recargo_equiv/>

<check_fac_iva_incluido/>

<check_precio_mayorista/>

<cuenta_ventas/>

<cuenta_ventas_servicios/>

<zona/>

<ruta/>

<intranet_acceso/>

<intranet_password/>

<api_codigo_cliente/>

<api_origen_cliente/>

<fecha_alta/>

<mandato_fecha/>

</cliente>

</clientes>

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.

<?xml version="1.0" encoding="UTF-8"?>
<clientes>
    <cliente>
        <codigo required="S" type="int(11)"/>
        <nombre required="S" type="char(50)"/>
        <grupo required="S" type="char(30)"/>
        <nombre_comercial type="char(40)"/>
        <direccion type="char(100)"/>
        <poblacion type="char(50)"/>
        <provincia type="char(20)"/>
        <pais defaultValue="España" type="char(30)"/>
        <cod_postal type="char(10)"/>
        <nif type="char(30)"/>
        <tlf1 type="char(20)"/>
        <tlf2 type="char(20)"/>
        <fax type="char(20)"/>
        <email type="char(60)"/>
        <persona_contacto type="char(30)"/>
        <observaciones type="char(255)"/>
        <agente type="int(11)"/>
        <nombre_agente type="char(50)"/>
        <forma_pago defaultValue="CONTADO" type="char(15)"/>
        <dia_pago_1 type="smallint(6)"/>
        <dia_pago_2 type="smallint(6)"/>
        <dia_pago_3 type="smallint(6)"/>
        <dto_especial defaultValue="0.00" type="double(5,2) porcentual dos decimales"/>
        <dto_pronto_pago defaultValue="0.00" type="double(5,2) porcentual dos decimales"/>
        <tipo_dto defaultValue="0" type="smallint(6) 0 a 6 uno de los 6 descuentos previamente definidos en articulos"/>
        <divisa defaultValue="EUR" type="char(20)"/>
        <riesgo_maximo defaultValue="0.00" type="double(12,3)"/>
        <riesgo_alcanzado defaultValue="0.00" type="double(12,3)"/>
        <euros_impagados defaultValue="0.00" type="double(12,3)"/>
        <num_copias_factura defaultValue="0" type="smallint(6)"/>
        <serie_facturas defaultValue="B" type="char(10)"/>
        <tipo_rappel type="char(3)"/>
        <cuenta_remesas type="char(2)"/>
        <regimen_iva defaultValue="General" type="char(13)"/>
        <transportista type="char(50)"/>
        <check_recargo_equiv defaultValue="N" type="char(1)"/>
        <check_fac_iva_incluido defaultValue="N" type="char(1)"/>
        <check_precio_mayorista defaultValue="N" type="char(1)"/>
        <subcuenta type="char(14)"/>
        <cuenta_ventas type="char(14)"/>
        <cuenta_ventas_servicios type="char(10)"/>
        <responsable type="char(50)"/>
        <zona type="char(50)"/>
        <ruta type="char(20)"/>
        <franquicia type="varchar(50)"/>
        <valoracion type="varchar(20)"/>
        <activo defaultValue="SI" type="varchar(2)"/>
        <intranet_acceso defaultValue="SI" type="varchar(2)"/>
        <intranet_password type="varchar(30)"/>
        <notas type="varchar(255)"/>
        <api_codigo_cliente type="char(10)"/>
        <api_origen_cliente type="char(10)"/>
        <fecha_alta defaultValue="2018-12-18" required="S" type="date"/>
        <mandato type="char(35)"/>
        <mandato_fecha type="date"/>
    </cliente>
</clientes>

<?xml version="1.0" encoding="UTF-8"?>

<nombre_comercial type="char(40)"/>

<cod_postal type="char(10)"/>

<persona_contacto type="char(30)"/>

<nombre_agente type="char(50)"/>

<forma_pago defaultValue="CONTADO" type="char(15)"/>

<dia_pago_1 type="smallint(6)"/>

<dia_pago_2 type="smallint(6)"/>

<dia_pago_3 type="smallint(6)"/>

<dto_especial defaultValue="0.00" type="double(5,2) porcentual dos decimales"/>

<dto_pronto_pago defaultValue="0.00" type="double(5,2) porcentual dos decimales"/>

<tipo_dto defaultValue="0" type="smallint(6) 0 a 6 uno de los 6 descuentos previamente definidos en articulos"/>

<riesgo_maximo defaultValue="0.00" type="double(12,3)"/>

<riesgo_alcanzado defaultValue="0.00" type="double(12,3)"/>

<euros_impagados defaultValue="0.00" type="double(12,3)"/>

<num_copias_factura defaultValue="0" type="smallint(6)"/>

<serie_facturas defaultValue="B" type="char(10)"/>

<tipo_rappel type="char(3)"/>

<cuenta_remesas type="char(2)"/>

<regimen_iva defaultValue="General" type="char(13)"/>

<check_recargo_equiv defaultValue="N" type="char(1)"/>

<check_fac_iva_incluido defaultValue="N" type="char(1)"/>

<check_precio_mayorista defaultValue="N" type="char(1)"/>

<cuenta_ventas type="char(14)"/>

<cuenta_ventas_servicios type="char(10)"/>

<intranet_acceso defaultValue="SI" type="varchar(2)"/>

<intranet_password type="varchar(30)"/>

<api_codigo_cliente type="char(10)"/>

<api_origen_cliente type="char(10)"/>

<fecha_alta defaultValue="2018-12-18" required="S" type="date"/>

<mandato_fecha type="date"/>

</cliente>

</clientes>

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.

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <message>Para borrado o modificación, es requerido el nodo clave
        primaria codigo</message>
    <code>417</code>
</error>

<?xml version="1.0" encoding="UTF-8"?>

<error>

<message>Para borrado o modificación, es requerido el nodo clave

primaria codigo</message>

</error>

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

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <message>Faltan los campos:  forma_pago  Sobran los campos:  test</message>
</error>

<?xml version="1.0" encoding="UTF-8"?>

<error>

<message>Faltan los campos: forma_pago Sobran los campos: test</message>

</error>

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.delete (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'.

<?xml version="1.0" encoding="UTF-8"?>
<paises>
    <paises>
        <iso><![CDATA[API]]></iso>
        <pais><![CDATA[newPais]]></pais>
        <newPais/>
    </paises>
</paises>

<?xml version="1.0" encoding="UTF-8"?>

</paises>

Otros

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

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

<?xml version="1.0" encoding="UTF-8" ?>
<error>
	<message>Contraseña incorrecta</message>
</error>

<?xml version="1.0" encoding="UTF-8" ?>

<error>

<message>Contraseña incorrecta</message>

</error>

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

<?xml version="1.0" encoding="UTF-8" ?>
<error>
	<message>Usuario incorrecto</message>
</error>

<?xml version="1.0" encoding="UTF-8" ?>

<error>

<message>Usuario incorrecto</message>

</error>

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:

Ejemplos en PHP para utilizar la API

2 comentarios en - Documentación API

Banesa dice:

el 22 marzo, 2024 a las 07:53

Coste de la API

Responder
- Ricardo de myGESTIÓN dice:
  
  el 25 marzo, 2024 a las 13:02
  
  ¡Hola!
  
  El uso de la API es 100 % gratuito, no tiene coste adicional.
  
  ¡Un saludo!
  
  Responder

Deja un comentario Cancelar la respuesta

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

2 comentarios en - Documentación API

Deja un comentario Cancelar la respuesta

Guías de usuario