دليل تكامل Xero لجدولة الإنتاج باستخدام SkyPlanner APS
يوضح هذا الدليل لمستشاري Xero وفرق تقنية المعلومات كيفية ربط Xero بـSkyPlanner APS. يتكامل SkyPlanner مع Xero في الاتجاهين عبر Xero Accounting API وProjects API:
- تُستورد جهات الاتصال والأصناف التي يُتتبّع مخزونها مع الكميات المتاحة، وعروض الأسعار المقبولة، وأوامر الشراء مع تواريخ وصولها.
- يُعاد تاريخ الانتهاء المخطط له إلى Xero كملاحظة في سجل كل عرض أسعار.
- تُعاد الطلبات المكتملة إلى Xero كمسودات فواتير مبيعات تتضمن بنود عرض الأسعار ومرجعه، وتتغير حالة العرض إلى Invoiced.
- تُعاد ساعات العمل المسجلة على المشاريع إلى Xero Projects كقيود وقت.
- تُبلغ إشعارات الويب في Xero عن التغييرات في جهات الاتصال والفواتير، وتُرسل إشعارات الويب في SkyPlanner تغييرات الجدول فور حدوثها.
Xero برنامج محاسبة، لذا لا يحتفظ بقوائم المواد أو مسارات الإنتاج أو الآلات أو أوامر الإنتاج. وتُدار محطات العمل وخطوات العمليات والورديات وأوقات الإعداد في SkyPlanner. يتولى فريق SkyPlanner تهيئة التكامل مع مؤسستك في Xero خلال الإعداد الأولي، ويقدم الدعم بعد بدء التشغيل الفعلي. هذا الدليل موجه إلى المستشارين والمطورين الراغبين في المشاركة أو بناء حلول بأنفسهم باستخدام REST API الموثقة من SkyPlanner (مرجع API).
واجهة Xero Accounting API
Xero منتج سحابي واحد متعدد المستأجرين، وتستخدم جميع المؤسسات واجهة API نفسها. وAccounting API هي واجهة REST API على العنوان https://api.xero.com/api.xro/2.0/، وتدعم JSON أو XML. يحدد كل استدعاء المؤسسة في ترويسة Xero-tenant-id. (المصدر)
نقاط النهاية اللازمة لجدولة الإنتاج:
- البيانات الرئيسية:
/Contacts(العملاء والموردون)، و/Items(Code، IsTrackedAsInventory، QuantityOnHand). - الطلب:
/Quotes(Status بالقيمة ACCEPTED، وLineItems)، وللورش التي تصدر الفواتير أولاً،/Invoicesمع Type بالقيمة ACCREC. - التوريد:
/PurchaseOrders(DeliveryDate، ExpectedArrivalDate، وLineItems التي تتضمن ItemCode). - إعادة البيانات إلى Xero:
/Quotes/{QuoteID}/History، و/Invoices، و/Quotes، وProjects API على العنوانhttps://api.xero.com/projects.xro/2.0/projects/{projectId}/time.
تقبل كل نقطة نهاية لسرد البيانات ترويسة If-Modified-Since، لذا لا تقرأ كل مزامنة إلا ما تغير. وتُرسل عمليات الإنشاء والتحديث على دفعات. لا توجد نقطة نهاية لقوائم المواد أو مسارات الإنتاج أو أوامر الإنتاج.
المصادقة ونطاقات الصلاحيات والحدود
يستخدم Xero بروتوكول OAuth 2.0. يسجل مسؤول Xero الدخول مرة واحدة، ويوافق على التطبيق ويختار المؤسسة. يطلب التطبيق نطاق offline_access للحفاظ على الاتصال باستخدام رموز التحديث. (المصدر)
يستبدل Xero نطاقات الصلاحيات الواسعة بنطاقات أكثر تفصيلاً، وتحصل التطبيقات الجديدة على النطاقات التفصيلية. يحتاج تكامل الجدولة إلى:
accounting.invoicesلعروض الأسعار والفواتير وأوامر الشراء والأصنافaccounting.contactsللعملاء والموردينaccounting.settings.readلإعدادات الأصنافprojectsلقيود الوقتoffline_access
يضع Xero حدوداً للاستدعاءات لكل مؤسسة (المتزامنة، وفي الدقيقة، وفي اليوم) ولكل تطبيق، ويُرجع HTTP 429 مع ترويسة Retry-After عندما يتجاوز التطبيق الحد. يعتمد الحد اليومي وعدد المؤسسات المتصلة على فئة الشراكة الخاصة بالتطبيق. وكلاهما موضح في صفحة حدود API لدى Xero. تُبقي إشعارات الويب والقراءة باستخدام If-Modified-Since والكتابة على دفعات تكامل الجدولة بعيداً عن تجاوز هذه الحدود.
أما في SkyPlanner، فتستخدم REST API رمز API للمصادقة في ترويسة Authorization-Token (SkyPlanner Settings > API)، وهي موثقة في Swagger/OpenAPI. يشرح الدرس التطبيقي للتكامل كيفية إجراء الاستدعاءات الأولى.
إشعارات الويب
“Webhooks allow you to subscribe to certain events that happen in Xero.” (تتيح لك إشعارات الويب الاشتراك في أحداث معينة تقع في Xero.) (المصدر) الأحداث المهمة للجدولة هي Contact وInvoice، ولكل منهما CREATE وUPDATE.
آلية عملها:
- يكفي إعداد إشعار ويب واحد لكل تطبيق لتغطية جميع المؤسسات المتصلة.
- تتضمن كل رسالة مصفوفة أحداث تحتوي على معرّف المورد ونوع الحدث. ثم تقرأ الجهة المستقبلة المورد بعد ذلك.
- تُوقّع كل رسالة بترويسة
x-xero-signatureتُنشأ باستخدام مفتاح إشعارات الويب الخاص بالتطبيق. ويرسل Xero اختبار “Intent to receive” للتحقق من الاستعداد للاستقبال قبل بدء إرسال الإشعارات. - يعيد Xero محاولة إرسال الرسائل التي فشل تسليمها، ويعطّل إشعار الويب إذا استمر الفشل. لذلك ترد الجهة المستقبلة بسرعة ثم تنفذ المعالجة لاحقاً.
لا تتوفر أحداث إشعارات ويب لعروض الأسعار أو الأصناف أو أوامر الشراء. يقرأها SkyPlanner بالاستقصاء على فترات قصيرة باستخدام If-Modified-Since، وهو ما يستهلك استدعاءً واحداً لكل كيان عندما لا يتغير شيء.
تعيين البيانات
| كائن Xero (نقطة النهاية) | الكائن في SkyPlanner | الاتجاه | وتيرة التحديث |
|---|---|---|---|
Contact مع IsCustomer (/Contacts) | Customer (external_identifier، delivery_priority) | Xero → SkyPlanner | تحميل أولي، ثم عند ورود إشعار ويب |
Item، سواء كان مخزونه متتبّعاً أم لا، مع QuantityOnHand (/Items) | المنتجات والمواد والمخزون | Xero → SkyPlanner | تحميل أولي، ثم باستخدام If-Modified-Since |
Quote بحقل Status قيمته ACCEPTED، مع LineItems (/Quotes) | Order (external_order_number، delivery_date)، ومهام لكل بند | Xero → SkyPlanner | استقصاء باستخدام If-Modified-Since |
Invoice بحقل Type قيمته ACCREC (للورش التي تصدر الفواتير أولاً) (/Invoices) | Order والمهام | Xero → SkyPlanner | فورياً عبر إشعار ويب |
PurchaseOrder مع ExpectedArrivalDate أو DeliveryDate (/PurchaseOrders) | المواد الواردة (estimated_delivery_date) | Xero → SkyPlanner | استقصاء باستخدام If-Modified-Since |
ملاحظة في سجل عرض الأسعار (PUT /Quotes/{QuoteID}/History) | تاريخ الانتهاء المخطط له | SkyPlanner → Xero | عند تغير الجدول |
Invoice بحقل Type قيمته ACCREC، وStatus قيمته DRAFT، وReference = رقم عرض الأسعار (POST /Invoices) | الطلب المكتمل | SkyPlanner → Xero | عند اكتمال الطلب |
Quote بحقل Status قيمته INVOICED (POST /Quotes) | الطلب المكتمل | SkyPlanner → Xero | عند إنشاء الفاتورة |
قيد وقت في Projects (POST /projects/{projectId}/time) | Mobile Confirmations وسجلات الوقت | SkyPlanner → Xero | عند تسجيل العمل |
| غير موجود في Xero | محطات العمل، وخطوات العمليات، والورديات، والغياب، ومصفوفة أوقات الإعداد، والأدوات، وأعداد المشغّلين، ومحطات العمل البديلة | تُدار في SkyPlanner | تُهيّأ خلال الإعداد الأولي |
أنماط التكامل
1. التحميل الأولي للبيانات الرئيسية. اقرأ جهات الاتصال والأصناف صفحة تلو الأخرى، ثم أوامر الشراء المفتوحة وعروض الأسعار المقبولة. أنشئ العملاء في SkyPlanner باستخدام ContactID من Xero كقيمة لحقل external_identifier، والمنتجات والمواد باستخدام رمز الصنف كمفتاح. ثم أنشئ ما لا يحتفظ به Xero: محطات العمل، وخطوات العمليات لكل منتج، والورديات، والإجازات، وأوقات الإعداد. الاستيراد من CSV أو Excel هو أسرع طريقة لإدخال خطوات العمليات.
2. مزامنة الطلبات. استقصِ عروض الأسعار باستخدام If-Modified-Since. عندما تتغير حالة عرض أسعار إلى ACCEPTED، ينشئ SkyPlanner طلباً مستخدماً رقم العرض كقيمة لحقل external_order_number. وتأتي قيمة delivery_date من الحقل الذي تستخدمه ورشتك لموعد التسليم المتعهد به، ويُحدد هذا التعيين خلال الإعداد الأولي. يتحول كل بند إلى مهام وفق خطوات عمليات المنتج. وتتحول بنود أوامر الشراء إلى مواد واردة في تاريخ وصولها المتوقع، فتنتظر المهام وصول التوريد. وتلتقط قراءة كاملة كل ليلة لعروض الأسعار وأوامر الشراء المفتوحة أي تغييرات فاتت المزامنة.
3. إعادة بيانات الجدولة والإكمال إلى Xero. تنقل ثلاثة استدعاءات النتائج إلى Xero:
- يضيف PUT
/Quotes/{QuoteID}/Historyملاحظة تتضمن تاريخ الانتهاء المخطط له. لا يسمح عرض الأسعار المقبول إلا بتغيير جهة الاتصال والملاحظات، لذا يُحفظ التاريخ في ملاحظة السجل. (المصدر) - عند اكتمال الطلب، ينشئ POST
/Invoicesفاتورة مبيعات بحقل Type قيمته ACCREC، وStatus قيمته DRAFT، مع جهة الاتصال وبنود عرض الأسعار، ورقم العرض في حقل Reference. ويتولى مسؤول الحسابات لديك اعتمادها وإرسالها من Xero. - يُغلق POST
/Quotesعرض الأسعار عند إرسال QuoteID وحقل Status بالقيمة INVOICED. والانتقال من Accepted إلى Invoiced تغيير حالة مسموح به في Accounting API.
4. تأكيدات العمل في المصنع ووقت المشاريع. يسجل المشغّلون العمل باستخدام SkyPlanner Mobile Confirmations أو Production Timer أو Quick Log Mode. يُحدَّث الجدول فور تسجيل التقدم، ويعيد Autopilot تخطيط العمل المتبقي. ولأعمال المشاريع، يرسل SkyPlanner الساعات كقيود وقت على مهمة المشروع، مع مستخدم Xero والتاريخ والمدة. (المصدر)
5. قواعد ملكية البيانات وحل التعارضات. دوّنها قبل بدء التشغيل الفعلي:
| البيانات | النظام المسؤول |
|---|---|
| جهات الاتصال، والأصناف، والأسعار، وعروض الأسعار، وأوامر الشراء، والفواتير، والمحاسبة | Xero |
| محطات العمل، وخطوات العمليات، والورديات، والغياب، ومصفوفة أوقات الإعداد، والأدوات، والموارد البديلة | SkyPlanner |
| تسلسل المهام، وأوقات البدء والانتهاء، ومحطة العمل لكل مهمة | SkyPlanner |
| ملاحظة تاريخ الانتهاء المخطط له على عرض الأسعار | SkyPlanner، وتُكتب في Xero |
| مسودة فاتورة للطلبات المكتملة، والوقت المسجّل على المشاريع | ينشئها SkyPlanner، ويتولى Xero إدارتها بعد اعتمادها |
الخطوات المعتادة للمشروع
يكتمل التنفيذ عادةً خلال أسابيع من بدء التهيئة. وقبل ذلك، يمكنك استخدام التجربة المجانية لمدة 30 يومًا ببياناتك الفعلية، من خلال تصدير جهات الاتصال والمنتجات وعروض الأسعار المفتوحة من Xero بصيغة CSV.
يشمل المشروع الخطوات التالية:
- الربط. يمنح مسؤول Xero الموافقة على SkyPlanner ويختار المؤسسة.
- مصدر الطلب. اتفقوا على ما إذا كان بدء الإنتاج سيعتمد على عروض الأسعار المقبولة أم فواتير المبيعات.
- مطابقة البيانات. حدّدوا جدول المطابقة ورموز الأصناف وحسابات الفواتير والإعدادات الضريبية الافتراضية، وقواعد ملكية البيانات.
- التحميل الأولي. تحميل جهات الاتصال والأصناف وأوامر الشراء المفتوحة وعروض الأسعار المقبولة.
- نموذج الإنتاج. إعداد محطات العمل وخطوات التشغيل لكل منتج والورديات ومصفوفة أوقات التجهيز والأدوات وأعداد المشغّلين في SkyPlanner.
- المزامنة. استخدام إشعارات الويب لجهات الاتصال والفواتير، والاستقصاء باستخدام
If-Modified-Sinceلعروض الأسعار والأصناف وأوامر الشراء، مع مطابقة البيانات كل ليلة. - إعادة البيانات إلى Xero. البدء بملاحظات عروض الأسعار، ثم مسودات الفواتير وحالة عروض الأسعار، ثم الوقت المسجّل على المشاريع عند استخدامه.
- الاختبار بالتوازي وبدء التشغيل الفعلي. قارنوا تواريخ SkyPlanner بخطتكم الحالية، واطلبوا من المحاسب مراجعة مسودات الفواتير الأولى، ثم فعّلوا إعادة البيانات إلى Xero.
ما ينبغي مراعاته عند التخطيط للتكامل مع Xero
- لا يتضمن Xero كائنات بيانات للإنتاج. احتفظوا بخطوات التشغيل لكل منتج في SkyPlanner، واربطوها برمز الصنف في Xero. حافظوا على ثبات رموز الأصناف.
- لا تتوفر إشعارات ويب لعروض الأسعار. استقصوا تحديثاتها على فترات قصيرة باستخدام
If-Modified-Since، مع الالتزام بالحدود المسموح بها للدقيقة واليوم. - تُقفل عروض الأسعار بعد قبولها. لا يمكن بعد القبول تغيير سوى بيانات الاتصال والملاحظات، لذا يُقرأ التاريخ المتعهد به مرة واحدة عند القبول، ويُكتب التاريخ المخطط له كملاحظة في سجل العرض.
- يتغير المخزون تبعًا لفواتير البيع والشراء. يحدّث Xero الكمية المتاحة من الأصناف الخاضعة لتتبع المخزون من خلال فواتير المبيعات وفواتير المشتريات والإشعارات الدائنة. اتفقوا مع المحاسب على كيفية المعالجة المحاسبية للمنتجات التامة والمواد المستهلكة.
- تسجيل وقت المشاريع يتطلب مستخدمين في Xero. يرتبط كل قيد وقت بمستخدم في Xero. حدّدوا المشغّلين الذين ستُنقل قيود وقتهم إلى Xero Projects، واحتفظوا بقيود البقية في SkyPlanner.
- نطاقات صلاحيات محددة. اطلبوا نطاقات صلاحيات محددة منذ البداية، إذ يجري إيقاف النطاقات الواسعة.
- فئة التطبيق. تحدّد فئة الشريك عدد المؤسسات التي يمكن للتطبيق الاتصال بها، وعدد الاستدعاءات المتاحة له يوميًا. اختاروا الفئة وفقًا لعدد المصانع.
التكامل مع Xero: من يتولى إعداده ودعمه؟
يشمل العمل أصنافكم وعروض أسعاركم وأوامر الشراء لديكم، وكيفية انتقال الأعمال المكتملة إلى الفوترة. ويضيف البيانات التي لا يحتفظ بها Xero: محطات العمل وخطوات التشغيل والورديات ومصفوفة أوقات التجهيز والأدوات وأعداد المشغّلين والموارد البديلة.
- يتولى فريق SkyPlanner إعداد التكامل أثناء التهيئة، ويدعمه بعد بدء التشغيل الفعلي. لكل ورشة طريقتها في إعداد الأصناف وعروض الأسعار والمخزون في Xero، وتُوظَّف هذه المعرفة عند إعداد التكامل.
- يمكن لمستشار Xero أو شريك التكامل لديكم بناء التكامل. يوفّر SkyPlanner واجهة REST API ووثائق Swagger/OpenAPI وإشعارات الويب.
- يمكن لمطوّريكم تطوير التكامل باستخدام رمز API. يكفي رمز API للبدء، ويساعد فريق SkyPlanner عند الحاجة. تتوفر وثائق المنتج، بما فيها أوامر الشراء وواجهة API للمنتجات والمواد، في وثائق SkyPlanner.
يبدأ سعر SkyPlanner من 199 € شهريًا، ويشمل 5 محطات عمل، مع فوترة شهرية. ويُقدَّم لكم مسبقًا عرض سعر للتكامل يناسب سير عملكم واحتياجاتكم، إلى جانب سعر خطتكم، لتعرفوا التكلفة الكاملة قبل البدء. اطّلعوا على الأسعار والميزات، وتعرّفوا على ما يقدّمه Xero بمفرده في هل يوفّر Xero جدولة الإنتاج؟ تجدون نظرة عامة في صفحة Xero، والأنظمة الأخرى في جميع عمليات التكامل.
آراء المصنّعين في SkyPlanner
2 ستُوفَّر كل أسبوع
“نقل SkyPlanner تخطيط الإنتاج لدينا من جداول Excel إلى تحسين الإنتاج في الوقت الفعلي.”
كالي كاليومّاكي، أخصائي سلسلة الإمداد
UTU · لوحات التوزيع ومعدات الفصل والتوصيل الكهربائية
يوفّر تخطيط الإنتاج 2 ساعة من وقت العمل كل أسبوع، وتصل قائمة مهام جديدة إلى خط الإنتاج خلال ثوانٍ.
+90%في كفاءة الإنتاج
“ارتفعت كفاءة الإنتاج بنسبة 90%.”
عبدول روتشيينغا، رئيس قسم تقنية المعلومات
Laboratory & Allied · صناعة الأدوية
ارتفعت كفاءة الإنتاج بنسبة 90%، ويستغرق إعداد خطة محسّنة لثلاثة أشهر تشمل جميع محطات العمل أقل من 30 دقيقة.
توقفات أقلبسبب نقص المواد
“تكمن قيمة SkyPlanner بالنسبة لنا في أنه أداة عملية للاستخدام اليومي، خصوصًا لتحديد مواعيد التسليم.”
تومي مانيستو، مدير تخطيط الإنتاج
Eskomatic · التشغيل الميكانيكي حسب التعاقد
تتيح الجدولة التلقائية لأحمال العمل تحديد مواعيد تسليم أدق، وقد انخفضت بشدة توقفات الإنتاج الناجمة عن نقص المواد.
آلاف (1,000s)أوامر العمل تُجدول تلقائيًا
“أصبحنا نتحكم في الإنتاج بطريقة مختلفة، وبلغ فهمنا للطاقة الإنتاجية مستوى مختلفًا تمامًا.”
هانو ريونانن، الرئيس التنفيذي
Mamec · خلاطات ومضخات صناعية وتصنيع تعاقدي بتقنيات متقدمة
تُجدول آلاف أوامر العمل تلقائيًا، مع إتاحة رؤية للإنتاج في الوقت الفعلي لجميع أقسام المؤسسة.
الأسئلة الشائعة
هل يوفّر Xero واجهة API لبيانات الإنتاج؟
يوفّر Xero واجهتَي Accounting API وProjects API، وكلتاهما تعمل وفق REST مع OAuth 2.0. وتغطيان جهات الاتصال والأصناف وعروض الأسعار والفواتير وأوامر الشراء وقيود الوقت. أما بيانات الإنتاج، مثل محطات العمل وخطوات التشغيل، فتُحفظ في SkyPlanner.
هل يمكن لـ SkyPlanner إعادة البيانات إلى Xero؟
نعم. يضيف SkyPlanner تاريخ الانتهاء المخطط له إلى سجل كل عرض سعر، وينشئ عند اكتمال الطلب مسودة فاتورة مبيعات تتضمن بنود العرض، ويغيّر حالة العرض إلى Invoiced، ويرسل قيود وقت المشاريع.
هل يرسل Xero التغييرات فور حدوثها؟
تغطي إشعارات الويب في Xero جهات الاتصال والفواتير. ويقرأ SkyPlanner عروض الأسعار والأصناف وأوامر الشراء التي تغيرت منذ آخر مزامنة باستخدام If-Modified-Since، ويطابق البيانات كل ليلة، لذا يصل عرض السعر المقبول حديثًا إلى الجدول بسرعة.
من أين تأتي قوائم المواد ومسارات الإنتاج والآلات إذا لم تكن موجودة في Xero؟
من SkyPlanner. تُعدّون محطات العمل وخطوات التشغيل لكل منتج والورديات وأوقات التجهيز مرة واحدة، يدويًا أو باستيراد ملف CSV أو Excel. ويرتبط كل منتج برمز الصنف في Xero، فتُجدول عروض الأسعار المقبولة حديثًا تلقائيًا.
هل يمكننا تجربة SkyPlanner قبل بناء التكامل؟
نعم. تدعم التجربة المجانية لمدة 30 يومًا ما يصل إلى 20 محطة عمل، مع استيراد البيانات من Xero بصيغة CSV، ولا تتطلب بطاقة ائتمان. ابدأ التجربة، أو تواصل مع المبيعات لتحديد نطاق التكامل.
