Cómo obtener archivos adjuntos de registros en Zoho

Recuperar archivos adjuntos de registros en Zoho CRM y Zoho Desk es sencillo una vez que conoces los endpoints de API y los patrones de URL correctos. Esta guía te explica el proceso paso a paso.

Por qué esto es importante

Los archivos adjuntos —como contratos, imágenes o documentos de soporte— suelen almacenarse directamente en los registros de CRM o Desk. Si estás creando una integración, automatizando la recuperación de documentos o auditando archivos vinculados a cuentas, necesitas una forma fiable de obtenerlos mediante programación. Conocer el endpoint correcto para cada tipo de registro ahorra un tiempo considerable de depuración y evita errores comunes relacionados con los IDs de registro y las rutas de módulo.

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

---

Paso a paso

Paso 1. Identifica el tipo de registro y su ID.

Antes de realizar cualquier llamada a la API, confirma si estás trabajando con un módulo de CRM (p. ej., Contacts, Leads, Accounts) o con una entidad de Zoho Desk (p. ej., una Account o un Ticket). También necesitarás el ID único del registro — este es el {accountId}, {attachmentId} o el identificador equivalente que aparece en la URL del registro. Para los registros de CRM, la URL directa sigue el patrón https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, donde {dc} es el sufijo de tu centro de datos (p. ej., com, eu, in). ^[1]

Paso 2. Lista todos los adjuntos de un registro de Account en Desk.

Para recuperar todos los archivos adjuntos asociados a una Account específica de Desk, envía una solicitud GET al siguiente endpoint, sustituyendo el identificador real de la cuenta:

GET /api/v1/accounts/{accountId}/attachments

Esta operación (listaccountattachments) acepta el accountId como parámetro de ruta obligatorio, más un parámetro opcional p para paginación o filtrado. ^[8]

Paso 3. Obtén un adjunto específico de un registro de Account en Desk.

Una vez que tengas la lista de adjuntos y conozcas el attachmentId que necesitas, recupera ese archivo individual usando:

GET /api/v1/accounts/{accountId}/attachments/{attachmentId}

Esta operación (getaccountattachment) requiere tanto accountId como attachmentId como parámetros de ruta, con un parámetro opcional p disponible. ^[5]

Paso 4. Accede a la documentación general de adjuntos.

Si necesitas revisar el esquema general de adjuntos o explorar los metadatos relacionados con adjuntos en distintos tipos de registro, el endpoint de documentación es:

GET /api/v1/_doc/attachments

Esta operación get_attachments acepta un parámetro opcional p y devuelve la documentación de referencia de adjuntos. ^[7]

Paso 5. Construye enlaces directos a los registros.

Tras recuperar los datos de los adjuntos, es posible que quieras mostrar enlaces clicables a los registros padre en tu interfaz o en los registros de actividad. Para los registros de CRM, construye el enlace como https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Para los registros de Desk, el patrón es https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. Ajusta el segmento {dc} para que coincida con el centro de datos de tu organización. ^[1]

Paso 6. Gestiona la respuesta de la API y muestra los enlaces.

Cuando tu herramienta o integración devuelva resultados, revisa el payload de la respuesta para obtener los datos de los adjuntos. Si tu sistema construye enlaces a registros automáticamente, estos suelen añadirse en una sección «Abrir en Zoho» con el formato 🔗 {name}: {url} para facilitar la navegación. ^{[2] [4]}

---

Errores comunes

• Sufijo de centro de datos incorrecto. El valor {dc} en tu URL base debe coincidir con el lugar donde está alojada tu organización de Zoho. Usar com cuando tu organización está en eu provocará errores de autenticación o errores 404. Confirma siempre tu centro de datos antes de construir las URLs. ^[1]

• Confundir los endpoints de CRM y Desk. Los endpoints de adjuntos mostrados anteriormente (/api/v1/accounts/{accountId}/attachments) son endpoints de Zoho Desk, no de Zoho CRM. Enviar solicitudes con formato Desk a una URL base de CRM —o viceversa— fallará. Confirma qué producto contiene el registro antes de elegir tu endpoint. ^{[5] [8]}

• accountId ausente o incorrecto. Tanto el endpoint de lista como el de adjunto individual requieren un accountId válido. Pasar un ID de registro de CRM a un endpoint de Desk, u omitir el ID por completo, devolverá un error. Obtén siempre el ID directamente del registro del sistema de destino. ^{[5] [8]}

• Olvidar los parámetros de paginación. El parámetro opcional p en los endpoints de lista controla la paginación. Si una cuenta tiene muchos adjuntos, omitir el manejo de la paginación puede hacer que solo recibas la primera página de resultados. ^[8]

---

Qué verificar

• Confirma que la URL base y el centro de datos correctos (com, eu, in, etc.) coincidan con la región de tu organización de Zoho antes de realizar cualquier llamada a la API. ^[1]
• Verifica que tanto accountId como attachmentId provengan de Zoho Desk, no de un registro de CRM, cuando uses los endpoints de adjuntos de Desk. ^{[5] [8]}
• Revisa el payload de la respuesta en busca de una clave error — si está presente, examina el mensaje para diagnosticar problemas de permisos, IDs no válidos o solicitudes mal formadas antes de volver a intentarlo. ^[6]