# API de exportación de casos de prueba

> Descarga los casos de prueba activos de un proyecto en JSON, XML, CSV, XLSX o archivos Gherkin `.feature` mediante la API para integradores.

El endpoint de exportación descarga los casos de prueba **activos** (no archivados) de un proyecto como un único artefacto. Admite cinco formatos y tres opciones de alcance, de forma que un integrador puede descargar un proyecto completo, el subárbol de una suite, o exactamente el subconjunto filtrado que un usuario está viendo en el repositorio.

El endpoint es **de solo lectura** — no emite eventos de auditoría ni realiza cambios de estado. Los adjuntos (evidencia de defectos, archivos de casos, archivos de resultados e imágenes dentro de los textos) **nunca se incluyen** en ningún formato exportado; solo viajan con el artefacto el texto, las etiquetas, los valores de campos personalizados y la estructura de suites. Las imágenes de un texto viajan como referencias `attachment:`.

Todas las peticiones requieren autenticación (token de API Bearer o cookie de sesión) con el permiso de importación/exportación (que tienen `owner`/`admin`/`member`). Los usuarios con rol `viewer` reciben `403 forbidden`.

## Exportar casos de prueba

`GET /api/v1/projects/{projectId}/exports`

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

### Parámetros de consulta

| Parámetro      | Por defecto | Notas                                                                                                                                                                                                                                                                |
| -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`       | —           | Obligatorio. Uno de `json`, `xml`, `csv`, `xlsx`, `feature`. Un valor no listado devuelve `422 validation_failed`. `feature` devuelve un zip de archivos `.feature`, uno por suite, solo con casos Gherkin; un alcance sin ningún caso Gherkin se rechaza con `422`. |
| `scope`        | `project`   | `project` (todo el proyecto), `suite` (la suite indicada por `suite`, más todas sus suites descendientes), o `filtered` (el servidor reevalúa `q`/`cf`/`reviewStatus` — ver abajo).                                                                                  |
| `suite`        | —           | ULID de la suite. Obligatorio cuando `scope=suite`; se ignora en otro caso. Un ULID de suite no resoluble devuelve `404 not_found`.                                                                                                                                  |
| `q`            | —           | Filtro de subcadena, aplicado solo cuando `scope=filtered`. Mismo contrato de coincidencia de subcadena que el [endpoint de búsqueda de casos de prueba](https://docs.probara.net/es/developers/api/test-case-search/).                                                                      |
| `cf`           | —           | Filtro de campo personalizado, repetible, aplicado solo cuando `scope=filtered`. Cada entrada es `<fieldUlid>:<value[,value…]>` — contrato idéntico al de los endpoints de búsqueda/listado.                                                                         |
| `reviewStatus` | —           | Estados de revisión separados por comas (`not_reviewed`, `in_review`, `approved`), aplicados solo cuando `scope=filtered`. Mismo contrato que el [endpoint de búsqueda de casos de prueba](https://docs.probara.net/es/developers/api/test-case-search/).                                    |

### Respuesta

`200` con el cuerpo del artefacto en el formato solicitado. La respuesta siempre lleva un `Content-Type` correspondiente y una cabecera `Content-Disposition: attachment` que nombra el archivo `<projectId>-export.<extension>` (o `<projectId>-features.zip` para `feature`):

| `format`  | `Content-Type`                                                      | Extensión |
| --------- | ------------------------------------------------------------------- | --------- |
| `json`    | `application/json`                                                  | `.json`   |
| `xml`     | `application/xml`                                                   | `.xml`    |
| `csv`     | `text/csv`                                                          | `.csv`    |
| `xlsx`    | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx`   |
| `feature` | `application/zip`                                                   | `.zip`    |

Los formatos JSON, XML, CSV y XLSX llevan los mismos datos subyacentes: para cada caso de prueba activo, su título, descripción, etiquetas, ruta de suite, pasos, los valores completos de campos personalizados (campos fijos — prioridad/tipo/estado — más cada campo personalizado configurado en el proyecto) y su clave de automatización (`automationKey` en JSON, un elemento `<automationKey>` en XML — vacío cuando no está asignada — y una columna `automation_key` justo después de `step_expected` en CSV/XLSX). Cada caso indica también su formato de pasos (`stepFormat`, o una columna `step_format` en CSV/XLSX), y cada paso su palabra clave Gherkin (`keyword`, o una columna `step_keyword`); es `null` o está vacía en un paso clásico. Las celdas de CSV y XLSX que comienzan con `=`, `+`, `-`, `@`, un tabulador o un retorno de carro se prefijan con una comilla simple (`'`) inicial para neutralizar la inyección de fórmulas en hojas de cálculo — esto es visible si abres el archivo en una aplicación de hoja de cálculo.

