إنشاء فاتورة

POST /v1/invoices

ينشئ الفاتورة، يبني مستند UBL، ويُرسلها إلى بوابة الفوترة الوطنية في طلب واحد متزامن.

الترويسات

الترويسة	إلزامية	الوصف
`Authorization`	نعم	`Bearer <API_KEY>`
`Content-Type`	نعم	`application/json`
`Idempotency-Key`	مستحسنة بشدّة	مفتاح فريد لمنع التكرار عند إعادة الإرسال. التفاصيل.

حقول الجسم

الحقل	النوع	إلزامي	الوصف
`invoice_number`	string(64)	نعم	رقم الفاتورة في نظامك. فريد لكل حساب داخل الوضع نفسه.
`issue_date`	date	لا	`YYYY-MM-DD`. الافتراضي: تاريخ اليوم.
`payment_method`	enum	لا	`cash` (نقدي) أو `receivable` (ذمم). الافتراضي `cash`.
`currency`	string(3)	لا	ISO-4217. الافتراضي `JOD`.
`note`	string(500)	لا	ملاحظة تُرسل في `cbc:Note`.
`global_discount`	number	لا	خصم على مستوى الفاتورة. يُوزّع تناسبيًا على البنود (انظر أدناه).
`metadata`	object	لا	بيانات حرّة تُخزَّن معنا ولا تُرسل إلى البوابة.
`customer`	object	نعم	بيانات المشتري.
`lines`	array	نعم	بند واحد على الأقل، و 300 كحدٍّ أعلى.

كائن `customer`

الحقل	النوع	إلزامي	الوصف
`name`	string(191)	نعم	اسم المشتري. استخدم «مستهلك نهائي» للبيع النقدي للأفراد.
`identity_type`	enum	لا	`tax` (رقم ضريبي، يُرسل كـ `TN`)، `national` (رقم وطني، `NIN`)، `passport` (جواز، `PN`). الافتراضي `tax`.
`identity_number`	string	لا	قيمة الهوية حسب النوع. إن تركته نأخذ `tin`.
`tin`	string	لا	الرقم الضريبي للمشتري إن كان مكلّفًا.
`phone`	string	لا	يُرسل في `AccountingContact/Telephone`.
`city`	string	لا	المدينة.
`address`	string	لا	الشارع / العنوان.
`postal_code`	string	لا	الرمز البريدي.
`country_code`	string(2)	لا	الافتراضي `JO`.
`email`	string	لا	يُخزَّن لديك فقط.

عناصر `lines[]`

الحقل	النوع	إلزامي	الوصف
`name`	string(191)	نعم	اسم الصنف أو الخدمة.
`quantity`	number	لا	أكبر من صفر. الافتراضي `1`.
`unit_price`	number	نعم	سعر الوحدة قبل الضريبة.
`discount`	number	لا	خصم مبلغي على السطر، لا يتجاوز `quantity × unit_price`.
`tax_percent`	number	لا	نسبة الضريبة. الافتراضي نسبة المنشأة. تُفرض صفرًا لمكلّف الدخل.
`tax_category`	enum	لا	`S` خاضع · `Z` نسبة صفرية · `E` معفى · `O` خارج النطاق. تُستنتج تلقائيًا.
`unit_code`	string	لا	كود الوحدة UN/ECE. الافتراضي `PCE`.
`description`, `sku`	string	لا	للتوثيق لديك.

مطابقة شاشة «تنظيم فاتورة» في المنصة بحقول الـAPI

إن كنت تصدر فواتيرك اليوم يدوياً من منصة الفوترة الوطني، فهذه الخريطة تختصر مرحلة التحليل: كل حقل في شاشة «تنظيم فاتورة» وما يقابله هنا. المصدر هو «دليل المستخدم الخاص بمنصة الـPortal» الصادر عن نظام الفوترة الوطني.

يتم تمييز الحقول الإجبارية بوجود علامة *.

دليل المستخدم — «تنظيم فاتورة»

