دليل واجهة Sandbox

تحاكي بيئة Sandbox واجهة الإنتاج مع بيانات ومعرّفات اختبار. يشرح هذا الدليل كيف يجهّز المدمج حساب Partner، ويطلب أقل الصلاحيات اللازمة، ثم كيف تفوّضه المؤسسة الحريفة قبل أن يتمكن من إصدار فواتير باسمها.

بيانات اختبار فقط

لا تستخدم أسراراً أو شهادات أو رمز SEAL PIN أو بيانات جبائية تخص الإنتاج داخل Sandbox. لا تحتوي الصور التالية على كلمة مرور أو سر API قابل للاستعمال.

حساب Partner

توفّر لوحة Partner النفاذ إلى الملف العام، ومعرّفات API، والمؤسسات الحريفة المفوّضة، والفواتير، والعمليات، والطلبات، وسجل التدقيق.

1. إكمال ملف Partner

افتح Partner → Partner profile وأدخل الاسم القانوني والصيغة القانونية والعنوان. يدار المعرّف الجبائي من المنصة ولا يمكن تعديله من هذه الصفحة.

في تبويب Catalog، أضف تسمية واضحة ووصفاً بالإنجليزية والفرنسية والعربية يشرح الخدمة وسبب طلب الصلاحيات.

2. اختيار الصلاحيات المطلوبة

من تبويب API طبّق مبدأ أقل صلاحية:

Scope	الاستعمال
invoice:read	قراءة الفواتير وحالاتها
invoice:write	إنشاء الفواتير أو تعديلها
ttn:submit	إرسال الفواتير إلى TTN
digigo:sign	بدء توقيع DigiGO مع موافقة المستخدم
seal:sign	تشغيل توقيع SEAL عندما تهيئه المؤسسة

لا تمنح هذه الاختيارات أي نفاذ قبل موافقة المؤسسة الصريحة.

3. حماية معرّفات API

تعرض صفحة Partner → API credentials معرّفات OAuth2. احتفظ بالسر على الخادم داخل مخزن أسرار، ولا تضعه في المتصفح أو تطبيق الهاتف أو مستودع الشفرة ولا ترسله إلى الحريف.

تعرض صفحة Clients المؤسسات التي منحت تفويضاً فعلياً فقط.

حساب المؤسسة

يدير حساب Organization الفواتير واستيراد TEIF والمنتجات وتطبيقات API والبيانات الجبائية والشركاء المفوضين.

1. التحقق من المؤسسة وطريقة الربط

راجع الهوية القانونية، وخاصة الاسم والمعرّف الجبائي، قبل إصدار الفواتير.

للربط المباشر دون Partner، افتح API Keys وأنشئ تطبيق OAuth2 تابعاً للمؤسسة. لا يظهر السر إلا عند الإنشاء ويجب أن يبقى على خادم المدمج.

2. العثور على Partner وتفويضه

افتح App catalog، وابحث عن Partner، ثم راجع الوصف وحالة التحقق والصلاحيات المقترحة.

اضغط Activate واقرأ تفاصيل كل صلاحية. ألغ العملية إذا لم تكن إحدى الصلاحيات مبررة واطلب من Partner تقليصها.

بعد تأكيد الموافقة، أدخل OTP الذي يتلقاه مالك المؤسسة. في الإنتاج لا تستخدم إلا الرمز المرسل عبر القناة الآمنة.

عند نجاح العملية تظهر علامة Activated وتضاف المؤسسة إلى Partner → Clients. عند الخطأ لا تتجاوز الموافقة؛ سجّل الوقت واسم Partner والمؤسسة ورسالة الخطأ واتصل بالدعم.

بعد التفويض

يستعمل Partner معرّفات OAuth2 الخاصة به، ويختار مؤسسة مفوضة حسب دليل Partner API، ويقرأ الهوية العامة غير الحساسة، ثم ينشئ أو يوقّع أو يرسل الفواتير في حدود الصلاحيات الممنوحة.

لاختبار المسارين استعمل Workflow Bash ومجموعات Postman المذكورة في مرجعي Partner API وOrganization API.

قائمة التحقق

• يشرح ملف Partner الخدمة بوضوح.
• لا تطلب إلا الصلاحيات الضرورية.
• تراجع المؤسسة كل صلاحية قبل OTP.
• تظهر علامة Activated بعد التأكيد.
• تظهر المؤسسة في قائمة Clients لدى Partner.
• يستطيع Partner قراءة الهوية العامة دون بيانات الخطة أو الاشتراك أو معلومات حساسة أخرى.
• تصل فاتورة اختبار كاملة إلى الحالة المنتظرة في Sandbox.