Leitfaden zur QuickBooks Online Schnittstelle für die Feinplanung mit SkyPlanner APS

QuickBooks Online ist ein mandantenfähiges Cloud-Produkt. Alle Unternehmen nutzen dieselbe Accounting API, eine REST API in der Version v3. Jeder Aufruf adressiert ein Unternehmen über dessen Realm-ID: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Für Tests steht ein separater Sandbox-Host bereit. Anfragen und Antworten verwenden JSON; über den Parameter minorversion wird die Schemaversion ausgewählt. (Quelle)

Für die Feinplanung sind folgende Entitäten relevant:

• Stammdaten: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Bedarf: Estimate (TxnStatus Accepted, Positionen, ShipDate) sowie Invoice oder SalesReceipt für Betriebe, die vorab abrechnen.
• Versorgung: PurchaseOrder (POStatus Open, Positionen mit Artikeln und Mengen), Bill.
• Rückschreiben: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Lesezugriffe erfolgen über den Query-Endpunkt, zum Beispiel select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Teilaktualisierungen sind möglich, sodass SkyPlanner nur die geänderten Felder sendet. Die Accounting API enthält keine Entitäten für Kundenaufträge, Arbeitspläne, Arbeitsstationen oder Fertigungsaufträge.

QuickBooks-Webhooks benachrichtigen die App, wenn sich Daten eines angebundenen Unternehmens ändern. „Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.“ (Webhooks benachrichtigen Sie automatisch, sobald sich Daten in den QuickBooks Online-Unternehmensdateien Ihres Endnutzers ändern.) (Quelle) Für die Feinplanung sind folgende Entitäten relevant:

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

Zu den Operationen gehören Create, Update, Delete, Merge und Void. Eine Benachrichtigung enthält den Entitätsnamen, die ID, die Operation und den Zeitpunkt der letzten Änderung, nicht aber den vollständigen Datensatz. Diesen liest der Empfänger anschließend aus.

Change Data Capture (GET /cdc?entities=...&changedSince=...) liefert alle Änderungen seit einem angegebenen Zeitpunkt innerhalb eines begrenzten zurückliegenden Zeitfensters. SkyPlanner nutzt dies für einen nächtlichen Abgleich. So bleibt kein Auftrag wegen eines verpassten Webhooks auf einem veralteten Stand. TimeActivity wird von Change Data Capture nicht erfasst und deshalb über eine Abfrage abgeglichen. (Quelle)

1. Erstimport der Stammdaten. Lesen Sie Kunden, Artikel, Mitarbeiter und offene Bestellungen seitenweise über den Query-Endpunkt aus. Legen Sie Kunden in SkyPlanner mit der QuickBooks-ID als external_identifier an. Verwenden Sie für Produkte und Materialien die Artikel-ID als Schlüssel. Ergänzen Sie anschließend die Daten, die QuickBooks nicht verwaltet: Arbeitsstationen, Prozessschritte je Produkt, Schichten, Urlaub und Rüstzeiten. Für Prozessschritte ist der Import per CSV oder Excel der schnellste Weg.

2. Auftragssynchronisierung. Abonnieren Sie Webhooks für Estimate, Invoice, Item und PurchaseOrder. Sobald ein Angebot den Status Accepted erhält, liest SkyPlanner es aus und legt einen Auftrag an. Die Angebotsnummer wird als external_order_number und das Versanddatum als delivery_date übernommen. Aus jeder Position entstehen Arbeitsgänge entsprechend den Prozessschritten des Produkts. Offene Bestellpositionen werden als erwartete Materialzugänge übernommen, sodass Arbeitsgänge bis zur Lieferung warten. Der nächtliche Abgleich per Change Data Capture erfasst alle verpassten Ereignisse.

3. Planungs- und Abschlussdaten zurückschreiben. Vier Aufrufe übertragen die Ergebnisse nach QuickBooks:

• Eine Teilaktualisierung von Estimate schreibt ShipDate, damit der zugesagte Termin in QuickBooks dem Plan entspricht.
• Bei Auftragsabschluss erstellt POST /invoice die Rechnung mit den Angebotspositionen und einem LinkedTxn zum Angebot. Intuit erlaubt je Angebot eine Rechnungsverknüpfung. Der Umgang mit Teillieferungen wird daher bei der Anforderungsaufnahme vereinbart.
• POST /timeactivity erfasst die protokollierten Stunden jedes Bedieners mit Bezug zum Mitarbeiter, zum Kunden und zu einem Dienstleistungsartikel. Abrechenbare Stunden können anschließend in QuickBooks zur Rechnung hinzugefügt werden.
• POST /inventoryadjustment erhöht den Bestand an Fertigerzeugnissen und reduziert den Bestand der verbrauchten Materialien. Intuit stellt diese Entität in den USA für QuickBooks Online Plus und Advanced bereit. (Quelle)

4. Rückmeldungen aus der Fertigung. Bediener erfassen ihre Arbeit mit SkyPlanner Mobile Confirmations, Production Timer oder Quick Log Mode. Der Fortschritt fließt sofort in den Plan ein, und Autopilot plant die übrigen Arbeiten neu. Die Stunden werden als Zeiteinträge an QuickBooks übertragen. Wenn ein Betrieb QuickBooks Time weiterhin für die Lohnabrechnung nutzt, legen Sie bei der Anforderungsaufnahme einen einzigen Übertragungsweg für die Arbeitsgangstunden fest.

5. Datenhoheit und Konfliktregeln. Halten Sie diese vor dem Produktivstart schriftlich fest:

• Kundenaufträge bleiben in der QuickBooks-Oberfläche. Plus und Advanced bieten Kundenaufträge in der Anwendung. Die Schnittstelle liest hingegen angenommene Angebote oder, bei Betrieben mit vorgelagerter Rechnungsstellung, Rechnungen ein. Legen Sie einen einheitlichen Auslöser fest, damit jeder Auftrag auf demselben Weg übernommen wird.
• Keine Arbeitspläne in QuickBooks. Pflegen Sie die Prozessschritte je Produkt in SkyPlanner und verknüpfen Sie sie über den Artikelschlüssel mit dem QuickBooks-Artikel.
• Eine Rechnung je Angebotsverknüpfung. Für Teillieferungen brauchen Sie eine Regel, etwa ein Angebot pro Lieferung.
• Bestandskorrekturen hängen von Tarif und Region ab. In den USA unterstützen Plus und Advanced diese Funktion. In anderen Regionen stimmen Sie mit Ihrer Buchhaltung ab, wie Fertigerzeugnisse in QuickBooks erfasst werden.
• Fertigungsaufträge in Intuit Enterprise Suite. Wenn Sie diese nutzen, legen Sie fest, welches System für Fertigungen und Komponentenreservierungen führend ist.
• Bundles sind über die API nur lesbar. Group-Artikel lassen sich nicht über die API anlegen. Pflegen Sie Bundles deshalb in QuickBooks.
• Rotation der Refresh Tokens. Speichern Sie nach jeder Aktualisierung das neueste Refresh Token, sonst bricht die Verbindung ab.