0. مصطلحات مستخدمة في هذا الدليل

مسرد قصير حتى يبدأ كل قارئ من نفس الأساس. تستخدم بقية الوثيقة هذه المصطلحات دون إعادة شرح.

1. نظرة عامة — ما تقدمه تراست بل لـ Fusion

لا يحتوي Oracle Fusion Cloud ERP على نقطة وصول أصلية للهيئة الاتحادية للضرائب. فهو لا يُنشئ ملفات PINT-AE XML، ولا يتحدث Peppol AS4، ولا يمكنه التواصل مباشرة مع بوابة الفوترة الإلكترونية للهيئة. تجلس تراست بل بين Fusion والهيئة: نأخذ بيانات الفاتورة البيعية من Fusion، ونحولها إلى ملف PINT-AE UBL للإمارات، ونتحقق منها وفق قواعد الأعمال للهيئة، ونرسلها عبر ASP معتمد من الهيئة ببروتوكول Peppol AS4، ثم نُعيد إلى Fusion الوثيقة الموقعة المعتمدة كتحديث للحالة إضافة إلى نسخة PDF/A-3 الرسمية.

تبقى بصمة Fusion لديكم كما هي. لا نُخصّص شاشات Fusion القياسية، ولا نطلب تغيير استراتيجية ترقيم الفواتير، ولا نحتاج إلى ارتباط مع Oracle Managed Services، ولا نُثبّت أي شيء داخل بيئة Fusion. تعمل كل منطق التحويل والهيئة داخل تراست بل.

2. ثلاثة خيارات للتكامل — مقارنة جنبًا إلى جنب

لا يحتاج كل عميل Fusion نفس عمق التكامل. نقدّم ثلاثة خيارات بثلاث نقاط سعرية. اختاروا الأنسب لحجم فواتيركم، ومرحلة إدارة التغيير لديكم، ومدى الحاجة لعودة UUID الهيئة على الفاتورة المطبوعة فورًا.

تستخدم الخيارات الثلاثة نفس خط PINT-AE وASP المعتمد من الهيئة. يختلف فقط محفّز Fusion ومسار الكتابة العكسية. البدء بالخيار 1 والترقية لاحقًا هو تغيير إعداد وليس إعادة بناء.

يُفصّل القسم §4 النطاق والجهد لكل خيار حتى تستطيعوا (أو MSP الخاص بكم) التخطيط للعمل الداخلي قبل التوقيع. التسعير مُدار منفصلًا على صفحة أسعار تكامل ERP — تبقى هذه الوثيقة تقنية.

3. معمارية التكامل المتقدم

مسار الخيار المتقدم ثلاثة أنظمة متسلسلة. Fusion هو نظام السجل، وOracle Integration Cloud (OIC) هو المنسّق داخل محيطكم، وتراست بل هي طبقة الامتثال في الإمارات التي تنتهي عند ASP المعتمد والهيئة.

1. يُطلق Fusion حدث عمل (قياسي: `oracle.apps.financials.receivables.transactions.transactionCreated` أو `.transactionComplete`) عند اكتمال فاتورة البيع وحساب الضريبة.
2. يشترك تكامل OIC بالحدث، ويُثريه ببيانات العميل وسعر الصرف والكيان القانوني، ثم يرسل JSON إلى `https://api.trustbill.ae/v1/partner/invoices`.
3. تتحقق تراست بل من الحمولة، وتحوّلها إلى PINT-AE 1.0 UBL، وتطبّق قواعد الهيئة، وتوقّعها، وترسلها إلى ASP المعتمد عبر Peppol AS4.
4. يُرسل ASP الفاتورة للهيئة. تُعيد الهيئة حالة المقاصة ورقم UUID الرسمي.
5. ترسل تراست بل كول باك موقّعًا بـ HMAC إلى نقطة OIC الواردة المسجّلة، يحمل UUID وطابع المقاصة الزمني ورابط PDF/A-3 والـ UBL الموقّع.
6. يُعيد تدفق OIC كتابة UUID والحالة إلى فاتورة Fusion (دمج قياسي: Descriptive Flexfield + عمود حالة ظاهر على شاشة AR Transactions).

