PDFVela — pdfvela.com
جميع أدوات PDF

كيف ترسل ملف PDF إلى واجهة API بصيغة Base64

تطلب منك واجهة للفواتير الإلكترونية أو التوقيع الإلكتروني أو الشحن أن تضع المستند في حقل JSON. إليك كيف تحوّل ملف PDF إلى النص المناسب، وتتحقق منه، وتتجنب الأخطاء التي تُفشل الطلب.

بقلم · تاريخ التحديث: 10 نوفمبر 2026

ما الذي تتوقعه واجهة API عادةً

تصف معظم واجهات API الخاصة بالمستندات نص طلب JSON فيه حقل اسمه content أو file أو data أو document. وقيمته هي كود Base64 لملف PDF، وغالبًا ما يرافقه اسم الملف ونوعه:

{
  "fileName": "invoice-1024.pdf",
  "mimeType": "application/pdf",
  "content": "JVBERi0xLjcKJ..."
}

قبل أن تكتب أي سطر برمجي، ابحث في التوثيق عن ثلاثة أشياء: اسم الحقل، وهل البادئة «data:» مطلوبة (غالبًا لا)، والحد الأقصى للحجم.

1. حوّل ملف PDF إلى Base64

أسرع طريقة للحصول على قيمة للاختبار هي أداة PDF إلى Base64. اختر ملف PDF، ثم اختر كود Base64 فقط وانسخ النتيجة. وإذا أردت نص طلب كاملًا تبدأ منه، فاختر JSON بدلًا من ذلك، إذ يضيف اسم الملف ونوعه تلقائيًا. يتم الترميز داخل متصفحك ولا يُرفع ملف PDF، وهذا مهم حين يكون مستند الاختبار فاتورة حقيقية.

تحقّق من النتيجة: يجب أن تبدأ بـ JVBERi0، وألا تحتوي على مسافات، وألا تضم سوى الحروف والأرقام والرمزين + و/، باستثناء علامة = أو علامتين في النهاية.

2. أرسله من الكود الخاص بك

هذه الخطوة نفسها بثلاث لغات برمجة شائعة. كل مثال يقرأ الملف ويرمّزه ثم يرسل JSON:

# curl (Linux / macOS): base64 -w 0 keeps it on one line
curl -X POST https://api.example.com/documents \
  -H "Content-Type: application/json" \
  -d "{\"fileName\":\"invoice.pdf\",\"content\":\"$(base64 -w 0 invoice.pdf)\"}"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const content = (await readFile('invoice.pdf')).toString('base64');
await fetch('https://api.example.com/documents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ fileName: 'invoice.pdf', content }),
});
# Python 3 with requests
import base64, requests
with open("invoice.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode("ascii")
requests.post("https://api.example.com/documents",
              json={"fileName": "invoice.pdf", "content": content})

على macOS يستخدم سطر curl الأمر base64 -i invoice.pdf بدلًا من -w 0. العنوان وأسماء الحقول هنا مجرد أمثلة، فاستخدم ما ورد في توثيق الخدمة التي تتعامل معها.

3. تحقّق من سلامة الملف ذهابًا وإيابًا

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

أخطاء شائعة

العَرَضالسبب المحتملالحل
«Invalid Base64»فواصل أسطر (أسطر من 76 حرفًا) أو بادئة «data:»أرسل الكود المجرد في سطر واحد
«Payload too large» (413)ملف PDF كبير جدًا بعد الترميزصغّره باستخدام ضغط PDF
يُفتح ملف PDF فارغًا أو تالفًاانقطع جزء من النصرمّز الملف من جديد وأرسل القيمة كاملة
تظهر الحروف الخاصة في أسماء الملفات بشكل خاطئأُرسل اسم الملف بترميز خاطئاجعل نص طلب JSON بترميز UTF-8

هل أنت مستعد للتجربة؟ الأداة مجانية، ويبقى ملفك على جهازك.

افتح أداة PDF إلى Base64

أسئلة حول إرسال ملف PDF بصيغة Base64

لماذا تطلب واجهات API صيغة Base64 بدلًا من الملف نفسه؟

لا يحمل JSON إلا النصوص. وBase64 يكتب بايتات ملف PDF بالحروف والأرقام والرمزين + و/، فيتسع المستند كله في حقل نصي واحد بجانب بقية البيانات، مثل رقم العميل أو تاريخ الفاتورة.

هل أرسل البادئة «data:application/pdf;base64,» أيضًا؟

في الغالب لا. تتوقع معظم واجهات API الكود وحده، وهو يبدأ بـ JVBERi0. لا ترسل Data URI إلا إذا ظهر في التوثيق، أو إذا احتاج المتصفح إلى رابط، كما في iframe مثلًا.

تقول الواجهة إن كود Base64 غير صالح، فما السبب الأكثر شيوعًا؟

وجود فواصل أسطر أو بادئة في النص، أو كود انقطع جزء منه عند لصقه. استخدم الكود المجرد في سطر واحد، وتأكد من أن نهاية النص وصلت كاملة.

ما أقصى حجم لملف PDF؟

يختلف ذلك من خدمة إلى أخرى، لكن النص أكبر من الملف بنحو الثلث، فملف PDF حجمه 3 ميغابايت يصبح قرابة 4 ميغابايت من JSON. وكثير من واجهات API تتوقف عند بضعة ميغابايتات، وأبسط حل هو ضغط ملف PDF أولًا.

هل Base64 نوع من التشفير؟

لا. يستطيع أي شخص يملك الكود أن يعيده إلى مستند. لذا أرسله عبر HTTPS فقط، ولا تلصق ملف PDF سريًا في موقع يرفعه إلى خادمه.