Connecter QuickBooks Online : commandes, clients, factures, paiements et stock
Prenez le Realm ID (Company ID) dans QuickBooks sous l’icône engrenage → Account and settings → Billing & subscription, obtenez un access token dans l’OAuth2 playground d’Intuit Developer pour votre app, saisissez les deux dans Integration, testez, mappez et activez. Le jeton expire après 1 heure, donc un test échoué signifie le plus souvent qu’il faut simplement un jeton frais.
Le connecteur QuickBooks Online travaille avec votre entreprise QuickBooks dans les deux sens : il importe les commandes de vente, les clients, les factures, les produits et les paiements, il peut renvoyer des clients, des factures, des produits et des paiements, et il consulte le stock par article. Un paiement envoyé vers QuickBooks peut être lié à sa facture pour la solder. La connexion est identifiée par votre Realm ID (Company ID) et un access token que vous collez. Ce jeton expire après 1 heure — quand quelque chose cesse soudain de fonctionner, prenez d’abord un jeton frais avant de changer quoi que ce soit d’autre.
Prérequis#
- Une entreprise QuickBooks Online à laquelle vous pouvez vous connecter, avec le droit d’ouvrir Account and settings.
- Une app dans Intuit Developer, afin de pouvoir exécuter son OAuth2 playground et obtenir un access token pour cette entreprise.
- Vous savez dans quel environnement se trouve l’entreprise : production pour une entreprise réelle, sandbox pour une entreprise sandbox d’Intuit Developer.
- Du temps pour finir sans tarder après avoir obtenu le jeton : l’access token expire après 1 heure, donc prenez-le en dernier, juste avant de le saisir et de tester.
Obtenir les identifiants#
- Prenez le Realm ID dans QuickBooks même : connectez-vous à QuickBooks, cliquez sur l’icône engrenage ⚙ en haut à droite, ouvrez Account and settings, allez dans Billing & subscription et copiez le Company ID qui s’y affiche — ce Company ID est le Realm ID.
- Prenez l’access token dans Intuit Developer : ouvrez Intuit Developer, ouvrez votre app et ouvrez son OAuth2 playground.
- Dans l’OAuth2 playground, exécutez le flux OAuth2 pour la même entreprise et le même environnement (production ou sandbox) et copiez l’access token qu’il renvoie.
- Passez directement à l’étape de saisie : cet access token expire après 1 heure. Le renouvellement d’un jeton utilise le Client ID et le Client Secret de cette même app Intuit Developer, donc gardez aussi ces valeurs de l’app à portée de main.
Remplir dans Integration#
- Ouvrez Integration → Marketplace → QuickBooks Online → Nouvelle connexion.
- realm_id, obligatoire, Realm ID (Company ID) : collez le Company ID copié depuis QuickBooks → icône engrenage ⚙ → Account and settings → Billing & subscription, par ex. 123456789.
- environment, facultatif, Environment : saisissez production pour une entreprise réelle, ou sandbox pour une entreprise sandbox d’Intuit Developer. Si vous le laissez vide, production est utilisé.
- access_token, obligatoire, Access token : collez l’access token d’Intuit Developer → votre app → OAuth2 playground, en entier et tout de suite, car il expire après 1 heure. C’est un champ de type mot de passe, conservé comme secret.
Tester la connexion#
Cliquez sur Tester la connexion. Avec votre jeton comme identifiant bearer, le test lit les informations de votre entreprise depuis QuickBooks — en production, il appelle les informations de l’entreprise pour votre realm_id, et en sandbox il utilise à la place l’adresse sandbox. Une réponse réussie renvoie le nom de votre entreprise, ce qui vous permet de savoir que le jeton et le Realm ID appartiennent bien à l’entreprise attendue. Si realm_id manque, le test s’arrête avec MISSING_REALM_ID ; si access_token manque, il s’arrête avec MISSING_TOKEN, sans envoyer de requête. Une réponse 401 est signalée comme INVALID_TOKEN — le jeton est invalide ou, le plus souvent, a simplement dépassé son heure. Le test attend 12 secondes avant de signaler TEST_TIMEOUT.
Mapping / choisir un modèle#
Choisissez le mapping standard QuickBooks Online. Il couvre les objets avec lesquels cette connexion travaille : commandes de vente, clients, factures, produits (items), paiements et quantités de stock par article. Après un test réussi, lancez une extraction et comparez un enregistrement réel côte à côte (un numéro de commande ou de facture, le client, les lignes et les montants), puis envoyez un client ou un produit et confirmez qu’il apparaît dans QuickBooks, avant d’activer. Si un nom dans votre entreprise diffère de l’objet standard, ajustez ce champ dans le mapping plutôt que de renommer quoi que ce soit dans QuickBooks.
Activer#
Après activation, la connexion importe les commandes de vente, les clients, les factures, les produits et les paiements de QuickBooks Online selon la fréquence définie, renvoie les clients, les factures, les produits et les paiements quand ces flux s’exécutent, et répond aux consultations de stock par article. Surveillez les premières exécutions dans Runs / Logs et comparez-les avec QuickBooks avant de laisser la connexion sans surveillance.
Gardez le jeton frais : il expire après 1 heure, donc quand une exécution commence à échouer avec une erreur de jeton, retournez dans Intuit Developer → votre app → OAuth2 playground, prenez un nouvel access token pour la même entreprise et le même environnement, collez-le dans access_token et retestez. Rien d’autre dans la connexion n’a besoin de changer pour un renouvellement de routine du jeton.
FAQ#
Le test échoue avec INVALID_TOKEN (401)
QuickBooks a refusé l’access token. La cause la plus fréquente, de loin, est le temps : le jeton expire après 1 heure, donc un jeton qui fonctionnait quand vous l’avez collé peut déjà être expiré quand vous testez ou quand une exécution ultérieure démarre. Un jeton pris pour une autre entreprise ou un autre environnement est refusé de la même façon.
Ne changez pas d’abord realm_id ni environment. Allez dans Intuit Developer → votre app → OAuth2 playground, relancez le flux pour la même entreprise et le même environnement, collez le nouvel access token dans access_token, enregistrez et retestez aussitôt.
Le test s’arrête avec MISSING_REALM_ID ou MISSING_TOKEN
L’une des deux valeurs d’identification est vide, et le test n’envoie aucune requête sans les deux. MISSING_REALM_ID signifie que realm_id est vide ; MISSING_TOKEN signifie que access_token est vide — ou que le jeton que vous avez collé a été tronqué et que rien d’utilisable n’a été enregistré.
Remplissez realm_id depuis QuickBooks → icône engrenage ⚙ → Account and settings → Billing & subscription → Company ID, et collez en entier un nouvel access token du OAuth2 playground. Enregistrez et retestez immédiatement, avant que le nouveau jeton ne vieillisse.
Le test échoue avec MISSING_SCOPE
Le jeton a été accepté comme jeton, mais il ne porte pas le périmètre comptable dont cette connexion a besoin (com.intuit.quickbooks.accounting), donc QuickBooks ne le laisse pas lire les informations de l’entreprise.
Dans l’OAuth2 playground, relancez le flux en vous assurant que le périmètre comptable est inclus pour votre app, copiez le nouvel access token, collez-le dans access_token et retestez.
Le test renvoie un nom d’entreprise différent de celui attendu
Le jeton et le Realm ID ne décrivent pas la même entreprise. Le nom d’entreprise dans le résultat du test vient de l’entreprise vers laquelle le jeton et le realm_id pointent réellement — souvent une entreprise sandbox alors que vous attendiez production, ou le jeton a été pris dans le playground pour une autre entreprise.
Vérifiez les trois valeurs ensemble : realm_id de l’entreprise visée sous icône engrenage ⚙ → Account and settings → Billing & subscription → Company ID, environment réglé sur production ou sandbox selon cette entreprise, et un jeton du playground exécuté pour cette même entreprise et ce même environnement. Corrigez celui qui ne correspond pas et retestez.
Tout fonctionnait, puis une heure plus tard les exécutions ont commencé à échouer
Ce moment est la durée de vie du jeton, pas un mapping cassé ni une entreprise changée. L’access token expire après 1 heure, donc une connexion qui a réussi le test échouera lors d’exécutions ultérieures avec une erreur de jeton jusqu’à ce qu’un jeton frais soit collé.
Prenez un nouvel access token dans Intuit Developer → votre app → OAuth2 playground pour la même entreprise et le même environnement, collez-le dans access_token et testez. Le renouvellement d’un jeton utilise le Client ID et le Client Secret de cette app — gardez ces valeurs de l’app prêtes pour que le renouvellement soit rapide.
Le test signale TEST_TIMEOUT ou CONNECTION_FAILED
La requête d’informations sur l’entreprise ne s’est pas terminée. TEST_TIMEOUT signifie qu’aucune réponse complète n’est arrivée en 12 secondes ; CONNECTION_FAILED signifie que la requête vers QuickBooks n’est pas passée. Avant de blâmer le réseau longtemps, rappelez-vous l’ordre de suspicion ici : un jeton expiré ou d’un mauvais environnement reste la première chose à écarter sur cette connexion.
Collez d’abord un nouvel access token pour la même entreprise et vérifiez que environment lui correspond (production ou sandbox), puis retestez. Si un jeton frais et bien assorti expire toujours, réessayez après une courte attente et consultez Runs / Logs pour l’erreur exacte avant de changer realm_id.