تخطي إلى المحتوى الرئيسي

اعثر على أداتك التالية

الوثائق/API/معالجة المستندات جماعيًا عبر API
API

معالجة المستندات جماعيًا عبر API

حوّل مئات الملفات أو اضغطها أو طبّق عليها OCR: اختر بين مهام الدفعات وتشغيلات مسارات العمل الجماعية، والتزم بحدود خطتك، وأعد تشغيل ما فشل فقط.

إجابة مختصرة

لتحويل من خطوة واحدة لما يصل إلى 20 ملفًا في كل استدعاء، استخدم POST /api/v1/jobs/batch/ مع مصفوفة "jobs" وتابعه عبر GET /api/v1/jobs/batch/{batchId}/. ولعدة خطوات لكل ملف، أنشئ مسار عمل وشغّله باستخدام "mode": "each" على ما يصل إلى 100 مستند في كل استدعاء. امنح كل استدعاء Idempotency-Key ثابتًا كي لا تبدأ إعادة المحاولة إلا ما ينقص.

اختر الأداة المناسبة

في خطة Free يُحتسب كل استدعاء معالجة طلبًا من الطلبات اليومية العشرة (10)، لذا يحتاج العمل الجماعي إلى خطة مدفوعة أو أرصدة مشتراة.

المهمةاستخدملكل استدعاء
التحويل نفسه لملفات كثيرة (DOCX ← PDF)POST /jobs/batch/1–20 ملفًا، 2 رصيد لكل دفعة
عدة خطوات لكل ملف (تحويل، ضغط، تدوير)مسار عمل + تشغيلات باستخدام mode "each"1–100 مستند، 3 أرصدة لكل تشغيل
دمج ملفات كثيرة في ملف واحد (merge)مسار عمل + تشغيلات باستخدام mode "together"حتى 100 مستند في تشغيل واحد
الفيديو والصوتمهمة /media/process/ واحدة لكل ملفملف 1، رصيد 1

عمليات التحويل المجمّعة

يقبل كل عنصر الحقول نفسها التي يقبلها POST /jobs/: url أو sourceKey، وfilename وformat، واختياريًا inputFormat. تُتحقق الدفعة كاملة (يذكر الرد فهرس أول عنصر غير صالح)، ويصبح كل عنصر مهمة مستقلة.

curl -X POST 'https://maxscanner.app/api/v1/jobs/batch/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "jobs": [
    { "url": "https://example.com/a.docx", "filename": "a.docx", "format": "pdf" },
    { "url": "https://example.com/b.xlsx", "filename": "b.xlsx", "format": "pdf" }
  ] }'

curl 'https://maxscanner.app/api/v1/jobs/batch/$BATCH_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"

تشغيلات مسارات العمل الجماعية

استورد الملفات أو ارفعها أولًا (يعيد كل استيراد documentId)، ثم ابدأ تشغيلًا لكل مستند في استدعاء واحد. تدخل التشغيلات قائمة الانتظار وتُعالج بالترتيب على معالجات مشتركة، لذا تستغرق 100 ملف Office دقائق لا ثوانٍ؛ استعلم عن GET /api/v1/automations/{automationId}/runs/ كل 15–30 ثانية واقرأ الأعداد لكل حالة.

import os, requests

KEY = os.environ["MAXSCANNER_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://maxscanner.app/api/v1"

doc_ids = [requests.post(f"{BASE}/documents/import/", headers=H, json={"url": u, "filename": u.rsplit("/", 1)[-1]}, timeout=60).json()["documentId"] for u in urls]
r = requests.post(f"{BASE}/automations/{automation_id}/runs/", headers={**H, "Idempotency-Key": "invoices-2026-11"},
                  json={"mode": "each", "inputs": [{"kind": "document", "documentId": d} for d in doc_ids]}, timeout=60)
print(r.status_code, r.json().get("notStarted"))

أعد المحاولة بأمان

  • كرر استدعاء التشغيل الجماعي باستخدام Idempotency-Key نفسه: تُتخطى التشغيلات الموجودة (replayedCount) ولا يبدأ إلا الناقص منها
  • إذا ظهر notStarted فقد أوقف حد الخطة الاستدعاء؛ أضف أرصدة أو انتظر إعادة التعيين ثم كرر الطلب نفسه
  • لا يؤثر تشغيل فاشل في التشغيلات الأخرى؛ ابدأ تشغيلًا جديدًا لذلك المستند باستخدام Idempotency-Key جديد
  • لا تُبقِ أكثر من بضع مئات من التشغيلات قيد التنفيذ؛ انتظر حتى يرتفع counts.completed قبل إرسال المئة التالية

الأسئلة الشائعة

هل يوجد حد لعدد التشغيلات في قائمة الانتظار؟

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

هل يمكنني الحصول على ملف ZIP واحد بكل النتائج؟

ليس من API بعد. نزّل كل ناتج من مستنده، أو استخدم أدوات ZIP على الموقع.

أدلة ذات صلة