Google Calendar

Del lado de Google está la lista de calendarios de un usuario: un calendario principal, los calendarios secundarios que le pertenecen, los calendarios que otros comparten con él y la información de disponibilidad (libre/ocupado) que Google expone para cada uno. Los eventos tienen inicio y fin, zona horaria, asistentes con su estado de respuesta, una ubicación o un enlace de videollamada, una regla de recurrencia y un ajuste de visibilidad. Del lado de AppBO está un calendario de reservas: a quién se puede reservar, con qué duración de horario, dentro de qué horario laboral, con qué márgenes, anticipación mínima y límite diario, asociado a un usuario y a los flujos de trabajo que confirman, recuerdan y dan seguimiento.

Los conectas porque un calendario de reservas solo es tan bueno como su visión de la realidad. Un horario que se ofrece cuando la persona ya tiene otro compromiso es peor que no ofrecer ningún horario. Conectados en ambas direcciones, la plataforma lee Google para saber cuándo una persona no está disponible, y escribe de vuelta para que todo lo que se reserve en la plataforma aparezca donde esa persona de verdad mira. Su calendario se vuelve el único lugar donde maneja su día; la plataforma se vuelve el único lugar donde los prospectos lo reservan.

La conexión es por usuario, no por subcuenta, y ese detalle define todo lo demás. Cada miembro del equipo autoriza su propia cuenta de Google y la plataforma guarda un token para ese usuario. Es sencillo para alguien que trabaja solo y es cuestión de disciplina para un equipo. La única persona que nunca terminó de autorizar se vuelve la única persona cuyas reservas dobles nadie puede explicar.

1. Decide qué cuenta de Google va a conectar cada miembro del equipo. Se pueden conectar tanto una cuenta personal como una de Workspace, pero la disponibilidad solo es tan confiable como la cuenta que tiene los compromisos reales.
2. Confirma que el perfil del usuario en AppBO tenga el email correcto y, sobre todo, la zona horaria correcta. Una zona horaria que no coincide entre el perfil del usuario, el calendario de reservas y el calendario de Google es la causa más común de horarios que aparecen a la hora equivocada.
3. Abre la sección de integraciones de la subcuenta, o la configuración de calendario en el perfil del propio usuario, e inicia la conexión con Google. El nombre exacto del menú cambia entre versiones de la plataforma. Busca el panel de calendario o de integraciones y, si el texto es distinto, compáralo con la documentación vigente de la plataforma.
4. Completa la pantalla de consentimiento OAuth de Google con la sesión iniciada como ese usuario. Revisa los permisos que se piden en la propia pantalla y otórgalos; no supongas un texto de alcance (scope) en particular, porque cambian y la pantalla de consentimiento es la lista oficial.
5. Si la cuenta es de Workspace y está bajo control de un administrador, revisa si el acceso de aplicaciones de terceros está restringido. Puede que un administrador tenga que permitir la aplicación antes de que la pantalla de consentimiento funcione para cualquier persona del dominio.
6. Una vez conectada, elige los calendarios que se leen para revisar choques. Selecciona todos los calendarios que tengan compromisos reales, incluidos los calendarios compartidos del equipo y cualquier calendario personal que la persona de verdad use.
7. Elige el único calendario donde escribe la plataforma. Solo un calendario de destino debe recibir las reservas creadas por la plataforma; escribir en varios crea duplicados que después se leen como choques.
8. Define a propósito la dirección de la sincronización. En ambas direcciones significa leer choques y escribir reservas. Solo lectura conviene para una persona cuyas reservas tienen que quedarse en otro sistema.
9. Configura el calendario de reservas: duración del horario, horario laboral por día de la semana, margen antes y después, anticipación mínima, máximo de días hacia adelante y el límite diario o semanal.
10. En un calendario de equipo, define la regla de distribución (rotativo (round-robin), ponderación por prioridad o distribución pareja) y confirma que cada usuario asignado completó su propia autorización de Google. Un usuario sin autorizar dentro de la rotación se va a ofrecer sin revisión de choques.
11. Decide qué contiene el evento que se escribe: el patrón del título, la descripción, si el contacto se agrega como invitado en Google y si se genera un enlace de videollamada.
12. Verifica la dirección de lectura. Crea un evento de prueba directamente en Google en un horario que la página de reservas está ofreciendo, espera la sincronización, recarga la página de reservas y confirma que el horario desapareció.
13. Verifica la dirección de escritura. Reserva una cita de prueba en la página de reservas y confirma que aparece en el calendario de Google elegido con la hora, la zona horaria y los asistentes correctos.
14. Verifica los caminos de edición y cancelación. Reagenda la reserva de prueba en la plataforma y confirma que Google la sigue; cancélala en Google y confirma que la plataforma refleja la cancelación.
15. Confirma que los flujos de notificación se dispararon para la reserva de prueba (confirmación, recordatorio y cualquier alerta interna) y después borra los datos de prueba.
16. Registra qué usuario conectó qué cuenta y en qué fecha, para que un token vencido más adelante tenga un responsable en lugar de convertirse en un misterio.

