Panduan Integrasi QuickBooks Online untuk Penjadwalan Produksi dengan SkyPlanner APS

QuickBooks Online merupakan satu produk cloud multitenan, dan setiap perusahaan menggunakan Accounting API yang sama. API ini adalah REST API versi v3. Setiap panggilan mengakses satu perusahaan berdasarkan realm ID-nya: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}, dengan host sandbox terpisah untuk pengujian. Permintaan dan respons menggunakan JSON, sedangkan versi skema dipilih melalui parameter minorversion. (sumber)

Entitas yang diperlukan untuk penjadwalan:

• Master data: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Permintaan: Estimate (TxnStatus Accepted, baris rincian, ShipDate), serta Invoice atau SalesReceipt untuk pabrik yang menagih lebih dahulu.
• Pasokan: PurchaseOrder (POStatus Open, baris rincian berisi item dan jumlah), Bill.
• Penulisan balik: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Data dibaca melalui endpoint kueri, misalnya select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Pembaruan dapat dilakukan secara parsial, sehingga SkyPlanner hanya mengirim field yang diubah. Accounting API tidak memiliki entitas pesanan penjualan, routing, work center, atau perintah produksi.

Webhook QuickBooks memberi tahu aplikasi saat data di perusahaan yang terhubung berubah. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.” (Webhook secara otomatis memberi tahu Anda setiap kali data berubah dalam berkas perusahaan QuickBooks Online milik pengguna akhir Anda.) (sumber) Entitas yang relevan untuk penjadwalan:

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

Operasi yang tersedia mencakup Create, Update, Delete, Merge, dan Void. Notifikasi memuat nama entitas, ID, operasi, dan waktu pembaruan terakhir, bukan rekaman lengkap. Penerima kemudian membaca rekaman tersebut.

Penangkapan perubahan data (GET /cdc?entities=...&changedSince=...) mengembalikan semua perubahan sejak stempel waktu tertentu, tetapi hanya untuk rentang waktu terkini. SkyPlanner menggunakannya untuk rekonsiliasi setiap malam, sehingga data pesanan selalu diperbarui meskipun ada webhook yang terlewat. TimeActivity tidak tercakup dalam penangkapan perubahan data, sehingga rekonsiliasinya menggunakan kueri. (sumber)

1. Pemuatan awal master data. Ambil data pelanggan, item, karyawan, dan pesanan pembelian yang masih terbuka halaman demi halaman melalui endpoint kueri. Buat pelanggan di SkyPlanner dengan ID QuickBooks sebagai external_identifier, serta produk dan material dengan ID item sebagai kunci. Lalu siapkan data yang tidak disimpan di QuickBooks: stasiun kerja, tahapan proses per produk, sif, cuti, dan waktu penyiapan. Impor CSV atau Excel adalah cara tercepat untuk memasukkan tahapan proses.

2. Sinkronisasi pesanan. Berlangganan webhook Estimate, Invoice, Item, dan PurchaseOrder. Saat status penawaran berubah menjadi Accepted, SkyPlanner membacanya dan membuat pesanan dengan nomor penawaran sebagai external_order_number dan tanggal pengiriman sebagai delivery_date. Setiap baris rincian menjadi serangkaian job yang mengikuti tahapan proses produk. Baris rincian pesanan pembelian yang masih terbuka menjadi material yang akan datang, sehingga job menunggu kiriman tersebut. Penangkapan perubahan data setiap malam menjaring peristiwa yang terlewat.

3. Penulisan balik jadwal dan penyelesaian. Empat panggilan memasukkan hasilnya ke QuickBooks:

• Pembaruan parsial pada Estimate mengisi ShipDate, sehingga tanggal yang dijanjikan di QuickBooks mengikuti rencana.
• Saat pesanan selesai, POST /invoice membuat faktur berisi baris rincian penawaran dan LinkedTxn ke penawaran tersebut. Intuit mengizinkan satu tautan faktur per penawaran, sehingga penanganan pengiriman parsial disepakati saat penentuan lingkup.
• POST /timeactivity mencatat jam kerja yang dilaporkan setiap operator dengan mengaitkannya ke karyawan, pelanggan, dan item jasa. Jam kerja yang dapat ditagihkan kemudian bisa ditambahkan ke faktur di QuickBooks.
• POST /inventoryadjustment menambah stok barang jadi dan mengurangi stok material yang terpakai. Intuit menyediakan entitas ini di QuickBooks Online Plus dan Advanced di AS. (sumber)

4. Konfirmasi dari lantai produksi. Operator mencatat pekerjaan menggunakan SkyPlanner Mobile Confirmations, Production Timer, atau Quick Log Mode. Progres langsung memperbarui jadwal, lalu Autopilot merencanakan ulang pekerjaan yang tersisa. Jam kerja dikirim ke QuickBooks sebagai aktivitas waktu. Jika pabrik tetap menggunakan QuickBooks Time untuk penggajian, pilih satu saluran untuk mencatat jam kerja setiap job saat penentuan lingkup.

5. Aturan kepemilikan data dan penanganan konflik. Dokumentasikan aturan ini sebelum sistem mulai digunakan:

• Pesanan penjualan tetap di antarmuka QuickBooks. Plus dan Advanced menyediakan pesanan penjualan di aplikasi, sedangkan integrasi membaca penawaran yang diterima, atau faktur untuk pabrik yang menagih lebih dahulu. Sepakati satu pemicu agar setiap pesanan masuk dengan cara yang sama.
• QuickBooks tidak menyimpan routing. Simpan langkah proses per produk di SkyPlanner dan hubungkan dengan kunci item QuickBooks.
• Setiap penawaran hanya dapat ditautkan ke satu faktur. Pengiriman bertahap memerlukan aturan, misalnya satu penawaran untuk setiap pengiriman.
• Penyesuaian persediaan bergantung pada paket dan wilayah. Plus dan Advanced di AS mendukungnya. Di wilayah lain, sepakati dengan akuntan Anda cara mencatat barang jadi di QuickBooks.
• Perintah produksi Intuit Enterprise Suite. Jika Anda menggunakannya, tentukan sistem yang menjadi pemilik data perakitan dan reservasi komponen.
• Bundel hanya dapat dibaca melalui API. Item Group tidak dapat dibuat melalui API, jadi tetap kelola bundel di QuickBooks.
• Rotasi refresh token. Simpan refresh token terbaru setiap kali token diperbarui. Jika tidak, koneksi akan terputus.