# API de configuración de revisión de casos

> Leer y cambiar la configuración de revisión de casos de prueba de un proyecto — si la revisión está activada, si es obligatoria, la fusión por el autor, las aprobaciones necesarias, la fusión automática y los revisores predeterminados.

Cada proyecto tiene una **configuración de revisión de casos de prueba**: si los cambios en sus
casos pasan por una revisión antes de llegar al repositorio, y cómo funciona esa revisión. Es la
contraparte en la API de la pestaña **Repositorio** de la configuración del proyecto.

La revisión de casos de prueba se incluye en los planes **Pro** y **Enterprise** (y está disponible durante la
prueba gratuita). En los demás planes, ambos endpoints y sus herramientas MCP responden
`403 forbidden`; `GET /api/v1/orgs/current` incluye `caseReviewEnabled` para que puedas
comprobarlo antes. Un cambio a un plan inferior conserva la configuración guardada.

`{projectId}` es el **código** del proyecto (por ejemplo `ACME`).

## Opciones

| Clave                    | Tipo                       | Por defecto | Significado                                                                                                                                                              |
| ------------------------ | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`                | `boolean`                  | `false`     | La revisión de casos está activada en el proyecto. Mientras sea `false`, el resto se guarda pero no tiene efecto.                                                        |
| `mandatory`              | `boolean`                  | `false`     | Cada caso nuevo y cada cambio en un caso deben enviarse a revisión.                                                                                                      |
| `allowSelfMerge`         | `boolean`                  | `false`     | El autor de una solicitud de revisión puede fusionarla.                                                                                                                  |
| `approvalsRequired`      | entero `>= 0`              | `1`         | Aprobaciones que necesita una solicitud para poder fusionarse. `0` significa que no hay mínimo.                                                                          |
| `autoMerge`              | `boolean`                  | `false`     | Fusiona una solicitud en cuanto alcanza `approvalsRequired`. Requiere `approvalsRequired` de al menos `1`.                                                               |
| `onlyApprovedInRuns`     | `boolean`                  | `false`     | Solo los casos de prueba con `reviewStatus` `approved` pueden añadirse a ejecuciones. Consulta [Casos de ejecución](https://docs.probara.net/es/developers/api/run-cases/#solo-casos-aprobados). |
| `defaultReviewerUserIds` | arreglo de ULID de miembro | `[]`        | Miembros asignados a cada nueva solicitud de revisión, en el orden indicado. Como máximo 50.                                                                             |

## Obtener la configuración de revisión

```http
GET /api/v1/projects/{projectId}/review-settings
```

Disponible para cualquiera que pueda leer el proyecto.

```json
{
  "enabled": true,
  "mandatory": false,
  "allowSelfMerge": false,
  "approvalsRequired": 1,
  "autoMerge": false,
  "onlyApprovedInRuns": false,
  "defaultReviewerUserIds": ["01J8Z3W4X5Y6Z7A8B9C0D1E2F3"]
}
```

Un revisor predeterminado que dejó la organización o perdió el acceso al proyecto no aparece en la
lista. Vuelve a aparecer si recupera el acceso.

## Actualizar la configuración de revisión

```http
PATCH /api/v1/projects/{projectId}/review-settings
```

Envía solo las claves que quieras cambiar; se requiere al menos una, y una clave desconocida se
rechaza. La respuesta es la configuración completa, tal como la devuelve `GET`.

```json
{
  "enabled": true,
  "mandatory": true,
  "approvalsRequired": 2,
  "defaultReviewerUserIds": ["01J8Z3W4X5Y6Z7A8B9C0D1E2F3"]
}
```

- `defaultReviewerUserIds` reemplaza la lista completa; `[]` la vacía. Cada ULID debe corresponder a
  un miembro actual de la organización con acceso al proyecto cuyo rol tenga el permiso
  `test-cases.review`; si no, la solicitud responde
  `422 validation_failed`, `details.defaultReviewerUserIds` enumera los ULID rechazados y no se
  guarda nada.
- `autoMerge: true` requiere `approvalsRequired` de al menos `1`. La regla también se comprueba con
  la configuración guardada: activar `autoMerge` mientras el valor guardado es `0`, o bajar el valor a
  `0` mientras `autoMerge` está activado, responde `422 validation_failed` y no guarda nada.
- Un cambio registra un evento de auditoría `project.review_settings_updated` cuyo
  `metadata.changes` nombra cada opción modificada con su valor anterior y el nuevo. Para
  `defaultReviewers`, los valores son la cantidad de revisores. Una solicitud que no cambia nada no
  registra ningún evento.

### Autorización

Requiere el permiso `projects.manage` (que hoy tienen los propietarios y administradores), o ser
el propietario actual del proyecto, igual que la
[configuración de ejecución](https://docs.probara.net/es/developers/api/project-run-settings/). Cualquier otro recibe
`403 forbidden`. Los proyectos archivados mantienen su configuración editable.

## Errores

| Estado | Código              | Cuándo                                                                                                                              |
| ------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `forbidden`         | El plan no incluye la revisión de casos, o quien llama no puede cambiar la configuración.                                           |
| `404`  | `not_found`         | No hay un proyecto con ese código en tu organización, o no puedes leerlo.                                                           |
| `422`  | `validation_failed` | Clave desconocida, cuerpo vacío, valor no válido, fusión automática sin aprobación necesaria o un revisor predeterminado no válido. |

## Herramientas MCP

`get_project_review_settings` y `update_project_review_settings` reciben `project_id` y las mismas
claves. Consulta la [referencia de herramientas MCP](https://docs.probara.net/es/developers/mcp-tools/).