كيف أستخدم PDF123 من الشيفرة؟
تستدعي الواجهات الأربع العمليات نفسها، فيعطي الدمج النتيجة ذاتها في كل واحدة منها. اختر الواجهة بحسب المكان الذي تعمل فيه شيفرتك.
| الواجهة | الأنسب لـ | التثبيت أو العنوان | الدليل |
|---|---|---|---|
| REST API | أي لغة برمجة، والخوادم، ونصوص الصَّدفة (shell) | https://pdf123.xyz/api/v1 | مرجع API |
| TypeScript SDK | شيفرة Node وBun والمتصفح التي تحتاج إلى الأنواع | npm install @pdf123/sdk | دليل SDK |
| سطر الأوامر | الطرفية ومهام CI ودفعات الملفات المحلية | npm install -g @pdf123/cli | دليل CLI |
| MCP | وكلاء الذكاء الاصطناعي مثل Claude Code وClaude Desktop وCursor | npx -y @pdf123/mcp أو https://pdf123.xyz/mcp | دليل MCP |
استخدم REST API إذا لم تكن شيفرتك مكتوبة بـ TypeScript. واستخدم SDK إذا كانت كذلك، لأن خيارات كل أداة محدّدة الأنواع ويجري التحقق منها قبل الرفع. واستخدم سطر الأوامر للمهام لمرة واحدة ولنصوص الصَّدفة. واستخدم MCP حين تريد أن يقرّر وكيل ذكاء اصطناعي أي أداة يشغّل.
يضم الكتالوج 97 أداة. لـ 58 منها صفحة على هذا الموقع، مثل دمج PDF وتقسيم PDF وضغط PDF. أما الباقي فعمليات في الخلفية بلا صفحة ويب، وكلها متاحة في SDK وفي سطر الأوامر وفي MCP.
كيف أشغّل أول طلب؟
ادمج ملفين باستخدام curl. الطلب نموذج multipart يحمل جزءًا واحدًا باسم fileInput لكل ملف.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfالدمج نفسه باستخدام TypeScript SDK:
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";
const client = new Pdf123Client();
const result = await client.run("merge", {
input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });الدمج نفسه باستخدام سطر الأوامر:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfكيف تعمل المصادقة؟
لا تحتاج الطلبات المجهولة إلى واجهة API العامة إلى حساب ولا إلى مفتاح. أرسل مفتاح API في الترويسة X-API-KEY عندما تريد تمييز حركتك، أو عند استدعاء نقطة نهاية MCP المستضافة التي تتطلب مفتاحًا دائمًا.
سجّل الدخول لإنشاء مفتاح في اللوحة أدناه، واحفظه في مكان آمن.
جارٍ التحقق من جلستك…
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-H "X-API-KEY: <your-key>" \
-F [email protected] -F [email protected] -o merged.pdfيأخذ SDK المفتاح عبر الخيار apiKey. أما سطر الأوامر وخادم MCP المحلي فيقرآنه من متغيّر البيئة PDFX_API_KEY.
ملاحظة
على الخادم المستضاف ذاتيًا، عيّن متغيّر البيئة SECURITY_CUSTOMGLOBALAPIKEY لتحديد مفتاح واحد يقبله الخادم. راجع الاستضافة الذاتية.
أين مرجع API؟
يُوثَّق REST API بصيغتين. تتيح لك Swagger UI تجربة كل نقطة نهاية في المتصفح. أما مستند OpenAPI فهو المصدر المقروء آليًا لمولّدات العملاء.
كل عملية هي طلب POST تحت العنوان الأساسي https://pdf123.xyz/api/v1، وهي مصنّفة في فئات. فمثلًا الدمج هو /general/merge-pdfs والضغط هو /misc/compress-pdf.
كيف أسلسل عدة أدوات في طلب واحد؟
يقبل POST /api/v1/pipeline أجزاء fileInput وحقلًا اسمه steps. حقل الخطوات مصفوفة JSON من كائنات، لكل منها op وparams اختياري. وتتلقى كل خطوة ناتج الخطوة السابقة.
curl -X POST https://pdf123.xyz/api/v1/pipeline \
-F [email protected] -F [email protected] \
-F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
-o out.pdfكيف أعيد المحاولة بأمان؟
أرسل الترويسة Idempotency-Key مع أي عملية. وإذا تكرّر الطلب نفسه خلال 24 ساعة، يعيد الخادم النتيجة الأولى مع الترويسة Idempotency-Replayed: true بدلًا من التنفيذ من جديد. ويُرفض استخدام المفتاح نفسه لطلب مختلف. لا تُخزَّن النتائج الأكبر من 32 MiB، ولذلك يردّ تكرار مثل هذا الطلب بالرمز 409 ويحتاج إلى مفتاح جديد.
ما حدود الحجم ومعدل الطلبات؟
| الحد | القيمة |
|---|---|
| حجم الملف على الموقع | 500 MB للملف الواحد |
| جسم طلب API مباشر واحد | 100 MiB، شاملةً إطار multipart |
| الرفع المجزّأ | يتحول SDK تلقائيًا إلى واجهة الرفع عندما يتجاوز المجموع 95 MB |
تحمل الاستجابات الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وتضيف الاستجابة ذات الحالة 429 الترويسة Retry-After. اقرأ الترويسات ولا تفترض حصة ثابتة، فالخادم المستضاف ذاتيًا يحدّد حدوده بنفسه. ويشرح مقال حد حجم الطلب في المدونة الخطأ الذي يظهر عند إرسال جسم طلب أكبر من المسموح.
كيف يبدو الخطأ؟
تُرجع حالات الفشل application/problem+json بالحقول type وtitle وstatus وdetail وcode وreason وhint. وجّه منطقك بحسب reason، واعتمد على code إن لم يوجد. نص detail مكتوب للبشر ولا يتضمن أبدًا مخرجات الأداة الخام. تجد كل الرموز في رموز الأخطاء.
| الرمز أو السبب | حالة HTTP | المعنى |
|---|---|---|
bad_request | 400 | معاملات أو جسم multipart غير صالح |
password_required | 400 | ملف PDF مشفّر ولم تُرسل كلمة المرور |
invalid_pdf | 400 | الملف ليس PDF أو أنه تالف؛ جرّب إصلاح PDF |
page_out_of_range | 400 | الصفحة المطلوبة غير موجودة |
not_found | 404 | مسار عملية غير معروف |
rate_limited | 429 | استُنفدت الحصة؛ انتظر مدة Retry-After |
ما الأدوات التي أبدأ بها؟
تغطي هذه الأدوات الاثنتا عشرة معظم الطلبات. استخدم صفحة الأداة لتجربتها في المتصفح.
| صفحة الأداة | نقطة نهاية API | أمر CLI | وظيفتها |
|---|---|---|---|
| دمج | /general/merge-pdfs | pdfx merge | دمج عدة ملفات PDF في ملف واحد |
| تقسيم | /general/split-pages | pdfx split | تقسيم ملف PDF إلى ملفات منفصلة |
| ضغط | /misc/compress-pdf | pdfx compress | إعادة ضغط تدفقات PDF لتقليل الحجم |
| تدوير | /general/rotate-pdf | pdfx rotate | تغيير اتجاه الصفحات |
| حماية | /security/add-password | pdfx protect | تشفير ملف PDF بكلمة مرور |
| فتح القفل | /security/remove-password | pdfx unlock | إزالة الحماية بكلمة المرور |
| علامة مائية | /security/add-watermark | pdfx watermark | إضافة علامة مائية نصية أو صورة |
| OCR | /misc/ocr-pdf | pdfx ocr | قراءة ملف PDF ممسوح ضوئيًا وإرجاع Markdown |
| PDF إلى Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | تحويل ملف PDF إلى Markdown |
| PDF إلى Word | /convert/pdf/word | pdfx convert-to-word | تحويل ملف PDF إلى ملف Word قابل للتحرير |
| معلومات المستند | /security/get-info-on-pdf | pdfx get-info | عرض البيانات الوصفية والأذونات والخطوط والبنية |
| إصلاح | /misc/repair | pdfx repair | إعادة بناء بنية ملف PDF تالف |
نقاط النهاية نسبية إلى https://pdf123.xyz/api/v1. شغّل pdfx list أو افتح مستند OpenAPI لترى الأدوات الـ 97 كلها.
كيف أستخدم PDF123 من وكيل ذكاء اصطناعي؟
يمكن للوكيل استخدام الأدوات بثلاث طرق:
- وصل خادم MCP. يشرح دليل MCP الخادم المحلي
@pdf123/mcpللملفات الموجودة على جهازك، ونقطة النهاية المستضافة علىhttps://pdf123.xyz/mcp. - تحميل مهارة وكيل. مهارات الوكلاء هي ملفات
SKILL.mdلـ Claude Code وCodex وCursor وأدوات مشابهة، واحد للكتالوج وواحد لكل أداة. - قراءة فهرس الموقع. يسرد /llms.txt الأدوات وAPI ونقطة نهاية MCP بنص عادي، ويصف
/site.jsonldالموقع ببيانات منظمة.
يشرح مقال "Built for AI Agents, Not Just Browsers" في مدونة PDF123 كيف يتكامل REST API مع MCP.
هل يمكنني تشغيل PDF123 على خادمي؟
نعم. الواجهة الخلفية هي برنامج pdfx-server الذي يعمل داخل Docker. وجّه SDK أو سطر الأوامر أو خادم MCP إليه عبر PDFX_API_BASE، وتبقى ملفاتك داخل شبكتك. راجع الاستضافة الذاتية للإعداد والمؤسسات لخيارات الدعم.
الأسئلة الشائعة
هل PDF123 API مجانية؟
نعم للاستخدام المجهول. لا تحتاج طلبات API العامة إلى حساب ولا إلى مفتاح. وتتضمن الاستجابات المستضافة ترويسات حدّ المعدل، فيستطيع العميل أن يبطئ قبل أن يتلقى الاستجابة 429.
هل أحتاج إلى مفتاح API؟
لا، بالنسبة إلى REST API وSDK وسطر الأوامر عند استخدام الموقع العام. نعم، بالنسبة إلى نقطة نهاية MCP المستضافة على /mcp، فهي تردّ بالرمز 401 إذا غابت الترويسة X-API-KEY. يمكنك إنشاء مفتاح في هذه الصفحة بعد تسجيل الدخول.
ما الحد الأقصى لحجم الملف؟
يقبل الموقع ملفات حتى 500 MB للملف الواحد. ويمكن أن يبلغ جسم طلب API مباشر واحد 100 MiB شاملةً إطار multipart. ويرفع SDK المدخلات الأكبر على دفعات تلقائيًا بمجرد أن يتجاوز المجموع 95 MB.
هل يمكنني استضافة API ذاتيًا؟
نعم. شغّل الخادم بنفسك وعيّن عنوان API الأساسي ليشير إليه. يقبل SDK وسطر الأوامر وخادم MCP المحلي جميعها عنوانًا أساسيًا مخصصًا.
كيف أبلغ عن خطأ؟
انسخ الحقول code وreason وdetail من استجابة المشكلة، مع وقت إرسال الطلب، وأرسلها عبر صفحة الاتصال. لا ترسل ملف PDF نفسه إلا إذا طلب الدعم ذلك.
هل أستخدم SDK أم سطر الأوامر أم MCP؟
استخدم SDK داخل شيفرة TypeScript، وسطر الأوامر للنصوص البرمجية ودفعات الملفات المحلية، وMCP عندما يختار وكيل ذكاء اصطناعي الأداة. تستخدم الثلاثة الكتالوج نفسه والخادم نفسه، فيمكنك الجمع بينها.