Comment récupérer les factures dans Zoho

La récupération des factures dans Zoho CRM est simple une fois votre connexion OAuth établie — vous pouvez récupérer soit une liste complète de factures, soit une seule facture par son identifiant, grâce à deux opérations API dédiées.

Pourquoi c'est important

Si vous créez une intégration, automatisez des flux de facturation ou auditez simplement vos enregistrements de ventes par programmation, vous aurez besoin d'un accès fiable aux données de factures stockées dans Zoho CRM. Savoir quels endpoints appeler — et comment l'authentification est gérée en coulisses — permet d'économiser un temps de débogage considérable. Ce guide est fourni par Beam Help, votre support expert indépendant pour Zoho (et non le support officiel de Zoho).

Étape par étape

Étape 1. Assurez-vous que votre connexion Zoho CRM est active et que votre jeton d'accès est valide. Le système vérifie l'expiration du jeton stocké et le rafraîchit automatiquement environ deux minutes avant son expiration, en utilisant le refresh_token sauvegardé dans votre enregistrement de connexion. Si le rafraîchissement échoue ou qu'aucune connexion n'existe pour votre utilisateur, l'appel API ne peut pas aboutir. ^[2]

Étape 2. Vérifiez que vos scopes OAuth incluent les autorisations Zoho CRM nécessaires. Les scopes ZohoCRM.org.ALL et les scopes ZohoCRM associés doivent figurer dans votre liste de scopes autorisés pour que les données CRM — y compris les factures — soient accessibles. ^[8]

Étape 3. Pour récupérer toutes les factures, envoyez une requête GET vers l'endpoint /Invoices. Dans le code, cette opération est exposée sous le nom get_invoices et accepte un dictionnaire de paramètres optionnel (p) pour le filtrage ou la pagination. Un appel minimal passe un dictionnaire vide si aucun filtre n'est nécessaire. ^[4]

# Récupérer toutes les factures (sans filtres)
result = api.get_invoices(p={})

# Récupérer les factures avec des paramètres de requête optionnels
result = api.get_invoices(p={"page": 1, "per_page": 50})

Étape 4. Pour récupérer une seule facture par son identifiant unique, envoyez une requête GET vers /Invoices/{invid}, en remplaçant l'identifiant réel de la facture. Il s'agit de l'opération getinvoice, qui ne requiert que la chaîne inv_id comme argument. ^[7]

# Récupérer une facture spécifique
result = api.get_invoice(inv_id="4876000000123456")

Étape 5. Le client API sous-jacent (getzohoapi) gère le rafraîchissement du jeton de manière transparente via un callback tokenrefresher. Si une expiration du jeton survient en cours de requête, le rafraîchisseur récupère le dernier refreshtoken depuis votre base de données, appelle ZohoOAuth.refreshtokens, et stocke les nouvelles valeurs accesstoken et tokenexpiresat avant de réessayer. Vous n'avez pas besoin de gérer cela manuellement. ^[1]

Étape 6. Analysez la réponse de l'un ou l'autre appel. getinvoices et getinvoice retournent tous deux la réponse brute de la couche REST de Zoho CRM. Pour un appel de liste, attendez-vous à une structure paginée ; pour un appel d'enregistrement unique, attendez-vous à un objet d'enregistrement indexé par les champs de la facture. ^[4][7]

Erreurs courantes

• Connexion manquante ou expirée : Si getzohoconnection retourne None — c'est-à-dire qu'aucune ligne n'existe dans zohoconnections pour le userid donné — l'instance API ne peut pas être créée et tous les appels de factures échoueront silencieusement. Vérifiez toujours que l'enregistrement de connexion existe avant d'effectuer des requêtes. ^[2]

• Le rafraîchissement du jeton ne retourne pas de jeton d'accès : Lors du flux de rafraîchissement, si la réponse de ZohoOAuth.refreshtokens ne contient pas de clé accesstoken, le rafraîchisseur retourne None et la requête sera bloquée. Cela indique généralement un refresh_token expiré ou révoqué, nécessitant une nouvelle authentification de l'utilisateur. ^[1][6]

• Scopes OAuth insuffisants : Si les scopes accordés lors de l'autorisation OAuth n'incluent pas les autorisations ZohoCRM requises, l'API de Zoho retournera une erreur de permission plutôt que les données de factures. Vérifiez que les scopes CRM corrects ont bien été demandés au moment de la connexion. ^[8]

• Paramètre apptype incorrect : L'assistant getzohoapi accepte un argument apptype — passer "desk" au lieu de "crm" redirigera votre requête vers Zoho Desk plutôt que vers Zoho CRM, où l'endpoint /Invoices n'existe pas. Passez toujours app_type="crm" lorsque vous travaillez avec des factures. ^[1]

Ce qu'il faut vérifier

• L'enregistrement de connexion existe : Confirmez qu'une ligne valide est présente dans votre table zohoconnections pour le userid cible, avec un refresh_token non expiré. ^[2]
• Les scopes incluent l'accès CRM : Vérifiez que l'autorisation OAuth incluait bien l'ensemble de scopes ZohoCRM nécessaires, et pas uniquement les scopes Zoho Desk. ^[8]
• Format correct de l'endpoint et de l'identifiant : Pour la récupération d'une seule facture, assurez-vous que la valeur inv_id correspond bien à l'identifiant complet de l'enregistrement Zoho CRM (généralement une longue chaîne numérique), et non à un numéro d'affichage ou à la valeur d'un champ personnalisé. ^[7]