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

# Calendario

> Lee la zona horaria de la organización y gestiona los eventos de Google Calendar de un miembro. Agenda reuniones que además registran una actividad en el lead.

La API de Calendario opera sobre el **Google Calendar** conectado de un miembro específico de la organización. Es **member-scoped** (a nivel de miembro): cada lectura o escritura de eventos actúa sobre el calendario `primary` de Google de un solo miembro.

Como las API keys son **org-scoped** (a nivel de organización, no atadas a un usuario), quien llama debe identificar al miembro que actúa con un `userId` en cada llamada de eventos. Ese miembro debe haber conectado Google Calendar dentro de FlowEstate.

> [!NOTE]
>
> **Resolución del miembro.** Para llamadas con API key, `userId` es **requerido** — pasa el id del miembro cuyo calendario se usará. Para llamadas con token OAuth, `userId` es opcional y por defecto es el dueño del token. Si se envía `userId` pero no es miembro de la organización autenticada, la API devuelve `404 INVALID_MEMBER`. Si el miembro resuelto no ha conectado (o desconectó) Google Calendar, la API devuelve `403 FORBIDDEN` con un mensaje para reconectar.

Agendar una reunión respeta las mismas reglas de visibilidad de leads que el resto de la API: un miembro solo puede agendar sobre leads a los que tiene permitido acceder.

***

## Obtener la zona horaria del calendario

```http theme={null}
GET /calendar/timezone
```

**Scope:** `calendar:read`. Devuelve la zona horaria IANA de la organización. Úsala para renderizar e interpretar las horas de reloj locales que aceptan los endpoints de eventos. Esta llamada es org-scoped y no requiere `userId`.

### Request

```bash theme={null}
curl https://panel.flowestate.app/api/v1/calendar/timezone \
  -H "Authorization: Bearer fe_k_tu_key_aqui"
```

### Response 200

```json theme={null}
{ "timezone": "America/Panama" }
```

Cuando la organización no tiene zona horaria configurada, FlowEstate usa `America/Panama` por defecto.

***

## Listar eventos

```http theme={null}
GET /calendar/events
```

**Scope:** `calendar:read`. Lista los eventos del calendario `primary` del miembro que actúa dentro de una ventana de tiempo. Los eventos recurrentes se expanden en instancias individuales y se ordenan por hora de inicio.

### Query parameters

| Parámetro | Requerido | Notas |
| - | - | - |
| `userId` | sí (API key) | El miembro cuyo calendario se lee. Opcional para llamadas OAuth (por defecto, el dueño del token). |
| `timeMin` | sí | Límite inferior, ISO 8601 con offset, ej. `2026-06-20T00:00:00-05:00`. |
| `timeMax` | sí | Límite superior, ISO 8601 con offset, ej. `2026-06-21T00:00:00-05:00`. |

### Request

```bash theme={null}
curl -G https://panel.flowestate.app/api/v1/calendar/events \
  -H "Authorization: Bearer fe_k_tu_key_aqui" \
  --data-urlencode "userId=user_..." \
  --data-urlencode "timeMin=2026-06-20T00:00:00-05:00" \
  --data-urlencode "timeMax=2026-06-21T00:00:00-05:00"
```

### Response 200

```json theme={null}
{
  "events": [
    {
      "id": "abcd1234efgh5678",
      "title": "Reunión con Ada Lovelace",
      "description": "Discutir disponibilidad de unidades",
      "start": "2026-06-20T15:00:00-05:00",
      "end": "2026-06-20T15:30:00-05:00",
      "allDay": false,
      "location": "Oficina de ventas",
      "htmlLink": "https://www.google.com/calendar/event?eid=...",
      "attendees": ["ada@example.com"]
    }
  ]
}
```

### Campos del evento

| Campo | Descripción |
| - | - |
| `id` | Id del evento en Google Calendar. Úsalo en `PATCH` / `DELETE`. |
| `title` | Resumen del evento. Usa `(sin título)` cuando Google no tiene resumen. |
| `description` | Texto libre opcional. Se omite cuando está vacío. |
| `start`, `end` | Datetime ISO 8601, o `YYYY-MM-DD` para eventos de todo el día. |
| `allDay` | `true` para eventos de solo fecha (todo el día). |
| `location` | Opcional. Se omite cuando no está definido. |
| `htmlLink` | Enlace al evento en Google Calendar. Opcional. |
| `attendees` | Arreglo de emails de invitados. Se omite cuando no hay ninguno. |

### Errores comunes

* `400 BAD_REQUEST` — falta `userId` (las llamadas con API key deben enviarlo).
* `400 VALIDATION_ERROR` — falta `timeMin` / `timeMax` o no son ISO 8601 con offset.
* `403 FORBIDDEN` — el miembro no ha conectado Google Calendar, o su autorización expiró. El mensaje le pide reconectar su calendario en FlowEstate.
* `404 INVALID_MEMBER` — `userId` no es miembro de esta organización.

***

## Agendar una reunión

```http theme={null}
POST /calendar/events
```

**Scope:** `calendar:write`. Crea un evento en el calendario `primary` del miembro **y** registra una actividad de tipo `meeting` en la línea de tiempo del lead. El email del lead (cuando existe) se agrega como invitado, y Google envía las invitaciones a todos los invitados.

### Request body

```json theme={null}
{
  "userId": "user_...",
  "leadId": "uuid",
  "startAt": "2026-06-20T15:00",
  "durationMinutes": 30,
  "title": "Reunión con Ada Lovelace",
  "description": "Discutir disponibilidad de unidades"
}
```

