Come ottenere gli allegati dai record in Zoho

Recuperare gli allegati dai record in Zoho CRM e Zoho Desk è semplice una volta che si conoscono gli endpoint API e i pattern URL corretti da utilizzare. Questa guida ti accompagna nel processo passo dopo passo.

Perché è importante

Gli allegati — come contratti, immagini o documenti di supporto — sono spesso archiviati direttamente nei record CRM o Desk. Se stai costruendo un'integrazione, automatizzando il recupero di documenti o verificando i file collegati agli account, hai bisogno di un modo affidabile per recuperarli in modo programmatico. Conoscere l'endpoint corretto per ogni tipo di record consente di risparmiare molto tempo nel debug e di evitare errori comuni relativi agli ID dei record e ai percorsi dei moduli.

> Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale di Zoho.

---

Passo dopo passo

Passo 1. Identifica il tipo di record e il suo ID.

Prima di effettuare qualsiasi chiamata API, verifica se stai lavorando con un modulo CRM (ad es. Contatti, Lead, Account) o con un'entità Zoho Desk (ad es. un Account o un Ticket). Avrai anche bisogno dell'ID univoco del record — si tratta dell'{accountId}, dell'{attachmentId} o dell'identificatore equivalente che appare nell'URL del record. Per i record CRM, l'URL diretto segue il pattern https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, dove {dc} è il suffisso del tuo data center (ad es. com, eu, in). ^[1]

Passo 2. Elenca tutti gli allegati di un record Account in Desk.

Per recuperare tutti gli allegati associati a uno specifico Account Desk, invia una richiesta GET al seguente endpoint, sostituendo l'identificatore reale dell'account:

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

Questa operazione (listaccountattachments) accetta l'accountId come parametro di percorso obbligatorio, più un parametro opzionale p per la paginazione o il filtraggio. ^[8]

Passo 3. Recupera un singolo allegato specifico da un Account Desk.

Una volta ottenuto l'elenco degli allegati e identificato l'attachmentId necessario, recupera quel singolo file utilizzando:

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

Questa operazione (getaccountattachment) richiede sia accountId che attachmentId come parametri di percorso, con un parametro opzionale p disponibile. ^[5]

Passo 4. Accedi alla documentazione generale sugli allegati.

Se hai bisogno di consultare lo schema generale degli allegati o di esplorare i metadati relativi agli allegati tra i vari tipi di record, l'endpoint della documentazione è:

GET /api/v1/_doc/attachments

Questa operazione get_attachments accetta un parametro opzionale p e restituisce la documentazione di riferimento sugli allegati. ^[7]

Passo 5. Costruisci i link diretti ai record.

Dopo aver recuperato i dati degli allegati, potresti voler mostrare link cliccabili ai record padre nella tua interfaccia o nei log. Per i record CRM, costruisci il link come https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Per i record Desk, il pattern è https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. Adatta il segmento {dc} al data center della tua organizzazione. ^[1]

Passo 6. Gestisci la risposta API e mostra i link.

Quando il tuo strumento o la tua integrazione restituisce i risultati, verifica nel payload della risposta i dati degli allegati. Se il tuo sistema costruisce automaticamente i link ai record, questi vengono tipicamente aggiunti in una sezione "Apri in Zoho" formattata come 🔗 {name}: {url} per una navigazione semplice. ^{[2] [4]}

---

Errori comuni

• Suffisso del data center errato. Il valore {dc} nell'URL base deve corrispondere alla posizione in cui è ospitata la tua organizzazione Zoho. Usare com quando la tua organizzazione si trova su eu causerà errori di autenticazione o errori 404. Verifica sempre il tuo data center prima di costruire gli URL. ^[1]

• Confusione tra endpoint CRM e Desk. Gli endpoint degli allegati mostrati sopra (/api/v1/accounts/{accountId}/attachments) sono endpoint di Zoho Desk, non di Zoho CRM. Inviare richieste in stile Desk a un URL base CRM — o viceversa — non funzionerà. Verifica quale prodotto contiene il record prima di scegliere l'endpoint. ^{[5] [8]}

• accountId mancante o errato. Sia l'endpoint di elenco che quello del singolo allegato richiedono un accountId valido. Passare un ID record CRM a un endpoint Desk, o omettere completamente l'ID, restituirà un errore. Recupera sempre l'ID direttamente dal record del sistema di destinazione. ^{[5] [8]}

• Dimenticare i parametri di paginazione. Il parametro opzionale p negli endpoint di elenco controlla la paginazione. Se un account ha molti allegati, omettere la gestione della paginazione potrebbe far sì che tu riceva solo la prima pagina dei risultati. ^[8]

---

Cosa verificare

• Conferma che l'URL base e il data center corretti (com, eu, in, ecc.) corrispondano alla regione della tua organizzazione Zoho prima di effettuare qualsiasi chiamata API. ^[1]
• Verifica che sia accountId che attachmentId provengano da Zoho Desk, e non da un record CRM, quando utilizzi gli endpoint degli allegati Desk. ^{[5] [8]}
• Controlla il payload della risposta per una chiave error — se presente, esamina il messaggio per diagnosticare problemi di autorizzazione, ID non validi o richieste malformate prima di riprovare. ^[6]