شاشة تنظيم فاتورة في منصة الفوترة الوطني: بيانات الفاتورة وبيانات البائع والمشتري وبنود السلع والمجاميع — شاشة «تنظيم فاتورة» في المنصة — المرجع الذي بُنيت عليه حقول نداء الإنشاء لدينا.

حقل الشاشة	ما يقابله هنا	ملاحظة من الدليل
رقم فاتورة البائع	`invoice_number`	الرقم التسلسلي للفاتورة الخاص بالبائع.
تاريخ إصدار الفاتورة *	`issue_date`	يُضبط بتاريخ اليوم مع إمكانية تغييره لتاريخ سابق — لا لتاريخ لاحق.
نوع العملة *	`currency`	في المنصة لا يمكن تغييره بعد إضافة أول سلعة.
فاتورة نقدية / فاتورة ذمم	`payment_method`	`cash` أو `receivable`.
نوع الفاتورة: محلية / تصدير / مناطق تنموية *	`lines[].tax_percent` + `customer.tin`	«محلية» مختارة تلقائياً. «تصدير» و«مناطق تنموية/تشجيع استثمار» بنسبة 0%، والثانية يجب فيها إدخال الرقم الضريبي للمشتري.
بيانات البائع	الإعدادات	في المنصة تُدخل تلقائياً من بيانات التسجيل. لدينا تُقرأ من إعدادات المنشأة.
اسم المشتري	`customer.name`	إجباري لفواتير الذمم وللفواتير بقيمة 10,000 وأكثر.
نوع المعرفات الإضافية	`customer.identity_type`	الرقم الوطني أو الرقم الضريبي أو الرقم الشخصي.
رقم المشتري	`customer.identity_number`	قيمة الهوية حسب النوع المختار.
رقم الهاتف / المدينة / الرمز البريدي	`customer.phone` · `customer.city` · `customer.postal_code`	اختيارية في الشاشة وعندنا.
وصف السلعة أو الخدمة *	`lines[].name`	تفاصيل السلعة أو الخدمة.
الكمية * / سعر الوحدة *	`lines[].quantity` · `lines[].unit_price`	لا ترسل مجاميع — تُحتسب كما تحتسبها المنصة.
قيمة الخصم	`lines[].discount`	خصم على مستوى البند، يُطرح قبل احتساب الضريبة.
نسبة الضريبة العامة *	`lines[].tax_percent`	لا تظهر لفواتير الدخل. يمكن أن تختلف من بند لآخر.
النوع (سلعة/خدمة أو بدل خدمة) *	`lines[].unit_code`	لا تظهر لفواتير الدخل.
التصنيف الوطني للأنشطة	الإعدادات	اختياري في الشاشة. يُرسل من بيانات المنشأة عند ضبطه.
قيمة الضريبة الخاصة *	مكلّف الضريبة الخاصة	تخصّ فواتير الضريبة الخاصة وحدها.

الاسم: لإدخال اسم المشتري، ويكون إجبارياً لفواتير الذمم والفواتير بقيمة 10000 وأكثر.

دليل المستخدم — «تنظيم فاتورة» / بيانات المشتري

لهذا نجعل customer.name إلزامياً دائماً: هو أكثر سبب رفض شيوعاً في فواتير الذمم، وفرضه مسبقاً أرخص من رفض من البوابة.

الاقتباسات واللقطة أعلاه من «نظام الفوترة الوطني — دليل المستخدم الخاص بمنصة الـPortal»، وتعود ملكيتها لجهة إصداره. أُدرجت للتوضيح التقني، والدليل الرسمي هو المرجع عند أي اختلاف.

كيف تُحسب الإجماليات

لكل بند:

gross = quantity × unit_price
net   = gross − discount                  // = LineExtensionAmount في UBL
tax   = round(net × tax_percent / 100, 3)
total = net + tax

وعلى مستوى الفاتورة:

subtotal       = Σ gross
discount_total = Σ discount
taxable        = Σ net                    // = TaxExclusiveAmount
tax_total      = Σ tax
total          = taxable + tax_total      // = TaxInclusiveAmount = PayableAmount

