Saltar a contenido

API REST

La nueva API HTTP/JSON expone operaciones de negocio del catálogo MCP sin un sobre JSON-RPC. Las operaciones disponibles dependen de la versión del servidor instalada. Es una API orientada a operaciones, no una interfaz CRUD separada para cada tabla de base de datos.

Acceso y permisos

Envíe una clave API MCP existente como Authorization: Bearer <key>. MCP debe estar habilitado globalmente y para el proyecto. Las claves de proyecto también requieren X-ZTM-Project-UniqueId. Las claves globales necesitan acceso explícito al proyecto para operaciones del proyecto. El inicio de sesión en navegador y Windows no reemplaza una clave API.

Los permisos de usuario, puertas de escritura, capacidades permitidas y restricciones de demostración se aplican igual que en MCP. Use HTTPS fuera de pruebas locales. Nunca coloque claves en URLs, código fuente o registros. Vea Acciones seguras y MCP.

Descubrir operaciones

Solicitud Resultado
GET /api/v1/operations Operaciones y contratos de entrada disponibles para la clave y proyecto actuales
GET /api/v1/operations/{operationId} Un contrato de operación
GET /api/v1/openapi.json OpenAPI 3.1 para el mismo contexto de autorización
POST /api/v1/operations/{operationId} Ejecutar con el objeto argumento como cuerpo de la solicitud
POST /api/v1/resources/read Leer un recurso de exportación vinculado a clave

OpenAPI contiene una ruta POST concreta para cada operación disponible. Las entradas usan los mismos esquemas que MCP. La salud de la biblioteca, estabilidad de resultados, archivos adjuntos del proyecto y comparaciones/snapshots de versiones tienen esquemas de salida tipados. Otros resultados dinámicos de consultas/acciones mantienen contratos JSON extensibles. El catálogo incluye herramientas compartidas de consulta y acción; no todos los elementos del menú web tienen un endpoint dedicado.