4. النطاق والجهد — لكل خيار

هذا القسم مرجع فريقكم وفريقنا في اتفاقية العمل. نُدرج لكل خيار ما تُسلّمه تراست بل، وما يُسلّمه فريق Fusion لديكم، وعدد أيام العمل اللازمة من كل جانب. التسعير يُدار منفصلًا على صفحة أسعار تكامل ERP.

— — — — — — — — — — — — — — — — — — — — — — — — — — —

— — — — — — — — — — — — — — — — — — — — — — — — — — —

— — — — — — — — — — — — — — — — — — — — — — — — — — —

5. قائمة المتطلبات

جهّزوا ما يلي قبل الانطلاق. أي بند ناقص يؤجّل عادة تاريخ الإطلاق أسبوعًا.

1. Oracle Fusion Cloud ERP: الإصدارات المدعومة 24A فأحدث. يُدعم 23D حتى يوليو 2026.
2. Oracle Integration Cloud (OIC Gen 2 أو Gen 3) — إصدار Standard كافٍ.
3. مهندس مؤسسة محدَّد من جهتكم، مُفوَّض باعتماد قرارات تصميم الواجهة في اجتماع واحد.
4. مسؤول وظيفي محدَّد لـ Fusion AR + Tax.
5. مطوّر OIC محدَّد يستطيع النشر على البيئات الثلاث ضمن قطار الإصدار.
6. اتفاقية عمل موقّعة تحدد النطاق على فواتير AR / البيع فقط.
7. TRN واحد لكل كيان قانوني في النطاق، مُطابق لوحدات أعمال Fusion.
8. بيئات DEV وUAT وPROD متاحة من OIC (غير محصورة بـ SSO فقط).
9. تذاكر تغيير جدار ناري مرفوعة للخروج إلى `api.trustbill.ae` والدخول من CIDR نحن نُقدّمه.
10. موافقة من مدير المالية/الضرائب بأن فواتير AR قابلة للإرسال للهيئة من تاريخ الإطلاق.

6. نموذج المصادقة

تستخدم واجهة الشركاء مصادقة من طبقتين. الطبقة الأولى تُثبت أن المُستدعي شريك ERP معروف لدى تراست بل. الطبقة الثانية سرّ لكل SME تُثبت أن هذا الدفع يخص الكيان الذي صدرت فاتورته. كلاهما مطلوب في كل كتابة.

7. الحمولة — ما يُرسله OIC إلى تراست بل

تبدو حمولة فاتورة ضريبية بسيطة كالآتي. المخطط الكامل منشور في `https://api.trustbill.ae/v1/partner/openapi.json` ويغطّي الفواتير المبسطة والتجارية وإشعارات الدائن والمدين تحت نفس الشكل.

POST /v1/partner/invoices HTTP/1.1
Host: api.trustbill.ae
Content-Type: application/json
X-API-Key: tbp_live_7f3c…
X-API-Secret: tbs_live_••••••••
x-erp-partner-secret: ers_live_••••••••
Idempotency-Key: fusion-inv-2026-10-16-00042

{
  "documentType": "tax_invoice",
  "externalRef": "INV-2026-00042",
  "issueDate": "2026-10-16",
  "dueDate":   "2026-11-15",
  "currency": "AED",
  "seller": {
    "trn": "100123456700003",
    "legalName": "Acme Trading L.L.C"
  },
  "buyer": {
    "trn": "100987654300003",
    "legalName": "Beta Distribution F.Z.E"
  },
  "lines": [
    {
      "description": "Industrial pump, model X9",
      "quantity": 2,
      "unitPrice": 1500.00,
      "taxCategory": "S",
      "taxRate": 5
    }
  ],
  "totals": {
    "netAmount":   3000.00,
    "taxAmount":    150.00,
    "grossAmount": 3150.00
  }
}

