Cómo buscar en todos los módulos de Zoho Desk

La búsqueda en todos los módulos de Zoho Desk se realiza mediante un único endpoint de API que consulta tickets, contactos, cuentas, tareas y más en una sola llamada, siempre que tu token OAuth incluya el scope de búsqueda correcto.

Por qué esto es importante

Cuando los agentes de soporte o las integraciones necesitan localizar un registro sin saber en qué módulo se encuentra, la búsqueda módulo por módulo es lenta y propensa a errores. Zoho Desk expone una operación de búsqueda entre módulos dedicada para que puedas recuperar registros coincidentes de todas las áreas relevantes de tu helpdesk en un único viaje de ida y vuelta. Esto es especialmente útil en flujos de trabajo automatizados, chatbots o portales personalizados construidos sobre la API de Zoho Desk.

Paso a paso

Paso 1. Confirma que tu aplicación OAuth incluye el scope Desk.search.READ. Sin él, el endpoint de búsqueda devolverá un error de autorización. Este scope se sitúa junto a los demás scopes de Desk, como Desk.tickets.READ, Desk.contacts.READ y Desk.articles.READ, todos los cuales también pueden ser necesarios según los módulos de los que quieras obtener resultados. ^[1]

Paso 2. Solicita (o renueva) un token de acceso OAuth que incluya Desk.search.READ entre sus scopes concedidos. Si estás creando una integración de múltiples aplicaciones que también utiliza Zoho CRM, combina los scopes de Desk con los de CRM en una única solicitud de autorización para que solo necesites un token. ^[1][3]

Paso 3. Realiza una solicitud HTTP GET al endpoint de la API de Zoho Desk /api/v1/search, pasando los parámetros de consulta en la solicitud. La operación se identifica internamente como searchacrossmodules. ^[2]

GET https://desk.zoho.com/api/v1/search
Authorization: Zoho-oauthtoken <your_access_token>

Paso 4. Proporciona tu término de búsqueda y cualquier filtro opcional como parámetros de cadena de consulta (representados como el diccionario p en el wrapper de la API). Como mínimo, normalmente pasarás un parámetro word o searchStr que contenga el texto que deseas encontrar. ^[2]

Paso 5. Analiza la respuesta JSON. Los resultados están agrupados por módulo, por lo que tu código debe iterar sobre las claves del objeto devuelto (p. ej., tickets, contacts, accounts) para mostrar los registros relevantes al usuario o al sistema receptor. ^[2]

Paso 6. Si estás integrando esto dentro de un asistente conversacional o una interfaz de chat, la herramienta puede invocarse dinámicamente cuando un usuario hace una pregunta que hace referencia a sus datos de Desk. La capa del asistente llama a searchacrossmodules y luego formatea los resultados en una respuesta legible para el usuario. ^[4][7]

Errores comunes

• Scope ausente en el momento de generación del token. El scope Desk.search.READ debe estar presente cuando el token OAuth se *crea por primera vez*. Añadirlo a tu configuración después del hecho no tiene ningún efecto hasta que el usuario vuelva a autorizar. Verifica tu lista de scopes antes de pasar a producción. ^[1][3]

• URL base del centro de datos incorrecto. Zoho Desk está alojado en múltiples centros de datos (com, eu, in, com.au, etc.). Asegúrate de que la URL base que utilizas coincida con el centro de datos donde se creó el portal; de lo contrario, recibirás una redirección o un error 404. ^[7]

• Conflictos de scopes en integraciones combinadas. Si tu aplicación también se conecta a Zoho CRM, la cadena de scopes combinada debe construirse con cuidado: los scopes de Desk y los de CRM se concatenan juntos. Un error de formato (p. ej., una coma faltante o un espacio al final) puede eliminar scopes del token de forma silenciosa. ^[1][3]

• Errores de API que se manifiestan como errores de herramienta. Si Zoho rechaza la solicitud (por ejemplo, debido a un token caducado o un parámetro mal formado), la respuesta contendrá un campo error en lugar de resultados. Implementa lógica de manejo de errores que detecte esto y solicite al usuario que corrija los parámetros o reintente la llamada. ^[6]

Qué verificar

• El scope está presente en el token activo — decodifica tu token de acceso o inspecciona la concesión OAuth para confirmar que Desk.search.READ aparece en la lista de scopes antes de realizar la primera llamada. ^[1]
• La ruta del endpoint y la URL del centro de datos son correctas — verifica que tu URL base coincida con el centro de datos del portal y que la ruta sea exactamente /api/v1/search. ^[2][7]
• La respuesta contiene resultados para los módulos esperados — ejecuta una consulta de prueba para un registro conocido y confirma que el módulo que esperas (p. ej., tickets o contacts) aparece en el payload de la respuesta. ^[2]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho. Consulta siempre la documentación de la API de Zoho Desk para conocer las especificaciones más recientes de scopes y endpoints.*