Cómo obtener los detalles de tu perfil en Zoho Desk

Recuperar los detalles de tu perfil en Zoho Desk es sencillo gracias al endpoint dedicado de perfiles, que devuelve información sobre el agente autenticado en ese momento. Esto es lo que necesitas saber para llamarlo correctamente e interpretar la respuesta.

Por qué esto es importante

Al crear integraciones o automatizaciones sobre Zoho Desk, a menudo necesitas identificar al agente que ha iniciado sesión — por ejemplo, para rellenar previamente campos de asignación, auditar acciones o personalizar un panel de soporte. Saber qué endpoint de API llamar y qué ámbitos de OAuth habilitar ahorra un tiempo considerable de depuración. Como soporte experto independiente para Zoho (no soporte oficial de Zoho), Beam Help te guía por los pasos exactos a continuación.

---

Paso a paso

Paso 1. Asegúrate de que tu conexión OAuth tiene los ámbitos correctos configurados antes de realizar cualquier llamada a la API. Como mínimo, tu integración con Zoho Desk requiere Desk.basic.READ para leer datos de agentes y a nivel de organización. ^[4]

Paso 2. Autentica tu cliente de API usando un token de acceso válido. Si tu token ha expirado, el cliente debe usar un token de actualización para obtener un nuevo token de acceso antes de continuar. El flujo de actualización intercambia el token de actualización almacenado por un nuevo access_token y actualiza la marca de tiempo de expiración en consecuencia. ^[2]

Paso 3. Asegúrate de que tu cliente de la API de Desk tenga un org_id válido configurado. Zoho Desk limita todas las llamadas a la API a una organización específica. Si el ID de organización aún no está almacenado, el cliente puede descubrirlo automáticamente llamando primero al endpoint de lista de organizaciones y guardando el id de la primera organización devuelta para futuras solicitudes. [^2, ^6]

Paso 4. Llama al endpoint de detalles del perfil:

GET /api/v1/profiles/mine

Esta operación, identificada como getmyprofile_details, acepta un diccionario de parámetros de consulta opcionales (p) y devuelve el registro de perfil del agente autenticado en ese momento. ^[7]

Paso 5. Analiza la respuesta y muestra los campos clave. Un formato de salida limpio para los datos del perfil presentaría campos como nombre, correo electrónico y estado en líneas separadas, omitiendo los valores vacíos o los IDs internos. ^[5]

Paso 6. Si necesitas cruzar los detalles de la cuenta Zoho del usuario autenticado (como su ZUID, dirección de correo electrónico o nombre de organización), puedes complementar la llamada al perfil de Desk con una solicitud al endpoint de información de usuario de Zoho Accounts:

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

Pasa la cabecera Authorization: Bearer <accesstoken>. La respuesta puede incluir campos como ZUID, Email, orgid, organizationid, ZGID, companyname y organization_name — ten en cuenta que los nombres exactos de los campos pueden variar según la región de tu centro de datos. ^[3]

---

Errores comunes

• ID de organización ausente: Si deskorgid está en blanco cuando se inicializa el cliente de API, las llamadas a /api/v1/profiles/mine pueden fallar o devolver resultados inesperados. Confirma siempre que el ID de organización está resuelto antes de realizar solicitudes de perfil. [^2, ^6]
• Ámbitos insuficientes: Omitir Desk.basic.READ de tu lista de ámbitos de OAuth impedirá que el endpoint de perfiles devuelva datos. Verifica que este ámbito esté incluido junto con cualquier ámbito de tickets o contactos que hayas configurado. ^[4]
• Discrepancia de centro de datos: El valor ZOHO_DC utilizado en tu configuración de OAuth debe coincidir con el centro de datos donde está alojada tu cuenta de Zoho (p. ej., com, eu, in, com.au). Una discrepancia provoca que las llamadas de actualización de token e información de usuario fallen silenciosamente. ^[3]
• Variación en nombres de campos: Al leer información de usuario desde el endpoint de Zoho Accounts, no asumas un único nombre de campo para el ID o el nombre de la organización — el esquema de respuesta difiere entre centros de datos, por lo que tu código debe comprobar múltiples claves posibles antes de recurrir a un valor predeterminado. ^[3]

---

Qué verificar

• Lista de ámbitos: Confirma que Desk.basic.READ (e idealmente Desk.basic.CREATE) aparecen en tus ámbitos de OAuth configurados antes de iniciar el flujo de autenticación. ^[4]
• Resolución del ID de organización: Tras autenticarte, verifica que un deskorgid no vacío esté almacenado en tu registro de conexión; si falta, activa el flujo de descubrimiento automático contra el endpoint de lista de organizaciones. [^2, ^6]
• Validez del token: Antes de llamar a /api/v1/profiles/mine, comprueba que el accesstoken almacenado no haya superado su marca de tiempo tokenexpires_at, y actualízalo de forma proactiva si es necesario. ^[2]