# حقول PINT AE التي تدعمها واجهة API

> كيف تُعيَّن مصطلحات الأعمال (BT / IBT) في PINT AE إلى حقول JSON في واجهة API في عليا بوكس.

Source: /help/ar/api/ibt-field-support

يسمي PINT AE كل جزء من بيانات الفاتورة بمصطلح أعمال مثل BT-1 (رقم الفاتورة). تعرض الجداول حقل JSON المقابل بصيغة camelCase في واجهة API في عليا بوكس. أما المصطلحات غير المدرجة (مثل BT-23 وBT-24) فتضبطها عليا بوكس.

## مستوى المستند

| المصطلح | المعنى | حقل API |
|---|---|---|
| BT-1 | رقم الفاتورة | `invoiceNumber` (اختياري، يُخصص من السلسلة) |
| BT-2 / BT-9 | تاريخ الإصدار / تاريخ الاستحقاق | `issueDate`؛ `dueDate` أو `payment.termsDays` |
| BT-3 | رمز النوع | `invoiceTypeCode` (380، 381، 480، 81؛ و389 و261 عند تفعيل الفوترة الذاتية) |
| BT-5 / BT-6 | العملة / عملة محاسبة ضريبة القيمة المضافة | `currency`، `vatAccountingCurrency` |
| BT-10 / BT-13 | مرجع المشتري / مرجع الطلب | `buyerReference`، مرجع الطلب |
| BT-22 | الملاحظات | `notes` |
| BT-25 / BT-26 | رقم الفاتورة السابقة / تاريخها | `precedingInvoice.number`، `precedingInvoice.issueDate` |
| IBG-03 | فاتورة الدفعة المقدمة (على الفاتورة) | `prepaymentInvoice.number`، `prepaymentInvoice.issueDate` |
| IBT-113 / IBT-114 / IBT-115 | المدفوع مقدماً / التقريب / المبلغ المستحق | `prepaidAmount`، `roundingAmount`؛ ويُعاد `payableAmount` |
| BTAE-02 | علامات نوع المعاملة | `transactionType` |
| BTAE-01 | معرّف المستفيد (المنطقة الحرة) | `beneficiaryId`؛ وهو المشتري إذا تُرك فارغاً |
| BTAE-14 | معرّف الموكّل (الوكيل المعلن) | `principalId` |
| BTAE-06 | تكرار الفوترة | `billingPeriod.frequency` |
| IBT-079 | إمارة أو ولاية أو منطقة التسليم | `delivery.emirate` |
| IBG-12 | عنوان الممثل الضريبي | `taxRepresentative.street` و`.city` و`.emirate` و`.country` |

تُستكمل مصطلحات الترويسة الأخرى (BT-7 وBT-11 وBT-12 وBT-20 وBT-59 إلى BT-80: نقطة الضريبة والمشروع والعقد وشروط السداد والمستفيد والممثل الضريبي والتسليم) في تكوين الحقول في التطبيق.

## الأطراف

| المصطلح | المعنى | المصدر |
|---|---|---|
| BT-27 إلى BT-43 | اسم البائع والرقم الضريبي (TRN) ومعرّف Peppol والعنوان وجهة الاتصال | **Settings** (الإعدادات) (وليس لكل طلب) |
| BT-44, BT-48, BT-49 | اسم المشتري والرقم الضريبي (TRN) ومعرّف Peppol | `buyer.name`، `buyer.trn`، `buyer.peppolId` |
| BG-8 | عنوان المشتري | `buyer.address.{street, additional, city, emirate, postalCode, country}` |

## السداد والخصومات والبنود

| المصطلح | المعنى | حقل API |
|---|---|---|
| BT-81 إلى BT-86 | وسيلة الدفع ومعرّف الدفع وIBAN واسم الحساب وBIC | `payment.accountId` وحقول السداد ذات الصلة |
| BT-92 إلى BT-104 | خصومات المستند ورسومه | `allowances[]` مع `amount` و`chargeIndicator` و`reason` و`taxCategory` و`taxRate` |
| BT-126 إلى BT-146 | معرّف البند والكمية والوحدة والمبلغ الصافي والسعر الصافي | موضع `items[]`، `quantity`، رمز الوحدة، `unitPrice`؛ ويُحتسب المبلغ |
| BT-151 / BT-152 | فئة الضريبة / النسبة | `items[].taxCategory` (`standard` أو `zero_rated` أو `exempt` أو `reverse_charge`)، `items[].taxRate` |
| BT-153 / BT-158 | الوصف / رمز HS | `items[].description`، `items[].hsnSacCode` |
| BTAE-13 / BTAE-17 | نوع الصنف / رمز محاسبة الخدمات | `items[].itemType` (`G` أو `S` أو `B`)، `items[].serviceAccountingCode` |
| IBT-134 / IBT-135 | بداية / نهاية فترة فوترة البند | `items[].billingPeriod.startDate`، `items[].billingPeriod.endDate` |

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

- القائمة الكاملة مع مسارات UBL موجودة في تبويب **Fields** (الحقول) في صفحة **PINT AE Reference** (مرجع PINT AE) وفي مواصفة OpenAPI المرتبطة من **API access** (الوصول إلى API).
- تُرسل المصطلحات الاختيارية، مثل سطر العنوان الثالث والطرف المستلم ومراجع البنود وخصائص الصنف، ضمن `optionalFields` على الفاتورة وعلى كل بند. ينتمي كل منها إلى مجموعة يفعّلها دعم عليا بوكس لكل شركة؛ راجع [حقول الفاتورة الإلكترونية الاختيارية](/help/ar/settings/optional-e-invoice-fields). الحقل الذي مجموعته معطّلة يُرفض، ويسمّيه الخطأ.
- يذكر `exchangeRateSource` مصدر `exchangeRate` المُرسل (نص حر، 200 حرف)؛ أرسله للعملات التي لا ينشرها المصرف المركزي. يُحفظ مع الفاتورة ولا يُكتب في ملف XML.
- للمشتري خارج الإمارات (`buyer.address.country` ليست `AE`) يُقبل أي رقم ضريبة قيمة مضافة في `buyer.trn` حتى 30 حرفاً؛ أما للمشترين في الإمارات فيجب أن يكون 15 رقماً.
- الحقول المخصصة (`metadata`) ليست مصطلحات PINT AE ولا تُكتب في ملف XML. أما الإجماليات (BT-106 إلى BT-115) فتحتسبها عليا بوكس دائماً.

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

- [الحقول المطلوبة عند إنشاء الفواتير عبر API](/help/ar/api/required-fields)
- [فئات ضريبة القيمة المضافة والرقم الضريبي](/help/ar/vat/tax-categories-and-trn)