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.
- 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
- Api (Listado de todas las Tablas)
- ApiAlbaranesCliente
- ApiAlbaranesProveedor
- ApiAlmacenes
- ApiArticulos
- ApiAtributos
- ApiClientes
- ApiCombinaciones
- ApiContactos
- ApiDelegaciones
- ApiDetallesAlbaranesCliente
- ApiDetallesAlbaranesProveedor
- ApiDetallesFacturasCliente
- ApiDetallesFacturasProveedor
- ApiDetallesPedidosCliente
- ApiDetallesPedidosProveedor
- ApiDetallesPresupuestosCliente
- ApiDetallesPresupuestosProveedor
- ApiDivisas
- ApiEstadosPedidosCliente
- ApiEstadosPedidosProveedor
- ApiFacturasCliente
- ApiFacturasProveedor
- ApiFamilias
- ApiFormasPago
- ApiGrupos
- ApiGruposAtributos
- ApiMarcas
- ApiOrigenes
- ApiPaises
- ApiPedidosCliente
- ApiPedidosProveedor
- ApiPersonal
- ApiPresupuestosCliente
- ApiPresupuestosProveedor
- ApiProductosAtributos
- ApiProveedores
- ApiProvincias
- ApiSeriesFacturasCliente
- ApiStock
- ApiSubfamilias
- ApiTarifas
- ApiTiposIVA
- ApiTransportistas
- ApiZonas
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:
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<?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> |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 |
<?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> |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 |
<?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> |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 |
<?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> |
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.
"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%'.
"sort"
Permite ordenar los registros del resultado:
sort=[campo]=[DESC]/sort=[campo]=[ASC]
Campo: nombre del campo a ordenar.
"limit"
Limita el número de registros:
limit=4 =>limit 4
limit=4,3 =>limit 4 offset 3
ApiClientes.post (INSERT)
La funcionalidad y gestión de errores es igual a la de UPDATE.
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.
1 2 3 4 5 6 |
<?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> |
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
1 2 3 4 |
<?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.
ApiClientes.delete (DELETE)
La funcionalidad y gestión de errores es igual a la de UPDATE.
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'.
1 2 3 4 5 6 7 8 |
<?xml version="1.0" encoding="UTF-8"?> <paises> <paises> <iso><![CDATA[API]]></iso> <pais><![CDATA[newPais]]></pais> <newPais/> </paises> </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
1 2 3 4 |
<?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
1 2 3 4 |
<?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:
2 comentarios en - Documentación API
Coste de la API
¡Hola!
El uso de la API es 100 % gratuito, no tiene coste adicional.
¡Un saludo!