Lea y escriba artefactos, enlaces, módulos y líneas base desde sus propios programas, scripts o su pipeline de CI.
La API REST requiere el complemento ETRM API a una suscripción Single o Team propia. Sin ambas suscripciones responde con el estado 403 y el código de error subscription_required.
Cree una clave de acceso en Perfil, Acceso API y envíela en cada solicitud en la cabecera Authorization. La clave actúa con sus derechos en los grupos. Las claves sin derecho de escritura solo pueden leer.
curl -H "Authorization: Bearer etrm_…" https://engineering-toolbox.com/etrm/api/v1/
https://engineering-toolbox.com/etrm/api/v1/. Las solicitudes y respuestas son JSON (UTF-8).| GETprojects/ | Sus proyectos con rol (los archivados con ?archived=1). |
| GETprojects/<id>/ | Proyecto con configuración: tipos de artefacto, atributos con valores permitidos, tipos de enlace, módulos. |
| GETprojects/<id>/metrics/ | Indicadores como en el panel: alcance, cobertura, enlaces sospechosos, volatilidad, indicaciones de redacción. |
| GETprojects/<id>/artifacts/ | Lista. Filtros: type (varios), module, tag (varios, basta uno), q (texto completo), changed_since (ISO 8601), attr.<clave>=<valor>, deleted=1 (incluida la papelera). |
| POSTprojects/<id>/artifacts/ | Crear. Opcionalmente con tags (lista), module, parent (número de un encabezado en el módulo) y position. |
| GETprojects/<id>/artifacts/<nr>/ | Un artefacto con módulos y enlaces. |
| PATCHprojects/<id>/artifacts/<nr>/ | Modificar title, text, type, attributes y tags (sustituye toda la lista). rev (estado actual) es obligatorio; si el artefacto ha cambiado entretanto, se devuelve 409 con el estado actual. En attributes, null elimina un valor. |
| DELETEprojects/<id>/artifacts/<nr>/ | A la papelera (se puede restaurar en la interfaz). |
Ejemplo: crear un requisito de sistema
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
-d '{"type": "systemanforderung", "title": "Zellspannung messen",
"text": "<p>Das BMS muss jede Zellspannung mit ±2 mV messen.</p>",
"attributes": {"status": "entwurf", "prioritaet": "muss"}, "module": 3, "parent": 12}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/
Respuesta (abreviada)
{"number": 131, "id": "#131", "uid": "6f1c…", "type": "systemanforderung", "title": "Zellspannung messen",
"text": "<p>…</p>", "attributes": {"status": "entwurf", "prioritaet": "muss"}, "tags": [], "rev": 1,
"deleted": false, "quality": [], "url": "…/artifacts/131/"}
El campo quality contiene las indicaciones de la revisión de redacción (p. ej. términos vagos o puntos abiertos).
| GETprojects/<id>/tags/ | Etiquetas del proyecto con color, active y count (artefactos fuera de la papelera). |
| GETprojects/<id>/artifacts/<nr>/tags/ | Etiquetas de un artefacto. |
| POSTprojects/<id>/artifacts/<nr>/tags/ | Añadir etiquetas: tags (lista de nombres). Los nombres desconocidos se crean en el proyecto. added indica lo que se ha añadido. |
| DELETEprojects/<id>/artifacts/<nr>/tags/<name>/ | Quitar una etiqueta del artefacto. Se mantiene en el proyecto; removed es null si no estaba asignada. |
| POSTprojects/<id>/tags/<name>/artifacts/ | Acción masiva como en la tabla: asignar una etiqueta a varios artefactos (numbers, como máximo 500). |
| DELETEprojects/<id>/tags/<name>/ | Eliminar una etiqueta no utilizada del proyecto (solo administradores del grupo). Respuesta: name y deleted. Si sigue asignada a artefactos (también en la papelera), la respuesta es 409 tag_in_use con count. |
Se aplican las mismas reglas que en la interfaz: no se distingue entre mayúsculas y minúsculas, los nombres tienen como máximo 50 caracteres y ninguna coma. Añadir y quitar se pueden repetir sin riesgo, no cambian rev y aparecen en el historial del artefacto. Codifique en la URL los nombres con caracteres especiales.
Solo se pueden eliminar las etiquetas no utilizadas. Las líneas base y el historial conservan los nombres, por lo que los estados anteriores no cambian.
Ejemplo: añadir dos etiquetas
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" \
-d '{"tags": ["Sicherheit", "ASIL B"]}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/artifacts/131/tags/
Respuesta (abreviada)
{"number": 131, "tags": ["ASIL B", "Sicherheit"], "added": ["ASIL B"]}
| GETprojects/<id>/links/ | Lista. Filtros: type, artifact (número, origen o destino), suspect=1. |
| POSTprojects/<id>/links/ | Crear con type, source, target (números). Se aplican los tipos de origen y destino permitidos del tipo de enlace. |
| DELETEprojects/<id>/links/<link>/ | Eliminar. |
| POSTprojects/<id>/links/<link>/clear-suspect/ | Confirmar sospecha (revisado, sigue siendo válido). |
| GETprojects/<id>/modules/ | Lista de módulos con structure_rev. |
| GETprojects/<id>/modules/<modul>/ | Estructura en orden del documento con número (1.2, 1.2-3), profundidad, artefacto, parent (número del encabezado) y position. El encabezado ETag contiene el estado de la estructura. |
| POSTprojects/<id>/modules/<modul>/artifacts/ | Insertar un artefacto existente: artifact (número), opcionalmente parent y position. Sin ellos, al final del nivel superior. |
| GETprojects/<id>/modules/<modul>/artifacts/<nr>/ | Posición de un artefacto en el módulo. |
| PATCHprojects/<id>/modules/<modul>/artifacts/<nr>/ | Cambiar el encabezado (parent, null para el nivel superior) y/o position. Los artefactos subordinados se mueven con él. |
| DELETEprojects/<id>/modules/<modul>/artifacts/<nr>/ | Quitar del módulo. El artefacto permanece en el proyecto con su número, UID, historial y enlaces; los artefactos subordinados ocupan su lugar. |
position cuenta desde 0 dentro del nivel; los artefactos en la papelera no cuentan. Un artefacto aparece como máximo una vez por módulo; en varios módulos es el mismo artefacto.
Cambios simultáneos: envíe el ETag leído en el encabezado If-Match (o como structure_rev en el contenido). Si la estructura ha cambiado entretanto, también en la interfaz, recibirá 409 con la estructura actual en current. Sin él no se comprueba.
Ejemplo: insertar un artefacto en primer lugar bajo el encabezado #12
curl -X POST -H "Authorization: Bearer etrm_…" -H "Content-Type: application/json" -H 'If-Match: "s-7"' \
-d '{"artifact": 131, "parent": 12, "position": 0}' \
https://engineering-toolbox.com/etrm/api/v1/projects/<id>/modules/3/artifacts/
| GETprojects/<id>/baselines/ | Lista. |
| POSTprojects/<id>/baselines/ | Crear un nuevo estado: name, opcionalmente note y module. |
| GETprojects/<id>/baselines/<b>/ | Una línea base; con ?payload=1 el estado completo e inmutable. |
| GETprojects/<id>/baselines/<b>/compare/ | Diferencias con el estado actual o, con ?with=<b>, con otra línea base: nuevos, eliminados, modificados, desplazados, enlaces. |
Los errores se devuelven como JSON con error (código) y message (texto); con datos no válidos, además details por campo.
| 400 | datos no válidos (validation, invalid_json, invalid_parameter) |
| 401 | token ausente, desconocido o revocado |
| 403 | El rol no es suficiente, el token solo puede leer o no hay un complemento ETRM API activo (subscription_required) |
| 404 | no encontrado (también proyectos de los que no es miembro) |
| 405 | método no permitido |
| 409 | conflicto: el artefacto o la estructura del módulo se ha modificado entretanto (la respuesta contiene current), el artefacto está en la papelera o ya está en el módulo (already_bound) |
{"error": "validation", "message": "Die Angaben sind nicht gültig.", "details": {"prioritaet": ["Pflichtfeld."]}}