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

عمليات التكامل مع Make وZapier

قبل الاتصال

تحتاج إلى حساب عميل PDFgine، وقالب في مساحة العمل تلك، وحصة صفحات متاحة، وحساب Make أو Zapier. أنشئ القالب أولًا ودوّن قيمة Template Code الخاصة به.

تطبيق Make قيد المراجعة لإدراجه في الكتالوج. تكامل Zapier خاص. تواصل مع PDFgine للحصول على الوصول؛ لم يُدرج أيٌّ من التكاملين في الكتالوج العام بعد.

اطلب الوصول إلى التكامل

اربط مساحة عملك

أنشئ مفتاح API مخصصًا في حساب PDFgine بصلاحيتي usage:read وdocuments:render. استخدم عنوان API المستضاف أدناه. أضف templates:read فقط إذا كنت تستخدم محدد Brand Kit الاختياري للمعاينات.

https://api.pdfgine.com · usage:read · documents:render

يوفّر محدد Locale في الموصّل حاليًا الإنجليزية والتركية. لا تغيّر لغة الموقع بيانات المستند أو الحقول المتاحة في الموصّل.

أعدّ سيناريو Make

  1. اقبل الوصول إلى التطبيق الخاص الذي يوفّره PDFgine. أضف وحدة PDFgine إلى السيناريو وأنشئ اتصالًا بعنوان API ومفتاح API المخصص.
  2. اختر Create a Document، واضبط Template Code وFormat، ثم اربط قيم الوحدة السابقة بكائن JSON في Template Data. استخدم Queue a Document للعمل غير المتزامن أو Create a Public Preview لرابط موجّه للمستلم.
  3. شغّل Run once ببيانات تجريبية وافحص نتيجة الوحدة والمستند المُولَّد. لا تفعّل الجدولة إلا بعد صحة الربط. يدعم Make an API call مسارات API النسبية المُصرَّح بها؛ وتبقى صلاحيات الاتصال سارية.

أعدّ Zap

  1. اقبل دعوة تكامل PDFgine الخاص في حساب Zapier. اختر المُشغِّل، وأضف إجراء PDFgine، ثم اتصل باستخدام عنوان API ومفتاح API المخصص.
  2. في Create Document، اضبط Template Code وFormat، ثم اربط بيانات المُشغِّل بحقل Template Data بصيغة JSON صالحة. يُعدّ Queue Document وCreate Public Preview إجراءين منفصلين. Brand Kits مصدر اختياري لقائمة منسدلة، وليس مُشغِّلًا.
  3. اختبر الإجراء، وانشر Zap، ثم أرسل حدث تشغيل جديدًا. تأكد من نجاح التنفيذ في Zap History وافحص مستند ذلك الحدث؛ فلا تكفي نتيجة Test Step في المحرر وحدها لإثبات تشغيل سير العمل الفعلي.

اربط قيمًا فعلية وحافظ على JSON صالح

يجب أن يكون Template Data كائن JSON مطابقًا لحقول القالب، لا مسار ملف أو عنصرًا نائبًا فارغًا. المثال أدناه لقالب عرض سعر. اربط الأسماء والمبالغ من المُشغِّل، وأبقِ القيم الرقمية أرقامًا، وتحقق من الإجماليات المحسوبة قبل الإرسال.

JSON 
{
  "document": { "title": "DEMO ONLY" },
  "referenceNo": "DEMO-001",
  "issueDate": "2026-10-27",
  "currency": "USD",
  "customer": "Demo Customer",
  "quoteItems": [
    { "name": "Demo service", "quantity": 2, "unitPrice": 50, "total": 100 }
  ],
  "subtotal": 100,
  "vatAmount": 20,
  "grandTotal": 120
}

اختر المخرج المناسب

يُرجع Create Document رابط downloadUrl محميًا يتطلب مصادقة API. لرابط يفتحه العميل في المتصفح، استخدم Create Public Preview واختر مدة وصول مسموحًا بها. يُرجع Queue Document رابط statusUrl لحالة المهمة؛ والاستجابة بأن المهمة في الانتظار لا تعني اكتمال المستند.

الإنشاء عبر قائمة الانتظار · روابط المعاينة

اختبر قبل التفعيل

ابدأ ببيانات عملاء اصطناعية. تحقق من المستلم والمرجع والبنود والإجماليات وصيغة المخرج. بعد تفعيل سير العمل، أرسل حدثًا جديدًا واحدًا وتحقق من سجل التنفيذ في المنصة. تجنّب تكرار عمليات الإنتاج؛ فالصفحات المُولَّدة تستهلك حصتك في PDFgine.

الحدود واستكشاف الأخطاء

عند 401 أو 403، تحقق من الاتصال وصلاحيات API. عند 402، تحقق من الحصة المتاحة. عند 429، التزم بقيمة Retry-After وخفّض تكرار الطلبات. أصلح JSON أو بيانات القالب غير الصالحة قبل إعادة المحاولة. تعتمد مدة المعاينة وحدود التوليد على خطتك.

الأخطاء · قراءة حصتك

حافظ على سرية مفاتيح الاتصال

أدخل مفتاح API في إعدادات اتصال المنصة فقط. لا تضعه في Template Data أو لقطات الشاشة أو سجلات التنفيذ المشتركة. استخدم مفتاحًا منفصلًا لكل اتصال وألغِه في PDFgine عند انتهاء الحاجة إلى الوصول.

هل تحتاج إلى أحداث المستندات؟ راجع دليل webhooks الخاص بـ API. إشعارات Webhook