الموارد · PDFgine

رفع مورد

تُرفع الشعارات والتوقيعات والخطوط مرة واحدة ثم يُشار إليها بالمعرّف. الطلب من نوع multipart؛ يوضع الملف في الحقل file ويكون altText اختياريًا.

الطلب

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@logo.png" \
  -F "altText=شعار الشركة"

HTTP 201

{
  "assetId": "ast_985f87e2b22d486db2d6d8bacd29288e",
  "fileName": "logo.png",
  "contentType": "image/png",
  "length": 20184,
  "altText": "شعار الشركة",
  "createdAt": "2026-09-26T15:29:44.8420041+00:00",
  "expiresAt": null,
  "fontEmbedding": null
}

يُقرأ النوع من أول بايتات الملف، وليس من Content-Type المُرسل: يُرفض ملف .png إذا كان PDF فعليًا. تُقبل PNG وJPEG وWebP وTTF وOTF حتى 10 MB لكل ملف.

استخدامه في مستند

أرسل المعرّف حيث يتوقع القالب صورة. يقبل الحقل نفسه أيضًا عنوان URI من نوع data:، لكن المورد المرفوع أصغر أثناء النقل ويمكن إعادة استخدامه.

الطلب

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "data": { "logo": "ast_985f87e2b22d486db2d6d8bacd29288e" }
      }'

الموارد المؤقتة وسردها وحذفها

لا تحتاج صورة لمستند واحد إلى حذف يدوي: حدّد expiresInMinutes بين 1 و10080 (سبعة أيام) ليُحذف المورد تلقائيًا.

الطلب

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@signature.png" \
  -F "expiresInMinutes=60"

# السرد ومحتوى مورد واحد والحذف
curl https://api.pdfgine.com/api/v1/assets -H "X-PDFgine-Key: $PDFGINE_KEY"
curl https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e/content \
  -H "X-PDFgine-Key: $PDFGINE_KEY" -o logo.png
curl -X DELETE https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

الخطوط وما يجوز تضمينه

يحدد ملف الخط في بتات fsType الخاصة به ما يُسمح للمستند بفعله به. يقرأ PDFgine ذلك عند الرفع ويجيب بـ fontEmbedding، فتعرف النتيجة قبل إنتاج المستند بدلًا من معرفتها بعد فتحه.

`fontEmbedding`	ما يُسمح للمستند بفعله
`installable`	بلا قيود؛ يُضمّن في PDF وWord.
`editable`	يُضمّن في PDF وWord.
`preview-print`	يُضمّن في PDF. لا يُضمّن في Word لأن مستند Word قابل للتحرير؛ ويستبدل Word الخط.
`restricted`	لا يُضمّن في أي موضع. يُنتج المستند مع ذلك ويُستخدم خط لدى القارئ بدلًا منه.
`bitmap-only`	يُسمح بتضمين الصور النقطية فقط، وهو غير قابل للاستخدام في المستند. لا يُضمّن.
`unstated`	لا يحدد الملف إذنًا. يُعامل كخط قابل للتضمين وفق ما تطلبه مواصفة OpenType.

تُرفض WOFF وWOFF2 عند الرفع. لا يمكن تضمينها في مستند Word، فيظهر القالب نفسه صحيحًا في PDF وخاطئًا في Word؛ وهو فرق قد لا تلاحظه إلا بعد إرسال المستند.

الخطوط المدمجة

تأتي هذه العائلات مع المنتج؛ استخدم أسماءها في style.fontFamily وpage.defaultFont. يُستخدم نمط الخط نفسه في PDF وWord والمحرر. لا يُرفض وزن غير موجود في العائلة؛ بل يُستخدم أقرب نمط.

العائلة	المجموعة	الأوزان	أنظمة الكتابة
`Inter`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Roboto`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Montserrat`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, cyrillic, vietnamese
`Poppins`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`DM Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`Nunito`	`sans`	200, 300, 400, 500, 600, 700, 800, 900	latin, cyrillic, vietnamese
`Manrope`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, greek, cyrillic, vietnamese
`Noto Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Plus Jakarta Sans`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Work Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, vietnamese
`Roboto Condensed`	`condensed`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Oswald`	`condensed`	200, 300, 400, 500, 600, 700	latin, latin-ext, cyrillic, vietnamese
`Noto Serif`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`EB Garamond`	`serif`	400, 500, 600, 700, 800	latin, latin-ext, greek, cyrillic, vietnamese
`Newsreader`	`serif`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Literata`	`serif`	200, 300, 400, 500, 600, 700, 800, 900	latin, greek, cyrillic, vietnamese
`Tinos`	`serif`	400, 700	latin, latin-ext, greek, cyrillic, vietnamese
`Rokkitt`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Inconsolata`	`mono`	200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Noto Sans Mono`	`mono`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Arial`	`system`	400, 700
`Georgia`	`system`	400, 700

عندما يُرفض الرفع

يعيد كل رفض الحالة 400 مع السبب تحت errors.file. اعرض تلك الجملة على من يرفع الملف؛ فهي توضح بالفعل ما يجب فعله.

HTTP 400

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": ["ارفع خطًا بتنسيق TTF أو OTF ليتمكن مستند Word الناتج من استخدامه. لا يمكن تضمين ملفات WOFF وWOFF2 في مستند Word."]
  },
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

الأخطاء →

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

يُقرأ النوع من أول البايتات لا من اسم الملف. تغيير اسم PDF إلى .png لا يجعله صورة؛ يُرفض الرفع.
تُرفض WOFF وWOFF2 عمدًا. لا يمكن تضمينهما في Word فيظهر القالب صحيحًا في PDF وخاطئًا في Word؛ ارفع TTF أو OTF.
يجيب الرفع بـ fontEmbedding. تجاهله يعني أنك لن تعلم باستبدال الخط إلا بعد إرسال المستند.
يُنقل عنوان URI من نوع data: مع كل طلب. لشعار يظهر في كل مستند، ارفعه مرة واحدة وأرسل معرّفه.
لا تحتاج صورة لمستند واحد إلى حذف يدوي. حدّد expiresInMinutes لتُحذف تلقائيًا.