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

Xero, çok kiracılı tek bir bulut ürünüdür ve tüm kuruluşlar aynı API’yi kullanır. Accounting API, https://api.xero.com/api.xro/2.0/ adresinde sunulan, JSON veya XML ile çalışan bir REST API’dir. Her çağrıda kuruluş, Xero-tenant-id başlığında belirtilir. (kaynak)

Çizelgeleme için gereken uç noktalar:

• Ana veriler: /Contacts (müşteriler ve tedarikçiler), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Talep: /Quotes (Status değeri ACCEPTED, LineItems) ve önce fatura kesen atölyeler için Type değeri ACCREC olan /Invoices.
• Tedarik: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, ItemCode içeren LineItems).
• Geri yazma: /Quotes/{QuoteID}/History, /Invoices, /Quotes ve https://api.xero.com/projects.xro/2.0/projects/{projectId}/time adresindeki Projects API.

Tüm liste uç noktaları If-Modified-Since başlığını kabul eder; böylece her eşitlemede yalnızca değişen veriler okunur. Oluşturma ve güncelleme işlemleri toplu olarak yapılır. Ürün ağacı, rota veya üretim emri için uç nokta yoktur.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhook’lar, Xero’da gerçekleşen belirli olaylara abone olmanızı sağlar.) (kaynak) Çizelgeleme açısından önemli olaylar Contact ve Invoice olaylarıdır; her ikisi için de CREATE ve UPDATE bulunur.

Nasıl çalışırlar:

• Her uygulama için tek bir webhook, bağlı tüm kuruluşları kapsar.
• Her bildirimde, kaynak kimliğini ve olay türünü içeren bir events dizisi bulunur. Alıcı daha sonra kaynağı okur.
• Her bildirim, uygulamanın webhook anahtarından oluşturulan x-xero-signature başlığıyla imzalanır. Xero, bildirim göndermeye başlamadan önce bir “Intent to receive” (bildirim almaya hazır olma) kontrolü gönderir.
• Xero, başarısız bildirimleri yeniden gönderir ve sürekli başarısız olan webhook’u devre dışı bırakır. Bu nedenle alıcı hızlıca yanıt verir, asıl işlemi daha sonra yapar.

Teklifler, kalemler ve satın alma siparişleri için webhook olayı yoktur. SkyPlanner bunları kısa aralıklarla If-Modified-Since kullanarak sorgular. Hiçbir şey değişmediyse her varlık türü için yalnızca bir çağrı gerekir.

1. Ana verilerin ilk yüklemesi. Müşteri ve tedarikçi kayıtları ile kalemleri sayfa sayfa okuyun; ardından açık satın alma siparişlerini ve kabul edilmiş teklifleri alın. SkyPlanner’da müşterileri oluştururken Xero ContactID değerini external_identifier olarak kullanın. Ürün ve malzemeleri oluştururken anahtar olarak kalem kodunu kullanın. Ardından Xero’da bulunmayan verileri 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 aktarmaktır.

2. Sipariş eşitleme. Teklifleri If-Modified-Since ile periyodik olarak sorgulayın. Bir teklifin durumu ACCEPTED olduğunda SkyPlanner, teklif numarasını external_order_number olarak kullanarak bir sipariş oluşturur. delivery_date, atölyenizin taahhüt edilen tarih için kullandığı alandan alınır; bu alan devreye alma sürecinde eşlenir. Her teklif satırı, ürünün işlem adımlarına göre işlere dönüştürülür. Satın alma siparişi satırları, beklenen varış tarihinde gelecek malzeme olarak işlenir; böylece işler teslimatı bekler. Açık tekliflerin ve satın alma siparişlerinin her gece tümüyle okunması, gözden kaçan değişiklikleri yakalar.

3. Çizelge ve tamamlanma bilgilerinin geri yazılması. Sonuçlar üç çağrıyla Xero’ya aktarılır:

• PUT /Quotes/{QuoteID}/History, planlanan bitiş tarihini içeren bir not ekler. Kabul edilmiş bir teklifte yalnızca müşteri bilgileri ve notlar değiştirilebildiği için tarih, geçmiş notunda tutulur. (kaynak)
• Sipariş tamamlandığında POST /Invoices bir satış faturası oluşturur. Faturada Type değeri ACCREC, Status değeri DRAFT olur; teklifteki müşteri ve satır kalemleri kullanılır, Reference alanına teklif numarası yazılır. Muhasebe sorumlunuz faturayı Xero’da onaylar ve gönderir.
• QuoteID ve INVOICED değerindeki Status ile yapılan POST /Quotes çağrısı teklifi kapatır. Accepted durumundan Invoiced durumuna geçiş, Accounting API’de geçerli bir durum değişikliğidir.

4. Üretim sahası bildirimleri ve proje süreleri. Operatörler, SkyPlanner Mobile Confirmations, Production Timer veya Quick Log Mode ile yaptıkları çalışmaları kaydeder. İlerleme bilgisi çizelgeyi anında günceller; Autopilot kalan işleri yeniden planlar. Proje işlerinde SkyPlanner, çalışma saatlerini Xero kullanıcısı, tarih ve süre bilgileriyle birlikte ilgili proje görevine süre kaydı olarak gönderir. (kaynak)

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

• Xero’da üretim nesneleri bulunmaz. Ürün bazında işlem adımlarını, Xero stok koduyla ilişkilendirerek SkyPlanner’da tutun. Stok kodlarını değiştirmeyin.
• Teklifler için webhook yoktur. Dakikalık ve günlük sınırları aşmadan, If-Modified-Since ile kısa aralıklarla sorgulama yapın.
• Kabul edilen teklifler kilitlenir. Kabulden sonra yalnızca müşteri bilgileri ve notlar değiştirilebilir. Bu nedenle taahhüt edilen tarih, kabul sırasında bir kez okunur; planlanan tarih ise geçmişe not olarak yazılır.
• Stok, faturalara göre güncellenir. Xero, takibi yapılan stok kalemlerinin eldeki miktarını satış faturaları, alış faturaları ve alacak dekontları üzerinden günceller. Mamullerin ve kullanılan malzemelerin nasıl muhasebeleştirileceğini muhasebecinizle kararlaştırın.
• Proje sürelerini kaydetmek için Xero kullanıcısı olmak gerekir. Her süre kaydı bir Xero kullanıcısına aittir. Hangi operatörlerin sürelerini Xero Projects’e kaydedeceğini belirleyin; diğerlerinin kayıtlarını SkyPlanner’da tutun.
• Ayrıntılı yetki kapsamları. Geniş yetki kapsamları kullanımdan kaldırıldığı için en baştan ayrıntılı yetki kapsamları talep edin.
• Uygulama kademesi. İş ortaklığı kademesi, bir uygulamanın kaç kuruluşa bağlanabileceğini ve günde kaç API çağrısı yapabileceğini belirler. Kademeyi tesis sayınıza göre planlayın.