قم بإنشاء ملفات PDF من HTML وMarkdown باستخدام REST API

يقوم تطبيقك بإنشاء الفواتير. لديك قالب HTML. الآن أنت بحاجة إلى تحويله إلى PDF للتحميل. النهج القياسي: تثبيت Puppeteer، وتشغيل مثيل Chromium بدون رأس، اتصل page.pdf(). هذا يتراوح بين 300 و500 ميجابايت من التبعيات لوظيفة الطباعة.

ويزداد الأمر سوءًا في الإنتاج. يقوم Chromium بتسريب الذاكرة تحت الحمل. تتضخم صور Docker بعد 1 جيجابايت. تستغرق البداية الباردة 3-8 ثواني. ينتهي بك الأمر إلى الحفاظ على تجمع عمليات المتصفح لشيء ما يجب أن يكون ذلك استدعاء دالة واحدة.

هناك طريق أقصر. أرسل HTML الخاص بك إلى واجهة برمجة التطبيقات (API)، واحصل على ملف PDF مرة أخرى.

HTML إلى PDF في طلب POST واحد

ال /v1/pdf/from-html تقبل نقطة النهاية سلسلة HTML وتقوم بإرجاع ملف PDF. لا يوجد متصفح ثنائي، ولا تبعيات، ولا تكوين.

curl -X POST https://api.botoi.com/v1/pdf/from-html \\
  -H "Content-Type: application/json" \\
  -d '{
    "html": "<h1>Invoice #1042</h1><p>Amount due: $2,450.00</p>"
  }'

إجابة:

{
  "success": true,
  "data": {
    "url": "https://api.botoi.com/pdfs/f7a2c1e8.pdf",
    "size_bytes": 24576,
    "pages": 1
  }
}

ال url يشير الحقل إلى ملف PDF الذي تم إنشاؤه. قم بتنزيله، وأعد توجيه المستخدم إليه، أو قم بتخزينه في حاوية S3 الخاصة بك. تتعامل واجهة برمجة التطبيقات مع العرض وترقيم الصفحات وتضمين الخط.

تخفيض السعر إلى PDF في طلب POST واحد

لا يبدأ كل مستند بتنسيق HTML. غالبًا ما تكون التقارير وسجلات التغيير والوثائق بمثابة Markdown. ال /v1/pdf/from-markdown تعمل نقطة النهاية على تحويل Markdown إلى ملف PDF مُصمم مباشرةً.

إجابة:

يتم عرض الجداول والعناوين والنص الغامق وكتل التعليمات البرمجية والقوائم بشكل صحيح. يتم تطبيق واجهة برمجة التطبيقات بشكل نظيف الإعدادات الافتراضية المطبعية بحيث يبدو الإخراج قابلاً للعرض بدون CSS مخصص.

مثال عملي: إنشاء الفاتورة

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

ينتج عن هذا الطلب الفردي فاتورة احترافية بصيغة PDF مع ترويسة Cascade Software، أربعة بنود يبلغ مجموعها 2,257.00 دولارًا أمريكيًا، وضريبة مبيعات 8.5% بقيمة 191.85 دولارًا أمريكيًا، وإجمالي إجمالي قدره 2,448.85 دولارًا أمريكيًا. CSS في <style> تتحكم العلامة في الخطوط والتباعد وحدود الجدول و صف إجمالي جريء. يمكنك استخدام أي ملف CSS يدعمه المتصفح، بما في ذلك flexbox وgrid و @page قواعد الهوامش وحجم الصفحة.

مثال عملي: تقرير ربع سنوي من Markdown

التقارير مناسبة بشكل طبيعي لـ Markdown. مديرو المنتجات والمحللون وفرق العمليات يكتبون بالفعل في تخفيض السعر. يعد التحويل إلى PDF لتوزيع البريد الإلكتروني أو الأرشفة بمثابة استدعاء واحد لواجهة برمجة التطبيقات:

تعرض واجهة برمجة التطبيقات (API) الجداول والعناوين والنص الغامق والقائمة المرقمة في ملف PDF نظيف. لا خطوة HTML المتوسطة على جانبك. قم بتمرير سلسلة Markdown من قاعدة بياناتك، Git مستودع، أو تصدير الفكرة.

