Cómo recuperar productos en Zoho

Recuperar productos en Zoho CRM requiere una conexión OAuth válida y un token de acceso correctamente actualizado antes de realizar cualquier llamada a la API — así es como nuestro equipo en Beam Help (soporte experto independiente para Zoho, no soporte oficial de Zoho) aborda el proceso de principio a fin.

Por qué esto es importante

Cuando necesitas extraer datos del catálogo de productos de Zoho CRM — para informes, sincronización con un sistema externo o la creación de una integración personalizada — primero debes asegurarte de que tus credenciales OAuth estén activas y de que tu cliente de API esté correctamente inicializado. Un token caducado o ausente bloqueará silenciosamente todas las solicitudes posteriores, por lo que entender el ciclo de vida del token es tan importante como saber qué herramienta utilizar.

Paso a paso

Paso 1. Verifica que existe tu conexión con Zoho.

Antes de intentar recuperar cualquier registro, confirma que existe una fila de conexión para el usuario correspondiente en tu almacén de datos. La función getzohoconnection consulta zohoconnections por userid y devuelve None si no se encuentra ningún registro — si eso ocurre, el usuario debe volver a conectarse antes de continuar. ^[3]

Paso 2. Permite que el sistema actualice el token de acceso automáticamente.

Los tokens de acceso caducan, por lo que la capa de conexión comprueba si el momento actual está dentro de los 120 segundos anteriores a tokenexpiresat. Si es así, se llama a ZohoOAuth.refreshtokens con el refreshtoken almacenado, y el nuevo accesstoken junto con el tokenexpires_at actualizado se escriben de vuelta en la base de datos antes de devolver el objeto de conexión al llamador. ^[3]

Paso 3. Obtén una instancia de la API de Zoho CRM.

Pasa el userid y apptype="crm" a getzohoapi. Internamente, esto llama a getzohoconnection (pasos 1–2) y luego construye el cliente de API usando el apidomain y el accesstoken del registro de conexión. También se configura un callback token_refresher para que los errores 401 durante una solicitud puedan resolverse sin intervención del usuario. ^[1]

Paso 4. Ejecuta la herramienta de recuperación de productos.

Con una instancia de API válida, llama a executetoolwithrepair, pasando el objeto api, apptype="crm", el nombre de tool apropiado para productos y los params de filtro que necesites. El indicador allowrepair=True permite que el sistema intente una corrección automática de parámetros si la primera llamada falla. El resultado se devuelve bajo la clave "result" del diccionario de salida. ^[2]

Paso 5. Gestiona la respuesta y construye los enlaces de navegación.

Una vez que toolresult está poblado, puedes llamar opcionalmente a buildzoholinks con el resultado, el nombre de la herramienta, los parámetros, apptype y los valores dc / crmorgid del registro de conexión. Esto genera URLs directas de "Abrir en Zoho" que puedes mostrar a los usuarios finales junto con los datos de productos. ^[8]

Paso 6. Confirma que los ámbitos OAuth cubren el módulo de Productos.

Cuando se genera por primera vez la URL de autorización OAuth, el parámetro scope se establece a partir de Config.ZOHO_SCOPES. Si el módulo de Productos no estaba incluido en esa cadena de ámbitos en el momento en que el usuario autorizó la aplicación, las llamadas a la API de ese módulo serán rechazadas. Es posible que debas revocar el permiso existente y volver a autorizar con una lista de ámbitos actualizada. ^[5]

Errores comunes

• accesstoken ausente tras la actualización. Si ZohoOAuth.refreshtokens devuelve un diccionario sin la clave "accesstoken", la actualización ha fallado (el método devuelve explícitamente {"error": "No access token in response"} en ese caso). Verifica que tu clientid, clientsecret y refreshtoken sean correctos y no hayan sido revocados. ^[6]
• Discrepancia en apidomain. El apidomain devuelto durante el intercambio inicial del código OAuth (p. ej., https://www.zohoapis.eu) debe almacenarse y reutilizarse en cada llamada posterior a la API. Usar el dominio regional incorrecto provocará errores 404 o de autenticación incluso con un token válido. ^[5]
• Confusión con el orgid de Desk. Si accidentalmente pasas apptype="desk" en lugar de "crm", el sistema intentará inicializar un ZohoDeskClient y buscar un ID de organización de Desk — una ruta de código completamente diferente que no llegará al módulo de Productos de CRM. ^[1]
• Colisiones en solicitudes concurrentes. El endpoint de chat utiliza un token de concurrencia (release_concurrency) para serializar las solicitudes por usuario. Si una solicitud anterior no liberó su token correctamente, las llamadas posteriores de recuperación de productos pueden quedar en cola o fallar. ^[4]

Qué verificar

• Confirma que la fila de zohoconnections para tu usuario contiene un accesstoken no vacío, un tokenexpiresat futuro y el api_domain correcto para tu centro de datos de Zoho. ^[3]
• Verifica que Config.ZOHO_SCOPES incluya el ámbito necesario para los Productos de CRM antes de generar una nueva URL de autorización. ^[5]
• Tras la recuperación, inspecciona el diccionario tool_result sin procesar en busca de claves de error antes de pasar los datos a procesos posteriores — una respuesta HTTP exitosa no garantiza que el payload contenga registros de productos. ^[2]