Introducción
API significa Interfaz de Programación de Aplicaciones. Una API le permite interactuar programáticamente con ciertas partes de RESPONSUM e intercambiar información. RESPONSUM proporciona puntos de conexión de API para funcionalidades/datos centrales que pueden ser útiles para ciertas automatizaciones e integraciones con otros sistemas/herramientas (operativos).
Estos puntos de conexión de la API se actualizarán/ampliarán con el tiempo, pero nos aseguraremos de que sigan siendo compatibles con versiones anteriores para que las integraciones creadas sigan funcionando. Si tiene alguna pregunta o consulta sobre nuevos puntos de conexión, háganoslo saber a través de support@responsum.eu.
Inicio rápido
- Asegúrese de que las API estén activadas para su inquilino. Están deshabilitadas por defecto, por lo que es posible que deba ponerse en contacto con support@responsum.eu.
- Una vez habilitado, puede ir a ajustes > configuración > mi organización. Al hacer clic en el nivel superior, podrá encontrar su «clave de inquilino» en las propiedades.
- Ahora puede encontrar nuestra documentación en ajustes > integraciones > Documentación de la API.
- Cree un token de API yendo a ajustes > integraciones > Tokens de API.
- Hay algunos ejemplos de código JavaScript de Node.JS disponibles aquí: https://github.com/RESPONSUM-BE/RESPONSUM-api-example. Puede usar la clave de inquilino + el token de API generados anteriormente para probarlo.
- Puede encontrar un diagrama en nuestro Centro de Ayuda que explica los conceptos principales de RESPONSUM. Esto le ayudará a comprender nuestra estructura básica para que pueda encontrar fácilmente los conceptos.
- Aquí tiene una introducción rápida a algunos conceptos importantes; puede leer más en profundidad a continuación.
- UUIDs: Puede crear sus propios UUIDs o generar algunos con formato RESPONSUM usando
https://api.responsum.app/v1/[tenant key]/uuids/[amount]. Si genera sus propios UUIDs, asegúrese de que sean 100 % únicos; existen bibliotecas si las necesita, no use math.random 🙂 - Objetos de enlace: RESPONSUM NO utiliza el modelado típico basado en relaciones. Los enlaces entre elementos son objetos para nosotros.
- Control de versiones: Casi todos los modelos de RESPONSUM tienen control de versiones. Esto significa que rastreamos los cambios de todo. Hay algunas API específicas disponibles para gestionar esto o solicitar información sobre el historial de versiones y la aprobación de cualquier objeto.
- Campos calculados: RESPONSUM calcula una serie de campos en el lado del servidor. Lo hace automáticamente. Al obtener un objeto, también le proporcionaremos nuestros campos calculados. No podrá actualizarlos manualmente.
- Orientado a eventos: Todo lo que sucede en RESPONSUM (crear, actualizar, eliminar, versionar,…) comienza como un evento. Puede usar webhooks para suscribirse a todo tipo de eventos. Esencialmente, cualquier cosa que suceda en RESPONSUM puede ser respondida usando las API de webhooks.
- UUIDs: Puede crear sus propios UUIDs o generar algunos con formato RESPONSUM usando
- Siempre se recomienda leer el manual completo antes de salir. Es un mundo peligroso y no querrá hacerse daño, pero armado con este inicio rápido, espero que lo haga funcionar. ¡Mucha suerte!
Primeros pasos
Asegurarse de que la API esté habilitada para su inquilino
Por defecto, la API de RESPONSUM está deshabilitada a nivel de inquilino y oculta en nuestra interfaz de usuario.
Para habilitar la API para su inquilino, deberá ponerse en contacto con nuestro equipo de soporte a través de support@responsum.eu, quienes pueden habilitarla y también responder a las preguntas que pueda tener después de leer la documentación disponible, y quienes pueden ponerle en contacto con las personas adecuadas para preguntas más técnicas, discusiones o solicitudes de implementación.
Toda la documentación posterior asumirá que la API de RESPONSUM ha sido habilitada para su inquilino.
Su clave de inquilino
Al usar la API de RESPONSUM, se le requerirá que utilice su clave de inquilino real, tal como está definida en nuestro sistema para cada solicitud. Esta clave de inquilino se puede encontrar en la aplicación navegando a ajustes > configuración > mi organización y abriendo la unidad organizativa más alta, ya que esto refleja su inquilino.
En los detalles de los «Metadatos» del inquilino (dos flechas hacia abajo en la parte superior del panel lateral), encontrará el campo de solo lectura «Clave de inquilino».

