Presentación
Propósito del documento
Este documento proporciona al técnico una noción general (Quick start) del funcionamiento del API REST de Gesio. Evita entrar en detalles centrándose en proporcionar un punto de partida para el desarrollador.
¿Qué es un API REST?
Un API REST (también llamadas API RESTful) es una interfaz de programación de aplicaciones (application programming interface) que cumple los requisitos de la arquitectura REST y permite la interacción con servicios web RESTful.
¿Qué es el API REST de Gesio?
El API REST de Gesio tiene como objetivo facilitar la integración de cualquier Gesio con otros sistemas permitiendo la consulta y modificación de los datos de cada Gesio.
Primeros pasos
¿Qué es la interfaz de documentación del API?
Cada GESIO con el módulo API REST activo tendrá un acceso a una interfaz de documentación de la misma (Por ejemplo: demo.gesio.com tiene la dirección https://api-demo.gesio.com/docs para alojar la documentación del API REST).
Esta documentación describe el API en formato OpenAPI (anteriormente conocido como Swagger) y además integra una versión de Swagger UI que permite operar directamente contra el API.
¿Qué se necesita para usar el API?
Para usar el API se requiere conocer las credenciales de acceso de un usuario del API. Con dichas credenciales se podrá obtener un token JWT que debe proporcionarse en las llamadas al API y que será el encargado de autenticar y autorizar dichas peticiones.
Usuarios y tokens
¿Dónde se gestionan los usuarios del API?
Los usuarios del API se gestionan en la sección "Administración > Sistema > REST API" de GESIO. Desde esta interfaz se pueden crear, borrar y modificar los usuarios del API.
También se puede obtener un token JWT de dichos usuarios pero lo más común será obtener los token solicitándolos al API de la forma que expondremos más tarde.
¿Cuánto dura un token JWT de acceso de GESIO?
Los token del API de GESIO se generan con una caducidad de unas 24 horas. GESIO se reserva el derecho a cambiar dicha caducidad en el futuro por consideraciones de seguridad.
¿Cómo puedo obtener un token de acceso con mis credenciales de usuario?
Para obtener un token de acceso nuevo, cosa que deberemos hacer periódicamente dado que los token tienen fecha de caducidad, debemos hacer una solicitud POST al API con nuestras credenciales de la forma que se muestra a continuación:
Ejemplo CURL:
curl -X POST -H "Content-Type: application/json" https://api-demo.gesio.com/login_check -d '{"username":"MiNombreDeUsuario","password":"MiContraseñaDeUsuario"}'
En el ejemplo la dirección URL del API es https://api-demo.gesio.com, el nombre de usuario es MiNombreDeUsuario y la contraseña de acceso MiContraseñaDeUsuario. Dichos valores deben corresponder con los que le haya proporcionado el administrador de GESIO.
Si las credenciales son correctas obtendrá una respuesta similar a esta que incluye el token de acceso JWT:
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NTgzODUzNDYsImV4cCI6MTY1ODQ3MTc0Niwicm9sZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJ1c2VybmFtZSI6InJhbW9uIn0.P947zBDyJvN7BLb38mQFGVC-OYNScBw793T7x4Vaq1gKXLAnDqLrkqSvnVztUE-VsJnCS_lWsYboFV0jMucfrOYzAWtMcr4azY0VjOUcH1BO2C8XxS6QfguJJ5CUl5ganO4GvMZMTgi8_NWKprDqRpIDUfgYQUHNiA5Jv0_CeEfuCJBrsYFg9vGrrkl4kE-dO3RDDwCNIm0Ip_g_M-GQ_q6SVrkDb5lBm4Vish6x8mS4wk8bTE8j6ttt_9Uq4P9pyQuVwLqsicjRt-dgTAvnnhmDhYNMNwoM1sjnYAwLE6MXCGZ6eLkYqg9gRE3yLgdXTNkL5Wpy7KE_HBjDxyOvag"}
En este caso el valor del token es la parte de la respuesta que hemos subrayado.
¿Cómo hacer una petición al API una vez dispongo de un token válido?
Para hacer una petición sobre un recurso del API debemos hacer una petición HTTP (CET, POST, PUT o DELETE en función del tipo de operación que queramos realizar) proporcionando una cabecera (access) con el formato de respuesta que preferimos (application/ld+json o application/json) y otra cabecera con el token de acceso (Authorization), el token de acceso debe ir precedido de la cadena Bearer y un espacio en blanco (ver ejemplo).
Ejemplo CURL de consulta de los tipos de IVA disponibles:
curl -X 'GET' 'https://api-demo.gesio.com/vat_rates' -H 'accept: application/ld+json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NTgzODUzNDYsImV4cCI6MTY1ODQ3MTc0Niwicm9sZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJ1c2VybmFtZSI6InJhbW9uIn0.P947zBDyJvN7BLb38mQFGVC-OYNScBw793T7x4Vaq1gKXLAnDqLrkqSvnVztUE-VsJnCS_lWsYboFV0jMucfrOYzAWtMcr4azY0VjOUcH1BO2C8XxS6QfguJJ5CUl5ganO4GvMZMTgi8_NWKprDqRpIDUfgYQUHNiA5Jv0_CeEfuCJBrsYFg9vGrrkl4kE-dO3RDDwCNIm0Ip_g_M-GQ_q6SVrkDb5lBm4Vish6x8mS4wk8bTE8j6ttt_9Uq4P9pyQuVwLqsicjRt-dgTAvnnhmDhYNMNwoM1sjnYAwLE6MXCGZ6eLkYqg9gRE3yLgdXTNkL5Wpy7KE_HBjDxyOvag'
Métodos y respuesta HTTP
Métodos HTTP: GET, POST, PUT, DELETE
Al API de GESIO entenderá que usaremos GET para solicitar información de un recurso (colección o recurso directamente si proporcionamos el ID del mismo).
POST Si queremos crear un nuevo recurso.
PUT para modificar un recurso existente (proporcionando el ID en la URL del recurso).
DELETE para eliminar un recurso existente (proporcionando el ID en la URL del recurso).
¿Están disponibles todos los métodos en los recursos?
No, muchos recursos no tienen habilitados los métodos POST, PUT y DELETE porque no se permite la creación, modificación y borrado de los mismos desde el API.
Códigos HTTP de respuesta correcta (2XX)
Como norma general obtendremos un código de respuesta 200 cuando solicitemos un recurso (GET) o una modificación (PUT o DELETE) y dicha solicitud se haya procesado correctamente.
Cuando una solicitud de creación (POST) de recurso sea positiva recibiremos un código de respuesta 201.
Códigos HTTP de error (4XX, 5XX)
Los código de error HTTP son muy variados, solo expondremos los más comunes:
- 401: requiere autorización (posiblemente no se haya proporcionado el token o sea incorrecto o esté cadudado)
- 403: acceso denegado (el usuario ha sido validado correctamente pero no tiene permiso para acceder al recurso o ejecutar la acción solicitada)
- 404: recurso no encontrado
Para más información puede consultar los códigos de estado HTTP en la siguiente página:
https://es.wikipedia.org/wiki/Anexo:C%C3%B3digos_de_estado_HTTP
Recursos
¿Cómo se controlan los permisos de acceso (Roles)?
Los usuarios del API tienen roles de acceso asociados que determinan a que recursos y qué acciones tienen autorizados. En el momento de la redacción de este documento estos son los roles existentes:
- ROLE_USER: Rol básico que de momento no tiene privilegios.
- ROLE_CUSTOMER: Rol para clientes que permitirá introducir pedidos y consultar información relativa al clientes (pedidos, facturas, recibos, etc).
- ROLE_SUPPLIER: Rol para proveedores que permite introducir órdenes de compra y facturas de proveedor.
- ROLE_PRODUCTS_ADMIN: Rol de administrador del catálogo que permite crear y modificar productos del catálogo de GESIO.
Recursos disponibles del API
Para consultar los recursos disponibles en el API (recursos que se irán ampliando con el paso del tiempo) la forma más sencilla es acceder a la interfaz de documentación del API (https://dominiodelapi/docs) con las credenciales de acceso de un usuario del API.
Acceso a una colección de recursos
Para acceder a los datos de una colección debemos hacer una solicitud GET a la URL del recurso.
Donde /vat_rates es la ruta del recurso (Tipos de IVA)
Acceso a un recurso (individualmente)
Cuando al acceder a una colección haya muchos recursos el sistema paginará los resultados y deberemos consultar las distintas páginas si queremos obtener la colección completa.
Si se solicita el formato ld+json se proporcionará información relativa a la paginación:
hydra:view {5}
@id: /products?page=1
@type: hydra:PartialCollectionView
hydra:first: /products?page=1
hydra:last: /products?page=67
hydra:next: /products?page=2
Si queremos acceder a los datos de un recurso debemos especificar el identificador del mismo en la URL.
curl -X 'GET' 'https://api-demo.gesio.com/vat_rates/2' -H 'accept: application/ld+json' -H 'Authorization: Bearer ELTOKEN'
{"@context":"/contexts/VatRate","@id":"/vat_rates/2","@type":"VatRate","id":2,"rate":"10.00","description":"Reducido 10%"
Paginación de las colecciones de recursos
Cuando al acceder a una colección haya muchos recursos el sistema paginará los resultados y deberemos consultar las distintas páginas si queremos obtener la colección completa.
Si se solicita el formato ld+json se proporcionará información relativa a la paginación:
hydra:view {5}
@id: /products?page=1
@type: hydra:PartialCollectionView
hydra:first: /products?page=1
hydra:last: /products?page=67
hydra:next: /products?page=2
|
|