متى تحتاج ملف PDF بصيغة Base64؟
لا تستطيع JSON وXML وكثير من النماذج حمل شيء غير النص، لذا يجب كتابة الملف الثنائي مثل PDF كنص أولًا. وBase64 هي الطريقة المعتادة لذلك:
- إرسال مستند إلى واجهة API. خدمات الفوترة الإلكترونية والتوقيع الإلكتروني والشحن وإدارة المستندات تطلب غالبًا ملف PDF في حقل اسمه content أو file أو data.
- اختبار التكامل الذي تبنيه. مع خيار JSON تحصل على جسم طلب جاهز تلصقه في Postman أو curl أو في اختبار وحدة، دون كتابة أي كود للترميز.
- التخزين في عمود نصي أو ملف إعدادات. بعض الأنظمة تحفظ القوالب الصغيرة أو الشهادات كنص، وBase64 يجعل ملف PDF مناسبًا لذلك.
- التضمين في صفحة ويب. يتيح Data URI لصفحة عرض ملف PDF داخل iframe دون استضافة ملف منفصل، وهذا مناسب للمستندات الصغيرة.
تجد أمثلة الطلبات خطوة بخطوة بلغات curl وJavaScript وPython في كيفية إرسال ملف PDF إلى واجهة API بصيغة Base64. ولتحويل الكود إلى ملف مرة أخرى، استخدم Base64 إلى PDF، وللصور راجع صورة إلى Base64.
كيف تبدو كل صيغة
| الصيغة | بدايتها | الاستخدام المعتاد |
|---|---|---|
| كود Base64 فقط | JVBERi0 | حقول API وJSON وXML وقواعد البيانات |
| Data URI | data:application/pdf;base64, | علامة تبويب المتصفح وiframe ووسم object |
| أسطر من 76 حرفًا | JVBERi0، مقسّمًا إلى أسطر قصيرة | مرفقات البريد الإلكتروني (MIME) والملفات بنمط PEM |
| JSON | { "fileName": … } | جسم طلب لاختبار التكامل |
إذا واجهتك مشكلة
«هذا الملف ليس ملف PDF صالحًا». لا يبدأ الملف بالتوقيع %PDF-، فقد يكون ملف Word أو صورة غُيّر اسمها إلى .pdf. افتحه أولًا في قارئ PDF، أو حوّله بالأداة المناسبة.
تقول واجهة API إن المحتوى غير صالح. تأكد من أنك أرسلت الكود المجرد دون البادئة data: ودون فواصل أسطر، ما لم تطلبها الوثائق. وتأكد أيضًا من أن شيئًا لم يُقتطع من نهايته عند اللصق.
النص أطول من أن يتسع له الحقل. صغّر حجم ملف PDF باستخدام ضغط PDF ثم حوّله مجددًا، فيصغر الكود بالنسبة نفسها.