Panduan Integrasi Xero untuk Penjadwalan Produksi dengan SkyPlanner APS

Xero merupakan satu produk cloud multitenan, dan semua organisasi menggunakan API yang sama. Accounting API adalah REST API di https://api.xero.com/api.xro/2.0/ yang menggunakan JSON atau XML. Setiap panggilan mencantumkan organisasi dalam header Xero-tenant-id. (sumber)

Endpoint yang dibutuhkan untuk penjadwalan:

• Master data: /Contacts (pelanggan dan pemasok), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Permintaan: /Quotes (Status ACCEPTED, LineItems), serta /Invoices dengan Type ACCREC untuk bengkel produksi yang menerbitkan faktur terlebih dahulu.
• Pasokan: /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems dengan ItemCode).
• Penulisan balik: /Quotes/{QuoteID}/History, /Invoices, /Quotes, serta Projects API di https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Setiap endpoint daftar menerima header If-Modified-Since, sehingga setiap sinkronisasi hanya membaca data yang berubah. Pembuatan dan pembaruan data dilakukan secara batch. Tidak ada endpoint untuk daftar kebutuhan bahan, routing, atau perintah produksi.

“Webhooks allow you to subscribe to certain events that happen in Xero.” (Webhook memungkinkan Anda berlangganan notifikasi peristiwa tertentu di Xero.) (sumber) Peristiwa yang relevan untuk penjadwalan adalah Contact dan Invoice, masing-masing dengan CREATE dan UPDATE.

Cara kerjanya:

• Satu webhook per aplikasi mencakup semua organisasi yang terhubung.
• Setiap pengiriman memuat array events dengan ID sumber daya dan jenis peristiwanya. Penerima kemudian membaca sumber daya tersebut.
• Setiap pengiriman ditandatangani melalui header x-xero-signature yang dibuat dari kunci webhook aplikasi. Xero mengirim pemeriksaan “Intent to receive” sebelum mulai mengirim notifikasi.
• Xero mencoba ulang pengiriman yang gagal dan menonaktifkan webhook yang terus gagal. Karena itu, penerima merespons dengan cepat lalu memprosesnya setelah itu.

Penawaran, barang, dan pesanan pembelian tidak memiliki peristiwa webhook. SkyPlanner membacanya melalui polling berkala dengan interval singkat menggunakan If-Modified-Since. Jika tidak ada perubahan, polling ini membutuhkan satu panggilan per entitas.

1. Pemuatan awal master data. Baca kontak dan barang halaman demi halaman, lalu pesanan pembelian yang masih terbuka dan penawaran yang telah diterima. Buat pelanggan di SkyPlanner dengan ContactID Xero sebagai external_identifier, serta produk dan bahan dengan kode barang sebagai kunci. Selanjutnya, siapkan data yang tidak disimpan Xero: 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. Lakukan polling penawaran menggunakan If-Modified-Since. Saat status penawaran menjadi ACCEPTED, SkyPlanner membuat pesanan dengan nomor penawaran sebagai external_order_number. Nilai delivery_date diambil dari field yang digunakan bengkel produksi Anda untuk tanggal yang dijanjikan. Field ini dipetakan selama penyiapan awal. Setiap baris item diubah menjadi job sesuai tahapan proses produk. Setiap baris pesanan pembelian dicatat sebagai penerimaan bahan pada tanggal perkiraan kedatangannya, sehingga job menunggu bahan tersebut tiba. Setiap malam, semua penawaran dan pesanan pembelian yang masih terbuka dibaca ulang untuk menemukan data yang terlewat.

3. Penulisan balik jadwal dan data penyelesaian. Tiga panggilan mengirim hasilnya ke Xero:

• PUT /Quotes/{QuoteID}/History menambahkan catatan berisi tanggal selesai yang direncanakan. Penawaran yang telah diterima hanya mengizinkan perubahan kontak dan catatan, sehingga tanggal tersebut disimpan dalam catatan riwayat. (sumber)
• Saat pesanan selesai, POST /Invoices membuat faktur penjualan dengan Type ACCREC, Status DRAFT, kontak dan rincian item dari penawaran, serta nomor penawaran sebagai Reference. Staf pembukuan Anda menyetujui dan mengirimkannya di Xero.
• POST /Quotes dengan QuoteID dan Status INVOICED menutup penawaran. Perubahan status dari Accepted ke Invoiced diperbolehkan dalam Accounting API.

4. Konfirmasi di lantai produksi dan waktu proyek. Operator mencatat pekerjaan menggunakan SkyPlanner Mobile Confirmations, Production Timer, atau Quick Log Mode. Kemajuan pekerjaan langsung memperbarui jadwal, lalu Autopilot menjadwalkan ulang sisanya. Untuk pekerjaan proyek, SkyPlanner mengirim jam kerja sebagai entri waktu pada tugas proyek, lengkap dengan pengguna Xero, tanggal, dan durasi. (sumber)

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

• Xero tidak memiliki objek produksi. Simpan tahapan proses per produk di SkyPlanner dengan kode item Xero sebagai kuncinya. Jangan mengubah kode item tersebut.
• Penawaran tidak memiliki webhook. Lakukan polling dengan If-Modified-Since pada interval pendek, tanpa melampaui batas per menit dan per hari.
• Penawaran yang diterima dikunci. Setelah diterima, hanya detail kontak dan catatan yang dapat diubah. Karena itu, tanggal yang dijanjikan dibaca satu kali saat penawaran diterima, sedangkan tanggal yang direncanakan ditulis sebagai catatan riwayat.
• Stok mengikuti faktur penjualan dan tagihan pembelian. Xero memperbarui jumlah stok yang tersedia melalui faktur penjualan, tagihan pembelian, dan nota kredit untuk item yang stoknya dilacak. Sepakati dengan staf pembukuan cara mencatat barang jadi dan bahan yang digunakan.
• Pencatatan waktu proyek memerlukan pengguna Xero. Setiap entri waktu terkait dengan pengguna Xero. Tentukan operator mana yang mencatat waktu ke Xero Projects, dan simpan catatan operator lainnya di SkyPlanner.
• Cakupan izin terperinci. Minta cakupan izin yang terperinci sejak awal karena cakupan izin yang luas sedang dihentikan.
• Tingkat aplikasi. Tingkat kemitraan menentukan jumlah organisasi yang dapat dihubungkan oleh aplikasi dan jumlah panggilan API yang diizinkan per hari. Rencanakan tingkat tersebut sesuai jumlah pabrik.