دليل المنتج وAPI

تنسيقات البيانات

تجد هنا البنية التي يجب أن تصل بها بياناتك. لا يطبع PDFgine القيمة المُرسلة كما هي، بل يطبق المنسّق المحدد في القالب بلغة المستند.

بعبارة واحدة: تصل البيانات خامًا ويتولى PDFgine تنسيقها. إذا أرسلت قيمة منسقة مسبقًا، سيعرضها المستند بشكل صحيح في لغة وخاطئ في أخرى.

نوع الحقل كيفية إرساله مثال إدخال المخرجات
date ISO 8601. استخدم YYYY-MM-DD للتاريخ وحده، وطابعًا زمنيًا كاملًا عندما يهم الوقت. لا تحوّله إلى تنسيق محلي. "2026-09-06" 6/9/2026
number عدد JSON، دون فواصل آلاف أو مسافات أو علامات اقتباس؛ والفاصل العشري نقطة. 24000 24,000.00
currency أرسل المبلغ كعدد خام. لا تضع العملة ضمنه؛ بل حدّدها في منسّق العمود كرمز ISO 4217. 24000 24,000.00 USD
percent نسبة من مئة بصيغتها الخام: أرسل 18 للتعبير عن 18%. يضيف المستند العلامة. 18 18.00%
string تُطبع كما تصل. لا ترسل تاريخًا أو مبلغًا أو نسبة كنص، وإلا فُقد التنسيق. "Northwind Trading Ltd." Northwind Trading Ltd.
boolean قيمة JSON من نوع true/false. تقرؤها الكتل الشرطية. true تحدد الشرط ولا تُطبع كنص مطلقًا

يُحدد المنسّق في ثلاثة مواضع: الحقل "format" في عمود جدول وصف ملخص، و"dataRules.formatter" في عنصر يطبع قيمة واحدة، والدالتان format_date وformat_money في نص يجمع عدة حقول.

البيانات والقالب 
{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "موقع الشركة الإلكتروني", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// في جانب القالب:
// عمود الجدول:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// عمود التاريخ:    "format": { "kind": "date", "dateStyle": "short" }
// عنصر النص:   "{{ referenceNo }} · {{ format_date issueDate }}"

تصل أرقام IBAN والهواتف والضرائب بصيغة موحدة أيضًا: IBAN دون مسافات، والهاتف بتنسيق E.164 ‏(+442071838750). تجميع الخانات تنسيق للعرض ولا مكان له في البيانات.

الاسم الذي يصل به المستند

يُسمى المستند المُنزّل "{document type} - {counterparty} - {reference no}". تأتي الأجزاء الثلاثة من البيانات التي ترسلها: document.title وcustomer وreferenceNo. يُحذف أي جزء مفقود، وإذا لم تنتج اسمًا صالحًا يُستخدم معرّف المستند، مثل quote-doc_94812af2.pdf.

ترويسة الاستجابة 
Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

يُكتب الاسم مرتين في الترويسة نفسها. يحافظ الحقل الموسع على لغة المستند، ويحمل الحقل التقليدي صيغة ASCII مقروءة للعملاء الذين لا يدعمون الحقل الموسع. تُحذف الأحرف التي لا تقبلها أنظمة الملفات (الشرطة المائلة، والشرطة المائلة العكسية، والنقطتان، والنجمة، وعلامة الاستفهام، والاقتباس، وأصغر من، وأكبر من، والخط العمودي) مع أحرف التحكم، ويُحد طول الاسم ليصلح لكل نظام ملفات.

الصور

يمكن ربط عنصر صورة في القالب بحقل بيانات، فيصل المصدر مع الطلب. تُقبل صيغتان: معرّف مورد مرفوع (ast_… للشعارات والأختام والتوقيعات المتكررة؛ يُرفع مرة ويُنقل المعرّف فقط)، وصورة مضمنة (data:image/png;base64,… للصور المستخدمة مرة واحدة). إذا غاب الحقل أو كان فارغًا تُستخدم صورة القالب، وإذا وُجدت قيمة غير قابلة للاستخدام يُرفض الطلب بالحالة 422 وتحدد الاستجابة حقل البيانات.

الطلب 
{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

الحدود: يجب أن تكون الصورة المضمنة PNG أو JPEG أو WebP، بحد 2 MB لكل صورة و6 MB لجميع صور المستند. قد يصل المورد المرفوع إلى 10 MB. للصور المؤقتة مرر expiresInMinutes عند الرفع (من دقيقة إلى 7 أيام)؛ يُحذف المورد المنتهي تلقائيًا.

الموارد

تُرفع الشعارات والتوقيعات والخطوط مرة واحدة ويُشار إليها بالمعرّف. تشرح صفحتها الرفع والحدود وما يسمح به الخط.

الموارد →

الأخطاء الشائعة

  • تُطبع القيمة المنسقة مسبقًا كما تصل. تُقرأ "1.234,56" بشكل صحيح في لغة وخاطئ في أخرى، ولا يستطيع أي منسّق إصلاحها بعد ذلك.
  • يجب أن يكون التاريخ بتنسيق ISO 8601. يصل التنسيق المحلي كنص، فلا يُنسّق ولا يُرتب ولا يُترجم.
  • لا تضع العملة داخل المبلغ. أرسل العدد ودع منسّق العمود يضيف رمز ISO.
  • تُرسل النسبة من مئة: 18 للتعبير عن 18%. إرسال 0.18 يطبع صفر فاصلة ثمانية عشر بالمئة.
  • يقرأ الشرط قيمة منطقية في JSON. النص "false" غير فارغ ويُعد موجودًا.