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

> الحد الأدنى من الحمولة لـ POST /invoices، وما تملؤه عليا بوكس نيابة عنك، وما لا يزال PINT AE يحتاج إليه.

Source: /help/ar/api/required-fields

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

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

| الحقل | القاعدة |
|---|---|
| `buyer.name` أو `buyer.id` | اسم المشتري، أو معرّف جهة اتصال موجودة |
| `items` | بند واحد على الأقل، و500 بند على الأكثر |
| `items[].description` | نص، حتى 1000 حرف |
| `items[].quantity` | رقم |
| `items[].unitPrice` | السعر الصافي |

لكل شيء آخر قيمة افتراضية: `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) والمشترين لديك يتوقعونها.

## مثال

```json
{ "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](/help/ar/api/ibt-field-support)
- [أخطاء API ورموز الحالة](/help/ar/api/error-handling)