# API de entornos

> Crear, listar, obtener, actualizar y eliminar entornos de prueba por proyecto en la API para integradores.

Los entornos son contextos de prueba por proyecto con nombre (por ejemplo `staging`, `pre-prod`, `production`) que pueden asociarse a ejecuciones de prueba. Cada entorno tiene un ULID único asignado por el servidor y un `slug` legible que debe ser único entre los entornos activos dentro de un proyecto.

## Crear

`POST /api/v1/projects/{projectId}/environments`

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

### Cuerpo de la petición

| Campo         | Obligatorio | Notas                                                                                                                                                       |
| ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | sí          | Cadena no vacía, máximo 120 caracteres                                                                                                                      |
| `slug`        | sí          | Segmentos alfanuméricos en minúsculas unidos por guiones simples. Sin guiones al inicio, al final ni dobles. Ejemplos: `staging`, `pre-prod`, `pre-prod-v2` |
| `description` | no          | Descripción en texto libre, máximo 2000 caracteres                                                                                                          |
| `url`         | no          | URL válida, máximo 2000 caracteres                                                                                                                          |
| `isDefault`   | no          | `true` para marcar como entorno predeterminado del proyecto. Demota atómicamente al predeterminado actual. Por defecto es `false`                           |

Los campos `ulid` enviados por el cliente son rechazados.

### Respuesta

`201` con el objeto del entorno creado. Ver [Campos de respuesta](#campos-de-respuesta).

Un `slug` duplicado entre entornos activos del proyecto devuelve `409 conflict`. Un formato de slug inválido o un `name` vacío devuelven `422 validation_failed`.

### Ejemplo

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Staging","slug":"staging","isDefault":true}' \
  "https://app.probara.net/api/v1/projects/ACME/environments"
```

## Listar

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

Devuelve los entornos activos (no eliminados) del proyecto, del más reciente al más antiguo. Paginación por página.

### Parámetros de consulta

| Parámetro  | Notas                                                 |
| ---------- | ----------------------------------------------------- |
| `page`     | Número de página (base 1, por defecto `1`)            |
| `pageSize` | Elementos por página (por defecto `50`, máximo `200`) |

### Respuesta

`200` con `{ items, page, pageSize, total }`. Cada ítem sigue el [formato de respuesta](#campos-de-respuesta).

### Ejemplo

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/projects/ACME/environments"
```

## Obtener

`GET /api/v1/environments/{environmentUlid}`

Devuelve un único entorno activo en el ámbito de la organización activa.

Devuelve `404 not_found` si el entorno no pertenece a la organización activa o ha sido eliminado.

### Ejemplo

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Actualizar

`PATCH /api/v1/environments/{environmentUlid}`

Actualización parcial. Se requiere al menos un campo; un cuerpo vacío devuelve `422 validation_failed`.

### Cuerpo de la petición

| Campo         | Obligatorio | Notas                                                                                                            |
| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `name`        | no          | Cadena no vacía, máximo 120 caracteres                                                                           |
| `slug`        | no          | Mismas reglas de formato que al crear                                                                            |
| `description` | no          | Máximo 2000 caracteres, o `null` para borrar                                                                     |
| `url`         | no          | URL válida, o `null` para borrar                                                                                 |
| `isDefault`   | no          | `true` para promover este entorno como predeterminado del proyecto; demota atómicamente al predeterminado actual |

Un `slug` duplicado devuelve `409 conflict`. Devuelve `404 not_found` si el entorno no pertenece a la organización activa.

### Ejemplo

```bash
curl -sS -X PATCH \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pre-producción","isDefault":false}' \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Eliminar

`DELETE /api/v1/environments/{environmentUlid}`

Elimina el entorno de forma lógica (soft-delete). Devuelve `204` si tiene éxito. Un `GET` posterior devuelve `404 not_found` y el entorno queda excluido de los resultados del listado.

Devuelve `404 not_found` si el entorno no pertenece a la organización activa.

### Ejemplo

```bash
curl -sS -X DELETE \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Campos de respuesta

Los endpoints de mutación (`POST`, `PATCH`) y `GET /api/v1/environments/{environmentUlid}` devuelven un único objeto de entorno con los siguientes campos.

| Campo         | Tipo           | Notas                                               |
| ------------- | -------------- | --------------------------------------------------- |
| `ulid`        | string (ULID)  | Identificador único asignado por el servidor        |
| `projectUlid` | string (ULID)  | El proyecto al que pertenece este entorno           |
| `name`        | string         | Nombre para mostrar                                 |
| `slug`        | string         | Identificador seguro para URLs                      |
| `description` | string \| null | Descripción opcional                                |
| `url`         | string \| null | URL opcional                                        |
| `isDefault`   | boolean        | Indica si es el entorno predeterminado del proyecto |
| `createdAt`   | number         | Milisegundos desde epoch Unix                       |
| `updatedAt`   | number         | Milisegundos desde epoch Unix                       |

## Eventos de auditoría

Las mutaciones de entorno emiten `environment.created`, `environment.updated` y `environment.deleted` en el feed de actividad de la organización. Ver [Eventos de auditoría](https://docs.probara.net/es/developers/api/audit-events/).