Autenticación
Para utilizar los diferentes recursos que ofrece la API, es necesario autenticarse como usuario de integraciones. Actualmente, existen dos vías para hacerlo: API Key y formulario de autenticación (deprecado).
API Key
El sistema de autenticación por API key funciona mediante la generación y el intercambio de una clave única (API Key) entre el cliente que realiza la petición y el servidor de la API.
Para utilizar este sistema de autenticación, basta con incorporar en cada llamada un header "Authorization" con valor "Bearer" y la API Key proporcionada por Orquest, tal y como se muestra en el siguiente ejemplo:
curl -X 'GET' \
'https://importer.orquest.es/api/v2/businesses/businessId/services' \
-H 'accept: */*' \
-H 'Authorization: Bearer XXXXXXXXXXXXXXXXXX'Cuando se recibe una solicitud que incluye una API Key, el servidor verifica la validez de la clave a través de la consulta a base de datos para asegurar que la clave proporcionada es válida y está asociada con un usuario a través de su userId.
Si la API Key es válida y se autoriza el acceso, la API responde a la solicitud con los datos solicitados o con la acción requerida. Si la clave no es válida o el acceso no está autorizado, la API devolverá el mensaje de error correspondiente.
Este proceso se repite en cada petición, pero no proporciona información adicional sobre el usuario o la aplicación en sí misma, es decir, la API Key no contiene datos compartidos sobre el usuario, como su nombre o dirección de correo electrónico.
Formulario
⚠️ Sección deprecada
El sistema tradicional utiliza autenticación basada en formularios, con usuario y contraseña como credenciales. Al enviar la petición HTTP POST a la URL login con las credenciales correctas, se obtiene un token de sesión (JSESSIONID).
Es necesario enviar username y password en el cuerpo de la petición como datos codificados en URL-encoded, tal y como aparece en el siguiente ejemplo:
curl -X POST https://importer.orquest.es/login \
-d "username=******&password=******" \
-H "Content-Type: application/x-www-form-urlencoded"Las credenciales se validan en el servidor y se crea una sesión vinculada a una clave única (token) que debe incluirse en todas las peticiones y respuestas HTTP que intercambien el cliente y el servidor.
El servidor devuelve una respuesta HTTP con código 200 que contiene un encabezado HTTP Set-Cookie con nombre JSESSIONID.
El valor de la cookie se incluye en el cuerpo de la respuesta para facilitar la gestión de la sesión en algunas herramientas de cliente con capacidades limitadas para procesar mensajes HTTP.
HTTP/1.1 200
Set-Cookie: JSESSIONID=MDY2MTFjZjktOWE2Yy00NDY5LTlhZjktYjE2NDBkNzZjNzFm; Path=/; HttpOnly; SameSite=Lax
Content-Type: application/json;charset=UTF-8
Content-Length: 65
{"JSESSIONID":"MDY2MTFjZjktOWE2Yy00NDY5LTlhZjktYjE2NDBkNzZjNzFm"}El servidor devuelve una respuesta HTTP con código 401, lo que indica que la petición no ha sido ejecutada porque carece de credenciales válidas de autenticación.
Se obtiene la misma respuesta en los siguientes supuestos:
-
Cuando se invoca una operación sin incluir la cookie JSESSIONID.
-
Cuando se incluye una cookie JSESSIONID no válida.
Así, tras una autenticación exitosa, todas las peticiones posteriores deberán incluir la cookie JSESSIONID con el valor proporcionado en la respuesta.
curl --localizacion --request POST 'http://server/api' --header 'Content-Type: application/json' \
-H 'Cookie: JSESSIONID=0000000000000000000000000'...|
Por razones de seguridad, es recomendable no enviar el usuario y la contraseña en la URL: |
Buenas prácticas
Periodos de inactividad
En la autenticación a través de formulario, la sesión no tiene un tiempo de vida máximo predefinido, pero sí se controlan los periodos de inactividad. En este sentido, pasado el tiempo máximo de inactividad, la sesión expira y el usuario tendrá que repetir el proceso de autenticación para recibir una nueva cookie JSESSIONID válida.
Cada nueva petición a la API reinicia el periodo de inactividad.
Manejo de sesiones
Con el fin de emplear los recursos de manera eficiente, es necesario que los usuarios manejen las sesiones de forma responsable. Se aconseja, por tanto, que se utilice el endpoint logout para garantizar que las sesiones no quedan abiertas.
El número de sesiones por usuario es 25.
El manejo de sesiones no es necesario en la autenticación por API Key, ya que en cada petición se debe incluir la API Key asignada al usuario.
Política de reintentos
La política de reintentos de la API permite manejar situaciones en las que una petición falla temporalmente. En lugar de simplemente devolver un error, la política de reintentos permite que se vuelva a intentar la petición después de un breve período de tiempo, esperando que la falla sea transitoria y la solicitud tenga éxito en un intento posterior. Esta política permite:
-
Detectar errores temporales como fallos de red, sobrecarga temporal del servidor o problemas de latencia.
-
Definir una estrategia de reintentos para determinar cuándo y cuántas veces se deben reintentar las peticiones fallidas.
-
Registrar y monitorear para identificar problemas persistentes que pueden requerir una revisión más profunda.