> ## 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.

# Unidades

> Unidades individuales dentro de un proyecto. Rastrea disponibilidad con estado: available / reserved / sold.

Las unidades siempre pertenecen a un proyecto. Todos los endpoints están scopeados bajo `/projects/{projectId}/units`.

***

## Listar unidades

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

**Scope:** `projects:read`. Devuelve todas las unidades del proyecto. Devuelve `404 NOT_FOUND` si el proyecto no existe o pertenece a otra organización.

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": "unit_...",
      "projectId": "proj_...",
      "name": "A-101",
      "type": "apartment",
      "price": 250000,
      "area": 110,
      "status": "available",
      "createdAt": "2025-09-01T12:00:00.000Z",
      "updatedAt": "2026-04-29T12:00:00.000Z"
    }
  ]
}
```

***

## Crear una unidad

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

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

### Request body

```json theme={null}
{
  "name": "A-101",
  "type": "apartment",
  "price": 250000,
  "area": 110,
  "status": "available"
}
```

| Campo    | Requerido | Notas                                      |
| -------- | --------- | ------------------------------------------ |
| `name`   | sí        | Texto libre, ≤ 255 caracteres.             |
| `price`  | sí        | Entero, en la moneda del proyecto.         |
| `type`   | no        | Texto libre, ≤ 100 caracteres.             |
| `area`   | no        | Entero (metros cuadrados).                 |
| `status` | no        | `available` (default), `reserved`, `sold`. |

### Response 201

Devuelve la unidad creada con todos sus campos.

### Efectos secundarios de webhooks

Se dispara un evento `unit.created`.

***

## Actualizar una unidad

```http theme={null}
PATCH /projects/{projectId}/units/{unitId}
```

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

### Request body

Mismos campos que crear. Pasa `null` para limpiar campos nullable, omítelos para dejarlos intactos.

### Response 200

Devuelve la unidad actualizada.

### Efectos secundarios de webhooks

* Siempre: `unit.updated`.
* Si cambió `status`: `unit.status_changed`. El payload incluye tanto la unidad como su proyecto padre, así los receptores no necesitan una segunda llamada al API para saber qué se vendió.

<Tip>El evento `unit.status_changed` es la señal canónica para **"una unidad acaba de pasar a available / reserved / sold"**. Úsalo para actualizar el inventario de tu sitio web, mandar notificaciones a Slack, o disparar flujos de comisiones.</Tip>