Guide d’intégration de QuickBooks Online pour l’ordonnancement de la production avec SkyPlanner APS

QuickBooks Online est un produit cloud mutualisé : toutes les sociétés utilisent la même Accounting API. Il s’agit d’une REST API, en version v3. Chaque appel cible une société par son realm ID : https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Les tests utilisent un hôte sandbox distinct. Les requêtes et les réponses sont au format JSON, et le paramètre minorversion permet de choisir la version du schéma. (source)

Les entités nécessaires à l’ordonnancement :

• Données de base : Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Demande : Estimate (TxnStatus Accepted, lignes, ShipDate) et, pour les ateliers qui facturent avant de produire, Invoice ou SalesReceipt.
• Approvisionnement : PurchaseOrder (POStatus Open, lignes avec articles et quantités), Bill.
• Écriture en retour : Estimate, Invoice, TimeActivity, InventoryAdjustment.

Les lectures passent par le point de terminaison de requête, par exemple select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Les mises à jour peuvent être partielles : SkyPlanner n’envoie donc que les champs qu’il modifie. L’Accounting API ne comporte aucune entité pour les commandes clients, les gammes de fabrication, les postes de charge ou les ordres de fabrication.

Les webhooks de QuickBooks avertissent l’application lorsque les données d’une société connectée changent. « Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files. » (Les webhooks vous avertissent automatiquement de toute modification des données dans les fichiers de société QuickBooks Online de votre utilisateur final.) (source) Les entités utiles à l’ordonnancement sont les suivantes :

• Customer, Item, Employee
• Estimate, Invoice, SalesReceipt
• PurchaseOrder, Bill
• TimeActivity

Les opérations comprennent Create, Update, Delete, Merge et Void. Une notification contient le nom de l’entité, son ID, l’opération et l’horodatage de dernière modification, mais pas l’enregistrement complet. Le destinataire lit ensuite cet enregistrement.

La capture des changements (GET /cdc?entities=...&changedSince=...) renvoie toutes les modifications survenues depuis un horodatage donné, sur une période récente. SkyPlanner l’utilise pour un rapprochement nocturne : les données d’une commande ne restent donc jamais périmées à cause d’un webhook manqué. TimeActivity n’est pas couvert par la capture des changements ; son rapprochement s’effectue par une requête. (source)

1. Chargement initial des données de base. Parcourez les clients, les articles, les employés et les commandes fournisseurs en cours par pages, via le point de terminaison de requête. Créez les clients dans SkyPlanner en utilisant l’ID QuickBooks comme external_identifier, puis les produits et les matières avec l’ID d’article comme clé. Configurez ensuite ce que QuickBooks ne contient pas : postes de travail, étapes de fabrication par produit, horaires d’équipe, congés et temps de réglage. L’import CSV ou Excel est le moyen le plus rapide pour les étapes de fabrication.

2. Synchronisation des commandes. Abonnez-vous aux webhooks Estimate, Invoice, Item et PurchaseOrder. Lorsqu’un devis passe au statut Accepted, SkyPlanner le lit et crée une commande avec le numéro du devis comme external_order_number et la date d’expédition comme delivery_date. Chaque ligne génère des opérations correspondant aux étapes de fabrication du produit. Les lignes des commandes fournisseurs en cours deviennent des matières attendues : les opérations attendent donc la livraison. La capture nocturne des changements récupère tout événement manqué.

3. Retour du planning et des données de fin de production. Quatre appels transmettent les résultats à QuickBooks :

• Une mise à jour partielle de l’Estimate renseigne ShipDate : la date promise dans QuickBooks suit ainsi le planning.
• Lorsque la commande est terminée, POST /invoice crée la facture avec les lignes du devis et un LinkedTxn vers ce devis. Intuit n’autorise qu’un seul lien de facture par devis : les modalités des livraisons partielles sont donc définies lors du cadrage.
• POST /timeactivity enregistre les heures saisies par chaque opérateur en les rattachant à l’employé, au client et à un article de service. Les heures facturables peuvent ensuite être ajoutées à la facture dans QuickBooks.
• POST /inventoryadjustment augmente le stock de produits finis et diminue celui des matières consommées. Intuit propose cette entité dans QuickBooks Online Plus et Advanced aux États-Unis. (source)

4. Déclarations en atelier. Les opérateurs saisissent leur travail avec SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. L’avancement met immédiatement le planning à jour, et Autopilot réordonnance le reste. Les heures sont transmises à QuickBooks sous forme de relevés de temps. Si l’atelier conserve QuickBooks Time pour la paie, choisissez un seul canal pour les heures des opérations lors du cadrage.

5. Systèmes de référence et règles de gestion des conflits. Consignez ces règles avant la mise en service :

• Les commandes clients restent dans les écrans QuickBooks. Les offres Plus et Advanced proposent des commandes clients dans l’application. L’intégration lit les devis acceptés, ou les factures pour les ateliers qui facturent avant de produire. Convenez d’un seul déclencheur pour que toutes les commandes suivent le même circuit.
• Pas de gammes de fabrication dans QuickBooks. Conservez les étapes de fabrication de chaque produit dans SkyPlanner, en les reliant à la clé de l’article QuickBooks.
• Une seule facture liée à chaque devis. Les livraisons fractionnées nécessitent une règle, par exemple un devis par livraison.
• Les ajustements de stocks dépendent de l’offre et de la région. Aux États-Unis, les offres Plus et Advanced les prennent en charge. Ailleurs, définissez avec votre comptable comment enregistrer les produits finis dans QuickBooks.
• Ordres de fabrication d’Intuit Enterprise Suite. Si vous les utilisez, déterminez quel système fait référence pour les fabrications et les réservations de composants.
• Les ensembles d’articles sont accessibles en lecture seule via l’API. Les articles de type Group ne peuvent pas être créés via l’API : gérez donc ces ensembles dans QuickBooks.
• Rotation des jetons de renouvellement. Enregistrez le nouveau jeton après chaque renouvellement, sinon la connexion est interrompue.