Cómo recuperar las horas de turno en Zoho

Recuperar las horas de turno en Zoho CRM es sencillo una vez que tu conexión OAuth está establecida: una sola llamada a la API del endpoint de configuración devuelve toda la configuración de horas de turno de tu organización.

Por qué esto es importante

Los horarios comerciales y los calendarios de turnos impulsan los cálculos de SLA, los disparadores de automatización y las ventanas de disponibilidad de soporte dentro de Zoho CRM. Si estás creando una integración o auditando tu configuración de CRM de forma programática, necesitas una manera confiable de extraer estos datos sin navegar manualmente por la interfaz. Comprender la llamada a la API subyacente también ayuda al solucionar discrepancias entre el comportamiento esperado y el real en cuanto a horarios comerciales.

Paso a paso

Paso 1. Asegúrate de que existe una conexión OAuth válida para el usuario.

Antes de que cualquier llamada a la API pueda tener éxito, tu aplicación debe contar con un token de acceso activo para la cuenta de Zoho de destino. El registro de conexión se busca por user_id en tu almacén local y, si el token está a menos de 120 segundos de expirar, se actualiza automáticamente antes de que se envíe la solicitud — este margen de actualización anticipada reduce los errores 401 a mitad de solicitud. ^[1]

Paso 2. Instancia el cliente de la API de Zoho CRM.

Usa el helper getzohoapi, pasando el userid correspondiente y especificando "crm" como apptype. Esta función recupera la conexión almacenada, configura un callback token_refresher para una reautenticación fluida y devuelve una instancia ZohoCrmApi lista para usar junto con el registro de conexión. ^[4]

Paso 3. Llama a la herramienta getshifthours.

Con el cliente de la API disponible, invoca getshifthours. Internamente, esto emite una solicitud HTTP GET al endpoint /settings/shift_hours usando la versión 6 de la API. ^[2]

result = api.get_shift_hours()

El método también está expuesto como una herramienta con nombre (getshifthours) dentro del registro de herramientas de CRM, por lo que también puede activarse a través de la ruta de despacho estándar execute_tool. ^[5]

Paso 4. Gestiona la respuesta.

La llamada devuelve el objeto de configuración de horas de turno de Zoho CRM. Analiza el diccionario devuelto para obtener los detalles de programación que necesitas. Si la respuesta contiene una clave "error", verifica primero la validez del token — la capa OAuth devuelve {"error": "No access token in response"} cuando el intercambio o la actualización del token falla. ^[3]

Paso 5. Actualiza los tokens de forma proactiva si ejecutas en un contexto de prueba o por lotes.

Cuando ejecutes múltiples llamadas a la API de forma secuencial (por ejemplo, durante pruebas de integración), vuelve a verificar el valor de tokenexpiresat antes de cada llamada e invoca el token_refresher si el tiempo actual está dentro de la ventana de desfase de 120 segundos. Este patrón evita que una sesión válida expire a mitad del lote. ^[6]

---

Errores comunes

• Registro de conexión obsoleto o inexistente. Si getzohoconnection devuelve None, no se puede realizar ninguna llamada a la API. Verifica que la tabla zohoconnections contenga una fila para el userid de destino antes de continuar. ^[1]

• apptype incorrecto pasado a getzohoapi. Pasar "desk" en lugar de "crm" enrutará la solicitud a través del cliente de Zoho Desk, que no expone el endpoint /settings/shifthours. Usa siempre "crm" para esta operación. ^[4]

• Incompatibilidad de versión de la API. La implementación de getshifthours apunta explícitamente a la versión 6 de la API de Zoho CRM. Sobrescribir la versión en un wrapper de cliente personalizado puede resultar en un error 404 o en un esquema de respuesta inesperado. ^[2]

• Permisos de OAuth insuficientes. Al token de acceso se le debe haber otorgado el alcance de configuración de CRM adecuado durante el flujo de autorización inicial. Si el token fue emitido sin permisos de lectura de configuración, el endpoint devolverá un error de autorización aunque el token en sí sea válido. ^[7]

---

Qué verificar

• Vigencia del token: Confirma que tokenexpiresat en tu registro de conexión esté en el futuro (teniendo en cuenta el desfase de 120 segundos) antes de realizar la llamada. ^[1]
• Endpoint y versión correctos: Verifica que tu cliente apunte a GET /settings/shift_hours en la versión 6 de la API. ^[2]
• Estructura de la respuesta: Asegúrate de que el objeto devuelto no contenga una clave "error"; si la contiene, revisa tus alcances de OAuth y la validez del token de actualización. ^[3]

---

*Beam Help es un recurso de soporte experto independiente para usuarios de Zoho — no somos el soporte oficial de Zoho. Para problemas a nivel de plataforma, consulta siempre la documentación oficial de Zoho.*