الحقول المطلوبة عند إنشاء الفواتير عبر API

يقبل POST /invoices فاتورة واحدة أو دفعة ضمن invoices. تتحقق عليا بوكس من الحمولة، ثم تجري فحص PINT AE الكامل قبل أن تغادر الفاتورة حالة المسودة. تفصل القائمة أدناه بين ما يجب أن يتضمنه الطلب وما يجب إعداده مرة واحدة في التطبيق.

المطلوب في الطلب

لكل شيء آخر قيمة افتراضية: issueDate هو اليوم، وcurrency هي AED، وinvoiceTypeCode هو 380 (فاتورة ضريبية)، وtaxCategory هي standard بنسبة 5 %، وlanguage هي en. يُشتق dueDate من payment.termsDays عند تقديمه. إذا أُرسل buyer.trn فيجب أن يكون مكوّناً من 15 رقماً.

المطلوب بموجب PINT AE

تأتي هذه من إعدادات مؤسستك ويُتحقق منها في كل فاتورة:

• اسم البائع والرقم الضريبي (TRN) (15 رقماً) والشارع والمدينة والدولة ضمن Settings → Profile (الإعدادات ← الملف الشخصي) وTax & currency (الضريبة والعملة) (BT-27 وBT-31 وBT-35 وBT-37 وBT-40).
• لإشعارات الدائن والمدين: precedingInvoice.number (BT-25).
• تاريخ استحقاق كلما كان هناك مبلغ مستحق (IBR-127-AE): dueDate، أو payment.termsDays لحسابه. يمكن إغفاله في الإشعارات الدائنة والفواتير المدفوعة مقدماً بالكامل (prepaidAmount مساوٍ للإجمالي).
• الحقول المخصصة المحددة كمطلوبة في القالب النشط لنوع المستند، وتُرسل كـ metadata: { key: value }.

يُعيد نقص بيانات البائع 400 E_VALIDATION مع مصطلحات الأعمال في extra.errors، ولا يُنشأ شيء. أضف draftOnly: true لإنشاء مسودة على أي حال وإكمالها في التطبيق.

الموصى به

الرقم الضريبي (TRN) للمشتري وبريده الإلكتروني، ووسيلة الدفع وIBAN (payment.accountId)، ومرجع الطلب أو مرجع المشتري. لا تثير هذه سوى تحذيرات، لكن الهيئة الاتحادية للضرائب (FTA) والمشترين لديك يتوقعونها.

مثال

{ "invoices": [{
  "buyer": { "name": "Buyer LLC", "trn": "100000000000011" },
  "issueDate": "2026-09-23",
  "payment": { "termsDays": 30 },
  "items": [{ "description": "Consulting, September", "quantity": 10, "unitPrice": 500 }],
  "submit": true
}] }

معلومات مفيدة

• لا يمكن الجمع بين draftOnly وsubmit أو send.
• invoiceNumber اختياري؛ ويُخصص الرقم التالي من السلسلة. يفشل الرقم المستخدم بالفعل مع field: invoiceNumber.
• في الدفعة، أُنشئت العناصر التي تحمل success: true حتى عندما تكون حالة الاستجابة 400؛ فأعد المحاولة للعناصر الفاشلة فقط.
• تُطابق جهات الاتصال بالمعرّف، ثم بالرقم الضريبي (TRN)، ثم بالاسم؛ ويُنشأ المشترون غير المعروفين.

مقالات ذات صلة

• حقول PINT AE التي تدعمها واجهة API
• أخطاء API ورموز الحالة