In Progress

هذا المستند لا يزال قيد الإعداد ولم يكتمل بعد

الربط مع الفاتورة الإلكترونية في الإمارات عبر Orchida osTax

نظرة عامة (Overview)

يدعم NamaERP إرسال الفواتير الإلكترونية إلى الهيئة الاتحادية للضرائب في الإمارات (FTA) عبر مزوّد الخدمة Orchida osTax. تعمل Orchida بصفتها مزوّد خدمة معتمدًا (ASP) ضمن نموذج الفوترة الإلكترونية ذي الخمسة أطراف المبني على شبكة Peppol في الإمارات.

يُرسل النظام الفواتير بصيغة JSON إلى Orchida التي تتحقق منها وتُبلّغ بيانات الضريبة إلى الهيئة الاتحادية للضرائب وتوجّهها إلى المشتري عبر شبكة Peppol.

المتطلبات الأساسية (Prerequisites)

قبل البدء في الإعداد، تحتاج إلى:

• حساب على منصة Orchida osTax (https://app.orchidatax.com)
• مفتاح API (Bearer Token) من لوحة تحكم Orchida
• معرّف الشركة (Company ID) من لوحة تحكم Orchida

الحصول على بيانات الاعتماد من Orchida

1. سجّل الدخول إلى لوحة تحكم Orchida
2. أدخل رمز OTP المُرسَل إلى بريدك الإلكتروني
3. اختر المستأجر والشركة المناسبَين
4. اذهب إلى Security > Generate Key
5. أنشئ مفتاحًا جديدًا (حدد تاريخ انتهاء الصلاحية والاسم)
6. انسخ مفتاح API ومعرّف الشركة

إعداد النظام (System Setup)

الخطوة الأولى: إعدادات الفاتورة الإلكترونية العامة (Step 1: Global E-Invoice Settings)

من الإعدادات العامة > الصفحة الثانية:

• اضبط عرض صفحة الفاتورة الإلكترونية الخاصة بـ على الفاتورة الإلكترونية بالإمارات
• بعد تغيير القيمة قم بعمل Regen UI

الخطوة الثانية: إعداد مصلحة الضرائب (Step 2: Tax Payer Configuration)

أنشئ إعداد مصلحة ضرائب جديدًا أو عدّل إعدادًا قائمًا.

المعلومات الأساسية (Basic Information)

الحقل	القيمة
نوع المصلحة (taxPayerType)	الإمارات - الفاتورة الإلكترونية التجريبية (للاختبار) أو الإمارات - الفاتورة الإلكترونية (للإنتاج)

إعدادات التكامل (Integration Settings)

الحقل	الوصف
API URL (apiUrl)	يُملأ تلقائيًا عند اختيار نوع المصلحة
كلمة المرور (password)	مفتاح API من Orchida (Bearer Token). مطلوب.
معرف الشركة في Orchida (orchidaCompanyId)	معرّف الشركة من لوحة تحكم Orchida. مطلوب.

تعرف Orchida البائع من معرّف الشركة، فلا تخرج من نما بيانات للبائع: رقم التسجيل الضريبى ونوع النشاط للفرع وحساب معرف الفرع من في صفحة الإمارات لا تُرسل مع فواتير الإمارات. اترك حساب معرف الفرع من فارغًا — فإذا مُلئ ظل حفظ الإعدادات يفحص كود مصلحة الضرائب وعنوان ذلك السجل.

إعداد أكواد الضريبة (Tax Code Configuration)

تتبع أكواد الضريبة في الإمارات معيار UN/EDIFACT 5305 (أكواد فئة الضريبة المنسَّقة).

نوع الضريبة (Tax Type):

الكود	الوصف
VAT	ضريبة القيمة المضافة

نوع الضريبة الفرعي (Tax SubType):

الكود	الوصف
S	النسبة القياسية (5%)
Z	خاضع للضريبة بنسبة صفر
E	معفي من الضريبة
O	خارج النطاق
AE	الاحتساب العكسي

WARNING

عند استخدام الكود S (النسبة القياسية)، يجب أن تكون نسبة ضريبة القيمة المضافة بالضبط 5.00

أدخل الأكواد في مجموعة الضريبة 1 بصفحة الإمارات (أو مجموعة خانة الضريبة التي تحمل ضريبة القيمة المضافة): الضريبة 1 كود الضريبة 1 (taxesCodes.tax1TaxAuthType) يأخذ VAT، والضريبة 1 كود الضريبة الفرعي 1 (taxesCodes.tax1TaxAuthSubType) يأخذ الفئة. وبقية المجموعة:

• الضريبة 1 كود الضريبة الصفرية 1 والضريبة 1 كود الضريبة الصفرية الفرعي 1 (taxesCodes.tax1ZeroTaxAuthType، taxesCodes.tax1ZeroTaxAuthSubType) يُرسلان بدلًا منهما حين تكون الضريبة في السطر صفرًا — مثل VAT و Z.
• إرسال الضريبة 1 بصفر (taxesCodes.sendTax1WithZero) يرسل الضريبة بنسبة صفر وقيمة صفر.
• عدم إرسال ضريبة 1 عند عدم وجود أكواد لها (doNotSendTax1IfNoCode) يُسقط الخانة إذا لم تكن لها أكواد.

وحساب اكواد أنواع الضرائب من (taxCodesType) يحدد هل تُقرأ الأكواد من هذه الصفحة (الافتراضي) أم من السياسة الضريبية في التوجيه أو الصنف أو العميل، وجدول مصادر أكواد الضرائب (taxCodesSource) يتجاوز ذلك لأنواع مستندات أو دفاتر أو توجيهات أو معايير أو تواريخ فعلية أو محددات بعينها.

سطور الأصناف والأسعار والتواريخ

الحقل	معرّف الحقل	ماذا يفعل
حساب الكود الضريبي للصنف من، قالب كود الصنف	itemCodeFrom، itemCodeTemplate	كود الصنف المرسل في كل سطر: كود مصلحة الضرائب في الصنف (أو في مجموعته أو تصنيفه أو فئته أو قسمه أو ماركته)، أو كود الصنف نفسه إن كان فارغًا. ومع من قالب كود الصنف يبنيه القالب.
تشغيل قالب وصف الصنف على (اسم 1 للصنف افتراضيا)، قالب الوصف	taxDescriptionFrom، taxDescriptionTemplate	اسم السطر ووصفه. افتراضيًا الاسم الأول للصنف، ويستطيع القالب بناءه من الصنف أو رأس المستند أو سطر المستند.
مصدر سعر الوحدة، نوع مصدر سعر الوحدة	unitPriceSource، unitPriceType	الخطوة التي يُقرأ منها سعر الوحدة في حساب السطر. انظر قسم «سعر الوحدة والكميات والتقريب» في الدليل العام.
عدد كسور الكمية	quantityFractionalPlaces	عدد الخانات العشرية للكمية؛ والفراغ يعني خانتين. القسم نفسه.
تجاهل وتقريب القيمة إذا كان عدد خانات الكسر أكبر من المسموح به	ignoreAndRoundAmountIfScaleIsInvalid	يقرّب سعر الوحدة الزائد الدقة بدلًا من إيقاف المستند. القسم نفسه.
اقصي عدد للسطور عند تجميع مستندات الضرائب	maxNumberOfLinesWhenCollectTaxAuthDocs	عدد السطور التي يجوز أن يجمعها التجميع الواحد. القسم نفسه.
لا ترسل مكونات الأصناف المجمعة	dontSendAssemblyComponentLines	يرسل الصنف المجمَّع سطرًا واحدًا بدلًا من مكوناته.
جدول إعدادات الخصومات	discountConfigs	يرسل الخصم قبل الضريبة أو بعدها أو لا يرسله، لكل خصم على حدة. انظر قسم «إعدادات الخصومات» في الدليل العام.
أقصي عدد أيام لإرسال الفواتير	maxDaysToSendInvoice	انظر قسم «الحد الأقصى لأيام الإرسال» أدناه.
بدء الإرسال من تاريخ	startSendingFromDate	المستندات المؤرخة قبل هذا اليوم لا تُرسل أبدًا.
عدد الأيام للسماح بإنشاء مستندات مستقبلية	futureDaysToAllowSaveDoc	كم يومًا للأمام يجوز أن يؤرَّخ مستند يذهب إلى Orchida. والصفر يعني لا يجوز.

وقالب كود نما وتشغيل قالب كود نما على (كود الصنف افتراضيا) يبنيان كودًا داخليًا لا يُرسل إلى Orchida؛ ومع ذلك يظل اقصي عدد حروف لكود الصنف الداخلي يحد طول هذا الكود، بخمسين حرفًا إذا تُرك فارغًا. أما حقول رسوم الخدمة (حقول رسوم الخدمة، ورسوم الخدمة شاملة الضريبة، ونسبة الضريبة للخدمة، واستبعاد رسوم الخدمة الغير معرفة) وموقع الخصم الإضافي على مستوى المستند فلا تؤثر في فواتير الإمارات. ولا تصل رسوم الخدمة إلى Orchida إلا عبر جدول رسوم الخدمة في صفحة الرئيسية — انظر قسم «معاملة رسوم الخدمة و ما يتحمله العميل» في الدليل العام.

الخطوة الثالثة: إعداد العميل (Step 3: Customer Setup)

لكل عميل سيستقبل فواتير إلكترونية، أكمل الحقول التالية:

البيانات الضريبية (Tax Information)

الحقل	الوصف
رقم التسجيل الضريبى	رقم التسجيل الضريبي (TRN) للعميل
الرقم المميز	معرّف نقطة نهاية Peppol للعميل
الوصف 4 (description4، غير ظاهر في شاشة العميل القياسية)	معرّف الجهة (مثلًا TL)
الوصف 5 (description5، غير ظاهر في شاشة العميل القياسية)	اسم الجهة (مثلًا اسم الشركة)

العنوان (Address)

الحقل	الوصف
كود الدولة	كود الدولة (مثلًا AE)؛ إن كان فارغًا تُرسَل الدولة بدلًا منه
المدينة	اسم المدينة
شارع	عنوان الشارع
المحافظة	كود الإمارة

أكواد الإمارات

الكود	الإمارة
AUH	أبوظبي
DXB	دبي
SHJ	الشارقة
AJM	عجمان
UAQ	أم القيوين
RAK	رأس الخيمة
FUJ	الفجيرة

الخطوة الرابعة: إعداد وحدات القياس (Step 4: Unit of Measure Setup)

يجب أن تمتلك كل وحدة قياس مستخدمة في الفواتير كودًا صالحًا لدى مصلحة الضرائب وفق معيار UN/ECE Rec 20:

الكود	الوصف
EA	وحدة
KGM	كيلوغرام
MTR	متر
LTR	لتر
XBX	صندوق
PCE	قطعة

الخطوة الخامسة: إعداد العملة (Step 5: Currency Setup)

تأكد من وجود عملة بكود مصلحة الضرائب AED وأنها مضبوطة كعملة افتراضية.

إرسال الفواتير (Sending Invoices)

إنشاء وثيقة إرسال لمصلحة الضرائب (Creating a Tax Authority Submission Document)

1. اذهب إلى إرسال مستندات الي مصلحة الضرائب
2. انقر على تجميع مستندات الضرائب لإضافة الفواتير المراد إرسالها
3. انقر على إرسال المستندات المختارة فقط أو إرسال المستندات التي لم تُرسل لتقديم الفواتير إلى Orchida

حالات الإرسال (Submission Statuses)

بعد الإرسال تُضبط حالة الوثيقة إلى:

• تم ارساله: قبلت Orchida الفاتورة للمعالجة
• لم يتم ارساله بشكل صحيح: رُفضت الفاتورة — راجع حقل الأخطاء للاطلاع على التفاصيل

أنواع الوثائق المدعومة (Supported Document Types)

النوع	مدعوم
فاتورة	نعم
إشعار دائن	نعم
إشعار مدين	لا

الحد الأقصى لأيام الإرسال (Maximum Days to Send)

العدد الافتراضي للأيام المسموح بها لإرسال الفاتورة بعد تاريخ قيمتها هو 14 يومًا. يمكن تغيير هذا الإعداد في إعداد مصلحة الضرائب ضمن حقل أقصي عدد أيام لإرسال الفواتير (maxDaysToSendInvoice). والمستند الأقدم من الحد لا يمكن حفظه ما دام دفتره أو توجيهه يرسل إلى مصلحة الضرائب، والمستند الذي يتجاوز الحد لا يُجمَّع بعد ذلك.