global_discount: يُوزَّع على البنود بنسبة قيمة كل بند من الإجمالي، ويُضاف إلى خصم السطر، مع تسوية فرق التقريب في البند الأخير. هذا يضمن أن TaxExclusiveAmount يساوي دائمًا مجموع LineExtensionAmount كما تتوقّعه البوابة.

مثال كامل — مكلّف مبيعات بنسبة 16%

الطلب

{
  "invoice_number": "S-2026-0042",
  "issue_date": "2026-10-23",
  "payment_method": "receivable",
  "currency": "JOD",
  "note": "دفعة أولى من العقد رقم 17",
  "global_discount": 5.000,
  "customer": {
    "name": "مؤسسة الفجر التجارية",
    "identity_type": "tax",
    "identity_number": "98765432",
    "tin": "98765432",
    "phone": "0795555555",
    "city": "Irbid",
    "address": "شارع الجامعة",
    "country_code": "JO"
  },
  "lines": [
    {
      "name": "لابتوب Dell Latitude 5440",
      "sku": "DL-5440",
      "quantity": 2,
      "unit_code": "PCE",
      "unit_price": 450.000,
      "discount": 20.000,
      "tax_percent": 16
    },
    {
      "name": "حقيبة لابتوب",
      "quantity": 2,
      "unit_price": 12.500,
      "tax_percent": 16
    }
  ],
  "metadata": { "erp_order_id": "SO-99813" }
}

الردّ — 201 Created

{
  "data": {
    "id": "inv_5c8d1e9a2b7f3046",
    "object": "invoice",
    "mode": "live",
    "document_type": "invoice",
    "invoice_number": "S-2026-0042",
    "uuid": "9c2e4f1b-7a3d-4856-b0c9-1d2e3f4a5b6c",
    "icv": 42,
    "type_code": "388",
    "type_name": "022",
    "payment_method": "receivable",
    "status": "accepted",
    "totals": {
      "subtotal": 925.000,
      "discount_total": 25.000,
      "tax_total": 144.000,
      "total": 1044.000
    },
    "qr_content": "AQ3YtNix...",
    "qr_image_url": "https://fawtara.codexal.co/api/v1/invoices/inv_5c8d1e9a2b7f3046/qr.png",
    "ubl_url": "https://fawtara.codexal.co/api/v1/invoices/inv_5c8d1e9a2b7f3046/ubl",
    "jofotara": { "status": "SUBMITTED", "uuid": "…", "http_code": 200 },
    "error": null,
    "attempts": 1,
    "submitted_at": "2026-10-23 00:32:09"
  }
}

رموز الاستجابة

الرمز	المعنى
`201`	أُنشئت وقُبلت من البوابة — `status = accepted`.
`202`	أُنشئت لدينا ولم تُقبل بعد (`rejected` أو `error`). راجع `error` ثم استخدم `retry`.
`200`	إعادة تشغيل لطلب سابق بنفس `Idempotency-Key` (مع `idempotent_replay: true`).
`402`	تجاوز الحصة الشهرية أو اشتراك غير نشط.
`409`	رقم فاتورة مكرّر، أو بيانات اعتماد البوابة غير مضبوطة.
`422`	خطأ تحقّق — `error.fields` يحدّد الحقل بدقّة.
`429`	تجاوز حد الطلبات في الدقيقة.

معاينة بدون إرسال

POST /v1/invoices/preview

نفس جسم الطلب، لكن لا يُنشأ سجل ولا يُرسل شيء ولا يُستهلك من حصّتك. يُعيد الإجماليات المحسوبة ومستند UBL المُنسَّق وubl_base64 — مثالي للتحقّق أثناء التطوير.

curl -X POST https://fawtara.codexal.co/api/v1/invoices/preview \
  -H "Authorization: Bearer fwt_test_xxx" \
  -H "Content-Type: application/json" \
  -d @invoice.json

→ مفاتيح البوابة من المنصة الإشعارات الدائنة (المرتجعات) ←