Cómo recuperar las preferencias de citas en Zoho

Recuperar las preferencias de citas en Zoho CRM es sencillo mediante un único endpoint de la API de configuración que devuelve la configuración de programación de tu organización en una sola llamada.

Por qué esto es importante

Cuando construyes integraciones o automatizaciones en torno a las funciones de programación de Zoho CRM, a menudo necesitas leer las preferencias de citas actuales de forma programática — por ejemplo, para validar reglas de reserva, sincronizar ventanas de disponibilidad o auditar cambios de configuración. Conocer el endpoint exacto y cómo conectarlo a un cliente autenticado ahorra un tiempo considerable de prueba y error. Como siempre, Beam Help es soporte experto independiente para Zoho y no es el soporte oficial de Zoho.

Paso a paso

Paso 1. Asegúrate de que tu conexión OAuth de Zoho CRM esté activa y de que tu token de acceso sea válido. La capa de la API gestiona la renovación del token automáticamente buscando el refreshtoken almacenado, llamando al endpoint de renovación OAuth y guardando el nuevo accesstoken en tu base de datos antes de realizar cualquier solicitud posterior. ^[3]

Paso 2. Confirma que tus scopes de OAuth incluyen los permisos de configuración de CRM necesarios. Tu configuración de scopes debe cubrir ZohoCRM.settings o el scope más amplio ZohoCRM.org.ALL para que el endpoint de configuración sea accesible. Sin los scopes correctos, la solicitud será rechazada antes de llegar al servidor. ^[2]

Paso 3. Instancia tu cliente de la API de Zoho CRM utilizando la conexión autenticada para el usuario objetivo. Pasa app_type="crm" al llamar a tu función de fábrica de la API para que se inicialice la clase de cliente correcta en lugar de la variante de Desk. ^[3]

Paso 4. Llama al endpoint de preferencias de citas. Emite una solicitud HTTP GET a /settings/appointment_preferences usando la versión 6 de la API. En Python, esto se ve así: ^[1]

def get_appointment_preferences(self):
    return self.c.request("GET", "/settings/appointment_preferences", version=6)

El método delega en tu cliente HTTP subyacente (self.c), que adjunta el token bearer y enruta automáticamente al dominio del centro de datos correcto. ^[1]

Paso 5. Analiza la respuesta. El endpoint devuelve un payload JSON que contiene la configuración de preferencias de citas de tu organización. Inspecciona el diccionario devuelto en busca de los campos relevantes para tu caso de uso — reglas de disponibilidad, ventanas de reserva o configuración de notificaciones — y gestiona cualquier clave de error antes de continuar. ^[1]

Endpoints de configuración relacionados

Si necesitas recuperar otras categorías de preferencias junto con los datos de citas, dos endpoints hermanos siguen el mismo patrón y versión:

• Preferencias de llamadas — GET /settings/telephony (operación: getcallpreferences) ^[4]
• Preferencias de servicios — GET /settings/servicepreferences (operación: getservice_preferences) ^[5]

Los tres usan la versión 6 de la API y el mismo cliente autenticado, por lo que puedes agruparlos en una sola sesión sin necesidad de volver a autenticarte.

Errores comunes

• Tokens de acceso caducados. Si el token ha expirado y la lógica de renovación falla (por ejemplo, porque la fila refreshtoken no existe en tu base de datos), getzoho_api devuelve None y la llamada de configuración nunca se ejecutará. Comprueba siempre que el objeto API devuelto no sea None antes de invocar cualquier método sobre él. ^[3]
• apptype incorrecto. Pasar apptype="desk" inicializará un ZohoDeskClient en lugar del cliente de CRM, y la ruta /settings/appointment_preferences no existirá en ese cliente, lo que resultará en un confuso error 404 o de atributo. ^[3]
• Scopes insuficientes. Si tu aplicación OAuth fue autorizada con un conjunto mínimo de scopes que excluye los scopes de organización o configuración de CRM, la API devolverá un error de autorización. Vuelve a autorizar la conexión incluyendo el scope completo ZohoCRM.org.ALL. ^[2]

Qué verificar

• Validez del token — confirma que el accesstoken almacenado no ha expirado y que la función tokenrefresher puede obtener correctamente uno nuevo desde tu tabla zoho_connections. ^[3]
• Cobertura de scopes — verifica que ZohoCRM.org.ALL o un scope de configuración equivalente esté presente en la lista de scopes autorizados de tu cliente OAuth. ^[2]
• Versión de la API — asegúrate de que la solicitud especifique explícitamente la versión 6, ya que el endpoint /settings/appointment_preferences está definido para esa versión y puede no resolverse correctamente en versiones anteriores. ^[1]