حقول PINT AE التي تدعمها واجهة API
كيف تُعيَّن مصطلحات الأعمال (BT / IBT) في PINT AE إلى حقول JSON في واجهة API في عليا بوكس.
يسمي 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على الفاتورة وعلى كل بند. ينتمي كل منها إلى مجموعة يفعّلها دعم عليا بوكس لكل شركة؛ راجع حقول الفاتورة الإلكترونية الاختيارية. الحقل الذي مجموعته معطّلة يُرفض، ويسمّيه الخطأ. - يذكر
exchangeRateSourceمصدرexchangeRateالمُرسل (نص حر، 200 حرف)؛ أرسله للعملات التي لا ينشرها المصرف المركزي. يُحفظ مع الفاتورة ولا يُكتب في ملف XML. - للمشتري خارج الإمارات (
buyer.address.countryليستAE) يُقبل أي رقم ضريبة قيمة مضافة فيbuyer.trnحتى 30 حرفاً؛ أما للمشترين في الإمارات فيجب أن يكون 15 رقماً. - الحقول المخصصة (
metadata) ليست مصطلحات PINT AE ولا تُكتب في ملف XML. أما الإجماليات (BT-106 إلى BT-115) فتحتسب ها عليا بوكس دائماً.