عند النجاح نُعيد `202 Accepted` مع ظرف يحتوي معرف الفاتورة في تراست بل وهاش المستند الموحّد وحقل `status: "queued"`. الكول باك هو القناة المرجعية لتسليم المقاصة النهائية.

8. خريطة الحقول Fusion ↔ تراست بل

تدفق OIC هو موضع هذه الخريطة. استخدموا الجدول كمعيار قبول لبناء OIC — متى اكتمل كل صف اكتمل 95% من UAT الوظيفي.

9. كول باك الحالة من تراست بل

عندما تصل الفاتورة إلى حالة نهائية (`delivered` أو `rejected`) ترسل تراست بل حدثًا واحدًا `invoice.status_changed` إلى رابط الكول باك المسجّل. الإرسال دائم وموقّع، ويُعاد محاولته بجدول ثابت.

POST /your-oic-webhook-url HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: 1760606062
X-Webhook-Signature: t=1760606062,v1=4e9c3d…hex…

{
  "event": "invoice.status_changed",
  "deliveredAt": "2026-10-16T09:14:22Z",
  "payload": {
    "event": "invoice.status_changed",
    "invoiceId":   "inv_01HZ…",
    "externalRef": "INV-2026-00042",
    "status":      "delivered",
    "ftaUuid":     "f1b8c7e2-9d4a-4b11-9c38-7c7a3a9c0e8b",
    "deliveredAt": "2026-10-16T09:14:19Z",
    "assets": {
      "signedUbl": "https://api.trustbill.ae/…/signed.xml",
      "pdfA3":     "https://api.trustbill.ae/…/invoice.pdf"
    }
  }
}

1. `status: "delivered"` — سُلّمت الفاتورة إلى الهيئة؛ `ftaUuid` هو المعرّف الرسمي الذي يُخزَّن على فاتورة Fusion ويُطبع.
2. `status: "rejected"` — رفضت الهيئة (أو التحقق قبل الإرسال). تحمل الحمولة الكود وسببًا بشريًا. تبقى الفاتورة مرفوضة في تراست بل؛ تُصحَّح بإصدار فاتورة جديدة أو إشعار دائن.

التحقق من التوقيع إلزامي. يجب على تدفق OIC الوارد تنفيذ هذه الفحوصات الأربعة قبل قبول الحمولة:

1. قراءة `X-Webhook-Timestamp` واستخراج `v1=<hex>` من `X-Webhook-Signature`.
2. رفض إذا كان `|now − t| > 300` ثانية — يمنع هجمات إعادة التشغيل.
3. حساب `hmac_sha256(webhook_secret, `${t}.${raw_body}`)` ومقارنته بـ `v1` بزمن ثابت.
4. فقط بعد نجاح الفحصين، حلّلوا JSON وحدّثوا حقول DFF على فاتورة Fusion.

جدول إعادة المحاولة عند 2xx- أو فشل نقل: 30 ث → 2 د → 10 د → 30 د → 1 س → 3 س. بعد المحاولة السادسة يُعلَّم الإرسال `exhausted`. حالة الفاتورة ذاتها في تراست بل لا تتأثر؛ يمكنكم `GET /v1/partner/invoices/:id` أو إطلاق محاولة جديدة بـ `POST /v1/partner/invoices/:id/replay-webhook`.

10. التعامل مع الأخطاء

كل استجابات الخطأ مستندات RFC 7807 بنوع `application/problem+json`. اعتمدوا على `type` المستقر في فروع OIC بدل العنوان البشري أو كود HTTP وحده. الأخطاء التي ستلتقونها فعلًا من واجهة الشركاء:

11. البيئات وخطة الانتقال

نشر Fusion ↔ تراست بل الصحي يمر على أربع بيئات متطابقة على الجانبين. كل انتقال يتطلب توقيع المسؤول المقابل في المستوى نفسه.