SkyPlanner APS ile Üretim Çizelgeleme için QuickBooks Online Entegrasyon Kılavuzu

QuickBooks Online, çok kiracılı tek bir bulut ürünüdür ve tüm şirketler aynı Accounting API’yi kullanır. Bu, v3 sürümünde bir REST API’dir. Her çağrı, realm ID ile tek bir şirkete yöneltilir: https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}. Testler için ayrı bir sandbox sunucusu bulunur. İstekler ve yanıtlar JSON biçimindedir; şema sürümü minorversion parametresiyle seçilir. (kaynak)

Üretim çizelgeleme için gereken nesneler:

• Ana veriler: Customer, Item (Inventory, NonInventory, Service), Employee, Vendor.
• Talep: Estimate (TxnStatus değeri Accepted, satırlar, ShipDate); önce faturalandırma yapan işletmeler için de Invoice veya SalesReceipt.
• Tedarik: PurchaseOrder (POStatus değeri Open, ürün ve miktar bilgisi içeren satırlar), Bill.
• Geri yazma: Estimate, Invoice, TimeActivity, InventoryAdjustment.

Okuma işlemleri query uç noktasını kullanır; örneğin select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'. Kısmi güncellemeler desteklendiği için SkyPlanner yalnızca değiştirdiği alanları gönderir. Accounting API’de satış siparişi, rota, iş merkezi veya üretim emri nesnesi bulunmaz.

QuickBooks webhook’ları, bağlı bir şirkette veriler değiştiğinde uygulamaya bildirim gönderir. “Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.” (Webhook’lar, son kullanıcınızın QuickBooks Online şirket dosyalarındaki veriler her değiştiğinde sizi otomatik olarak bilgilendirir.) (kaynak) Çizelgeleme açısından önemli nesneler:

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

Desteklenen işlemler arasında Create, Update, Delete, Merge ve Void bulunur. Bildirim, kaydın tamamını değil; nesne adını, ID’yi, işlemi ve son güncelleme zamanını içerir. Alıcı, daha sonra kaydı okur.

Değişiklik yakalama (GET /cdc?entities=...&changedSince=...), yakın geçmişteki bir zaman aralığında, belirtilen zaman damgasından bu yana değişen tüm verileri döndürür. SkyPlanner bunu her gece veri mutabakatı için kullanır; böylece kaçırılan bir webhook nedeniyle hiçbir sipariş güncelliğini yitirmiş halde kalmaz. TimeActivity, değişiklik yakalama kapsamına girmediği için bu nesnenin mutabakatı sorguyla yapılır. (kaynak)

1. Ana verilerin ilk yüklemesi. Query uç noktasıyla müşterileri, ürün ve hizmet kalemlerini, çalışanları ve açık satın alma siparişlerini sayfalar halinde alın. SkyPlanner müşterilerini oluştururken QuickBooks ID’sini external_identifier olarak, ürünleri ve malzemeleri oluştururken de kalem ID’sini anahtar olarak kullanın. Ardından QuickBooks’ta tutulmayan bilgileri tanımlayın: iş merkezleri, ürün bazında işlem adımları, vardiyalar, izinler ve hazırlık süreleri. İşlem adımları için en hızlı yol, CSV veya Excel’den içe aktarmadır.

2. Sipariş eşitleme. Estimate, Invoice, Item ve PurchaseOrder webhook’larına abone olun. Bir teklifin durumu Accepted olduğunda SkyPlanner teklifi okur ve teklif numarasını external_order_number, sevkiyat tarihini ise delivery_date olarak kullanarak bir sipariş oluşturur. Her satır, ürünün işlem adımlarına göre işlere dönüştürülür. Açık satın alma siparişi satırları gelecek malzeme olarak kaydedilir; böylece işler teslimatı bekler. Her gece çalışan değişiklik yakalama, kaçırılan tüm olayları yakalar.

3. Çizelge ve tamamlanma bilgilerinin geri yazılması. Sonuçlar dört çağrıyla QuickBooks’a aktarılır:

• Estimate üzerindeki kısmi güncelleme, ShipDate alanına yazar; böylece QuickBooks’ta taahhüt edilen tarih planla uyumlu kalır.
• Sipariş tamamlandığında POST /invoice, teklifin satırlarını içeren ve LinkedTxn ile teklife bağlı bir fatura oluşturur. Intuit her teklif için tek bir fatura bağlantısına izin verir; bu nedenle kısmi teslimatların nasıl ele alınacağı kapsam belirleme aşamasında kararlaştırılır.
• POST /timeactivity, her operatörün kaydettiği çalışma saatlerini çalışan, müşteri ve bir hizmet kalemiyle ilişkilendirerek kaydeder. Faturalandırılabilir saatler daha sonra QuickBooks’ta faturaya eklenebilir.
• POST /inventoryadjustment, mamul stoklarını artırır ve kullanılan malzemelerin stoklarını azaltır. Intuit bu nesneyi ABD’de QuickBooks Online Plus ve Advanced sürümlerinde sunar. (kaynak)

4. Üretim sahasından gerçekleşen iş bildirimleri. Operatörler, SkyPlanner Mobile Confirmations, Production Timer veya Quick Log Mode ile çalışmalarını kaydeder. İlerleme bilgisi çizelgeyi anında günceller; Autopilot da kalan işleri yeniden planlar. Çalışma saatleri QuickBooks’a süre kayıtları olarak aktarılır. İşletme bordro için QuickBooks Time kullanmaya devam ediyorsa kapsam belirleme aşamasında iş süreleri için tek bir kayıt kanalı seçin.

5. Veri sahipliği ve çakışma kuralları. Canlıya geçmeden önce bunları yazılı hale getirin:

• Satış siparişleri QuickBooks ekranlarında kalır. Plus ve Advanced paketlerinde satış siparişleri uygulamada yer alır. Entegrasyon ise kabul edilmiş teklifleri veya önce fatura kesen işletmelerde faturaları okur. Tüm siparişlerin aynı yoldan aktarılması için tek bir tetikleyici üzerinde anlaşın.
• QuickBooks’ta rota bulunmaz. Ürün bazında işlem adımlarını, ilgili QuickBooks kalemiyle eşleştirerek SkyPlanner’da tutun.
• Her teklife tek bir fatura bağlanır. Kısmi teslimatlar için her teslimata ayrı teklif açılması gibi bir kural belirlemek gerekir.
• Stok düzeltmeleri pakete ve bölgeye bağlıdır. ABD’deki Plus ve Advanced paketleri bu işlemleri destekler. Diğer bölgelerde mamullerin QuickBooks’a nasıl kaydedileceğini muhasebecinizle kararlaştırın.
• Intuit Enterprise Suite üretim emirleri. Bunları kullanıyorsanız üretim ve bileşen rezervasyonu kayıtlarının hangi sistemde yönetileceğine karar verin.
• Paketler API üzerinden yalnızca okunabilir. API üzerinden grup kalemleri oluşturulamaz; bu nedenle paketleri QuickBooks’ta tutun.
• Yenileme belirtecinin değişmesi. Her yenilemeden sonra en son yenileme belirtecini saklayın; aksi takdirde bağlantı kesilir.