Conectar Google Calendar y gestionar citas por API

Pasos

1. 1Consulta GET /api/v1/core/platforms/?search=Google y selecciona Google Calendar. No uses Google Workspace (Gmail) ni Google (Gemini).
2. 2Envía POST /api/v1/resource-connectors/oauth2/start/ con X-API-Key y body {"platform_id":"<calendar_platform_id>"}. Entrega data.authorize_url al usuario; expires_in indica su vigencia, actualmente 600 segundos.
3. 3El usuario elige su cuenta y permisos en Google. El callback crea un recurso de Google Calendar para el usuario y organización que generaron el enlace. Una conexión de Gmail no obtiene acceso a Calendar automáticamente.
4. 4Consulta GET /api/v1/resource-connectors/ y guarda el ID del recurso. Descubre las acciones con GET /api/v1/tools/?category=all&platform=<calendar_platform_id>; consulta sus inputs antes de ejecutar.
5. 5Prueba primero Listar calendarios y Listar eventos. Para ejecutar usa POST /api/v1/tools/<tool_id>/execute/ con resource_connection_id y los inputs. Este endpoint es de simulación de Pulbot, pero puede operar sobre Google real.

Referencia

Permisos de Pulbot

tool:write para generar el enlace y flow:simulate para ejecutar herramientas; las capacidades de organización se evalúan aparte. MCP es opcional: start_connector_oauth2 funciona con el ID de Calendar cuando esté desplegado.

calendar.calendarlist.readonly

Solicitado por defecto para listar calendarios.

calendar.events.readonly

Solicitado por defecto para leer eventos. Solicitado no significa concedido: se registra el scope devuelto por Google.

calendar.events

Opcional para crear, modificar y eliminar eventos. Se superpone con lectura; el usuario puede autorizar gestión o solo lectura según el consentimiento de Google.

calendar.events.freebusy

Opcional para consultar intervalos ocupados. Permiso específico porque calendar.events.readonly y calendar.events no equivalen automáticamente a autorización del endpoint freeBusy.

scopes_extra

Omitido/null: presenta los cuatro scopes configurados en Google. []: solo los dos predeterminados. No solicita acceso completo calendar ni permisos de Gmail. El proveedor controla agrupación y autorizaciones previas.

Herramientas disponibles en código

Google Calendar - Listar calendarios; Listar eventos; Obtener evento; Consultar disponibilidad; Crear evento; Modificar evento; Eliminar evento. Los nombres completos llevan el prefijo Google Calendar - y sus IDs se obtienen del catálogo, no son fijos.

Calendario y paginación

calendar_id es primary si se omite. Para otro calendario usa su ID, codificando caracteres reservados de URL. Listar calendarios y eventos conserva nextPageToken; pásalo como pageToken. Los campos opcionales vacíos no se añaden al query.

Ejemplo: consultar eventos

{"resource_connection_id":"<connector_id>","calendar_id":"primary","timeMin":"2026-11-03T00:00:00-04:00","timeMax":"2026-11-04T00:00:00-04:00","timeZone":"America/Caracas","singleEvents":true,"orderBy":"startTime"}

Ejemplo: disponibilidad

{"resource_connection_id":"<connector_id>","time_min":"2026-11-03T13:00:00Z","time_max":"2026-11-03T18:00:00Z","time_zone":"America/Caracas","calendars":[{"id":"primary"}]}

Ejemplo: crear cita

{"resource_connection_id":"<connector_id>","calendar_id":"primary","sendUpdates":"none","event":{"id":"appt20261103001","summary":"Cita de prueba","start":{"dateTime":"2026-11-03T09:00:00-04:00","timeZone":"America/Caracas"},"end":{"dateTime":"2026-11-03T09:30:00-04:00","timeZone":"America/Caracas"}}}

Fechas y zona horaria

Usa dateTime RFC3339 con offset y timeZone IANA. Para día completo usa start.date y end.date; el fin es exclusivo. Para recurrencias especifica zona horaria y recurrence en event. Pulbot transmite el objeto; Google valida coherencia y permisos.

Modificar y eliminar

Modificar evento recibe calendar_id, event_id y changes (objeto parcial). Los arrays enviados reemplazan su contenido completo. Puedes enviar If-Match con el etag leído. Eliminar evento recibe calendar_id y event_id; un resultado status_code 204 sin JSON significa éxito.

Invitados y avisos

event.attendees permite especificar invitados. sendUpdates acepta none (predeterminado), all o externalOnly. all puede enviar invitaciones y avisos reales; none no garantiza que Google no envíe ningún correo. No agregues asistentes en pruebas sin autorización.

Reintentos e idempotencia

Incluye event.id estable por operación: 5–1024 caracteres base32hex (a–v, 0–9). Ante timeout consulta ese ID antes de repetir; ante 409 concilia el evento existente. No se añadió una cabecera de idempotencia propia de Pulbot ni validación local del contenido de event.

Configuración del operador

Habilita Calendar API en Google Cloud y configura el consentimiento para estos scopes. Se reutilizan GOOGLE_WORKSPACE_CLIENT_ID y GOOGLE_WORKSPACE_CLIENT_SECRET del backend, no el cliente de Google Sign-In. Calendar no consulta el perfil Gmail. Deben coincidir los redirect URI del entorno.

Estado de validación

Las siete acciones se probaron con el intérprete HTTP real y respuestas simuladas: filtros, paginación, cuerpos estructurados, zonas horarias, 403, 204, etags y renovación de token. El recorrido con Google real, consentimiento, despliegue y operaciones de la cuenta del usuario siguen pendientes.

Errores comunes

403

Puede indicar scopes no concedidos o acceso insuficiente al calendario. freeBusy además exige su permiso específico.

409 / 412

409 al crear: consulta event.id y concilia. 412: etag cambió; vuelve a leer antes de modificar o eliminar.

Disponibilidad

HTTP 200 puede incluir calendars.<id>.errors. Revisa errores por calendario antes de ofrecer un horario. Consultar disponibilidad no reserva la cita ni evita carreras.

401 / invalid_state

Revisa credenciales de Pulbot, renovación del token o vigencia del enlace. Genera otro enlace si el estado venció o ya se consumió.

Siguiente paso

Continúa con API → Integrar un asistente para combinar Calendar, Gmail y WhatsApp. No anuncies producción hasta comprobar el recorrido real con cuentas de prueba.