VISMA Latinoamérica para su línea de productos de administración de personal: Visma People & Payroll, ofrece un conjunto de integraciones que llamamos “WEB API” que se disponibiliza sin costo para todos nuestros clientes y que el objetivo principal es facilitar el acceso en tiempo real, de forma sincrónica, a su información en nuestra nube.
\nSu propósito principal es brindar una interfaz amigable y segura para ser utilizada por cualquier programador experimentado y con la cual sea fácil integrar nuestra solución cloud a sus sistemas legados existentes, utilizando una arquitectura muy probada y ampliamente difundida hoy en día como ser API REST.
\nPara ello la WEB API ofrece un conjunto de servicios típicos, por ejemplo: Crear un nuevo empleado, Obtener datos de un empleado, Obtener direcciones, Obtener familiares, etc.
\nToda la documentación técnica que un desarrollador necesita para poder consumir los servicios está publicada en las URLs listadas arriba.
Esta documentación es auto-generada cada vez que se despliega una nueva versión de la documentación en POSTMAN, por lo que se garantiza que la información allí provista siempre estará al día y consistente.
Esto es una herramienta que permite documentar y probar las APIs. Es así como no sólo se puede explorar la lista de servicios y su correspondiente información (cabecera de los mensajes, parámetros, estructura de las respuestas, etc.) sino que también se pueden probar los servicios a través del navegador mismo, sin necesidad de escribir código de programación.
Todas las llamadas a las apis debe incluir un encabezado (Header) obligatorio, el cual en esta collección se encuentra agregado por codigo.
\nEl primer paso a entender es que la WEB API (así como casi cualquier otra aplicación de negocios) requiere que el usuario que desee usarla realice un Login, previo al posterior consumo de los servicios. Esto se debe a que al proveer las credenciales (usuario y clave) la WEB API determina los roles y permisos del usuario y así permitirá o denegará las peticiones a ciertos servicios, en función de si el usuario tiene suficientes permisos.
\nPor lo tanto, el primer servicio a consumir es el del Login. No obstante, una vez hecho esto satisfactoriamente, la WEB API devuelve un Token (in Base64 format), el cual sirve de “vale” para el acceso al resto de los demás servicios.
\nEste tipo de autenticación es un esquema de autenticación HTTP que cuenta con tokens de seguridad llamados “bearer” (portador), ya que para identificarse/autenticarse frente al sistema hay que ser portador de un token. El token es una cadena de caracteres encriptada, que una vez recibida tras realizar un Login exitoso, el cliente debe enviarla siempre en todas las peticiones que haga a la WEB API, en función de poder validar y conceder su permiso para dichas acciones.
\nUna vez autenticado, ya se tiene un Token de acceso y por lo tal se pueden consumir el resto de los servicios, pero esto no significa necesariamente que se tenga permisos para todos. Cada servicio tiene sus propias restricciones de seguridad, establecida según “roles”, de modo tal que si el usuario con el que se realizó el Login no tiene los roles que un servicio requiere, la petición fallará, acusando una denegación en la respuesta justamente debido a esto.
\nPara entender mejor la relación entre Usuario, Token y Tenants creemos conveniente reforzar los siguientes conceptos:
\nLas credenciales (usuario & clave) son las que se utilizarán únicamente para generar un token de acceso.
\nEste token será un parámetro requerido en todos los demás servicios de la WEB API, ya que mediante el token la WEB API realiza la autenticación y autorización a los distintos servicios.
\nEl tenant es la instancia de la aplicación asignada al cliente a la cual se conectará cada vez que se consuma un servicio, indicando así con qué fuente de datos trabajar.
\nIlustrado en el siguiente diagrama de flujo, se describe la secuencia de pasos a seguir para autenticarse frente al sistema:
\n![](\"https://lh7-qw.googleusercontent.com/docsz/AD_4nXcs_OyyW7g36O8BI_v0wQHS1dS1X1MCrkDWoHn0cjjLySfm6HXeQjC3MLyNmG_34VkhJaFMrMhaNkFgDadfBgA_Fil5oORt9SYQRzHGb_n61bo9HB5cYP0nhp6x0l15wnepGcFZj6486AUyHs1Nm0jnwMI?key=QyBRla3yulof9K4u1g78YQ\"){kind=spacer}
\n\nRealizar una petición al servicio \"/authentication/login\" para loguearse, enviando las credenciales (usuario y password). Si la respuesta es exitosa, se obtiene el Token de acceso.
\nImportante: no es necesario consumir este servicio previamente cada vez que se vaya a consumir un servicio de la WEB API, basta con hacerlo sólo una vez. Eventualmente, sí se deberá volver a realizar nuevamente el Login, y así obtener un nuevo Token, debido a alguna de las siguientes dos circunstancias:
- Se consumió el servicio \"/authentication/logout\"
- O bien se expiró el tiempo de validez del Token.
Como toda sesión de usuario, tiene un período que caduca tras determinado tiempo, y cuando esto sucede, el Token también caduca y deja de ser válido.
\n![](\"https://lh7-qw.googleusercontent.com/docsz/AD_4nXe-4TcqWPLJZJ9Nq56fKeIlSHkrpDT4ZZO344a9XQAg2ZRbXOSFW9rjlR3yip1N4Q1mm888bZgayLPeL8Vx2S7Je_1chEk9tLqzmNN4QSccrG-9vdsawntwcmeY8vmQcayaF1O_CS0ixgLQLDWU2vEGGlM?key=QyBRla3yulof9K4u1g78YQ\")
\n\nNota: el parámetro “grant_type” es un valor fijo: “password”.
La respuesta será similar a la siguiente
![](\"https://lh7-qw.googleusercontent.com/docsz/AD_4nXch5jdouQeI0zDzPiCxJLvSW5YUXgkA_CvncvqArGGuug1AslJjFXEVsBEzcdk3LftbbSV8Ghxel6Arp5MHau92xbTKIUmEq-EOtqThUqMpIWvgwjvHygqY_eN9eqErX12y4o1Uh9-wcuG81x5CfcSbzHE?key=QyBRla3yulof9K4u1g78YQ\")
\n\nAllí principalmente interesan los valores de:
\n• “expires_in”, que representa el tiempo (expresado en segundos) que el Token será válido hasta ser considerado como caducado. En este ejemplo, el valor 43.199 (segs) significa que el Token se podrá utilizar durante 12 horas, y habiendo transcurrido ese lapso de tiempo, el mismo quedará inutilizado.
\n• “access_token”, que es lo que se deberá enviar como parámetro al consumir otros endpoints.
\nRealizar una petición al servicio \"/accounts/tenants\" para obtener información de a qué bases de datos (“tenants”) se tiene concedido el permiso para poder trabajar con ellas. A este servicio - y cualquier otro - se debe presentar el Token.
Aclaración: el Identificador del Tenant o Base de Datos nunca cambiará, por lo que en realidad basta con consultar este servicio una única vez para obtener este dato.
Utilizar en la pestaña “Authorization” el token obtenido, seleccionando el type “Bearer”:
![](\"https://lh7-qw.googleusercontent.com/docsz/AD_4nXdCBN3xBWvnz1eelQIgBARuHyyMDJ6SikHIZChuAclpU7MZXt-uH-njnJUQ7Fb9YvykP-V1RGWlSzxR1JR6SwM8FDHDN5BAw1L__MxLJ0MmRmkOYXM2LtWZucKB9UKVEq0bi7XbcPIsit1DRAqo7FYEc0k?key=QyBRla3yulof9K4u1g78YQ\")
\n\nLa respuesta será similar a la siguiente:
• “Id”, que es el identificador de la Base de Datos.
• “TenantName”, que es el nombre de la Base de Datos.
• “WebApiEnabled”, que indica si la Base de Datos está habilitada para consumir vía Web API.
Una vez que ya se cuenta con un Token y un Tenant, se puede comenzar a consumir todo el resto de los servicios disponibles, en donde siempre – sin excepción – se deberá informar el ID del Tenant en el parámetro “X-RAET-Tenant-Id” y el Token en el parámetro “Authorization”.
\nEjemplo, Servicio employee:
\n![](\"https://lh7-qw.googleusercontent.com/docsz/AD_4nXcbLpnyTgIKsO7j-jhha0URex_EyykKufW2RC1hw-mwqIgNMNqjAvG_JAKR6WV4HhDLGVQ914EdLaj_ASKFZYXFyRWcEa1yKzCJ2FNxjuGRqv6LsVqTjO3rVAwwIyFCF97TZFNb-uBW4Ua8hkPvcFXDsVYV?key=QyBRla3yulof9K4u1g78YQ\")
\n\n2xx Success
\n4xx Client Error
\n5xx Client Error
\nCabe mencionar que la lista completa de código de estado/respuesta HTTP es más extensa, pero aquí sólo nos acotamos a los que la WEB API considera. Para mayor información, ver Lista completa de códigos de estado HTTP
\nLos códigos que comienzan con un 2 reflejan que el servidor ha podido resolver exitosamente la petición del cliente.
\nLos códigos que comienzan con 4 reflejan que el servidor identificó que hay algo “incorrecto” en la solicitud del cliente, y por eso la rechaza/niega. Esto puede ser o un error concreto en cómo se formuló la petición (400) o bien aún ésta estando bien, se intenta acceder a un servicio inexistente (404), a un servicio al cual no tenemos acceso (403), o bien directamente la solicitud no está autenticada (401).
\n5xx Server Error
\nLos códigos que comienzan con 5 reflejan que el servidor ha encontrado un problema y ocurrió un error. En este caso, el cliente está haciendo lo debido y es el código del servidor el que presenta fallas.
\nUn identificador (comúnmente referido sencillamente como “ID”) es una propiedad unívoca para identificar a un recurso, por el cual siempre se podrá ubicar/encontrar al mismo. Esto implica que el ID debe ser inmutable. En el contexto de una base de datos, esto es típicamente la “PK” (Primary Key o Clave Primaria) de una tabla, y este concepto es virtualmente el mismo aplicado al contexto de la WEB API.
\nIDs en la WEB API
\nHay 2 tipos de IDs: Internos y Externos:
\nLos IDs internos son valores estrictamente relacionados con los IDs en el repositorio de datos, los cuales el usuario puede o no conocer de antemano. Por esta razón, existe el segundo tipo de ID.
\nLos IDs externos son valores con los que el usuario está más familiarizado, por lo que en muchos casos le será más fácil usar éstos en vez de los IDs internos. Para ilustrar esto con un ejemplo, pensar en un libro. Probablemente no se conozca el ID interno del registro en una base de datos donde se listen libros (eso sería la Primary Key), pero sí es más accesible el código ISBN (está impreso en todos los libros del mundo), el cual no es un valor determinado arbitrariamente por la base de datos sino un estándar mundial para identificar libros.
\nUn escenario similar se puede aplicar a la WEB API de VISMA: al buscar por datos de un empleado, el usuario puede consumir un servicio que requiere se indique su ID para saber de qué empleado se devolverá la información. Ahora bien, la WEB API tiene a disposición del usuario la posibilidad de utilizar el servicio enviando el ID interno del empleado o bien su legajo (el ID externo, en este caso) para obtener exactamente la misma respuesta.
\nA continuación, se ve un ejemplo de cómo se ven las rutas URL en ambos casos:
\nUsando el ID externo (legajo del empleado): https://apim.vismalatam.com/webapi/employees/10941307
\nUsando el ID interno (id de la tabla de empleados en la base de datos) https://apim.vismalatam.com/webapi/employees/rh-22008
\nEn resumen, los IDs internos son identificadores que la WEB API utiliza para poder encontrar la información en la base de datos. Los ID externos son un medio más “amigable” provisto especialmente para que los usuarios puedan consumir los servicios con mayor facilidad. De todos modos, como se ha mencionado anteriormente, el uso ambos dos es totalmente intercambiables y la respuesta no será alterada; el resultado es el mismo.
\nPara ofrecer la máxima disponibilidad y fiabilidad de los recursos compartidos de nuestra plataforma cloud, todos los clientes que acceden a la WEB API están sujetos a unos determinados límites y cuotas definidos por cada instancia de la aplicación.
Cuando se detecten consumos mayores a lo permitido del servicio se interrumpirá de forma automática retornando un error de sobrepaso del límite de cuota permitida.
Si se supera la cuota de solicitud a la WEB API, ésta devolverá el código de error 429 y un mensaje indicando que la instancia ha superado la cuota permitida.
Los límites de cuota son diarios, en caso de sobrepaso deberá esperar hasta el día siguiente.
Se define como límite de cuota de uso las siguientes restricciones:
\n(Required) Tenant Id
\n"},{"key":"Accept","value":"application/json"}],"url":"https://apim.vismalatam.com/vlwebapiadmin/account/tenants/dbinfo","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"0"}]},"isInherited":true,"source":{"_postman_id":"c49f0dd0-5034-486f-94ed-4015ba622009","id":"c49f0dd0-5034-486f-94ed-4015ba622009","name":"Api Catalog | Visma Latam","type":"collection"}},"urlObject":{"path":["account","tenants","dbinfo"],"host":["https://apim.vismalatam.com/vlwebapiadmin"],"query":[],"variable":[]}},"response":[{"id":"5b2f0675-5078-4037-bfc4-e987f30af9d8","name":"OK","originalRequest":{"method":"GET","header":[{"key":"X-RAET-Tenant-Id","value":"Tenant Id. Leave it blank for non Tenant users.
\n"},{"key":"Accept","value":"application/json"}],"url":"https://apim.vismalatam.com/vlwebapiadmin/account/roles","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"0"}]},"isInherited":true,"source":{"_postman_id":"c49f0dd0-5034-486f-94ed-4015ba622009","id":"c49f0dd0-5034-486f-94ed-4015ba622009","name":"Api Catalog | Visma Latam","type":"collection"}},"urlObject":{"path":["account","roles"],"host":["https://apim.vismalatam.com/vlwebapiadmin"],"query":[],"variable":[]}},"response":[{"id":"68d863a9-4aa2-44cc-8033-2f7892706725","name":"OK","originalRequest":{"method":"GET","header":[{"key":"X-RAET-Tenant-Id","value":"(Required) Tenant Id
\n"},{"key":"Accept","value":"application/json"}],"url":"https://apim.vismalatam.com/vlwebapiadmin/account/account-info","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"0"}]},"isInherited":true,"source":{"_postman_id":"c49f0dd0-5034-486f-94ed-4015ba622009","id":"c49f0dd0-5034-486f-94ed-4015ba622009","name":"Api Catalog | Visma Latam","type":"collection"}},"urlObject":{"path":["account","account-info"],"host":["https://apim.vismalatam.com/vlwebapiadmin"],"query":[],"variable":[]}},"response":[{"id":"ae4673f1-af67-4db0-9a24-435948523e49","name":"OK","originalRequest":{"method":"GET","header":[{"key":"X-RAET-Tenant-Id","value":"