UBL ورمز QR

تنزيل مستند UBL

GET /v1/invoices/{id}/ubl

يُعيد application/xml — المستند نفسه الذي أُرسل إلى البوابة. أضف ?pretty=1 للتنسيق.

curl https://fawtara.codexal.co/api/v1/invoices/inv_5c8d1e9a2b7f3046/ubl?pretty=1 \
  -H "Authorization: Bearer fwt_live_xxx" -o invoice.xml

بنية المستند

هذا مثال مختصَر لفاتورة مبيعات نقدية بنسبة 16%:

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" …>
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:ID>S-2026-0042</cbc:ID>
  <cbc:UUID>9c2e4f1b-7a3d-4856-b0c9-1d2e3f4a5b6c</cbc:UUID>
  <cbc:IssueDate>2026-10-23</cbc:IssueDate>
  <cbc:InvoiceTypeCode name="012">388</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>JOD</cbc:DocumentCurrencyCode>
  <cbc:TaxCurrencyCode>JOD</cbc:TaxCurrencyCode>

  <cac:AdditionalDocumentReference>
    <cbc:ID>ICV</cbc:ID>
    <cbc:UUID>42</cbc:UUID>
  </cac:AdditionalDocumentReference>

  <cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>…</cac:AccountingCustomerParty>

  <cac:SellerSupplierParty>
    <cac:Party><cac:PartyIdentification>
      <cbc:ID>17688900</cbc:ID>   <!-- تسلسل مصدر الدخل -->
    </cac:PartyIdentification></cac:Party>
  </cac:SellerSupplierParty>

  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="JOD">144.000</cbc:TaxAmount>
    <cac:TaxSubtotal>…</cac:TaxSubtotal>
  </cac:TaxTotal>

  <cac:LegalMonetaryTotal>
    <cbc:TaxExclusiveAmount currencyID="JOD">900.000</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="JOD">1044.000</cbc:TaxInclusiveAmount>
    <cbc:AllowanceTotalAmount currencyID="JOD">25.000</cbc:AllowanceTotalAmount>
    <cbc:PayableAmount currencyID="JOD">1044.000</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>

  <cac:InvoiceLine>…</cac:InvoiceLine>
</Invoice>

الفرق بين فاتورة الدخل وفاتورة المبيعات

العنصر	مكلّف دخل	مكلّف مبيعات
الخانة الثالثة في `name`	`1` → `011` / `021`	`2` → `012` / `022`
`tax_percent`	تُفرض `0` دائمًا	حسب ما ترسله (16 عادةً)
`Item/ClassifiedTaxCategory`	لا يُضاف	يُضاف مع `Percent` و `TaxScheme`
`TaxTotal/TaxSubtotal`	لا يُضاف	يُضاف لكل نسبة ضريبية
إجمالي `TaxAmount`	`0.000`	مجموع ضريبة البنود

نختار المسار الصحيح تلقائيًا من حقل نوع التكليف في إعدادات حسابك — لذا اضبطه بدقّة.

رمز الاستجابة السريعة

GET /v1/invoices/{id}/qr.png

لديك ثلاث طرق للاستخدام:

صورة جاهزة: نادِ النقطة أعلاه من خادمك واحفظ الـ PNG. المعامل scale بين 2 و 14 يضبط الحجم (الافتراضي 6 ≈ 250 بكسل).
توليد محلي: خُذ qr_content من ردّ الفاتورة وولّد الصورة بأي مكتبة (chillerlan/php-qrcode، qrcode.js، qrcode في Python…).
تخزين مع الفاتورة: احفظ qr_content في جدول فواتيرك — فهو ما تطلبه الجهة الرقابية عند التحقّق، والصورة مجرّد تمثيل له.

# حفظ الصورة
curl "https://fawtara.codexal.co/api/v1/invoices/inv_5c8d1e9a2b7f3046/qr.png?scale=8" \
  -H "Authorization: Bearer fwt_live_xxx" -o qr.png

محتوى الرمز يأتي من البوابة نفسها (الحقل EINV_QR) وهو سلسلة Base64 لبنية TLV تحوي اسم البائع ورقمه الضريبي وتاريخ الفاتورة وإجماليها والضريبة ومعرّفها. لا نولّده نحن ولا نعدّله — نمرّره كما استلمناه. في بيئة الاختبار نولّد بنية TLV مماثلة الشكل لأغراض التطوير فقط.

الطباعة

الحد الأدنى الموصى به للطباعة: 2×2 سم، مع هامش هادئ (quiet zone) لا يقل عن وحدتين — وهو ما تنتجه نقطة الـ PNG افتراضيًا.

→ الاستعلام والسجل بيئة الاختبار ←