إنتقل إلى المحتوى الرئيسي

سير عمل Bash الكامل

ينفّذ fatoora-full-workflow.sh المسار الكامل: مصادقة OAuth2، جلب المعرّف الجبائي آليًا، إنشاء فاتورة TEIF أو التحقق منها، توقيع SEAL، الإرسال إلى TTN، متابعة المهمة، ثم تنزيل XML الموقّع وPDF.

تنزيل fatoora-full-workflow.sh

الرابط المباشر: /files/examples/fatoora-full-workflow.sh

عرض تنفيذ حقيقي​

تعرض هذه الحركة إعادة مجهّلة للاختبار الكامل الذي تم التحقق منه على بيئة sandbox: تصل الفاتورة إلى ACCEPTED_TTN ثم يتم تنزيل XML الموقّع وPDF.

عرض متحرك لتنفيذ سير عمل Fatoora في الطرفية

المتطلبات​

  • Bash 4 أو أحدث؛
  • الأدوات curl وjq وawk؛
  • مفتاح Organization API أو Partner API صالح؛
  • إعداد SEAL جاهز؛
  • معرّف جبائي مضبوط للمؤسسة.
chmod +x fatoora-full-workflow.sh
./fatoora-full-workflow.sh --help
حماية بيانات الدخول

لا تحفظ client_secret في Git أو الصور أو سجل أوامر مشترك. استخدم متغيرات البيئة وغيّر فورًا أي سر تم كشفه.

Organization API​

يجلب السكربت taxIdentifier من GET /api/v2/organization ويستعمله في MessageSenderIdentifier.

./fatoora-full-workflow.sh \
  --mode organization \
  --client-id "$FATOORA_CLIENT_ID" \
  --client-secret "$FATOORA_CLIENT_SECRET" \
  --format json --generate-invoice \
  --invoice-number "TEST-$(date +%s)" \
  --buyer-tax-id 7654321RAM000 --buyer-name "حريف تجريبي" \
  --item-description "خدمة تجريبية" --quantity 1 --unit-price 100 --vat-rate 19 \
  --signature-type seal \
  --base-url https://business.sandbox.fatoora.tn

Partner API​

يحصل السكربت أولًا على token للتطبيق، ثم يعرض المؤسسات التي رخّصت للشريك، وبعد الاختيار يحصل على token خاص بالمؤسسة.

./fatoora-full-workflow.sh \
  --mode partner \
  --client-id "$FATOORA_PARTNER_CLIENT_ID" \
  --client-secret "$FATOORA_PARTNER_CLIENT_SECRET" \
  --org-tax-id 1234567RAM000 \
  --format json --generate-invoice \
  --invoice-number "PARTNER-$(date +%s)" \
  --buyer-tax-id 7654321RAM000 --buyer-name "حريف تجريبي" \
  --item-description "خدمة تجريبية" --quantity 1 --unit-price 100 --vat-rate 19 \
  --signature-type seal

يمكن الاختيار بواسطة --org-id أو --org-tax-id أو --interactive. لا يتم الاختيار آليًا إلا إذا كانت هناك مؤسسة واحدة مرخِّصة.

فاتورة موجودة​

استخدم --invoice-file ./invoice.json أو --invoice-file ./invoice.xml مع --format المناسب. يتحقق السكربت من تطابق MessageSenderIdentifier مع taxIdentifier قبل الإرسال.

النتائج​

بعد الوصول إلى COMPLETED وACCEPTED_TTN، يحتوي مجلد النتائج على:

  • <invoice-id>.xml: ملف TEIF موقّع؛
  • <invoice-id>.pdf: ملف PDF للفاتورة.

من الخيارات المفيدة: --output-dir و--poll-interval و--poll-timeout و--debug. يخفي وضع debug الأسرار وbearer tokens. لا تستخدم --insecure إلا محليًا وفي بيئة مراقبة.

حل المشاكل​

  • الأتمتة الكاملة متاحة لـ SEAL فقط؛ DigiGO يتطلب تفاعل OAuth/OTP من المستخدم.
  • PARTNER_NOT_REGISTERED: أضف عنوان الحريف كاملًا أو أنشئه مسبقًا.
  • SENDER_MATRICULE_MISMATCH: معرّف البائع لا يطابق المؤسسة المصادق عليها.
  • NO_SIGNATURE_CREDITS: رصيد أو حصة التوقيع منتهية.
  • TTN_REJECTED أو VALIDATION_FAILED: راجع حالة المهمة وسجلاتها في Fatoora.