نظرة عامة

فواترا طبقة وسيطة (API Gateway) بين نظامك ونظام الفوترة الوطني الأردني (JoFotara). ترسل إلينا الفاتورة بصيغة JSON مألوفة، فنقوم نحن بما يلي:

1. التحقّق من صحّة البيانات وحساب الإجماليات والضريبة بدقّة ثلاث خانات عشرية.
2. تخصيص UUID وعدّاد ICV تصاعدي لا يتكرّر لمنشأتك.
3. بناء مستند UBL 2.1 مطابق لمتطلّبات البوابة، وترميزه base64.
4. الإرسال إلى البوابة بترويستي Client-Id و Secret-Key الخاصّتين بمنشأتك.
5. تفسير الردّ، واستخراج محتوى رمز QR، وتخزين الطلب والردّ كاملين للتدقيق.
6. إشعار نظامك عبر Webhook موقّع (في الخطط المدفوعة).

الأساسيات

شكل الردّ

الاستجابة الناجحة:

{
  "data": {
    "id": "inv_7a2f9c1b4e8d0536",
    "object": "invoice",
    "mode": "live",
    "invoice_number": "INV-1001",
    "status": "accepted",
    "qr_content": "AQ3YtNix...",
    "qr_image_url": "https://fawtara.codexal.co/api/v1/invoices/inv_7a2f9c1b4e8d0536/qr.png",
    "totals": { "subtotal": 150.000, "tax_total": 0.000, "total": 150.000 }
  }
}

الاستجابة في حالة الخطأ:

{
  "error": {
    "type": "validation_error",
    "message": "بيانات الطلب غير صحيحة.",
    "fields": {
      "lines.0.unit_price": ["سعر الوحدة مطلوب ولا يقبل القيم السالبة."]
    }
  }
}

حالات الفاتورة

قبل أن تبدأ

• سجّل منشأتك لدى دائرة ضريبة الدخل والمبيعات واحصل على Client-Id و Secret-Key من شاشة «ربط الأجهزة» — الخطوات بالصور في مفاتيح البوابة من المنصة.
• اعرف نوع تكليفك: دخل، أو مبيعات، أو مبيعات خاصة — فهو يُحدّد بنية الفاتورة.
• اعرف تسلسل مصدر الدخل الخاص بك من البوابة.
• أنشئ حساب مطوّر هنا، وابدأ على بيئة الاختبار قبل الإنتاج.