Cómo crear registros en Zoho

Crear registros en Zoho CRM o Zoho Desk es sencillo una vez que tu conexión OAuth y los permisos de módulo están correctamente configurados — esto es lo que necesitas saber para hacerlo bien.

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

Por qué esto es importante

Tanto si añades nuevos Leads, Contactos, Tickets o Tareas, cada llamada de creación de registros depende de tener los scopes OAuth correctos autorizados y una conexión válida en vigor. Hacerlo mal provoca fallos silenciosos o errores de permisos que pueden ser difíciles de diagnosticar. Entender el flujo completo — desde los scopes hasta la llamada API y el enlace al registro resultante — ahorra un tiempo considerable de resolución de problemas.

Paso a paso

Paso 1. Confirma que tus scopes OAuth incluyen permisos de CREATE.

Antes de que se pueda escribir cualquier registro, tu token OAuth de Zoho debe incluir el scope adecuado. Para registros de Zoho CRM necesitas scopes como ZohoCRM.modules.ALL o un scope CREATE específico del módulo. Para Zoho Desk, los scopes relevantes incluyen Desk.tickets.CREATE, Desk.contacts.CREATE, Desk.tasks.CREATE y Desk.events.CREATE, entre otros. ^[2]

Paso 2. Asegúrate de que tu conexión con Zoho está activa y autenticada.

Tu aplicación debe tener un accesstoken y un refreshtoken válidos almacenados en tu cuenta de usuario. Estos se capturan durante el callback OAuth y se guardan junto con tu apidomain, dc (centro de datos) y crmorg_id. Si la conexión falta o ha expirado, cualquier intento de crear un registro devolverá un error como *«Zoho is not connected for this app. Please reconnect.»* ^[3][5]

Paso 3. Identifica el módulo correcto para tu registro.

Cada registro pertenece a un módulo — por ejemplo Leads, Contacts, Deals o Accounts en Zoho CRM, o tickets en Zoho Desk. El nombre del módulo es un parámetro obligatorio que se pasa junto con los datos del registro. Asegúrate de que el nombre del módulo coincide exactamente con lo que espera la API, ya que una discrepancia hará que la solicitud falle. ^[1]

Paso 4. Envía la solicitud de creación mediante la herramienta o llamada API correspondiente.

Pasa el nombre de la herramienta elegida y un objeto params que incluya el module y todos los valores de campo obligatorios. El sistema ejecutará la herramienta y, si la operación se clasifica como una acción de escritura, puede que primero se almacene como una acción «planificada» con un risk_level asignado antes de que se apruebe su ejecución. ^[4]

Paso 5. Aprueba la acción planificada si es necesario.

Las operaciones de escritura — incluida la creación de registros — suelen mantenerse en estado planned almacenado en adminactions antes de aplicarse. Una vez que confirmas el plan, el sistema llama a applyplan, que ejecuta la herramienta con tus parámetros e intenta crear el registro en Zoho. ^[6]

Paso 6. Obtén el enlace directo a tu nuevo registro.

Tras una creación exitosa, el sistema construye una URL directa al nuevo registro. Para Zoho CRM, el enlace sigue el patrón https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Para tickets de Zoho Desk, el patrón es https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. Estos enlaces se devuelven junto con la respuesta de la API para que puedas navegar directamente al nuevo registro. ^[1][6]

Errores comunes

• Scopes ausentes o insuficientes. Si tu token OAuth se generó sin scopes CREATE para el módulo correspondiente, la API rechazará la solicitud. Debes volver a autorizar y asegurarte de que todos los scopes necesarios — como Desk.tickets.CREATE o el equivalente de CRM — estén incluidos. ^[2]

• Conexión expirada o inexistente. Si no existe una conexión válida para tu cuenta de usuario, el sistema no puede recuperar un access_token y se detendrá antes de realizar cualquier llamada API. Volver a autenticarse mediante el flujo OAuth resolverá esto. ^[3][5]

• Configuración incorrecta del centro de datos (dc). Tu conexión almacena un valor dc (p. ej., com, eu, in) derivado del api_domain devuelto durante OAuth. Si este valor es incorrecto, las URLs de registro generadas y los endpoints de la API apuntarán a la región equivocada, provocando fallos. ^[1][5]

• Operaciones de escritura bloqueadas en modo de solo lectura. Algunos contextos de chat o automatización se inicializan con read_only=True, lo que significa que las herramientas de creación/escritura no se ofrecerán ni ejecutarán. Asegúrate de operar en un contexto que permita acciones de escritura. ^[3]

Qué verificar

• Verifica que tus scopes OAuth incluyan el permiso CREATE relevante para tu módulo de destino (CRM o Desk) antes de intentar crear registros. ^[2]
• Confirma que tu registro de conexión tiene un accesstoken no expirado y los valores correctos de dc y crmorg_id. ^[5]
• Comprueba la URL del registro devuelta tras la creación para confirmar que el registro se escribió en el módulo y centro de datos esperados. ^[1][6]