Saltar al contenido principal
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

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

Response 200

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

Listar eventos

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

Request

Response 200

Campos del evento

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

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

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

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

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

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

Response 200

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

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

Request

Response 200

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.