Esta clave de inquilino se estableció cuando se creó su inquilino y, a diferencia del nombre del inquilino, no se puede cambiar y es única para este inquilino específico.
Especificaciones OpenAPI para la API de su inquilino
La API de RESPONSUM que utilizará se genera específicamente para su inquilino e incluye cualquier personalización (campos personalizados, relaciones personalizadas, reglas de negocio…) que se haya podido realizar. Como tal, los modelos proporcionados pueden diferir entre inquilinos.
Para facilitar la integración, proporcionamos un archivo JSON de especificación de acuerdo con las Especificaciones OpenAPI, puede cargarlo reemplazando el [tenant key] en la siguiente URL con su propia clave de inquilino encontrada anteriormente: https://api.responsum.app/v1/[tenant key]/spec.json.
También proporcionamos una documentación visual basada en este archivo de especificación para permitir algunas pruebas sencillas mientras se familiariza con la API, esto se puede encontrar en nuestra aplicación si navega a ajustes > integraciones > Documentación de la API.
La primera solicitud en esa documentación de la API también es para obtener las especificaciones de la API abierta y es una de las únicas solicitudes que puede realizar sin autenticación.
Autenticación y autorización
Todas las solicitudes funcionales a la API de RESPONSUM esperan que se pase un token de API como parte de la solicitud. Esto funciona tanto como autenticación (al verificar el token en sí) como autorización (al verificar los permisos de la cuenta de usuario vinculada a ese token) (el enlace de nivel de permiso de usuario).
Todas las acciones realizadas a través de la API utilizando este token también se registrarán como realizadas por el usuario vinculado al token de API, como tal, usted está suplantando a ese usuario al usar el token de API.
Creación de un token de API
Los tokens de API solo se pueden gestionar a través de nuestra aplicación yendo a ajustes > integraciones > Tokens de API.
Un token de API consta de:
- Un nombre para facilitar su reconocimiento en la lista y diferenciar los tokens entre sí;
- Una cadena de token, generada para usted y que se utilizará en cada solicitud a la API;
- Un nivel de permiso de usuario, que se vincula a una cuenta de usuario que será suplantada al usar este token de API. Como tal, si desea otorgar o denegar permisos a este token de API, lo hace otorgándolos o denegándolos a la cuenta de usuario vinculada aquí;
- Una fecha de caducidad; si se establece, el token dejará de funcionar después de esta fecha.
Una vez creada, la cadena de token de un token de API debería estar disponible para su uso de inmediato. Si su cadena de token se ve comprometida por alguna razón, regenerar la cadena de token y guardar el token de API actualizado invalidará la cadena de token antigua de inmediato.
Paso del token de API con las solicitudes
Una vez que tenga una cadena de token de API válida, puede pasarla a la API de RESPONSUM añadiendo un encabezado adicional a sus solicitudes Api-Token cuyo valor es su cadena de token de API.
Solicitudes de utilidad
UUIDs
Actualmente se utilizan varios estándares para los Identificadores Únicos Universales y la API de RESPONSUM debería aceptar la mayoría, ya que nuestra validación consiste en:
- Al menos 5 caracteres de longitud
- Solo consta de los caracteres:
- a a z:
abcdefghijklmnopqrstuvwxyz - 0 a 9:
0123456789 - guion:
-
- a a z:
Además, esperamos que el UUID sea único, pero solo haremos una comprobación limitada al respecto, en el sentido de que intentar crear un nuevo modelo o enlaces con un UUID que ya existe para ese modelo o enlace específico devolverá un error.
RESPONSUM utiliza una variante del algoritmo cuid2 modificada para que sea más fácil de reconocer y se ajuste a nuestro formato preferido.
Para facilitarle el uso de UUIDs que sigan este formato RESPONSUM, hemos añadido un punto de conexión de API que puede utilizar para generar entre 1 y 1000 UUIDs que están garantizados como únicos e indistinguibles de los generados internamente por RESPONSUM.
Reemplace la clave de inquilino y la cantidad en https://api.responsum.app/v1/[tenant key]/uuids/[amount] y realice una solicitud GET con ella, asegurándose de incluir el encabezado Api-Token y como valor de retorno obtendrá una matriz JSON que contiene los UUIDs como valores de cadena.
El proyecto de ejemplo contiene una operación de ejemplo que hace esto: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getUuids.ts
Enlaces
Formato de enlace y principio general
Los enlaces en RESPONSUM se manejan de manera un poco diferente a la mayoría de las soluciones comunes, ya que cada enlace se almacena como un objeto propio en la colección de enlaces, haciendo referencia a los diversos modelos que están vinculados entre sí, en lugar de referencias en los modelos que se vinculan a otros modelos.
Los enlaces tampoco se actualizan nunca; solo se pueden crear o eliminar, ya que cambiar un modelo vinculado se considera eliminar el enlace antiguo y crear un nuevo enlace.
Definiciones de enlace
Todos los enlaces se basan en varias definiciones de enlace; algunas de ellas están codificadas y otras pueden ser creadas por el usuario. Al obtener las definiciones de enlace utilizando el punto de conexión GET https://api.responsum.app/v1/[tenant key]/link-definitions, obtendrá un JSON que contiene un objeto grande, que puede verse como un diccionario de todas las definiciones de enlace.
Un fragmento de ejemplo para referencia:
{
"stakeholder-stakeholderContact-contacts": {
"stakeholder": {
"modelType": "stakeholder",
"oneOrMany": "one",
"isRequired": false,
"relationBehaviour": "reference-same-object"
},
"contact": {
"modelType": "stakeholder-contact",
"oneOrMany": "many",
"isRequired": false,
"relationBehaviour": "reference-same-object"
}
},
<snipped-for-size>
}
Un linkType es una clave descriptiva única para esta definición de enlace específica. En este ejemplo, puede ver que cada clave de objeto («stakeholder-stakeholderContact-contacts») es el linkType de la definición de enlace específica.
Un rol es una clave descriptiva, única dentro de la definición de enlace, para identificar las diversas ramas de la definición de enlace. En este caso, «stakeholder» y «contact» son los dos roles; como puede ver, estos no tienen por qué coincidir con el tipo de modelo. Otro ejemplo es para un enlace autorreferencial, estos roles podrían ser «padre» e «hijo».
También tenga en cuenta que, si bien la mayoría de los enlaces solo tienen dos ramas, se permiten más de dos y ya tenemos al menos un caso en el que tenemos enlaces de tres vías.
Debajo del rol, tiene una definición de rama, que describe algunas propiedades de esta rama en particular:
- El modelType describe qué tipos de modelo están permitidos; esto puede ser:
- Un único tipo de modelo
- Una matriz de tipos de modelo
- La constante «all-models»
- El oneOrMany describe si solo se debe permitir un enlace para vincular a esta combinación de tipo de modelo y UUID, o si puede haber muchos.
- El isRequired describe si este enlace es obligatorio en este lado del enlace. Si es verdadero, cada modelo del tipo (o tipos) definido en modelType debe tener al menos un enlace de este linkType.
- El relationBehaviour se utiliza principalmente internamente para decidir qué hacer con este enlace al duplicar modelos.
Objetos de enlace
Basándonos en la definición de enlace anterior, podemos encontrar lo mismo en los enlaces reales.
Un objeto de enlace de ejemplo podría verse así:
{
"uuid": "0fc0ea83-88df-49ec-a681-1ced0a6c0683",
"type": "link",
"linkType": "stakeholder-stakeholderContact-contacts",
"links": [
{
"modelType": "stakeholder",
"modelUuid": "55092a14-4d95-4665-ac50-eb687e535222",
"role" : "stakeholder"
},
{
"modelType": "stakeholder-contact",
"modelUuid": "ad95eded-3168-4a12-968d-456bc031af7e",
"role" : "contact"
}
]
}
Las propiedades uuid y type «link» siempre están presentes en cada objeto para identificarlo de forma única.
El linkType coincide con una de las definiciones de enlace, en este caso la del ejemplo de definiciones de enlace.
La propiedad «links» es una matriz de las diversas ramas. La cantidad de elementos en esta matriz siempre coincidirá con la cantidad de roles en la definición de enlace, ya que para cada rol esperamos un modelo vinculado.
- El rol coincide con uno de los roles definidos en la definición de enlace correspondiente.
- El modelType coincide con uno de los tipos de modelo permitidos para la definición de enlace y la definición de rol correspondientes.
- El uuid identifica entonces qué modelo específico del tipo de modelo dado referencia este enlace.
Además, también puede haber una propiedad metaData que puede contener un objeto de datos de forma libre con algunos metadatos adicionales sobre este enlace específico, aunque rara vez se utiliza.
Solicitudes de enlace directo
La mayoría de las veces obtendrá enlaces como parte de los modelos, y de manera similar creará o cambiará enlaces al crear o actualizar modelos.
Una propiedad de enlace en un modelo, cuando se rellena, se considerará la nueva lista de enlaces para esa propiedad, reemplazando cualquier enlace ya existente para la propiedad de ese modelo. Como tal, al añadir un nuevo enlace a un modelo, asegúrese de incluir también cualquier enlace existente que desee conservar.
Además de esto, también hay tres puntos de conexión para interactuar directamente con los enlaces.
El punto de conexión GET https://api.responsum.app/v1/[tenant key]/links le permite obtener todos los enlaces filtrados por varios filtros:
- uuids, los UUID de los objetos de enlace
- model-uuids, los UUID de los modelos referenciados en los objetos de enlace
- relation-names, los linkTypes de los objetos de enlace
Estos se pueden proporcionar como parámetros de consulta que contienen una matriz de cadenas JSON como valores.
El punto de conexión POST https://api.responsum.app/v1/[tenant key]/create, aunque se utiliza principalmente para crear modelos, también acepta objetos de enlace y, por lo tanto, se puede utilizar para crear nuevos enlaces.
El punto de conexión DELETE https://api.responsum.app/v1/[tenant key]/link le permite eliminar directamente uno o más enlaces de los que conoce el UUID del objeto de enlace.
Solicitudes de modelo
Todos los datos en RESPONSUM se almacenan en modelos, por lo que la mayoría de las operaciones de la API se realizarán hacia estos modelos.
Cada modelo debe tener un type y un uuid, ambos obligatorios y no se pueden cambiar después de la creación.
El tipo es uno de nuestros modelos predefinidos, como «actividad-de-procesamiento» o «riesgo».
Definición de modelo
Esto se refiere a una definición de modelo con todos los campos disponibles, incluidos los personalizados definidos en la aplicación. Para type contendrá el tipo esperado como una cadena; asegúrese de usar estos valores de cadena exactos.
Para los campos básicos, contendrá su tipo de datos y si son obligatorios o no.
Para los campos de enlace, contendrá una matriz de objetos de enlace.
Listado de modelos
Para cada tipo de modelo, tenemos un punto de conexión GET separado en la API para obtener todos los modelos o una lista filtrada de modelos para ese tipo.
Para filtrar, puede añadir un parámetro de consulta codificado en URI «param-filter» a la URL GET que contiene un objeto JSON con el filtro. Este filtro tiene como propiedad el nombre de la propiedad en la que desea filtrar y como valor una matriz de todos los valores de propiedad con los que desea coincidir.
Por ejemplo, si desea filtrar «advice» para encontrar cualquier modelo cuyo estado sea «new» o «ongoing», crearía un objeto de filtro JSON de la siguiente manera: {"status": ["new", "ongoing"]}. Después de eso, codifíquelo en URI como el valor para el parámetro de consulta param-filter, lo que le daría una solicitud GET como la siguiente: https://api.responsum.app/v1/[tenant key]/advice?param-filter=%7B%22status%22%3A%20%5B%22new%22%2C%20%22ongoing%22%5D%7D
También puede combinar filtros en múltiples propiedades añadiendo propiedades adicionales al objeto de filtro JSON, así: {"status": ["new", "ongoing"], "isObsolete": [false]}. Esto devolverá una matriz de modelos coincidentes o una matriz vacía si no se encuentran modelos.
El proyecto de ejemplo contiene una operación de ejemplo que hace esto: https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getCountriesByFilter.ts
Obtención de un único modelo
Para cada tipo de modelo, tenemos un punto de conexión GET separado en la API para obtener un modelo específico de ese tipo, basándose en su UUID; simplemente añada el UUID a la URL del tipo de modelo, lo que le dará una solicitud GET como la siguiente: https://api.responsum.app/v1/[tenant key]/advice/raou8qtt-60od-n7t5-g8el-c0sy99r0ppag
Esto devolverá ese único modelo o un error 404 «modelo no encontrado».
Creación de modelos (y enlaces)
Para crear modelos y enlaces entre esos modelos, tenemos un punto de conexión POST genérico https://api.responsum.app/v1/[tenant key]/create, ya que queremos hacer posible crear un conjunto de múltiples modelos relacionados y los enlaces entre ellos de una sola vez, para reducir la posibilidad de conjuntos parciales debido a fallos de validación o similares.
El punto de conexión de creación acepta una matriz de modelos, cada uno de los cuales debe tener el tipo, un UUID y cualquier propiedad requerida para ese tipo de modelo.
Para las propiedades de enlace en los modelos, también puede incluir una matriz de objetos de enlace, de los cuales tomaremos la unión entre los modelos proporcionados e insertaremos esos. Esto significa que si tiene dos modelos que se vinculan entre sí, nuestra API solo requiere el objeto de enlace que conecta esos dos en uno de los modelos para entender que debe añadirse; sin embargo, añadirlo en ambos modelos no hará ninguna diferencia.
El proyecto de ejemplo contiene una operación de ejemplo que hace esto.
Actualización de modelos (y enlaces)
Para actualizar modelos y enlaces entre esos modelos, tenemos un punto de conexión PATCH genérico https://api.responsum.app/v1/[tenant key]/update, ya que queremos hacer posible actualizar un conjunto de múltiples modelos relacionados y los enlaces entre ellos de una sola vez.
El punto de conexión de actualización acepta una matriz de modelos, cada uno de los cuales debe tener solo el tipo, el UUID y los campos que se están actualizando.
Para las propiedades de enlace en los modelos, estas son una vez más una matriz de objetos de enlace, de los cuales tomaremos la unión entre los modelos proporcionados y luego eliminaremos cualquier enlace que no forme parte de esta unión, antes de añadir cualquier enlace de esta unión que aún no esté en la base de datos. Esto significa que si desea añadir un enlace a una propiedad de modelo, también debe incluir los objetos de enlace de la propiedad de modelo existente o estos enlaces existentes se eliminarán.
El proyecto de ejemplo contiene una operación de ejemplo que hace esto.
Control de versiones del modelo
La mayoría de los modelos de RESPONSUM tienen el control de versiones habilitado, lo que significa que cada cambio realizado en estos modelos se registra y estas versiones pueden congelarse y aprobarse, etc.
Obtención de todas las versiones de un modelo
Puede obtener todos los cambios de versión para un modelo dado con la siguiente solicitud GET: https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]. Esto devolverá tanto las versiones «sin versión» (Borrador) como cada versión congelada con información adicional sobre esa versión, como el estado de la versión, quién la creó, quién la aprobó, etc.
Ciclo de vida de la versión
Cambios sin versión
Todos los cambios comienzan como cambios sin versión. Cada vez que se crea o actualiza un modelo, registramos el valor anterior y el nuevo para las propiedades cambiadas. Quién y cuándo realizó el cambio y qué tipo de operación fue.
La lista de operaciones tiene algunos valores comunes como ‘create’, ‘update’, ‘delete’, ‘merge’, ‘import’, ‘history-restoration’ y ‘update-link’, pero también puede contener valores especiales como ‘V2-create’ para nuestra importación heredada y en cualquier momento se pueden añadir nuevos valores dependiendo de futuros desarrollos.
Congelar
En cualquier momento, los cambios de un modelo pueden congelarse con POST https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/freeze, lo que creará una nueva versión con reviewStatus ‘frozen’ e incluirá cualquier cambio sin versión que hubiera. Si no hubiera cambios sin versión, no se creará ninguna nueva versión.
También puede proporcionar un nombre de versión al congelar, pero si no se proporciona ninguno, se calculará uno basándose en las versiones existentes actualmente.
En este punto, ciertas personas con el permiso adecuado ya pueden aprobar o rechazar esta versión, pero lo más importante es que cualquier cambio nuevo se añadirá como cambios sin versión, pero cualquier cambio en esta versión nunca cambiará.
Solicitar aprobación
Para que una versión sea aprobada o rechazada, puede solicitar a personas específicas que la revisen. Para ello, puede hacer PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/request-approval con un UUID de versión y un UUID de «usuario responsable». Esto activará notificaciones para que esta persona revise esta versión y la apruebe o rechace.
Aprobar o rechazar
También puede aprobar o rechazar versiones a través de la API si el usuario vinculado a su token tiene permisos suficientes.
Esto se puede hacer con los dos puntos de conexión PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/approve o https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/reject, requiriendo una vez más el UUID de la versión que desea aprobar o rechazar.
Webhooks
A veces también querrá ser notificado de la creación o actualización de modelos; para ello, tenemos webhooks que puede configurar yendo a ajustes > integraciones > webhooks.
Para facilitar su uso, los webhooks se pueden habilitar o deshabilitar; solo los webhooks habilitados activarán llamadas.
El nombre se utiliza puramente para distinguir los webhooks.
La URL proporcionada se llamará con los encabezados dados; será una solicitud POST que contendrá un cuerpo JSON con la acción de cambio (changeAction), el tipo de modelo (modelType) y los UUID (una matriz de UUID).
Puede seleccionar entre las siguientes acciones de cambio; el webhook solo se llamará para las seleccionadas:
- ‘link-deleted’: cuando se elimina un enlace de una o más propiedades
- ‘link-created’: cuando se añade un enlace para una o más propiedades
- ‘item-deleted’: cuando se elimina el elemento
- ‘item-meta-data-updated’: cuando se actualizan las propiedades calculadas, por ejemplo, última actualización por, estado de revisión, etc.
- ‘item-base-data-updated’: cuando se actualizan las propiedades base, por ejemplo, nombre, isObsolete, etc.
- ‘item-created’: cuando se crea el elemento
Puede seleccionar el submódulo para el que debe activarse el webhook; esto puede ser tan refinado como un solo tipo de modelo o tan amplio como cada modelo en la aplicación.
Según nuestra lógica interna, es posible que reciba múltiples llamadas de webhook para el mismo tipo de modelo y UUID en un corto espacio de tiempo, después de que un usuario guarde. Por ejemplo, añadir un enlace y establecer una propiedad activará una llamada ‘item-base-data-updated’, ‘item-meta-data-updated’ y ‘link-created’.
Aplicación de ejemplo
https://github.com/RESPONSUM-BE/RESPONSUM-api-example
Consulte el archivo Léame para empezar; una vez que lo tenga en funcionamiento y abra http://localhost:3000, debería ver algo como esto:

A medida que realice las diversas operaciones, verá un registro de las operaciones en el lado derecho de la página.
También puede encontrar todas estas operaciones en la carpeta src\operations\