| Campo | Requerido | Notas |
| - | - | - |
| `userId` | sí (API key) | El miembro cuyo calendario se usa. Opcional para llamadas OAuth. |
| `leadId` | sí | UUID del lead. Debe ser un lead al que el miembro que actúa pueda acceder. |
| `startAt` | sí | Datetime de reloj local `YYYY-MM-DDTHH:mm` (sin offset). Se interpreta en la **zona horaria de la organización**, así que `15:00` significa las 3pm hora local de la org sin importar la zona de quien llama. |
| `durationMinutes` | sí | Entero, `5`–`600`. La hora de fin se deriva de `startAt` + duración. |
| `title` | no | 1–300 caracteres. Por defecto `Reunión con {nombre del lead}`. |
| `description` | no | ≤ 5000 caracteres. Se guarda como la nota de la actividad de reunión. |

> [!TIP]
>
> Usa `GET /calendar/timezone` para confirmar la zona horaria de la organización, luego envía `startAt` como una hora local naive. No incluyas un offset — el servidor lo añade.

### Response 201

```json theme={null}
{
  "event": {
    "id": "abcd1234efgh5678",
    "title": "Reunión con Ada Lovelace",
    "description": "Discutir disponibilidad de unidades",
    "start": "2026-06-20T15:00:00-05:00",
    "end": "2026-06-20T15:30:00-05:00",
    "allDay": false,
    "htmlLink": "https://www.google.com/calendar/event?eid=...",
    "attendees": ["ada@example.com"]
  },
  "activityId": "act_..."
}
```

`activityId` es el id de la actividad `meeting` registrada en el lead. Puede estar ausente si la actividad no pudo persistirse.

### Errores comunes

* `400 BAD_REQUEST` — falta `userId` (las llamadas con API key deben enviarlo).
* `400 VALIDATION_ERROR` — `leadId` inválido, `startAt` mal formado, o `durationMinutes` fuera de rango.
* `403 FORBIDDEN` — el miembro no ha conectado Google Calendar, o su autorización expiró. El mensaje le pide reconectar su calendario.
* `404 INVALID_MEMBER` — `userId` no es miembro de esta organización.
* `404 NOT_FOUND` — el lead no existe o no es visible para el miembro que actúa.

### Efectos secundarios de webhooks

Se despacha un evento `lead.communication_logged` (un `meeting`, `outbound`), reflejando una comunicación registrada para que las integraciones externas también vean la reunión agendada.

***

## Actualizar un evento

```http theme={null}
PATCH /calendar/events/{eventId}
```

**Scope:** `calendar:write`. Actualiza el evento del miembro. Solo se cambian los campos que envías; los invitados existentes se preservan. Cuando el evento está vinculado a una actividad de reunión de un lead, FlowEstate mantiene la hora y la nota de esa actividad sincronizadas (best effort).

### Request body

```json theme={null}
{
  "userId": "user_...",
  "startAt": "2026-06-20T16:00",
  "durationMinutes": 45,
  "title": "Reunión con Ada Lovelace (reprogramada)",
  "description": "Movida 1 hora más tarde"
}
```

| Campo | Requerido | Notas |
| - | - | - |
| `userId` | sí (API key) | El miembro cuyo calendario se usa. Opcional para llamadas OAuth. |
| `startAt` | sí | Datetime de reloj local `YYYY-MM-DDTHH:mm`, interpretado en la zona horaria de la organización. |
| `durationMinutes` | sí | Entero, `5`–`600`. |
| `title` | sí | 1–300 caracteres. |
| `description` | no | ≤ 5000 caracteres. Cuando se provee, sobrescribe la nota de la actividad vinculada; omítelo para dejar la nota intacta. |

`eventId` viene en la ruta — no lo incluyas en el body.

### Response 200

```json theme={null}
{
  "event": {
    "id": "abcd1234efgh5678",
    "title": "Reunión con Ada Lovelace (reprogramada)",
    "description": "Movida 1 hora más tarde",
    "start": "2026-06-20T16:00:00-05:00",
    "end": "2026-06-20T16:45:00-05:00",
    "allDay": false,
    "htmlLink": "https://www.google.com/calendar/event?eid=...",
    "attendees": ["ada@example.com"]
  }
}
```

### Errores comunes

* `400 BAD_REQUEST` — falta `userId` (las llamadas con API key deben enviarlo).
* `400 VALIDATION_ERROR` — falta `title`, `startAt` mal formado, o `durationMinutes` fuera de rango.
* `403 FORBIDDEN` — el miembro no ha conectado Google Calendar, o su autorización expiró. El mensaje le pide reconectar su calendario.
* `404 INVALID_MEMBER` — `userId` no es miembro de esta organización.

***

## Eliminar un evento

```http theme={null}
DELETE /calendar/events/{eventId}
```

**Scope:** `calendar:write`. Elimina el evento del miembro de Google Calendar y borra la actividad de reunión vinculada al lead, si existe. Eliminar un evento ya eliminado se trata como éxito.

### Query parameters

| Parámetro | Requerido | Notas |
| - | - | - |
| `userId` | sí (API key) | El miembro cuyo calendario se usa. Opcional para llamadas OAuth. |

### Request

```bash theme={null}
curl -X DELETE -G https://panel.flowestate.app/api/v1/calendar/events/abcd1234efgh5678 \
  -H "Authorization: Bearer fe_k_tu_key_aqui" \
  --data-urlencode "userId=user_..."
```

### Response 200

```json theme={null}
{ "success": true }
```

### Errores comunes

* `400 BAD_REQUEST` — falta `userId` (las llamadas con API key deben enviarlo).
* `403 FORBIDDEN` — el miembro no ha conectado Google Calendar, o su autorización expiró. El mensaje le pide reconectar su calendario.
* `404 INVALID_MEMBER` — `userId` no es miembro de esta organización.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.