مثال عملي: إنشاء الإيصالات في Express

فيما يلي طريق سريع يقوم بإنشاء إيصال PDF عند الطلب عندما يطلب المستخدم ذلك للطلب السابق:

ال buildReceiptHtml تأخذ الوظيفة بيانات الطلب من قاعدة البيانات الخاصة بك وتنتجها سلسلة HTML مصممة. يرسله المسار إلى واجهة برمجة تطبيقات botoi ويعيد عنوان URL الخاص بملف PDF إلى الملف العميل. لا محرك الدمى. لا توجد عمليات نظام الملفات. لا توجد أدلة مؤقتة.

نفس النمط في هونو

إذا كنت تستخدم Cloudflare Workers أو Bun، فإن إصدار Hono يكون متطابقًا تقريبًا:

الفرق الرئيسي: يصل Hono إلى متغيرات البيئة من خلاله c.env بدلاً من process.env. كل شيء آخر يبقى على حاله. مكالمة جلب واحدة، استجابة JSON واحدة، عنوان URL واحد لملف PDF.

المقارنة: API vs Puppeteer vs wkhtmltopdf vs Prince

أربعة أساليب شائعة لتحويل HTML إلى PDF، مقارنة بما يهم في الإنتاج:

محرك الدمى يمنحك التحكم الكامل في المتصفح ولكنه يحمل تكاليف تشغيلية باهظة. أنت تقوم بتشغيل Chromium على الخادم الخاص بك، وإدارة حدود الذاكرة، وتصحيح الأمان نقاط الضعف في المتصفح الثنائي. يعمل بشكل جيد إذا كنت بحاجة إلى تنفيذ JavaScript أو ملف تعريف الارتباط الحقن، أو عرض الصفحة المصادق عليها.

com.wkhtmltopdf أخف من محرك الدمى ولكنه يستخدم QtWebKit المهمل المحرك. دعم CSS عالق عند مستويات 2015. Flexbox والشبكة لا يعملان. المشروع هو تمت أرشفته على GitHub بدون مشرفين نشطين.

الأمير XML تنتج مخرجات طباعة بأعلى جودة باستخدام وسائط CSS المقسمة إلى صفحات كاملة الدعم. المقايضة: رسوم ترخيص قدرها 3800 دولار لكل خادم. وهذا منطقي للنشر سير العمل، وليس لإنشاء الفواتير في تطبيق SaaS.

نهج واجهة برمجة التطبيقات يفوز عندما تحتاج إلى ملفات PDF من القوالب التي تتحكم فيها (الفواتير، الإيصالات والتقارير والعقود) ولا تحتاج إلى تقديم صفحات موثقة بشكل عشوائي. صفر الإعداد، عدم الحاجة إلى الصيانة، زمن الوصول المتوقع.

النقاط الرئيسية

• نقطتا نهاية، وتنسيقان للإدخال. /v1/pdf/from-html ل HTML كامل مع CSS. /v1/pdf/from-markdown لمحتوى تخفيض السعر.
• لا توجد تبعيات من جانب الخادم. لا محرك الدمى، ولا الكروم، ولا wkhtmltopdf ثنائي. مكالمة HTTP واحدة من أي لغة.
• دعم CSS الكامل. الأنماط المضمنة، وعلامات الأنماط، والمربع المرن، والشبكة، وخطوط Google، و @page استعلامات وسائل الإعلام عن العمل.
• الطبقة المجانية متاحة. 5 طلبات في الدقيقة بدون مفتاح API. الخطط المدفوعة ابدأ بسعر 9 دولارات شهريًا لأحمال عمل الإنتاج.
• حالات الاستخدام الشائع. الفواتير والإيصالات والتقارير والعقود والوثائق الصادرات ومرفقات البريد الإلكتروني.

تحقق من واجهة برمجة التطبيقات مستندات للحصول على مرجع المعلمة الكامل، بما في ذلك حجم الصفحة والهوامش والرأس/التذييل التكوين.