API de informes de trazabilidad

Un informe de trazabilidad abarca los requisitos de una herramienta de seguimiento: las incidencias de Jira de los proyectos y tipos de incidencia que elijas, o los issues de GitHub de los repositorios que elijas. Cada versión de un informe es una instantánea tomada al generarla: los requisitos que coinciden, sus casos de prueba vinculados, los últimos resultados y los defectos. Las pantallas se describen en Trazabilidad con Jira y en Trazabilidad con GitHub.

Todos los endpoints están bajo /api/v1/projects/{projectId}/traceability, donde {projectId} es el código del proyecto (por ejemplo ACME). Los endpoints necesitan el plan Pro o Enterprise; en otros planes responden 403 forbidden. Para leer se necesita acceso al proyecto. Para crear, generar, renombrar y eliminar se necesita el permiso test-cases.write, el mismo que vincula casos de prueba a incidencias de Jira.

Método y ruta	Qué hace
`GET /sources`	Lista las conexiones activas de Jira y de GitHub de la organización, cada una con su `provider`. Una lista vacía significa que no hay ninguna integración activa, así que no se puede crear ningún informe.
`GET /sources/{connectionUlid}/projects`	Lista los proyectos de Jira que permite esa conexión, leídos en directo de Jira.
`GET /sources/{connectionUlid}/issue-types?projects=WEB,API`	Lista los nombres distintos de tipos de incidencia de los proyectos de Jira indicados, ordenados.
`GET /sources/{connectionUlid}/repositories`	GitHub: lista los repositorios que un informe puede leer a través de esa conexión.
`GET /sources/{connectionUlid}/labels?repository=acme/shop`	GitHub: lista los nombres de las etiquetas del repositorio.
`GET /sources/{connectionUlid}/milestones?repository=acme/shop`	GitHub: lista los hitos del repositorio, abiertos y cerrados, con `title` y `state`.
`GET /reports`	Lista los informes del proyecto, del más reciente al más antiguo.
`POST /reports`	Guarda un informe y pone en cola su primera versión. Responde `201`.
`GET /reports/{reportUlid}`	Consulta un informe.
`PATCH /reports/{reportUlid}`	Renombra un informe.
`DELETE /reports/{reportUlid}`	Elimina el informe y todas sus versiones. Responde `204`.
`GET /reports/{reportUlid}/versions`	Lista las versiones del informe, de la más reciente a la más antigua.
`POST /reports/{reportUlid}/versions`	Pone en cola una nueva versión con los proyectos y tipos de incidencia del informe. Responde `201`.
`GET /versions/{versionUlid}`	Consulta una versión: su estado y sus totales y, cuando está lista, los totales de cada proyecto.
`PATCH /versions/{versionUlid}`	Renombra una versión. `null` quita el nombre.
`DELETE /versions/{versionUlid}`	Elimina la versión. Responde `204`.
`GET /versions/{versionUlid}/requirements`	Lista una pestaña de una versión lista, con filtros y paginación por página.

Elegir las fuentes

POST /reports toma el ULID de la conexión de GET /sources y las claves de proyecto que devuelve GET /sources/{connectionUlid}/projects. Los nombres de tipo de incidencia salen de GET /sources/{connectionUlid}/issue-types.

Crear un informe

POST /reports admite:

Campo	Regla
`name`	Obligatorio, de 1 a 200 caracteres después de quitar los espacios de los extremos.
`filters.provider`	`jira`. Para un informe de GitHub, `github` con otros filtros: consulta Informes de GitHub.
`filters.projects`	Obligatorio, de 1 a 20 objetos con `connectionUlid` y `projectKey`, sin duplicados. Cada proyecto debe estar permitido por una conexión activa de la organización. Si no lo está, la solicitud responde `422 traceability_project_not_allowed` y no guarda nada.
`filters.issueTypes`	Opcional, hasta 50 nombres. Si se omite o está vacío, incluye todos los tipos de incidencia de los proyectos. Los nombres se comparan sin distinguir mayúsculas y minúsculas, y los duplicados se eliminan.

La respuesta 201 contiene el report y su primera version, cuyo estado es pending. Consulta la versión hasta que su estado sea ready.

Informes de GitHub

Un informe con filters.provider: "github" lee los issues de hasta 20 repositorios:

{
  "name": "Checkout requirements",
  "filters": {
    "provider": "github",
    "repositories": [{ "connectionUlid": "01J9Z3K4M5N6P7Q8R9S0T1V2W3", "fullName": "acme/shop" }],
    "labels": ["requirement"],
    "milestone": "v2.0",
    "state": "all"
  }
}

Campo	Regla
`filters.repositories`	Obligatorio, de 1 a 20, de `GET /sources/{connectionUlid}/repositories`: la vinculación de repositorios del proyecto en esa conexión, o todos los repositorios que ve si el proyecto no vincula ninguno. Si no, responde `403 github_repository_not_mapped` o `422 github_repository_not_visible` y no se guarda nada.
`filters.labels`	Opcional, hasta 20 nombres sin comas. Un issue debe tener todas ellas. Vacío conserva todos los issues.
`filters.milestone`	Título de un hito, opcional, sin distinguir mayúsculas. Un repositorio sin un hito con ese título no aporta issues.
`filters.state`	`open`, `closed` o `all` (predeterminado).

Los repositorios se vuelven a comprobar al generar cada versión. Los pull requests nunca son requisitos. La clave de un requisito es propietario/nombre#número, su projectKey es propietario/nombre, su tipo es Issue y su estado es Open, Closed o Closed as not planned, en las categorías to_do (abierto) o done (cerrado). Un requisito de GitHub está vinculado cuando un caso de prueba del proyecto vincula el issue como requirement (consulta la API de GitHub).

