تحويل HTML إلى PDF
يحوّل مستند HTML أو صفحة ويب إلى ملف PDF. يتبع الطلب والاستجابة واجهة PDFShift v3.
POST https://api.sahifa.dev/v3/convert/pdf
Content-Type: application/jsonأبسط طلب
{ "source": "<h1>Hello</h1>" }جسم الاستجابة هو ملف PDF (Content-Type: application/pdf). وتعطي الترويسة X-Response-Duration زمن الإنشاء بالمللي ثانية.
المعاملات
المصدر والصفحة
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
source | نص | مطلوب | عنوان http(s):// لتحميله، أو مستند HTML. كل ما لا يبدأ بـ http:// أو https:// يُعامَل على أنه HTML. |
format | نص | A4 | من A0 إلى A6، و Letter و Legal و Tabloid و Ledger، أو مقاس مخصص مثل 210mmx297mm أو 8.5inx11in (الوحدات: px و in و cm و mm). |
landscape | منطقي | false | اتجاه أفقي. |
margin | نص أو كائن | بلا | صيغة CSS المختصرة ("20mm" أو "20mm 15mm" أو أربع قيم) أو كائن فيه top و right و bottom و left. الأرقام المجردة بالبكسل. |
pages | نص | الكل | الصفحات المطلوب الإبقاء عليها، مثل "1" أو "1-3" أو "1,3-5". |
zoom | عدد | 1 | مقياس المحتوى، من 0.1 إلى 2. |
use_print | منطقي | false | الإنشاء بورقة أنماط الطباعة (@media print). لازم لتكرار ترويسة الجدول في كل صفحة؛ راجع الجداول الممتدة على عدة صفحات. |
disable_backgrounds | منطقي | false | إسقاط ألوان الخلفية وصورها. |
الترويسة والتذييل
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
header | كائن | بلا | { "source": "<html>" } يتكرر أعلى كل صفحة. |
footer | كائن | بلا | مثله، أسفل كل صفحة. |
المتغيرات التي تُستبدل في كل صفحة: {{page}} و {{total}} و {{date}} و {{title}} و {{url}}.
تحتاج الترويسة أو التذييل إلى هامش. من دون margin يُرفض الطلب بالرمز 400، لأن الترويسة ستغطي المحتوى. تُرسم الترويسة والتذييل داخل الهامش بحجم 10 بكسل، فاترك لهما من 15 إلى 25 مم.
يُنشآن بمعزل عن المستند: لا تنطبق عليهما أنماط المستند الرئيسي، ولا تعمل فيهما السكربتات. ضع الأنماط داخل العنصر مباشرة. يُقبل المعامل height لكن المساحة تأتي من الهامش. ولا يُدعم start_at.
{
"source": "<html dir=\"rtl\">...</html>",
"margin": { "top": "25mm", "bottom": "20mm", "left": "15mm", "right": "15mm" },
"header": { "source": "<div style=\"width:100%;text-align:right;font-size:9px\">{{title}}</div>" },
"footer": { "source": "<div style=\"width:100%;text-align:center\">صفحة {{page}} من {{total}}</div>" }
}التحميل والتوقيت
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
delay | عدد صحيح | 0 | انتظار إضافي بعد تحميل الصفحة، بالمللي ثانية، حتى 10000. |
wait_for | نص | بلا | اسم دالة جافاسكربت عامة. يبدأ الإنشاء حين تُعيد قيمة صحيحة. مفيد للرسوم البيانية والبيانات التي تُحمَّل بالسكربت. |
timeout | عدد صحيح | 30 | أقصى زمن للإنشاء بالثواني. القيم الأكبر من 30 تُحدّ عند 30. |
raise_for_status | منطقي | false | لمصدر من نوع عنوان: يُعاد الخطأ 400 إذا ردّت الصفحة برمز 400 أو أعلى، بدلًا من إنشاء صفحة الخطأ. |
disable_javascript | منطقي | false | عدم تشغيل السكربتات في الصفحة. |
حقن الشيفرة
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
css | نص | بلا | نص CSS، أو عنوان ورقة أنماط، يُضاف بعد تحميل الصفحة. |
javascript | نص | بلا | نص جافاسكربت، أو عنوان سكربت، يُشغَّل بعد تحميل الصفحة. |
الوصول إلى الصفحات المحمية
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
auth | كائن | بلا | { "username": "...", "password": "..." } للمصادقة الأساسية على عنوان المصدر. |
http_headers | كائن | بلا | ترويسات طلب إضافية، مثل { "Accept-Language": "ar" }. |
cookies | مصفوفة | بلا | ملفات تعريف ارتباط للضبط: كائنات فيها name و value، واختياريًا domain و path و secure و http_only. |
خيارات الاستجابة
| الاسم | النوع | الافتراضي | الوصف |
|---|---|---|---|
encode | منطقي | false | إعادة JSON فيه ملف PDF بترميز base64 بدلًا من الملف الخام. |
sandbox | منطقي | false | مقبول للتوافق مع PDFShift، ويُتجاهَل. |
مع encode: true تكون الاستجابة:
{ "success": true, "data": "JVBERi0xLjQK...", "filesize": 40356, "duration": 412 }غير مدعوم
تُرفض المعاملات filename و webhook و s3_destination بالرمز 400. فهي تتطلب تخزين الملف، وصحيفة لا تخزّن ما تنشئه أبدًا: يُعاد ملف PDF في الاستجابة ولا يوجد في أي مكان آخر.
تحميل عنوان ويب
يُحمَّل المصدر من نوع العنوان بمتصفح حقيقي في جدة. ولا يُسمح إلا بعناوين http و https العامة؛ وتُحجب العناوين الخاصة والمحلية وعناوين بيانات السحابة الوصفية، للصفحة ولكل صورة وسكربت وإطار تحمّله.
{ "source": "https://example.com/report", "format": "A4", "margin": "15mm", "raise_for_status": true }الروابط النسبية في HTML
ليس لمصدر HTML عنوان خاص به، لذا لا يمكن حلّ الروابط النسبية مثل /logo.png. استخدم عناوين مطلقة، أو وسم <base href="https://your-site/">، أو ضمّن الصور بصيغة data:.