Cómo recuperar registros en Zoho CRM

La API GraphQL de Zoho CRM te permite obtener tanto datos de registros como metadatos de tus módulos de CRM en una sola consulta flexible, lo que la convierte en una poderosa alternativa a las llamadas REST tradicionales cuando necesitas extraer información de varios módulos a la vez.

Por qué esto es importante

Al crear integraciones, paneles de control o widgets personalizados, los desarrolladores suelen necesitar recuperar datos de varios módulos de Zoho CRM simultáneamente. La API GraphQL aborda esto permitiéndote combinar consultas de Records y Meta en una sola solicitud, lo que reduce los viajes de ida y vuelta y te da un control preciso sobre qué campos se devuelven. ^[1] Esto es especialmente útil para equipos que crean herramientas de informes o sincronizan datos de CRM con sistemas externos.

Paso a paso

Paso 1. Confirma que tu edición de Zoho CRM es compatible con GraphQL. La API GraphQL no está disponible en las versiones de prueba de ninguna edición de Zoho CRM, por lo que debes estar en un plan de pago antes de continuar. ^[1]

Paso 2. Autentica tu cliente de API. Necesitarás un token de acceso OAuth 2.0 válido con alcance para Zoho CRM antes de enviar cualquier solicitud GraphQL. Una vez que tengas tu token, configúralo como token Bearer en el encabezado Authorization de tu solicitud HTTP. ^[1]

Paso 3. Comprende los dos tipos de consulta raíz disponibles. El esquema GraphQL expone un tipo Query raíz con dos ramas principales: ^[1]

• Records — recupera filas de datos reales de cualquier módulo de CRM al que tu perfil tenga acceso. El filtrado y la paginación son compatibles con todos los módulos.
• Meta — recupera datos estructurales o de configuración de fuentes como Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles y Widgets. Algunos de estos también admiten filtrado y paginación.

Paso 4. Construye tu consulta GraphQL. A continuación se muestra un ejemplo que extrae AccountName del módulo Accounts, LastName de Leads, apiname de Roles y lastname de Users, todo en una sola solicitud: ^[1]

query {
    Records {
        Accounts {
            _data {
                Account_Name {
                    value
                }
            }
        }
        Leads {
            _data {
                Last_Name {
                    value
                }
            }
        }
    }
    Meta {
        Roles {
            _data {
                api_name
            }
        }
        Users {
            _data {
                last_name
            }
        }
    }
}

Observa que los valores de los campos de registro se acceden mediante la clave value anidada bajo cada nombre de campo, mientras que ciertos campos de metadatos (como api_name) se acceden directamente. ^[1]

Paso 5. Envía la consulta al endpoint GraphQL de Zoho CRM usando tu cliente HTTP preferido (por ejemplo, curl, Postman o un SDK del lado del servidor). Incluye tu token OAuth en el encabezado de la solicitud y establece el Content-Type en application/json. ^[1]

Paso 6. Analiza la respuesta. La API devuelve un objeto JSON estructurado que refleja la forma de tu consulta. Los registros aparecen bajo arrays _data dentro de cada nodo de módulo, y los campos de metadatos aparecen bajo sus respectivos nodos de tipo. ^[1]

Errores comunes

• Restricción de cuenta de prueba. Intentar usar la API GraphQL en una prueba de Zoho CRM generará un error. Primero debes actualizar a una edición de pago. ^[1]
• Acceso basado en perfil. La consulta Records solo muestra los módulos y campos que tu perfil de CRM tiene permiso para ver. Si un módulo aparece vacío o no está en la respuesta, revisa los permisos a nivel de campo y de módulo de tu perfil en Zoho CRM. ^[1]
• Distinción entre mayúsculas y minúsculas en los nombres de campo. Las consultas GraphQL en Zoho CRM distinguen entre mayúsculas y minúsculas. Por ejemplo, LastName y lastname hacen referencia a campos diferentes en contextos distintos (Records vs. Meta). Verifica los nombres de API exactos de tus campos antes de realizar la consulta. ^[1]
• Paginación para conjuntos de datos grandes. Aunque el filtrado y la paginación son compatibles con todos los módulos de Records y algunos tipos de Meta, omitir los argumentos de paginación en módulos grandes puede generar respuestas truncadas. Implementa siempre la paginación al consultar módulos con grandes volúmenes de registros. ^[1]

Qué verificar

• Edición y estado de prueba — verifica que tu organización esté en un plan de pago de Zoho CRM, ya que GraphQL está bloqueado en cuentas de prueba. ^[1]
• Alcance del token OAuth — confirma que tu token de acceso incluye los alcances de CRM correctos; un token con alcance insuficiente causará errores de autenticación aunque la sintaxis de la consulta sea correcta. ^[1]
• Nombres de API de los campos — compara los nombres de campo usados en tu consulta con los nombres de API reales en tu configuración de CRM (que se encuentran en Configuración → Módulos y campos) para evitar respuestas vacías o con errores. ^[1]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho. Para problemas a nivel de plataforma, verifica siempre con la documentación oficial de Zoho o los canales de soporte oficiales.*