Versiones

Una versión tiene estos campos:

status: pending, generating, ready o failed.
number: 1, 2, 3 y así sucesivamente dentro del informe. El número de una versión eliminada nunca se reutiliza.
name: el nombre que se le dio al renombrarla, o null para mostrarla como Versión {number}.
totals: requirements, linked y unlinked. Es null hasta que la versión está lista.
errorCode, en una versión fallida: connection_unavailable cuando la conexión de un proyecto seleccionado se eliminó, se pausó o ya no permite el proyecto; requirements_limit_exceeded cuando los filtros coinciden con más de 5.000 requisitos; provider_error cuando no se pudo leer Jira.
createdAt y generatedAt: milisegundos desde la época Unix. generatedAt es null hasta que la versión está lista.

Una versión lista no cambia nunca. Un informe solo puede tener una versión en estado pending o generating a la vez: un POST /reports/{reportUlid}/versions hecho mientras hay otra abierta responde 409 traceability_version_in_progress.

GET /versions/{versionUlid} también devuelve report (su ULID, nombre y filtros) y projects: una entrada por cada proyecto seleccionado, en el orden del informe, con su connectionUlid, projectKey, name y los recuentos requirements, linked y unlinked. projects está vacío hasta que la versión está lista.

Requisitos

GET /versions/{versionUlid}/requirements responde una pestaña de una versión lista. Una versión que no está lista responde 409 traceability_version_not_ready.

Parámetro	Significado
`tab`	`linked` (por defecto) o `unlinked`.
`q`	Hasta 200 caracteres. Coincide con la clave de Jira exacta, sin distinguir mayúsculas y minúsculas, o con una parte del título o de la clave, sin distinguir mayúsculas y minúsculas.
`projectKey`	Solo requisitos de este proyecto de Jira.
`status`	Categorías de estado separadas por comas: `to_do`, `in_progress`, `done`.
`resultStatus`	Últimos resultados de los casos vinculados, separados por comas: `passed`, `failed`, `skipped`, `blocked`, `untested`. Se ignora en `unlinked`.
`defectStatus`	Estados de los defectos vinculados, separados por comas: `open`, `in_progress`, `resolved`, `closed`. Se ignora en `unlinked`.
`page`	Desde 1. Por defecto, 1. Una página posterior a la última no devuelve elementos.
`pageSize`	De 1 a 100. Por defecto, 25.

Los filtros se combinan con Y, y los valores dentro de un mismo filtro se combinan con O.

Un requisito está vinculado cuando al menos un caso de prueba del proyecto lo vincula, incluidos los casos archivados. La pestaña unlinked contiene los demás.

La respuesta tiene items, page, pageSize y total (los requisitos que cumplen todos los filtros, en todas las páginas). Una versión no cambia una vez lista, así que las páginas consecutivas nunca se solapan. Cada requisito incluye sus identificadores y su URL de Jira, statusName y statusCategory, updatedAt tal como se leyó al generar la versión, caseCount, staleCaseCount, defects (total, los defectos distintos vinculados a sus casos, y byStatus, esos mismos defectos contados por estado actual: open, in_progress, resolved y closed), y hasta 200 cases, con casesTruncated cuando hay más. Cada caso incluye displayId, title, el indicador archived, caseUpdatedAt, el indicador stale, latestResult (o null) y hasta 20 defects, con defectsTruncated cuando hay más.

Límites de uso

Leer los proyectos o los tipos de incidencia de una conexión, crear informes y crear versiones tienen un límite de uso por organización. Una respuesta 429 too_many_requests incluye Retry-After.

Errores

Todos los errores usan el formato de error estándar.

Estado	Código	Cuándo
`403`	`forbidden`	El plan no incluye integraciones, o tu rol no tiene `test-cases.write` para crear, generar, renombrar o eliminar.
`403`	`github_repository_not_mapped`	GitHub: la vinculación de repositorios del proyecto deja fuera el repositorio.
`409`	`github_connection_stale`	GitHub: la instalación se suspendió o se desinstaló.
`422`	`github_repository_not_visible`	GitHub: la instalación no tiene acceso al repositorio.
`503`	`github_unavailable`	GitHub no responde en este momento.
`403`	`jira_project_not_allowed`	La conexión no permite el proyecto de Jira solicitado.
`403`	`jira_permission_denied`	Jira rechazó la lectura con la cuenta de la conexión.
`404`	`not_found`	No existe un informe, una versión o una conexión con ese ULID que puedas ver.
`404`	`jira_not_found`	Jira no encuentra el proyecto o el tipo de incidencia solicitado.
`409`	`jira_connection_stale`	La conexión de Jira está obsoleta. Revísala en la configuración de integraciones.
`409`	`traceability_version_in_progress`	Otra versión del informe está en cola o generándose.
`409`	`traceability_version_not_ready`	Se pidieron requisitos de una versión que no está lista.
`422`	`traceability_project_not_allowed`	Una conexión activa no permite algún proyecto seleccionado. No se guarda nada.
`422`	`validation_failed`	El cuerpo, un parámetro de consulta o un parámetro de ruta está mal formado.
`429`	`too_many_requests`	Se alcanzó el límite de uso de las lecturas o escrituras indicadas arriba. `Retry-After` indica cuándo reintentar.
`503`	`jira_unavailable`	No se puede contactar con Jira en este momento.
`503`	`jira_rate_limited`	Jira limita las solicitudes. `Retry-After` indica cuándo reintentar.