De la plataforma a Google

• Creación de un evento por cada cita reservada en un calendario conectado, escrito en el único calendario de destino elegido.
• Hora de inicio y de fin, calculadas a partir del horario y de la zona horaria del calendario de reservas.
• Título del evento armado con el patrón de título del calendario, que normalmente combina el nombre del servicio y el nombre del contacto.
• Descripción del evento, que por lo general incluye el teléfono y el email del contacto, las respuestas a las preguntas del formulario de reserva y un enlace de vuelta a la ficha del contacto.
• Asistentes, cuando el calendario está configurado para agregar al contacto como invitado en Google, que es lo que permite que Google envíe su propia invitación.
• Enlace de videollamada, cuando el calendario está configurado para generarlo.
• Actualizaciones y eliminaciones cuando una cita se reagenda o se cancela en la plataforma.

De Google a la plataforma

• Intervalos ocupados de cada calendario seleccionado para revisar choques, que quitan horarios de la página de reservas.
• Cambios en los eventos creados por la plataforma: una hora de inicio movida en Google o el evento borrado, que regresan como una reagenda o una cancelación.
• Estado de respuesta de los asistentes en los eventos creados por la plataforma, cuando la plataforma lo muestra.
• La propia lista de calendarios, para que elijas cuáles leer y en cuál escribir.

Lo que no se mueve

• Eventos históricos anteriores a la conexión. Nada se carga hacia atrás; solo se toma en cuenta el tiempo ocupado de ahí en adelante.
• Los eventos creados directamente en Google no se convierten en citas en la ficha de un contacto. Bloquean tiempo; no crean datos en el CRM.
• Google Tasks, las notas de Keep y los recordatorios. Solo los eventos de calendario entran en el alcance.
• Las listas de invitados de eventos de terceros. La revisión de choques lee el tiempo ocupado, no quién más está en la reunión.
• La configuración de notificaciones propia de Google. Los recordatorios de Google y los de la plataforma son sistemas separados y se van a disparar los dos a menos que apagues uno.
• Las excepciones de eventos recurrentes con total fidelidad. Trata la recurrencia compleja como solo lectura y verifica el comportamiento antes de depender de ella.

Escenario: un prospecto reserva una consulta desde un calendario de equipo rotativo, al vendedor asignado le surge un choque y la reserva se reagenda.

1. Un prospecto envía un formulario y un flujo de trabajo le manda el enlace de reserva del calendario de consultas de dos personas.
2. La página de reservas carga y la plataforma pide el tiempo ocupado de los calendarios de Google conectados de los dos vendedores para el rango de fechas visible.
3. El vendedor A tiene una cita personal el jueves por la mañana en un calendario secundario que se incluyó en la revisión de choques. Esos horarios se quitan de la disponibilidad que se ofrece para el vendedor A.
4. El vendedor B está libre el jueves por la mañana, así que el horario se sigue ofreciendo y la regla rotativa se lo asigna al vendedor B.
5. El prospecto elige el jueves a las diez y envía el formulario de reserva, respondiendo una pregunta de calificación.
6. La plataforma crea la cita en la ficha del contacto, se la asigna al vendedor B y escribe un evento en el calendario de Google elegido por el vendedor B, con el nombre del contacto en el título, el teléfono y la respuesta del formulario en la descripción, y el contacto agregado como invitado.
7. Google le envía su invitación al prospecto, que la acepta. El estado de la respuesta aparece en el evento.
8. Un flujo de AppBO que se dispara cuando se reserva una cita envía un email de confirmación con la marca del negocio y programa un recordatorio para la noche anterior y un SMS dos horas antes.
9. El miércoles, el vendedor B acepta una reunión con un cliente que se encima y mueve el evento de la consulta una hora más tarde directamente en Google.
10. El cambio se sincroniza de vuelta. La plataforma actualiza la hora de la cita y el flujo de recordatorios se recalcula para que los recordatorios se disparen según la hora nueva y no la original.
11. El prospecto recibe una confirmación actualizada. El horario del jueves a las diez vuelve a estar disponible en la página de reservas, y ahora el de las once está bloqueado.
12. Llega el jueves, la reunión se hace y el vendedor B marca el resultado de la cita en la plataforma. Un flujo de seguimiento se dispara con ese cambio de estado y la oportunidad avanza.

