Guida all’integrazione di QuickBooks Online per la schedulazione della produzione con SkyPlanner APS

QuickBooks Online è un unico prodotto cloud multi-tenant e tutte le aziende utilizzano la stessa Accounting API. Si tratta di una REST API, versione v3. Ogni chiamata si rivolge a un’azienda tramite il relativo realm ID: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Per i test è disponibile un host sandbox separato. Richieste e risposte sono in formato JSON e il parametro minorversion seleziona la versione dello schema. (fonte)

Le entità necessarie per la schedulazione:

• Anagrafiche: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Domanda: Estimate (TxnStatus Accepted, righe, ShipDate) e, per le aziende che fatturano prima di produrre, Invoice o SalesReceipt.
• Approvvigionamenti: PurchaseOrder (POStatus Open, righe con articoli e quantità), Bill.
• Scrittura di ritorno: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Le letture utilizzano l’endpoint di query, ad esempio select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Gli aggiornamenti possono essere parziali, quindi SkyPlanner invia solo i campi che modifica. Nell’Accounting API non esistono entità per ordini di vendita, cicli di lavorazione, centri di lavoro o ordini di produzione.

I webhook di QuickBooks avvisano l’app quando cambiano i dati di un’azienda collegata. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.” (I webhook notificano automaticamente ogni modifica ai dati aziendali dell’utente finale in QuickBooks Online.) (fonte) Le entità rilevanti per la schedulazione sono:

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

Le operazioni comprendono Create, Update, Delete, Merge e Void. Una notifica contiene il nome dell’entità, l’ID, l’operazione e la data e l’ora dell’ultimo aggiornamento, non il record completo. Il destinatario legge il record in un secondo momento.

L’acquisizione delle modifiche ai dati (GET /cdc?entities=...&changedSince=...) restituisce tutte le modifiche avvenute dopo un timestamp, entro una finestra temporale recente. SkyPlanner la utilizza per una riconciliazione notturna, così un webhook non ricevuto non lascia mai un ordine non aggiornato. TimeActivity non è coperta dall’acquisizione delle modifiche ai dati e viene quindi riconciliata tramite una query. (fonte)

1. Caricamento iniziale delle anagrafiche. Leggete clienti, articoli, dipendenti e ordini di acquisto aperti tramite l’endpoint di query, scorrendo le pagine dei risultati. Create i clienti in SkyPlanner utilizzando l’ID di QuickBooks come external_identifier, e i prodotti e i materiali utilizzando l’ID dell’articolo come chiave. Configurate poi ciò che QuickBooks non contiene: centri di lavoro, fasi di processo per prodotto, turni, ferie e tempi di attrezzaggio. Per le fasi di processo, l’importazione da CSV o Excel è la strada più rapida.

2. Sincronizzazione degli ordini. Sottoscrivete i webhook di Estimate, Invoice, Item e PurchaseOrder. Quando un preventivo passa allo stato Accepted, SkyPlanner lo legge e crea un ordine utilizzando il numero del preventivo come external_order_number e la data di spedizione come delivery_date. Da ogni riga vengono create le operazioni corrispondenti alle fasi di processo del prodotto. Le righe degli ordini di acquisto aperti diventano materiale in arrivo, quindi le operazioni attendono la consegna. L’acquisizione notturna delle modifiche ai dati recupera ogni evento non ricevuto.

3. Invio a QuickBooks dei dati di schedulazione e completamento. Quattro chiamate riportano i risultati in QuickBooks:

• Un aggiornamento parziale di Estimate scrive ShipDate, così la data promessa in QuickBooks segue il piano.
• Al completamento dell’ordine, POST /invoice crea la fattura con le righe del preventivo e un LinkedTxn al preventivo stesso. Intuit consente di collegare una sola fattura a ciascun preventivo, quindi la gestione delle consegne parziali viene concordata durante la definizione del perimetro.
• POST /timeactivity registra le ore consuntivate da ciascun operatore associandole al dipendente, al cliente e a un articolo di servizio. Le ore fatturabili possono poi essere aggiunte alla fattura in QuickBooks.
• POST /inventoryadjustment aumenta le giacenze dei prodotti finiti e riduce quelle dei materiali utilizzati. Intuit mette a disposizione questa entità su QuickBooks Online Plus e Advanced negli Stati Uniti. (fonte)

4. Consuntivazione in reparto. Gli operatori registrano il lavoro con SkyPlanner Mobile Confirmations, Production Timer o Quick Log Mode. L’avanzamento aggiorna subito la schedulazione e Autopilot rischedula il lavoro restante. Le ore vengono inviate a QuickBooks come registrazioni delle ore. Se l’azienda mantiene QuickBooks Time per la gestione delle paghe, scegliete un solo canale per le ore delle operazioni durante la definizione del perimetro.

5. Responsabilità sui dati e regole per i conflitti. Mettetele per iscritto prima della messa in produzione:

• Gli ordini di vendita restano nelle schermate di QuickBooks. Plus e Advanced includono gli ordini di vendita nell’app, mentre l’integrazione legge i preventivi accettati oppure, per le aziende che fatturano prima di produrre, le fatture. Concordate un unico evento di avvio, così ogni ordine entra nello stesso modo.
• QuickBooks non gestisce i cicli di lavorazione. Mantenete in SkyPlanner le fasi di lavorazione di ciascun prodotto, collegate tramite chiave all’articolo QuickBooks.
• Una sola fattura collegata a ciascun preventivo. Per le consegne frazionate serve una regola, ad esempio un preventivo per ogni consegna.
• Rettifiche di magazzino in base al piano e all’area geografica. Negli Stati Uniti, Plus e Advanced le supportano. Negli altri paesi, concorda con il tuo contabile come registrare i prodotti finiti in QuickBooks.
• Ordini di produzione di Intuit Enterprise Suite. Se li usi, decidi quale sistema gestisce gli assemblaggi e le prenotazioni dei componenti.
• I bundle sono accessibili tramite API solo in lettura. Gli articoli di tipo Group non possono essere creati tramite API, quindi mantieni i bundle in QuickBooks.
• Rotazione del refresh token. Salva il refresh token più recente dopo ogni rinnovo, altrimenti la connessione si interrompe.