Come recuperare le fatture in Zoho

Recuperare le fatture in Zoho CRM è semplice una volta stabilita la connessione OAuth — puoi ottenere un elenco completo di fatture o una singola fattura tramite il suo ID utilizzando due operazioni API dedicate.

Perché è importante

Se stai costruendo un'integrazione, automatizzando i flussi di lavoro di fatturazione o semplicemente verificando i tuoi record di vendita in modo programmatico, avrai bisogno di un accesso affidabile ai dati delle fatture archiviati in Zoho CRM. Sapere quali endpoint chiamare — e come viene gestita l'autenticazione in background — consente di risparmiare molto tempo nel debug. Questa guida è fornita da Beam Help, il tuo supporto esperto indipendente per Zoho (non il supporto ufficiale Zoho).

Procedura passo dopo passo

Passaggio 1. Assicurati che la tua connessione Zoho CRM sia attiva e che il tuo token di accesso sia valido. Il sistema verifica la scadenza del token memorizzato e lo aggiorna automaticamente circa due minuti prima della scadenza, utilizzando il refresh_token salvato nel record di connessione. Se l'aggiornamento fallisce o non esiste alcuna connessione per il tuo utente, la chiamata API non può procedere. ^[2]

Passaggio 2. Verifica che i tuoi scope OAuth includano le autorizzazioni Zoho CRM necessarie. Gli scope ZohoCRM.org.ALL e i relativi scope ZohoCRM devono essere presenti nell'elenco degli scope autorizzati affinché i dati CRM — incluse le fatture — siano accessibili. ^[8]

Passaggio 3. Per recuperare tutte le fatture, invia una richiesta GET all'endpoint /Invoices. Nel codice, questa operazione è esposta come get_invoices, che accetta un dizionario di parametri opzionale (p) per il filtraggio o la paginazione. Una chiamata minimale passa un dizionario vuoto se non sono necessari filtri. ^[4]

# Retrieve all invoices (no filters)
result = api.get_invoices(p={})

# Retrieve invoices with optional query parameters
result = api.get_invoices(p={"page": 1, "per_page": 50})

Passaggio 4. Per recuperare una singola fattura tramite il suo identificatore univoco, invia una richiesta GET a /Invoices/{invid}, sostituendo l'ID effettivo della fattura. Questa è l'operazione getinvoice e richiede solo la stringa inv_id come argomento. ^[7]

# Retrieve one specific invoice
result = api.get_invoice(inv_id="4876000000123456")

Passaggio 5. Il client API sottostante (getzohoapi) gestisce il rinnovo del token in modo trasparente tramite un callback tokenrefresher. Se si verifica una scadenza del token durante una richiesta, il refresher recupera il refreshtoken più recente dal database, chiama ZohoOAuth.refreshtokens e memorizza i nuovi valori accesstoken e tokenexpiresat prima di riprovare. Non è necessario gestire questo processo manualmente. ^[1]

Passaggio 6. Analizza la risposta di entrambe le chiamate. Sia getinvoices che getinvoice restituiscono la risposta grezza dal livello REST di Zoho CRM. Per una chiamata a lista, aspettati una struttura paginata; per una chiamata a record singolo, aspettati un oggetto record indicizzato dai campi della fattura. ^[4][7]

Errori comuni

• Connessione mancante o scaduta: Se getzohoconnection restituisce None — ovvero non esiste alcuna riga in zohoconnections per il userid specificato — l'istanza API non può essere creata e tutte le chiamate alle fatture falliranno silenziosamente. Verifica sempre che il record di connessione esista prima di effettuare richieste. ^[2]

• Il rinnovo del token non restituisce un access token: Durante il flusso di rinnovo, se la risposta di ZohoOAuth.refreshtokens non contiene una chiave accesstoken, il refresher restituisce None e la richiesta verrà bloccata. Questo indica in genere un refresh_token scaduto o revocato che richiede una nuova autenticazione da parte dell'utente. ^[1][6]

• Scope OAuth insufficienti: Se gli scope concessi durante l'autorizzazione OAuth non includono le autorizzazioni ZohoCRM richieste, l'API di Zoho restituirà un errore di autorizzazione anziché i dati delle fatture. Verifica che gli scope CRM corretti siano stati richiesti al momento della connessione. ^[8]

• Parametro apptype errato: L'helper getzohoapi accetta un argomento apptype — passare "desk" invece di "crm" instraderà la richiesta a Zoho Desk anziché a Zoho CRM, dove l'endpoint /Invoices non esiste. Passa sempre app_type="crm" quando lavori con le fatture. ^[1]

Cosa verificare

• Il record di connessione esiste: Conferma che sia presente una riga valida nella tabella zohoconnections per il userid di destinazione, con un refresh_token non scaduto. ^[2]
• Gli scope includono l'accesso CRM: Verifica che l'autorizzazione OAuth abbia incluso il set di scope ZohoCRM necessario, non solo gli scope di Zoho Desk. ^[8]
• Endpoint corretto e formato dell'ID: Per il recupero di una singola fattura, assicurati che il valore inv_id sia l'ID completo del record Zoho CRM (tipicamente una lunga stringa numerica), non un numero visualizzato o il valore di un campo personalizzato. ^[7]