> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Proyectos

> Gestiona tu catálogo inmobiliario al nivel de proyecto. Operaciones CRUD sobre el padre de las unidades.

Un proyecto es el contenedor de nivel superior para un desarrollo inmobiliario. Agrupa [unidades](/es/api-reference/units) y guarda metadata compartida (ubicación, banda de precios, amenidades).

***

## Listar proyectos

```http theme={null}
GET /projects
```

**Scope:** `projects:read`. Paginado.

### Query parameters

| Parámetro                               | Notas                                                                         |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `limit`, `offset`, `sortOrder`, `query` | Ver [Paginación](/es/pagination). `query` matchea nombre, ciudad y promotora. |
| `type`                                  | Filtrar por tipo de proyecto.                                                 |
| `status`                                | Filtrar por `draft`, `published` o `archived`.                                |
| `city`                                  | Filtrar por ciudad (match parcial).                                           |

### Response 200

`data[]` paginado. Cada item incluye un campo derivado `unitCount`.

```json theme={null}
{
  "id": "proj_...",
  "name": "Bavarian Forest",
  "type": "residential",
  "promotora": "Acme Developers",
  "city": "Punta Cana",
  "address": "Av. Estados Unidos #1",
  "description": "...",
  "country": "DO",
  "state": "La Altagracia",
  "operationType": "sale",
  "currency": "USD",
  "salePrice": 250000,
  "rentPrice": null,
  "minPrice": 180000,
  "maxPrice": 320000,
  "bedrooms": 2,
  "bathrooms": 2.5,
  "parkingSpots": 1,
  "builtArea": 110,
  "lotArea": 0,
  "status": "published",
  "image": "https://cdn.flowestate.app/...",
  "unitCount": 24,
  "createdAt": "2025-08-01T12:00:00.000Z",
  "updatedAt": "2026-04-29T12:00:00.000Z"
}
```

***

## Crear un proyecto

```http theme={null}
POST /projects
```

**Scope:** `projects:write`.

### Request body

Solo `name` es requerido. Puedes incluir un array `units[]` opcional para crear unidades iniciales en la misma llamada.

```json theme={null}
{
  "name": "Bavarian Forest",
  "type": "residential",
  "promotora": "Acme Developers",
  "city": "Punta Cana",
  "address": "Av. Estados Unidos #1",
  "description": "...",
  "country": "DO",
  "state": "La Altagracia",
  "operationType": "sale",
  "currency": "USD",
  "salePrice": 250000,
  "rentPrice": null,
  "bedrooms": 2,
  "bathrooms": 2.5,
  "parkingSpots": 1,
  "builtArea": 110,
  "lotArea": 0,
  "status": "draft",
  "units": [
    { "name": "A-101", "type": "apartment", "price": 250000, "area": 110, "status": "available" }
  ]
}
```

`status`: `draft` | `published` | `archived` (default `draft`).

### Response 201

```json theme={null}
{
  "id": "proj_...",
  "name": "Bavarian Forest",
  "type": "residential",
  "city": "Punta Cana",
  "status": "draft",
  "unitCount": 1,
  "createdAt": "2026-04-29T18:04:15.000Z"
}
```

### Efectos secundarios de webhooks

Se dispara un evento `project.created`. Si se proveyó `units[]`, también se dispara un `unit.created` por cada unidad.

***

## Obtener un proyecto

```http theme={null}
GET /projects/{projectId}
```

**Scope:** `projects:read`. Incluye el array embebido `units[]` con id, nombre, tipo, precio, área, estado y timestamps de cada unidad.

***

## Actualizar un proyecto

```http theme={null}
PUT /projects/{projectId}
```

**Scope:** `projects:write`. Todos los campos opcionales, debe proveerse al menos uno.

### Efectos secundarios de webhooks

Se dispara un evento `project.updated`.

***

## Eliminar un proyecto

```http theme={null}
DELETE /projects/{projectId}
```

**Scope:** `projects:write`.

<Warning>Eliminar un proyecto también elimina todas sus unidades. Esto es irreversible.</Warning>

### Response 200

```json theme={null}
{ "deleted": true, "id": "proj_..." }
```

### Efectos secundarios de webhooks

Se dispara un evento `project.deleted`.