Límites de uso

Google aplica cuotas por proyecto y por usuario a su API de Calendar, y una subcuenta con mucho movimiento, muchos usuarios conectados y páginas de reservas con mucho tráfico comparte ese presupuesto. El síntoma es una disponibilidad desactualizada, no un mensaje de error: la página de reservas muestra horarios que se ocuparon hace una hora. Google publica las cifras vigentes de cuotas en su documentación de la API y muestra el consumo en la consola de Cloud: revisa ahí en lugar de suponer un número.

Reintentos e idempotencia

Las operaciones de escritura se reintentan cuando hay una falla pasajera, y un reintento que funciona después de un tiempo de espera agotado puede dejar dos eventos para una sola reserva. Si creas los eventos tú mismo mediante la API en lugar de usar la conexión nativa, envía tu propio identificador de evento para que una repetición sea una actualización y no una inserción. Del lado de la plataforma, toma la cita reservada como ancla de idempotencia: un flujo de trabajo que puede correr dos veces sobre la misma cita va a enviar dos confirmaciones, así que protégelo con una etiqueta o una revisión de campo.

Trampas al mapear campos

La zona horaria es la trampa que importa. El perfil del usuario, el calendario de reservas, el calendario de Google y el contacto pueden tener cada uno una zona distinta, y la página de reservas se muestra en la del visitante. Verifica reservando a través de un límite de zona en lugar de razonarlo en abstracto. Los títulos y descripciones de eventos armados con campos combinados muestran el marcador literal cuando el campo está vacío, así que dale un valor por defecto a cada campo combinado. Agregar al contacto como invitado en Google significa que Google le escribe directamente, y ese email puede llegar antes que tu confirmación con marca o en lugar de ella: decide qué sistema es responsable de ese mensaje.

Creación de duplicados

Los duplicados vienen de tres lugares: un usuario que conecta dos cuentas de Google que comparten eventos; un calendario de destino que también está seleccionado para leer choques, así que el propio evento de la plataforma bloquea el horario que acaba de ocupar; y un segundo calendario de la plataforma que escribe en el mismo calendario de Google. Deja un solo destino de escritura por usuario y no excluyas nada de la lectura de choques salvo ese destino de escritura, si la plataforma lo permite.

Pruebas contra producción

No existe un calendario de pruebas. Prueba contra un calendario de Google desechable en una cuenta real y borra los eventos de prueba después, porque los bloques de prueba que quedan quitan disponibilidad real sin avisar.

Vencimiento de la autenticación

Los tokens vencen. Un cambio de contraseña, un permiso de aplicación revocado en la configuración de seguridad de la cuenta de Google, un administrador que restringe el acceso de terceros o mucho tiempo sin actividad pueden romper la conexión, y por lo general la falla es silenciosa. La página de reservas sigue funcionando y simplemente deja de revisar choques. Hazte el hábito de revisar periódicamente el estado de la conexión de cada usuario, y vuelve a autorizar en lugar de buscar el problema en otro lado cuando la disponibilidad se vea mal.

Lo que se rompe con más frecuencia

• Un miembro del equipo nuevo agregado a un calendario rotativo sin conectar su propia cuenta de Google, así que se le ofrece cada horario dentro de su horario laboral.
• Alguien que marca un bloque como libre en lugar de ocupado en Google, lo que lo vuelve invisible para la revisión de choques.
• Eventos de todo el día y de varios días que se comportan distinto a los que tienen hora; verifica cómo los trata tu configuración.
• Eventos recurrentes cuyas excepciones individuales no se propagan como se espera.
• Márgenes configurados en el calendario de reservas que no se toman en cuenta en las demás reservas de la persona, lo que produce reuniones seguidas sin tiempo de traslado.
• Los emails de invitación propios de Google, que confunden a los contactos que también reciben una confirmación de la plataforma con otro enlace para reagendar.
• Un calendario compartido con permisos de solo lectura, que bloquea la dirección de escritura sin avisar.