Calendario - FlowEstate Developers

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.

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

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

curl https://panel.flowestate.app/api/v1/calendar/timezone \
  -H "Authorization: Bearer fe_k_tu_key_aqui"

Response 200

{ "timezone": "America/Panama" }

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

Listar eventos

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

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

{
  "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

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

{
  "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.

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

{
  "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

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

{
  "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

{
  "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

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

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

{ "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.

​Obtener la zona horaria del calendario

​Request

​Response 200

​Listar eventos

​Query parameters

​Request

​Response 200

​Campos del evento

​Errores comunes

​Agendar una reunión

​Request body

​Response 201

​Errores comunes

​Efectos secundarios de webhooks

​Actualizar un evento

​Request body

​Response 200

​Errores comunes

​Eliminar un evento

​Query parameters

​Request

​Response 200

​Errores comunes

Obtener la zona horaria del calendario

Request

Response 200

Listar eventos

Query parameters

Request

Response 200

Campos del evento

Errores comunes

Agendar una reunión

Request body

Response 201

Errores comunes

Efectos secundarios de webhooks

Actualizar un evento

Request body

Response 200

Errores comunes

Eliminar un evento

Query parameters

Request

Response 200

Errores comunes