Cómo recuperar layouts en Zoho CRM

Recuperar layouts en Zoho CRM se realiza habitualmente a través de la API de Zoho CRM, que permite extraer metadatos de layouts —incluyendo la disposición de campos y la estructura de secciones— para cualquier módulo de tu cuenta. Aquí en Beam Help (soporte experto independiente para Zoho, no soporte oficial de Zoho), te explicamos los enfoques principales a continuación.

Por qué esto es importante

Cuando desarrollas integraciones, interfaces personalizadas o automatizaciones, a menudo necesitas saber exactamente cómo está estructurado el layout de página de un módulo antes de poder renderizar o validar datos correctamente. Los layouts definen qué campos aparecen, en qué orden y bajo qué secciones, por lo que obtenerlos de forma programática es un paso fundamental en cualquier proyecto serio de desarrollo con Zoho CRM. Esto también es relevante cuando deseas auditar diferencias de layouts entre perfiles o sincronizar cambios de layouts con un sistema externo. ^[3]

---

Paso a paso

Paso 1. Confirma que tu edición de Zoho CRM admite acceso a la API. Las APIs GraphQL, por ejemplo, no están disponibles en las versiones de prueba de ninguna edición de Zoho CRM, así que asegúrate de que tu cuenta esté en un plan de pago antes de intentar recuperar metadatos. ^[3]

Paso 2. Decide qué superficie de API se adapta mejor a tu caso de uso. Zoho CRM ofrece tanto endpoints de estilo REST como una API GraphQL. La API GraphQL es especialmente adecuada para la recuperación de layouts y metadatos, ya que expone un tipo raíz Meta dedicado que cubre módulos, usuarios, perfiles, roles y metadatos relacionados en una sola consulta. ^[3]

Paso 3. Autentica tu aplicación mediante OAuth 2.0 para obtener un token de acceso válido. Todas las llamadas a la API de Zoho CRM requieren un token bearer con el alcance adecuado para los permisos de CRM. Consulta la documentación para desarrolladores de Zoho CRM para conocer los scopes de OAuth correctos para el acceso a metadatos.

Paso 4. Para recuperar metadatos de layouts a través de la API GraphQL, envía una consulta dirigida al tipo Meta. El tipo Meta admite la recuperación desde Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles y Widgets. Algunos de estos tipos también admiten filtrado y paginación, lo que resulta útil cuando solo necesitas los layouts de un módulo específico. ^[3]

Una consulta GraphQL mínima dirigida a los metadatos de módulos tiene este aspecto:

query {
  Meta {
    Modules {
      _data {
        api_name
      }
    }
  }
}

Extiende el bloque _data con los campos específicos de layout que requiera tu integración (como el ID del layout, el nombre o los perfiles asociados). ^[3]

Paso 5. Si trabajas dentro de un widget basado en navegador o una aplicación del lado del cliente, considera usar el SDK de JavaScript de Zoho CRM en lugar de llamadas HTTP directas. El SDK proporciona una forma estructurada de realizar llamadas a la API desde el contexto de la interfaz de Zoho CRM, y hay código de ejemplo para obtener datos de módulos disponible en el repositorio de GitHub del SDK. ^[5]

Paso 6. Una vez que hayas recuperado los datos de layouts, compáralos con lo que ves en la interfaz de Zoho CRM navegando a Configuración → Módulos y Campos. Esta es la misma área donde se gestiona la personalización de módulos y layouts, y sirve como una útil verificación de que la respuesta de la API coincide con la configuración activa. ^{[1] [2]}

Paso 7. Si tu proyecto involucra layouts basados en Canvas (vistas de detalle de registro personalizadas), ten en cuenta que Canvas ahora admite vistas para páginas de creación de registros además de las vistas de detalle. Las vistas de Canvas también pueden exportarse e importarse entre cuentas de CRM mediante una clave única, que es válida por un período limitado. Si necesitas replicar layouts entre organizaciones, este mecanismo de exportación/importación puede complementar tu flujo de trabajo de recuperación basado en API. ^[8]

---

Errores comunes

• Restricciones de cuentas de prueba. Intentar consultas de metadatos GraphQL en una cuenta de Zoho CRM de prueba fallará. Actualiza a una edición de pago antes de realizar pruebas. ^[3]
• Scopes incorrectos. Si tu token OAuth carece del scope de metadatos de CRM correcto, la API devolverá un error de autorización en lugar de los datos de layouts. Verifica siempre que los scopes de tu token coincidan con el endpoint al que estás llamando.
• Confusión entre GraphQL y REST. El tipo Meta y sus subtipos (incluido Modules) son específicos de la API GraphQL. Si usas la API REST, la estructura del endpoint y el formato de respuesta difieren significativamente. Mezclar ambas es una fuente habitual de errores inesperados. ^[3]
• Los layouts de Canvas son independientes. Los layouts de página estándar y las vistas de Canvas son construcciones distintas en Zoho CRM. Los metadatos de la API para el layout estándar de un módulo no incluirán automáticamente los detalles de las plantillas de Canvas. ^[8]

---

Qué verificar

• Verifica que la respuesta de la API incluya los valores api_name de módulo esperados y que coincidan con los nombres de módulos visibles en Configuración → Módulos y Campos en tu cuenta de CRM. ^{[1] [3]}
• Confirma que la paginación está gestionada si tu CRM tiene un gran número de módulos o layouts — el tipo Meta de GraphQL admite paginación para algunos subtipos, y las respuestas truncadas son un fallo silencioso habitual. ^[3]
• Prueba con el SDK de JavaScript si tu integración se ejecuta dentro de un widget de Zoho CRM, para asegurarte de que se utiliza el contexto de autenticación correcto en lugar de un token OAuth gestionado manualmente. ^[5]