Οδηγός διασύνδεσης του QuickBooks Online για χρονοπρογραμματισμό παραγωγής με το SkyPlanner APS

Το QuickBooks Online είναι ένα ενιαίο προϊόν cloud με αρχιτεκτονική πολλαπλών μισθωτών και όλες οι εταιρείες χρησιμοποιούν το ίδιο Accounting API. Πρόκειται για REST API, έκδοσης v3. Κάθε κλήση απευθύνεται σε μία εταιρεία μέσω του realm ID της: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Για τις δοκιμές υπάρχει ξεχωριστός διακομιστής sandbox. Τα αιτήματα και οι αποκρίσεις είναι σε JSON, ενώ η παράμετρος minorversion επιλέγει την έκδοση του σχήματος. (πηγή)

Οι οντότητες που χρειάζονται για τον χρονοπρογραμματισμό:

• Βασικά δεδομένα: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Ζήτηση: Estimate (TxnStatus Accepted, γραμμές, ShipDate) και, για μονάδες που τιμολογούν πρώτα, Invoice ή SalesReceipt.
• Εφοδιασμός: PurchaseOrder (POStatus Open, γραμμές με είδη και ποσότητες), Bill.
• Επιστροφή δεδομένων: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Η ανάγνωση γίνεται μέσω του endpoint ερωτημάτων, για παράδειγμα select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Υποστηρίζονται επιλεκτικές ενημερώσεις, οπότε το SkyPlanner στέλνει μόνο τα πεδία που αλλάζει. Το Accounting API δεν διαθέτει οντότητες για παραγγελίες πώλησης, φασεολόγια, κέντρα εργασίας ή εντολές παραγωγής.

Τα webhooks του QuickBooks ειδοποιούν την εφαρμογή όταν αλλάζουν δεδομένα σε μια συνδεδεμένη εταιρεία. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.” (Τα webhooks σάς ειδοποιούν αυτόματα κάθε φορά που αλλάζουν δεδομένα στα αρχεία εταιρείας του τελικού χρήστη σας στο QuickBooks Online.) (πηγή) Οι οντότητες που ενδιαφέρουν τον χρονοπρογραμματισμό είναι:

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

Οι ενέργειες περιλαμβάνουν Create, Update, Delete, Merge και Void. Η ειδοποίηση περιέχει το όνομα της οντότητας, το ID, την ενέργεια και τον χρόνο τελευταίας ενημέρωσης, όχι ολόκληρη την εγγραφή. Ο παραλήπτης διαβάζει την εγγραφή στη συνέχεια.

Η καταγραφή αλλαγών δεδομένων (GET /cdc?entities=...&changedSince=...) επιστρέφει όλες τις αλλαγές από μια χρονική σήμανση και μετά, με δυνατότητα αναδρομής σε περιορισμένο πρόσφατο διάστημα. Το SkyPlanner τη χρησιμοποιεί κάθε νύχτα για συμφωνία δεδομένων, ώστε ακόμη και αν χαθεί ένα webhook, καμία παραγγελία να μη μένει χωρίς ενημέρωση. Το TimeActivity δεν καλύπτεται από την καταγραφή αλλαγών δεδομένων, οπότε η συμφωνία των δεδομένων του γίνεται μέσω ερωτήματος. (πηγή)

1. Αρχική φόρτωση βασικών δεδομένων. Ανακτήστε σελίδα προς σελίδα τους πελάτες, τα είδη, τους εργαζομένους και τις ανοικτές εντολές αγοράς μέσω του endpoint ερωτημάτων. Δημιουργήστε πελάτες στο SkyPlanner με το QuickBooks ID ως external_identifier, καθώς και προϊόντα και υλικά με κλειδί το ID του είδους. Στη συνέχεια ορίστε όσα δεν τηρεί το QuickBooks: κέντρα εργασίας, φάσεις ανά προϊόν, βάρδιες, άδειες και χρόνους προετοιμασίας. Η εισαγωγή από CSV ή Excel είναι ο ταχύτερος τρόπος για τις φάσεις.

2. Συγχρονισμός παραγγελιών. Εγγραφείτε στα webhooks των Estimate, Invoice, Item και PurchaseOrder. Όταν μια προσφορά αποκτήσει κατάσταση Accepted, το SkyPlanner τη διαβάζει και δημιουργεί μια παραγγελία με τον αριθμό της προσφοράς ως external_order_number και την ημερομηνία αποστολής ως delivery_date. Κάθε γραμμή μετατρέπεται σε εργασίες που ακολουθούν τις φάσεις του προϊόντος. Οι γραμμές των ανοικτών εντολών αγοράς γίνονται αναμενόμενα υλικά, ώστε οι εργασίες να περιμένουν την παράδοση. Η νυχτερινή καταγραφή αλλαγών δεδομένων εντοπίζει κάθε συμβάν που χάθηκε.

