Cómo obtener usuarios en Zoho

Recuperar usuarios en Zoho CRM mediante OAuth requiere un token de acceso válido y una llamada al endpoint de información de usuario de Zoho Accounts — aquí te explicamos exactamente cómo funciona ese flujo, desde la configuración de credenciales hasta el análisis de la respuesta.

Por qué esto es importante

Al crear integraciones o herramientas internas sobre Zoho CRM, a menudo necesitas identificar *quién* está autenticado — su ID de usuario, dirección de correo electrónico y detalles de la organización — antes de realizar cualquier llamada a la API de CRM. Hacerlo incorrectamente genera errores 401, IDs de organización incorrectos y lógica multitenant rota. Comprender el flujo completo de callback OAuth y recuperación de información de usuario ahorra un tiempo considerable de depuración.

> Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho.

---

Paso a paso

Paso 1. Registra tu aplicación en la Consola de API de Zoho y recopila las credenciales que necesitas. Navega a la Consola de API, crea una Aplicación basada en servidor, establece tu URI de redirección (p. ej. http://localhost:8080/api/auth_callback) y anota tu Client ID y Client Secret. Al seleccionar los scopes de OAuth, incluye como mínimo ZohoCRM.users.ALL, ZohoCRM.modules.ALL y ZohoCRM.settings.ALL. ^[7]

Paso 2. Configura tu entorno. Crea un archivo .env en la raíz del proyecto y complétalo con ZOHOCLIENTID, ZOHOCLIENTSECRET y, opcionalmente, ZOHO_DC (valores aceptados: com, eu, in, com.au, jp — el valor predeterminado es com). El valor del centro de datos controla qué endpoint regional se llama en los pasos siguientes. ^[7]

Paso 3. Gestiona el callback OAuth en tu servidor. Cuando Zoho redirige de vuelta a tu ruta de callback, extrae el parámetro code de la cadena de consulta. Pasa ese código a tu manejador OAuth (ZohoOAuth.handleoauthcallback(code)), que lo intercambia por un token de acceso y un token de actualización. Si la respuesta no contiene la clave access_token, muestra el error de inmediato en lugar de continuar. ^[6]

Paso 4. Llama al endpoint de información de usuario de Zoho Accounts para recuperar los detalles del usuario autenticado. Construye la URL de la siguiente manera:

https://accounts.zoho.<DC>/oauth/user/info

Envía una solicitud GET con un encabezado Authorization: Bearer <access_token>. La respuesta JSON contiene los campos que necesitas para identificar al usuario. ^[1]

Paso 5. Analiza la respuesta con cuidado — los nombres de los campos varían según el centro de datos. Extrae el ID de usuario de ZUID y el correo electrónico de Email. Para el ID de organización, prueba primero con orgid, luego con organizationid y después con ZGID; si ninguno está presente (organizaciones de un solo usuario), usa el valor de ZUID como alternativa. Para el nombre de la organización, comprueba companyname, luego organizationname y después Company_Name; si todos están ausentes, deriva un valor alternativo a partir de la parte del dominio de la dirección de correo electrónico. ^[1]

Paso 6. Persiste el usuario y la organización. Usa el zohouserid para buscar un registro de usuario existente; créalo si no existe. Por separado, llama a getorcreateorganization con los valores zohoorgid y orgname, luego vincula el usuario a esa organización mediante updateuserorg. Almacena el orgid en la sesión junto con userid para admitir escenarios multitenant. ^[6]

Paso 7. Almacena los tokens de conexión. Guarda el accesstoken, refreshtoken, apidomain, tokenexpiresat y dc en tu tabla zohoconnections, con clave user_id. Si ya existe un registro de conexión para ese usuario, actualízalo; de lo contrario, inserta una nueva fila. ^[8]

Paso 8. En solicitudes posteriores, recupera la conexión almacenada y actualiza de forma proactiva el token de acceso si está a menos de 120 segundos de expirar. Tras una actualización exitosa, actualiza tanto accesstoken como tokenexpires_at en la base de datos antes de proceder con cualquier llamada a la API de Zoho CRM. ^[2]

Paso 9. Para comprobar el estado del usuario autenticado actualmente en cualquier momento, consulta tu tabla users por session["userid"] y tu tabla zohoconnections por user_id. Devuelve connected: true solo cuando exista una fila de conexión, junto con la dirección de correo electrónico almacenada. ^[4]

---

Errores comunes

• Centro de datos incorrecto. Si ZOHODC está configurado como com pero tus usuarios están en el centro de datos de la UE o de India, la URL de información de usuario devolverá un error o una respuesta vacía. Siempre deriva el DC del apidomain devuelto en el callback OAuth (busca el segmento después de zohoapis.) y persístelo. ^[8]
• Campos de ID de organización ausentes. El nombre del campo de ID de organización no es consistente entre los centros de datos de Zoho. No probar las tres variantes (orgid, organizationid, ZGID) antes de usar el valor alternativo hará que la lógica de creación de organizaciones utilice silenciosamente el identificador incorrecto. ^[1]
• Expiración del token durante una solicitud. Los tokens de acceso expiran tras aproximadamente 3600 segundos. Sin una actualización proactiva (el margen de 120 segundos), las operaciones de larga duración encontrarán errores 401 a mitad del proceso. ^[2]
• Caso límite de organización de un solo usuario. En cuentas sin una organización formal, es posible que ninguno de los campos de ID de organización esté completado. La alternativa segura es usar el ZUID como identificador de organización para que la lógica de creación de organizaciones posterior no falle. ^[1]

---

Qué verificar

• Los scopes son correctos: Confirma que ZohoCRM.users.ALL está incluido en la lista de scopes de tu aplicación registrada; los scopes faltantes restringen silenciosamente lo que devuelve el endpoint de información de usuario. ^[7]
• El DC se persiste correctamente: Después del callback OAuth, verifica que la columna dc en zoho_connections coincida con el dominio regional real de la cuenta de Zoho del usuario autenticado. ^[8]
• La actualización del token funciona: Después de almacenar una conexión, simula un escenario de expiración próxima y confirma que getzohoconnection devuelve un access_token válido y actualizado en lugar de uno expirado. ^[2]