Saltar a contenido

Conceptos de la API

La API del espacio de trabajo permite que un programa lea y actúe sobre casos sin pasar por la interfaz. Es la API que usa la propia aplicación, documentada aquí para integraciones.

No es la interfaz anterior

Esta es la API actual, servida por la aplicación bajo /{espacio}/{idioma}/lurana/api. La API de tokens anterior bajo /api/1.0/ es una interfaz distinta y no se documenta aquí.

URL base

{host}/{espacio}/{idioma}/lurana/api

Por ejemplo, en un espacio llamado starter, en inglés:

https://bpm.example.com/starter/en/lurana/api

El espacio también se envía en el cuerpo de la mayoría de las llamadas. Los dos deben coincidir: una llamada a la ruta de starter que nombra otro espacio en su cuerpo se rechaza.

Peticiones

  • El cuerpo es JSON: envía Content-Type: application/json.
  • Casi todas las rutas son POST, incluidas las de lectura. Las excepciones son home/user-name-format y las dos rutas de descarga, que también aceptan GET.
  • Los parámetros son claves planas en el cuerpo, no un objeto anidado.
curl -X POST "$BASE/auth/check-user" \
  -H 'Content-Type: application/json' \
  -d '{"workspace":"starter","username":"admin"}'

Autenticación

  1. POST /auth/check-user confirma que el usuario existe en el espacio.
  2. POST /auth/login devuelve un token de acceso y un token de refresco.
  3. Envía el token de acceso en cada llamada: Authorization: Bearer <token>.
  4. Cuando el token de acceso expira, POST /auth/token/refresh emite un par nuevo.

El token de acceso dura cinco minutos y el de refresco diez. Una integración que corre mucho tiempo tiene que refrescar en lugar de iniciar sesión de nuevo.

Sin un token válido la API responde:

{"success": false, "error": "SESSION_EXPIRED", "message": "Unauthorized or session expired"}

con HTTP 401.

Para una integración entre servidores, POST /oauth/token emite un token OAuth2 (client_credentials, authorization_code o refresh_token) para un cliente registrado.

Respuestas

Las respuestas exitosas llevan una marca success y su contenido:

{"success": true, "data": [ … ]}

Algunos endpoints devuelven un objeto plano — admin/me, por ejemplo, devuelve user, workspace, role, groups y permissions en el nivel superior.

Los errores conservan la misma forma:

HTTP Cuerpo Significado
401 {"success":false,"error":"SESSION_EXPIRED",…} Token ausente o expirado
422 {"success":false,"error":"REQUIRED_FIELDS",…} Falta un parámetro obligatorio
500 {"success":false,"error":"…"} La operación falló

No hay un sobre de paginación común a todas las listas: cada endpoint de lista documenta sus propios parámetros y devuelve sus filas en data.

Qué se documenta aquí

Página Cubre
Autenticación Inicio de sesión, refresco, recuperación de contraseña, token OAuth
Casos Iniciar, leer y actuar sobre un caso: documentos, notas, mensajes, derivación
Búsqueda y favoritos Búsqueda global, favoritos, usuario actual
Referencia de endpoints Los 53 endpoints de integración, generados desde los archivos de rutas

Qué está en alcance

La API tiene 169 rutas. Las que usan las pantallas de administración para llamarse a sí mismas —ajustes, temas, fuentes de autenticación, log de correos, administración de clientes OAuth— no son para integraciones y no se documentan aquí. Lo que queda es la superficie que necesita un tercero:

  • iniciar sesión y renovar el token;
  • iniciar un caso y seguirlo: leerlo, subir y descargar documentos, agregar notas, reenviar mensajes, pausar, cancelar, reasignar, derivar;
  • buscar en el espacio de trabajo;
  • resolver a quién pertenece el token;
  • listar los procesos que un usuario puede iniciar;
  • crear y actualizar usuarios, con las listas necesarias para llenar el formulario.

Si una operación no está en esa lista, pertenece a las pantallas de administración y no a una integración.

Relacionado