Los parámetros y las combinaciones excluidas de un caso también se exportan, cuando el caso los tiene. JSON los lleva en las claves `parameters` y `excludedCombinations`, XML en los elementos `<parameters>` y `<excludedCombinations>`, y CSV y XLSX en las columnas `parameters` y `excluded_combinations`, que contienen JSON. JSON conserva un parámetro compartido como referencia, mientras que CSV y XLSX lo escriben como copia local de sus valores. El formato `feature` escribe las combinaciones que ejecuta el caso como una sola tabla Examples: las combinaciones excluidas y la división entre parámetros simples y grupos no se conservan. Consulta [Casos de prueba parametrizados](https://docs.probara.net/es/guides/parameterized-test-cases/).

### Límite de tamaño

Una exportación está acotada a `EXPORT_MAX_CASES` (5000) casos activos por petición. Cuando el alcance resuelto superaría ese límite, la petición falla **antes de leer o serializar cualquier fila**:

```json
{ "error": { "code": "too_many_cases", "message": "..." } }
```

Reduce el alcance (una suite más pequeña, o un alcance `filtered` con `q`/`cf`) y vuelve a intentarlo.

### Límite de tasa

Las peticiones de exportación están limitadas por organización. Superar el límite devuelve `429` con `{ "error": { "code": "too_many_requests", ... } }`. Espera un momento y reintenta.

### Errores

| Estado | Código              | Condición                                                                                                                   |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `forbidden`         | El rol del llamante es `viewer`                                                                                             |
| `404`  | `not_found`         | `projectId` no existe en la organización activa, o `scope=suite` referencia un ULID de suite que no existe en este proyecto |
| `422`  | `validation_failed` | Falta `format` o no es uno de los cinco valores listados, o `scope=suite` está presente sin `suite`                         |
| `422`  | `too_many_cases`    | El alcance resuelto supera `EXPORT_MAX_CASES`                                                                               |
| `429`  | `too_many_requests` | Se superó el límite de tasa de exportación de la organización                                                               |

### Reimportar una exportación

Todo archivo que produce este endpoint — JSON, XML, CSV o XLSX — puede reimportarse mediante la [API de importación](https://docs.probara.net/es/developers/api/import/) en dos pasos: `POST /api/v1/projects/{projectId}/imports:stage` para cargar el archivo y luego `POST /api/v1/projects/{projectId}/imports/commit` con el formato de origen `probara_json`/`probara_xml`/`probara_csv`/`probara_xlsx` correspondiente — un ciclo completo de ida y vuelta para respaldar y restaurar, o migrar casos entre proyectos. Los archivos del caso nunca se exportan. Las imágenes insertadas en los textos del caso viajan como referencias `attachment:<ulid>`: una reimportación en la misma organización conserva esas imágenes mientras sigan existiendo en ella, y descarta la referencia a una imagen que no conoce. Todo lo demás (título, descripción, etiquetas, ruta de suite, pasos y valores de campos personalizados) se conserva íntegramente en el ciclo. Una exportación `feature` no es una fuente de reimportación: importa uno de sus archivos `.feature` con el origen `gherkin_feature`.

### Ejemplo

Exportar un proyecto completo como CSV:

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -o acme-export.csv \
  "https://app.probara.net/api/v1/projects/ACME/exports?format=csv"
```

Exportar el subárbol de una suite (incluyendo sus descendientes) como XLSX:

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -o acme-suite-export.xlsx \
  "https://app.probara.net/api/v1/projects/ACME/exports?format=xlsx&scope=suite&suite=01JAAAA..."
```

Exportar el subconjunto filtrado que coincide con una búsqueda como JSON:

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -o acme-filtered-export.json \
  "https://app.probara.net/api/v1/projects/ACME/exports?format=json&scope=filtered&q=login"
```

Exporta los casos Gherkin como archivos `.feature`, uno por suite, en un zip:

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -o ACME-features.zip \
  "https://app.probara.net/api/v1/projects/ACME/exports?format=feature"
```

## Páginas relacionadas

- [API de búsqueda de casos de prueba](https://docs.probara.net/es/developers/api/test-case-search/) — el mismo contrato de filtros `q`/`cf` usado por `scope=filtered`.
- [API de importación de casos de prueba](https://docs.probara.net/es/developers/api/import/) — reimporta los archivos que produce este endpoint, con fidelidad completa para reimportaciones de Probara.