Cómo recuperar registros duplicados en Zoho

Los registros duplicados en Zoho pueden detectarse de forma programática mediante un endpoint de búsqueda dedicado, lo que te permite identificar y actuar sobre datos redundantes antes de que generen problemas en informes o flujos de trabajo.

Por qué esto es importante

Los registros duplicados inflan los números del pipeline, confunden a los agentes de soporte y socavan las reglas de automatización que asumen entradas únicas. Tanto si gestionas un catálogo de productos en Zoho Desk como contactos en Zoho CRM, detectar duplicados a tiempo mantiene tus datos limpios y tus procesos fiables. Como soporte experto independiente (no soporte oficial de Zoho), Beam Help te guía a través de los mecanismos para que tu equipo pueda automatizar esta verificación con confianza.

Paso a paso

Paso 1. Asegúrate de que tu conexión OAuth incluye los scopes correctos antes de realizar cualquier llamada a la API. Para Zoho CRM necesitas como mínimo ZohoCRM.modules.ALL o permisos de lectura equivalentes, y para Zoho Desk necesitas Desk.search.READ junto con los scopes de módulo relevantes, como Desk.contacts.READ. ^[1]

Paso 2. Autentícate y obtén un token de acceso válido. La plataforma almacena los detalles de tu conexión (token de acceso, token de actualización, dominio de API y marca de tiempo de expiración) en un registro de conexión vinculado a tu cuenta de usuario. Los tokens se actualizan automáticamente aproximadamente dos minutos antes de su expiración para evitar fallos durante las solicitudes, así que asegúrate de que tu integración siga el mismo patrón. ^[5]

Paso 3. Si tu token ha expirado, activa una actualización llamando a ZohoOAuth.refreshtokens() con el token de actualización almacenado. Si la operación es exitosa, persiste los nuevos valores accesstoken y tokenexpiresat actualizado en tu almacén de conexiones para que las llamadas posteriores permanezcan autenticadas. ^[3]

Paso 4. Para recuperar registros duplicados, realiza una solicitud GET al siguiente endpoint:

GET /api/v1/products/duplicate

Esta operación se identifica internamente como searchforduplicate_records y acepta un diccionario de parámetros opcional (p) que puedes usar para filtrar o paginar los resultados. ^[6]

Paso 5. Pasa los parámetros de filtro relevantes dentro del diccionario p. Las claves admitidas exactas dependen de tu configuración de Zoho Desk, pero el objeto de parámetros se reenvía directamente a la API de Zoho, así que consulta la lista de campos de tu módulo para acotar los resultados (por ejemplo, por categoría de producto o rango de fechas). ^[6]

Paso 6. Gestiona la respuesta. Una llamada exitosa devuelve un objeto de resultado estructurado. Si el resultado contiene una clave error, muestra ese mensaje al operador y detén el procesamiento. Si el resultado es correcto, itera sobre los registros devueltos para revisarlos, combinarlos o marcarlos según sea necesario. ^[8]

Paso 7. Al crear enlaces a registros duplicados individuales en tu interfaz de usuario, utiliza los valores dc (centro de datos), crmorgid, deskorgid y desk_portal almacenados en tu registro de conexión para construir URLs correctas específicas de cada región. ^[2]

Errores comunes

• Scopes faltantes. Si Desk.search.READ no está presente en tu concesión OAuth, el endpoint de búsqueda de duplicados devolverá un error de autorización. Verifica la lista completa de scopes en la configuración de tu cliente OAuth. ^[1]
• Tokens obsoletos. Llamar al endpoint con un token de acceso expirado produce una respuesta 401. Implementa una actualización proactiva del token (al menos 120 segundos antes de su expiración) para evitar esto durante las solicitudes. ^[5]
• Centro de datos incorrecto. Zoho aloja datos en múltiples regiones. Si tu apidomain apunta a zohoapis.eu pero tu cliente está configurado para zohoapis.com, las solicitudes fallarán silenciosamente o devolverán resultados vacíos. Extrae el sufijo del centro de datos del apidomain almacenado durante el callback de OAuth y úsalo de forma consistente. ^[7]
• Parámetro p vacío. Pasar None en lugar de un diccionario vacío {} para el argumento p puede causar un comportamiento inesperado dependiendo de cómo el cliente HTTP subyacente serialice la solicitud. Usa {} por defecto cuando no se necesiten filtros. ^[6]

Qué verificar

• Los scopes están presentes: Confirma que Desk.search.READ (y cualquier scope de lectura a nivel de módulo) aparecen en tu concesión OAuth activa antes de llamar al endpoint de duplicados. ^[1]
• El token está actualizado: Verifica que tokenexpiresat sea al menos 120 segundos en el futuro en el momento de la solicitud, y que tu lógica de actualización actualice el valor almacenado cuando sea exitosa. ^[5]
• El endpoint devuelve datos: Confirma que la respuesta de GET /api/v1/products/duplicate contiene un conjunto de resultados no vacío y ninguna clave error antes de continuar con cualquier flujo de trabajo de combinación o eliminación. ^[6]