3. Επιστροφή προγράμματος και στοιχείων ολοκλήρωσης. Τέσσερις κλήσεις μεταφέρουν τα αποτελέσματα στο QuickBooks:

• Μια επιλεκτική ενημέρωση του Estimate ενημερώνει το πεδίο ShipDate, ώστε η ημερομηνία που έχει υποσχεθεί η εταιρεία στον πελάτη και τηρείται στο QuickBooks να ακολουθεί το πρόγραμμα.
• Όταν ολοκληρωθεί η παραγγελία, η κλήση POST /invoice δημιουργεί το τιμολόγιο με τις γραμμές της προσφοράς και ένα LinkedTxn προς την προσφορά. Η Intuit επιτρέπει σύνδεση με ένα τιμολόγιο ανά προσφορά, οπότε ο χειρισμός των τμηματικών παραδόσεων συμφωνείται κατά τον καθορισμό εύρους.
• Η κλήση POST /timeactivity καταχωρίζει τις καταγεγραμμένες ώρες κάθε χειριστή, συνδέοντάς τες με τον εργαζόμενο, τον πελάτη και ένα είδος υπηρεσίας. Οι χρεώσιμες ώρες μπορούν στη συνέχεια να προστεθούν στο τιμολόγιο στο QuickBooks.
• Η κλήση POST /inventoryadjustment αυξάνει το απόθεμα έτοιμων προϊόντων και μειώνει το απόθεμα των υλικών που αναλώθηκαν. Η Intuit διαθέτει αυτή την οντότητα στα QuickBooks Online Plus και Advanced στις ΗΠΑ. (πηγή)

4. Επιβεβαιώσεις από τον χώρο παραγωγής. Οι χειριστές καταγράφουν την εργασία τους με το SkyPlanner Mobile Confirmations, το Production Timer ή το Quick Log Mode. Η πρόοδος ενημερώνει αμέσως το πρόγραμμα και το Autopilot επαναπρογραμματίζει τις υπόλοιπες εργασίες. Οι ώρες μεταφέρονται στο QuickBooks ως εγγραφές χρόνου. Αν η μονάδα διατηρεί το QuickBooks Time για τη μισθοδοσία, επιλέξτε ένα κανάλι για τις ώρες των εργασιών κατά τον καθορισμό εύρους.

5. Κανόνες ευθύνης δεδομένων και επίλυσης συγκρούσεων. Καταγράψτε τους πριν από την έναρξη λειτουργίας:

• Οι παραγγελίες πώλησης παραμένουν στις οθόνες του QuickBooks. Τα Plus και Advanced διαθέτουν παραγγελίες πώλησης μέσα στην εφαρμογή, ενώ η διασύνδεση διαβάζει αποδεκτές προσφορές ή τιμολόγια για μονάδες που τιμολογούν πριν από την παραγωγή. Συμφωνήστε σε ένα γεγονός ενεργοποίησης, ώστε κάθε παραγγελία να εισάγεται με τον ίδιο τρόπο.
• Το QuickBooks δεν διαθέτει φασεολόγια. Διατηρήστε τις φάσεις ανά προϊόν στο SkyPlanner, συνδεδεμένες με το αντίστοιχο είδος του QuickBooks.
• Κάθε προσφορά συνδέεται με ένα μόνο τιμολόγιο. Οι τμηματικές παραδόσεις χρειάζονται έναν κανόνα, όπως μία προσφορά ανά παράδοση.
• Προσαρμογές αποθέματος ανά πακέτο και περιοχή. Τα Plus και Advanced στις ΗΠΑ τις υποστηρίζουν. Στις άλλες περιοχές, συμφωνήστε με τον λογιστή σας πώς θα καταχωρίζονται τα έτοιμα προϊόντα στο QuickBooks.
• Εντολές παραγωγής του Intuit Enterprise Suite. Αν τις χρησιμοποιείτε, αποφασίστε ποιο σύστημα θα έχει την ευθύνη για τις παραγωγές και τις δεσμεύσεις εξαρτημάτων.
• Τα πακέτα ειδών είναι μόνο για ανάγνωση μέσω του API. Δεν είναι δυνατή η δημιουργία ειδών Group μέσω του API, οπότε διατηρήστε τα πακέτα ειδών στο QuickBooks.
• Εναλλαγή refresh token. Αποθηκεύετε το πιο πρόσφατο refresh token μετά από κάθε ανανέωση, διαφορετικά η σύνδεση διακόπτεται.