$headers = @{
    Authorization = "Bearer $env:ZTM_API_KEY"
    'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://your-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body '{}'

Estas variables de entorno son leídas por el script PowerShell que llama; no configuran automáticamente el servidor. Dirija proyectos usando encabezados, no argumentos de operación. Los cuerpos JSON están limitados a 1 MiB y 32 niveles de anidamiento. Se rechazan nombres de propiedad duplicados.

Leer la configuración de vista previa de Office

Una clave API global de MCP puede leer el modo XLSX efectivo de la instalación con POST /api/v1/operations/ztm_admin_office_preview_settings_get y el cuerpo {}. Una respuesta de ejemplo es {"xlsxPreviewMode":"HtmlTable"}; el otro valor posible es DevExpressPdf. Una clave de proyecto es insuficiente. Esta operación es solo de lectura. Use administración del servidor para cambiar la configuración.

Escrituras y exportaciones.

Siga la vista previa y el contrato de compromiso explícito de cada operación, por ejemplo ztm_project_action_prepare y ztm_project_action_commit. El acceso a la API no reemplaza la aprobación empresarial. Mantenga las vistas previas, claves de idempotencia y compromisos vinculados al mismo usuario y contexto de proyecto. Después de un tiempo de espera, verifique el estado de la acción en lugar de repetir ciegamente una escritura.

Las exportaciones pueden devolver un resourceUri. Léalo mediante POST /api/v1/resources/read con {"uri":"<resourceUri>"} usando la misma clave y proyecto. La respuesta contiene contents con texto o datos Base64 y un tipo MIME. Los tickets pueden expirar o permitir una sola lectura; trate las URIs de recursos como confidenciales.

Errores

Los errores devuelven estado HTTP y application/problem+json que contiene code y traceId: 400 entrada inválida, 401 autenticación faltante/rechazada, 403 permisos insuficientes, 404 objeto u operación no disponible, 409 conflicto de acción, 413 cuerpo demasiado grande, 415 tipo de contenido no soportado, 500 fallo interno. Los conflictos requieren revisión, no reintentos automáticos. Proporcione al soporte el traceId, nunca claves ni datos confidenciales.

Reglas de prerrequisitos y pruebas bloqueadas

ztm_project_query incluye rule para dependencias de biblioteca y planificadas: 0 = Solo pista, 1 = Debe tener éxito, 2 = No debe haber fallado.

Para cambiar una dependencia de biblioteca existente, use ztm_project_action_context, luego ztm_project_action_prepare con capabilityId: project.test-case.dependency.set-rule y argumentos testCaseId, dependencyId, rule. Revise la vista previa y confírmela con ztm_project_action_commit. La clave requiere esta capacidad explícita de escritura. La creación permanece compatible: una nueva relación comienza como una sugerencia; su regla puede cambiarse luego. Los planes y ejecuciones existentes no se sincronizan automáticamente.

POST /api/v1/operations/ztm_test_prerequisites_read con {"plannedVariantId":123} evalúa un caso de prueba planificado visible. La respuesta incluye isBlocked, needsRecheck y blockers. Predecesores invisibles o ausentes no se revelan por nombre; hasHiddenPrerequisites los indica. Esta evaluación puntual no otorga derechos de ejecución ni reemplaza la confirmación personal de reejecución. La misma operación está disponible a través de MCP.

Archivos adjuntos del proyecto

ztm_project_attachments_read lista los archivos adjuntos del proyecto y sus ownerId, con offset y limit (máximo 100). Proporcione attachmentId para descargar contentBase64 (máximo 32 MiB). Se requiere un administrador activo del proyecto o gerente de proyecto. Los archivos vinculados dinámicamente se listan pero no pueden descargarse mediante esta operación.

Las escrituras requieren la capacidad separada project.attachment.upload, project.attachment.update o project.attachment.delete. Las concesiones existentes de planificación de archivos adjuntos no otorgan acceso a archivos del proyecto. Use el ownerId devuelto, que puede ser 0 para un proyecto.

  1. Subir: llamar a ztm_project_attachment_stage con targetKind: "project", targetId: <ownerId>, fileName, mimeType y contentBase64. El límite de preparación existente es de 512 KiB por archivo.
  2. Llame a ztm_project_action_prepare con la capacidad, un nuevo idempotencyKey y arguments. Argumentos de carga: ownerKind: "project", ownerId, el attachmentReferenceId del ticket, opcional displayName y remarks. Actualización de metadatos: ownerKind, ownerId, attachmentId, displayName, remarks. Eliminar: ownerKind, ownerId, attachmentId.
  3. Revise la vista previa y confirme mediante ztm_project_action_commit con la misma clave. Las ediciones concurrentes causan un conflicto; reproducir un compromiso exitoso no crea otro archivo adjunto.

Comparaciones y decisiones de versión

ztm_release_snapshots_list lista comparaciones guardadas legibles con un filtro opcional targetId. Pase el NextCursor devuelto como cursor para leer la siguiente página.

ztm_release_compare acepta baseId, targetId, arreglos explícitos baseRunIds/targetRunIds y opcionales baseScopeRunIds/targetScopeRunIds de { "runId": 123, "scopeRunId": 123 }. Opcionales baseSnapshotId/targetSnapshotId seleccionan evidencia guardada. Devuelve la comparación web incluyendo Fingerprint, aplicando las mismas reglas de selección y permisos de objetos.

Para guardar evidencia, conceda explícitamente project.release-review.snapshot-create y prepare/realice commit de los argumentos query (el objeto de argumentos de comparación), name y fingerprint. Los cambios en la evidencia son rechazados. Lea la comparación guardada, decisionRevision y el historial de decisiones con ztm_release_snapshot_read y snapshotId; historyBeforeRevision pagina decisiones anteriores.

Una decisión también requiere project.release-review.decision-record, permiso de gestión de proyecto y autorización humana explícita. Preparar acepta snapshotId, targetId, revision, outcome (1 aceptado, 2 aceptado con condiciones, 3 rechazado, 4 revocado), responsibleUserId, comment, openPoints (uno por línea) y humanConfirmed: true. El servidor registra el actor autenticado; la bandera no reemplaza la aprobación humana real. Revise la vista previa, luego confirme. Las reglas web aún aplican: revisión actual, usuario responsable elegible, explicación, alcance completo y evidencia sin cambios. Copias históricas del proyecto no pueden recibir una nueva decisión.

Cobertura y límites

REST y MCP comparten su catálogo de operaciones. Esto no implica una cobertura completa de todas las funciones web. Los archivos adjuntos del proyecto ahora tienen un contrato de escritura separado; los contratos existentes para la carga de caso de prueba, requisito y plan de pruebas permanecen separados. Las operaciones diferidas siguen siendo visibles en el catálogo de capacidades.

La presentación en navegador, los diálogos para seleccionar archivos y el inicio de sesión interactivo no requieren puntos finales de dominio separados. La confirmación personal de una nueva ejecución manual de pruebas no se genera automáticamente en nombre del evaluador. La visión general de la versión/PDF y las importaciones de automatización utilizan sus operaciones existentes; el transporte REST no amplía su cobertura de dominio. Las escrituras de archivos adjuntos del proyecto y las operaciones de comparación/decisión de versiones ahora están disponibles como se describió anteriormente. Las rutas arbitrarias del servidor y los enlaces de archivos Local Bridge permanecen fuera de estas operaciones de API. La copia de variantes independiente y las importaciones de archivos de manifiesto no son acciones separadas en la implementación web revisada. Las salidas tipadas cubren archivos adjuntos del proyecto y comparaciones/snapshots de versiones; las salidas dinámicas existentes de consultas/acciones permanecen como JSON extensible, no modelos SDK completamente tipados.

Versiones de casos de prueba

Versionado de casos de prueba está disponible a través de POST /api/v1/operations/ztm_project_test_case_versions. Use operation: "list", testCaseID y opcionalmente skip y take para una lista acotada con la cabeza actual. read también requiere revisionID, mientras que compare añade otherRevisionID; asset usa revisionID y assetID y devuelve bytes codificados en base64. restore-preview verifica revisionID contra expectedHead.

Prepare la restauración mediante ztm_project_action_prepare, capacidad project.test-case-version.restore y argumentos testCaseID, revisionID, expectedHead, opcional note y options. Confirme el token devuelto mediante ztm_project_action_commit. options puede contener excludedAttributeIDs y flattenUnavailableReusableSteps explícitamente excluidos. La vinculación al proyecto, identidad activa del usuario, permisos de objetos, ámbitos de escritura y protección de demostración siguen aplicando. Nunca incluya claves API en ejemplos, registros o historial de shell.

Estado de la biblioteca y estabilidad de resultados

Estas operaciones de lectura usan los mismos servicios y permisos de objeto que los informes web. No se requiere permiso de escritura. No modifican, eliminan ni ejecutan pruebas.

Operación Filtros opcionales
ztm_library_health_read unitId incluyendo descendientes o caseId; ageDays 1–36500 (predeterminado 180); reason; page desde 1; pageSize 1–100 (predeterminado 50)
ztm_test_stability_read testPlanId; testEnvironmentId (0 para sin entorno); fromUtc, toUtc como marcas de tiempo UTC tales como 2026-11-08T12:00:00Z; lookbackRuns 1–200 (por defecto 50)

Ejemplo: POST /api/v1/operations/ztm_library_health_read con {"ageDays":180,"reason":"NoVisibleUsage","pageSize":25}. La respuesta tipada incluye Findings, CandidateCount, ScannedCaseCount, IsComplete, Limit, Page y PageSize. Las razones son NoVisibleUsage, NeverVisiblyExecuted, LongUnchanged, MissingTitle, MissingSteps, MissingExpectedResults, EmptyQuickContent y NoVariants. Las razones pueden superponerse. La ausencia de uso visible no establece que un caso de prueba esté sin uso en todo el proyecto; contenido sin cambios durante mucho tiempo no es automáticamente obsoleto. El análisis se limita a 2000 casos visibles y 20000 usos visibles. Cuando el análisis de uso es incompleto, se suprimen los indicadores negativos de uso.

Ejemplo: POST /api/v1/operations/ztm_test_stability_read con {"lookbackRuns":50}. La respuesta incluye Series, FailureGroups, Evidence individuales y los conteos EligibleRuns, IncludedRuns, EligibleResults, IncludedResults, Truncated y InvalidEvidenceCount. Utiliza el resultado actual por ejecución/caso/variante en ejecuciones terminadas visibles, no el historial completo de ejecución. Se analizan como máximo 20000 observaciones de resultados. Variantes, entornos y origen están separados; las diferencias de compilación permanecen visibles. ContentDifferences y ContentFingerprint comparan solo la descripción guardada del caso de prueba, no la especificación histórica completa. Los cambios en los resultados son indicadores, no prueba de inestabilidad. El texto de fallo coincidente no prueba una causa compartida. Origin: 0 = automatización actual verificada, 1 = otro origen o no verificado, 2 = evidencia de automatización cambiada o inválida.

Utilice la capitalización de entrada mostrada. Rangos inválidos, marcas de tiempo o filtros desconocidos devuelven 400; objetos explícitos de biblioteca ilegibles devuelven 403. Las mismas herramientas y filtros están disponibles a través de MCP.

Líneas base de referencia

Líneas base de referencia proporciona operaciones tipadas para opciones de alcance, listado, contenidos históricos, comparación actual y archivos guardados. La creación usa prepare/commit con la capacidad explícitamente otorgada project.library-baseline.create; no existe operación de editar, restaurar o eliminar. Consulte el capítulo enlazado para nombres de herramientas, argumentos de alcance, reglas de reintento y el límite de 512 KiB para respuestas de archivos API.

Árbol de planificación y estados personalizados de resultados

ztm_project_planning_tree_read devuelve el árbol de planificación permitido junto con definiciones de resultados disponibles y filtros de ejecución. Solicitud de ejemplo:

{"resultDefinitionIds": [12, 15], "includeNoResult": true}

Utilice IDs reales de resultDefinitions; los IDs de ejemplo son marcadores de posición. Los IDs de estado usan OR; el treeFilterObjectId opcional restringe aún más las ejecuciones. Las selecciones omitidas significan sin filtro para esa solicitud, independientemente de las preferencias guardadas de la interfaz. El resultado sigue la configuración de visibilidad del árbol del usuario y devuelve solo nodos permitidos. Se rechazan IDs explícitos desconocidos. La operación de lectura no cambia preferencias personales ni resultados de pruebas. El mismo contrato está disponible a través de MCP.

Origen del valor del atributo

Para acciones de atributo existentes, ztm_project_action_context agrega Metadata a PromotedFields y ObjectAttributes. Incluye AttributeId, AttributeStyleFieldId, nombre del campo, ID y nombre del estilo, tipo de campo, tipo e ID del propietario, Entail y SourceKind (direct, inherited, default). Un valor predeterminado no guardado no tiene ID de propietario. Las definiciones de campo faltantes conservan su ID de campo original mientras que los detalles de su definición son nulos.

La misma información está disponible a través de MCP y POST /api/v1/operations/ztm_project_action_context. Los permisos y capacidades de la acción de atributo existente aún aplican; el acceso al contexto no concede permiso adicional de lectura. Los campos de contraseña están excluidos. Leer contexto no persiste valores predeterminados. Atributos explica la diferencia entre herencia por nombre y campos promovidos.

Retroalimentación del resultado objetivo

Las herramientas solo lectura ztm_result_feedback_read, ztm_result_feedback_preview y ztm_result_feedback_export también están disponibles como operaciones POST bajo /api/v1/operations/. Cada una requiere su capacidad de lectura project.result-feedback.read, .preview o .export, además de acceso de lectura a los objetos seleccionados.

read acepta testRunId. preview añade resultItemIds (de 1 a 100 IDs únicos), opcionalmente recipient, subject, message, externalReference y includeResultText (por defecto false). Su respuesta incluye Fingerprint del contenido revisado. export usa la misma entrada más expectedFingerprint, format (html o xlsx) y opcionalmente language (de o en). La respuesta contiene FileName, ContentType y ContentBase64.

El contenido cambiado requiere otra vista previa. Los resultados seleccionados inaccesibles rechazan toda la salida; no hay exportación parcial silenciosa. Ninguna operación envía mensajes ni almacena destinatarios en el proyecto. Véase Compartir resultados de pruebas para el flujo de usuario y los límites de contenido.

Reglas de rol de AD

ztm_ldap_role_rules_get lee las reglas de una configuración de importación; ztm_ldap_role_rules_save las guarda con una revisión esperada; ztm_ldap_role_rules_preview previsualiza cambios de membresía. ztm_ldap_import_run ejecuta la importación AD existente incluyendo las reglas guardadas. Las mismas operaciones están disponibles como herramientas MCP.

Todas las llamadas requieren configurationId. Guardar, previsualizar e importar también requieren expectedRevision de la última respuesta leída. Guardar acepta rules que contiene IDs de reglas estables, estado habilitado, nombre de atributo, valor exacto, rol y un nombre de grupo dedicado. Los llamadores no eligen IDs de grupo. Los contratos OpenAPI generados describen los campos completos.

Guardar e importar son escrituras administrativas que requieren una clave administrativa habilitada con acceso al proyecto y el alcance correspondiente. También se verifican permisos de administración del proyecto. Vista previa de cambios no requiere membresías pero sí acceso al directorio configurado. La demo pública bloquea estas llamadas administrativas. En caso de conflicto de revisión, lea y revise la configuración nuevamente en lugar de reintentar ciegamente una importación con configuraciones obsoletas.

Actualización y evaluaciones manuales de defectos en la versión

ztm_release_evidence_read, ztm_release_evidence_configure y ztm_release_evidence_observe leen límites de antigüedad o límites de almacenamiento y evaluaciones manuales explícitas de defectos. Usan los contratos MCP correspondientes y el actual expectedRevision. Re-lea tras conflicto (409); no reintente ciegamente. observe requiere el actual referenceId y sourceFingerprint del report.EvidenceAssessment.Defects del resumen, además de state, criticality, observedUtc con zona horaria explícita, y comment.

Los ámbitos de escritura dedicados son project.release-evidence.configure y project.release-evidence.observe. También se aplican escrituras habilitadas del proyecto y los mismos permisos de gestión de versiones que en Web. Las declaraciones incluyen el usuario y hora de grabación; no son datos de rastreador verificados automáticamente y no deben inventarse sin instrucción humana explícita. ztm_release_overview_read añade EvidenceAssessment para nuevas capturas en vivo; el nivel assessment existente y sus razones lo incorporan. Las capturas históricas permanecen sin cambios. Consulte Comparación y aceptación de versión.

Conjuntos de datos de prueba estructurados

Estas herramientas MCP también están disponibles como POST /api/v1/operations/<tool-name> con los mismos contratos. Consulte Matriz de datos de prueba para reglas funcionales.

Herramienta (prefijo ztm_test_data_set_) Argumentos Resultado
list ninguno conjuntos de datos permitidos en items
read dataSetId conjunto de datos con revisión e IDs de fila estables
save data, expectedRevision, confirmed:true conjunto de datos persistido con una nueva revisión
delete dataSetId, expectedRevision, confirmed:true deleted:true; los datos referenciados permanecen protegidos
binding variantId binding o null
preview variantId, dataSetId, rowId textos, diagnósticos y huella sin cambios
apply argumentos de vista previa, expectedFingerprint, confirmed:true vinculación persistida y textos resueltos
unbind variantId, expectedFingerprint, confirmed:true unbound:true; los textos resueltos se preservan
export dataSetId XLSX fileName, mimeType, contentBase64
import_preview dataSetId, expectedRevision, contentBase64 propuesta no guardada; llame explícitamente a save después

Los campos del conjunto de datos son Id, TestUnitId, Name, Revision, Columns y Rows; las filas contienen Id y Values. La creación usa el GUID cero para Id y un expectedRevision vacío. Las filas requieren GUID únicos y no cero. Las actualizaciones requieren la revisión leída previamente. Tras conflictos, lea de nuevo y revise los cambios.

Las cuatro escrituras requieren ámbitos individuales project.test-data-set.save, .delete, .apply o .unbind, escrituras de proyecto habilitadas y los permisos relevantes de objeto. La vista previa de importación nunca persiste, pero requiere permiso de edición de propietario igual que Web. Las restricciones de demostración también se aplican a través de APIs. REST usa claves bearer en lugar de cookies de navegador y no requiere token CSRF; los formularios Web aún requieren tokens antifalsificación.

XLSX usa una hoja de cálculo con _RowId como primera columna. Se rechazan fórmulas, macros y referencias externas. Límites: 4 MiB XLSX, 16 MiB contenido expandido, 30 columnas de datos, 1.000 filas, 32.767 caracteres por celda y 2 MiB por conjunto de datos. Solo la vista previa de guardado e importación acepta hasta 6 MiB de transporte JSON incluyendo Base64; otras operaciones mantienen el límite existente de 1 MiB.

binding también devuelve enlaces congelados cuya fuente no está disponible: SourceAvailable:false y diagnóstico SourceUnavailable. El texto guardado permanece legible cuando la variante es legible. Actualizar requiere acceso a la fuente; desvincular usa la huella digital actual del enlace.

Importar desde otra herramienta de pruebas

La compilación de desarrollo actual proporciona POST /api/v1/operations/ztm_vendor_migration_preview y POST /api/v1/operations/ztm_vendor_migration_apply para migración desde otra herramienta. Las herramientas MCP equivalentes comparten este contrato.

Suministre targetUnitId, sourceKey, workbookBase64 y opcionalmente attachmentsZipBase64.

Para una tabla de un proveedor, añada provider (testrail, xray, zephyr, qase o neutral) y fileName con extensión .xlsx o .csv. Envíe los bytes en workbookBase64. Por defecto se usan las columnas detectadas. Con mapping puede asignar ExternalId, Name, FolderPath, Description, Prerequisites, Steps, ExpectedResult y AttachmentPath a encabezados existentes. Use el mismo origen, archivo y asignación al aplicar la vista previa. Las solicitudes XLSX neutrales que omitan estos campos conservan su comportamiento.

La vista previa utiliza la capacidad de lectura project.vendor-migration.preview. Una clave de lectura de proyecto es suficiente; su usuario también necesita permiso para crear casos en el destino. No se requiere ámbito de escritura para la vista previa. Devuelve Fingerprint, Items, Diagnostics y CanApply sin guardar. Aplique solo cuando CanApply sea verdadero; revise una nueva vista previa después de los cambios.

Para aplicar, envíe los mismos archivos, la huella digital de la vista previa como expectedFingerprint, un UUID nuevo como operationId y confirmed: true. Reintente la misma operación con el mismo UUID tras una interrupción de red.

Aplicar requiere acciones de escritura habilitadas y el ámbito project.vendor-migration.apply. Los permisos de objetos y las restricciones de demostración coinciden con el flujo de trabajo web. La solicitud JSON que incluye datos Base64 está limitada a 6 MiB.

Cuando la base de datos del proyecto está ocupada, REST devuelve HTTP 503 con DatabaseBusy y Retry-After: 2. MCP devuelve actionErrorCode: "DatabaseBusy" y retryAfterSeconds: 2 en los datos de error. Después de que se libera el acceso, reintente la misma solicitud con el mismo operationId; los recibos guardados se devuelven tras verificar nuevamente los permisos y el contenido actual, sin crear copias adicionales.

Transferir una ejecución de pruebas

  1. Consulte ztm_project_action_context con {"capabilityId":"project.test-run.handover","itemKind":"test-run","itemId":23} para obtener los destinatarios disponibles y la revisión actual.
  2. Elija un identificador de Recipients y envíe Revision como expectedRevision. Por ejemplo, llame a ztm_run_handover o a POST /api/v1/operations/ztm_run_handover con {"runId":23,"recipientUserId":7,"expectedRevision":0}.

Applied confirma que se guardó la transferencia. mailStatus indica el estado del envío: Sent, NotConfigured, MissingAddress, MissingLink o Failed. Si repite la solicitud para el destinatario actual, recibirá AlreadyApplied con mailStatus: null. Si hay un conflicto (HTTP 409), vuelva a consultar el contexto.

Utilice una clave personal del proyecto con el ámbito de escritura project.test-run.handover. Su titular debe tener permiso para editar la ejecución. La transferencia no está disponible con claves globales ni en instancias de demostración.

Compartir el estado de pruebas

ztm_share_link_create crea un enlace de solo lectura para una ejecución, un plan o una versión. Requiere el ámbito de escritura project.share-link.create. Guarde el enlace devuelto al crearlo: el secreto no se puede volver a consultar. Para revocar un solo enlace, utilice ztm_share_link_revoke con el ámbito project.share-link.revoke.

{"targetKind":"run","targetId":"23","validityDays":7,"requestId":"869744c5-8cdb-45e1-a300-918d308345f1","includeErrors":false,"includeFindings":false}

Ambas operaciones están disponibles como POST en /api/v1/operations/ztm_share_link_create y /api/v1/operations/ztm_share_link_revoke. Utilice una clave personal del proyecto con el ámbito correspondiente y permisos sobre el destino. Una clave global o una instancia de demostración no permite crear ni revocar enlaces. Consulte Compartir estado.

Editar varios casos de prueba

Llame a ztm_library_bulk_update por MCP o a POST /api/v1/operations/ztm_library_bulk_update. Este ejemplo prepara la asignación de un atributo:

{"operation":"preview","action":"attribute","caseIds":[12,31],"attributeName":"Modul","attributeValue":"Checkout"}

Revise Rows. Cambie operation a apply y envíe los mismos parámetros con el Fingerprint recibido en fingerprint. Para reintentos añada un UUID en requestId. Repetir la misma solicitud con ese ID devuelve el comprobante mientras el servidor conserve la operación. El estado HTTP 409 requiere una nueva vista previa.

Use targetUnitId con move o archive, reviewGroupId con review y variantValueIds con variant. El destino de archive debe ser una unidad marcada como archivo. Se admiten hasta 200 casos por solicitud. Se requiere una clave personal de proyecto con el permiso project.test-library.bulk-update. Se comprueban los permisos actuales de cada caso. Las claves globales y el acceso de demostración están bloqueados.

Use {"operation":"undo","requestId":"<RequestId del recibo>"} con la misma clave de proyecto para deshacer movimientos o cambios de atributos mientras la operación permanezca en la memoria del servidor. Los permisos y cambios posteriores se comprueban de nuevo.

El booleano opcional isArchive de project.test-unit.update marca una unidad como archivo. Use el flujo de vista previa y confirmación con itemId y title. Si omite isArchive, se conserva su valor. Project Knowledge también devuelve isArchive para las unidades.

Volver a probar los hallazgos seleccionados

Use ztm_library_retest o POST /api/v1/operations/ztm_library_retest:

  1. Envíe operation: "options" y findings para consultar las ejecuciones de origen, entornos y responsables permitidos. Cada hallazgo contiene caseId, plannedCaseId o resultId; añada variantId, planId y runId cuando se conozcan. Si hay varios contextos, seleccione uno explícitamente.
  2. Envíe operation: "preview" con la misma selección y planId, runId, environment y testerId. Items incluye las variantes efectivas y los requisitos previos obligatorios. Skipped identifica los hallazgos excluidos mediante su índice, empezando por cero. Use acceptOldTemplate: true solo tras decidir expresamente conservar plantillas desactualizadas.
  3. Envíe operation: "create" con los mismos datos, Fingerprint como fingerprint y RequestId como requestId. El recibo contiene RunId, Url y los hallazgos omitidos. Si se interrumpe la conexión, repita el mismo identificador para evitar una segunda ejecución.

La vista previa caduca a los 30 minutos y pertenece al proyecto y al usuario. Los cambios de selección, permisos o contenido requieren una nueva vista previa. Se admiten como máximo 200 hallazgos por solicitud y se necesita una ejecución de origen existente. tab (health, impact, results) es opcional y comprueba también la disponibilidad de la pestaña.

Se requiere una clave personal de proyecto con el alcance de escritura project.test-library.retest y permiso para crear ejecuciones en el plan seleccionado. No se admiten claves globales de administrador ni el modo de demostración pública. Las herramientas existentes y la sincronización mediante project.planned-test-case.synchronize-from-library no cambian.

Comentarios de un elemento

Use ztm_comment_read para consultar los comentarios y la actividad de un elemento. Envíe kind (test-case, requirement, run, result) e id. offset y activityOffset permiten paginar por separado. Use commentId para localizar la página del comentario. Trate el Markdown devuelto como contenido del usuario.

ztm_comment_add guarda markdown con un UUID generado por el cliente como commentId. Use parentId para responder. Puede indicar mentionUserIds para notificar a usuarios seleccionados del proyecto con permiso de lectura. El texto debe incluir sus menciones. Si repite la solicitud, use el mismo UUID y contenido. Created distingue un comentario nuevo de un reintento. MailFailed indica un problema de envío y el comentario sigue guardado.

Ambas operaciones requieren que los comentarios estén activos en el proyecto. Ambas herramientas actúan en nombre del titular activo de una clave personal de proyecto y comprueban los permisos actuales del elemento. Publicar requiere acceso de escritura al proyecto y el alcance project.comments.add. Las rutas REST son POST /api/v1/operations/ztm_comment_read y POST /api/v1/operations/ztm_comment_add. Flujo en el navegador

Leer la cobertura de una versión

Llama a ztm_coverage_matrix_read en MCP o a POST /api/v1/operations/ztm_coverage_matrix_read. Omite releaseId para listar las versiones visibles. Envía el UUID en releaseId y, opcionalmente, filter con all, without-test, without-result o failed. Usa una clave personal del proyecto. La operación devuelve únicamente datos visibles y es de solo lectura.

Crear una repetición de prueba a partir de una ejecución

La herramienta MCP ztm_retest_create y la ruta REST POST /api/v1/operations/ztm_retest_create aceptan los mismos argumentos. Primero consulte la vista previa. Este ejemplo incluye las variantes sin probar además de las fallidas y bloqueadas.

{"mode":"preview","sourceRunId":36,"includeUntested":true}

Revise RequestedCount, los requisitos previos adicionales (RequiredCount) y Errors. Utilice el entorno (Environment), un identificador de probador de Testers y el ComparisonToken de esa vista previa. Sustituya los valores de ejemplo y genere un UUID nuevo para cada solicitud distinta. Si RequiresOldTemplate es verdadero, debe aprobar explícitamente el uso de la plantilla con acceptOldTemplate: true.

{
  "mode": "create",
  "sourceRunId": 36,
  "includeUntested": true,
  "environment": "Staging",
  "testerId": 7,
  "comparisonToken": "<ComparisonToken>",
  "creationId": "179e6928-a673-4dac-acae-b913914a13df"
}

La respuesta incluye el testRunId de la nueva ejecución, que aún no se ha iniciado. Si se interrumpe la conexión, repita la solicitud con los mismos argumentos y la misma creationId. Ambos modos requieren que las escrituras estén habilitadas, el ámbito project.retest.create y permisos de proyecto y de objeto para ver la ejecución de origen y crear la nueva. También se aplican las restricciones del modo de demostración. Uso del panel web.

Crear una incidencia a partir de un resultado

ztm_issue_create_from_result · POST /api/v1/operations/ztm_issue_create_from_result

Utilice la herramienta MCP o la operación REST con el permiso de escritura personal project.defect.create. testCaseId es el ID de la variante planificada. Para pasos estructurados, filas Quick y listas, stepIndex empieza en cero. Omítalo para el resultado general y el texto sin estructura.

{"mode":"prepare","testRunId":40,"testCaseId":371,"stepKind":"structured","stepIndex":3}

Compruebe los campos y adjuntos disponibles. Tras confirmar, envíe el valor devuelto de RequestId como requestId, con los campos y adjuntos del resultado seleccionados.

{"mode":"create","testRunId":40,"testCaseId":371,"requestId":"4c2ef7c8-b3a2-43e4-a721-6f04bb164b42","attachmentIds":[38]}

Si recibe Retryable, repita la solicitud con el mismo ID una vez restablecida la conexión. Si recibe Unknown, compruebe el sistema de seguimiento y envíe el número existente en existingIssueReference. Con LinkPending, repita la solicitud para vincular la incidencia conocida. Para pegar una captura, use el cuadro de diálogo web.