واجهة API لمسارات العمل متعددة الخطوات
أنشئ مسار عمل للمستندات متعدد الخطوات باستدعاء API واحد، وشغّله على ملف واحد أو على مئات الملفات، وتابع كل تشغيل ونزّل النتائج.
إجابة مختصرة
أرسل POST https://maxscanner.app/api/v1/workflows/ مع قائمة بالخطوات، مثل [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. يتحقق MaxScanner من إمكانية تشغيل السلسلة في السحابة، ثم يحفظها ويربطها بمفتاح API الخاص بك ويعيد automationId. ابدأها باستخدام POST /api/v1/automations/{automationId}/runs/ مع Idempotency-Key، وتابعها عبر GET /api/v1/automation-runs/{runId}/، ونزّل كل ناتج من /api/v1/documents/{documentId}/download/.
البدء السريع
- 1استخدم GET /api/v1/workflow-steps/ لرؤية الخطوات وما تقبله كل خطوة وما تنتجه وإعداداتها.
- 2أرسل POST /api/v1/workflows/ مع اسم و1–10 خطوات. احتفظ بقيمة workflow.automationId من الرد.
- 3استورد الملفات أو ارفعها، ثم أرسل POST /api/v1/automations/{automationId}/runs/ مع قيم documentId الخاصة بها وIdempotency-Key.
- 4استعلم عن GET /api/v1/automation-runs/{runId}/ حتى تصبح الحالة completed، أو اعرض كل تشغيلات الأتمتة.
- 5نزّل كل عنصر في run.outputs باستخدام GET /api/v1/documents/{documentId}/download/.
لماذا مسار عمل بدلًا من استدعاءات منفصلة
يبقي مسار العمل السلسلة على جانب MaxScanner: ينتقل ناتج كل خطوة مباشرة إلى الخطوة التالية دون العودة إلى خادمك، ويُعاد كل تشغيل عند الفشل ويُسجَّل، وتصل النتائج إلى مستنداتي. يمكنك فتح مسار عمل أنشأته عبر API من لوحة التحكم ← مسارات العمل لمراجعته، وتغيير السلسلة لاحقًا دون إعادة نشر الكود: أنشئ مسار عمل جديدًا واستبدل automation id.
الخطوات المتاحة
تعمل هذه الخطوات على معالجات MaxScanner السحابية، لذا يمكن لمسار عمل مكوّن منها أن يعمل دون متصفح.
| step | المدخل ← المخرج | الإعدادات |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | ملف Office ← PDF | — |
| merge-pdf | 2 أو أكثر من ملفات PDF ← ملف PDF واحد (كخطوة أولى فقط) | — |
| compress-pdf | PDF ← PDF أصغر | — |
| rotate-pdf | PDF ← PDF | degrees: 90 أو 180 أو 270 |
| extract-pages | PDF ← PDF | pages: "1,3-5" (يبدأ العدّ من 1) |
| image-transform | JPG أو PNG أو WebP ← JPG أو PNG أو WebP أو AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG أو PNG أو WebP ← نص (إنجليزي) | — |
إنشاء مسار عمل
تعمل الخطوات بالترتيب الذي تحدده، ويجب أن تقبل كل خطوة ما تنتجه الخطوة السابقة؛ وإن لم تتوافق فالرد هو 422 workflow_not_runnable مع السبب. أرسل Idempotency-Key كي يعيد الطلب المكرر مسار العمل نفسه. يكلف إنشاء مسار عمل طلبًا واحدًا (رصيدًا واحدًا في الخطط المدفوعة)، ويمكن لكل مفتاح امتلاك ما يصل إلى 25 مسار عمل نشطًا.
curl -X POST 'https://maxscanner.app/api/v1/workflows/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: create-contract-flow-v1' \
-d '{
"name": "Contracts to small PDF",
"steps": [
{ "step": "word-to-pdf" },
{ "step": "compress-pdf" }
]
}'شغّله على ملف واحد أو على ملفات كثيرة
المدخلات مستندات موجودة بالفعل في الحساب: استيرادات API، وعمليات الرفع المكتملة عبر /extension/upload/complete/، والمخرجات السابقة، ومسوحات Android. يحتاج كل تشغيل إلى Idempotency-Key؛ وتكرارها لا يبدأ تشغيلًا ثانيًا أبدًا. استخدم "mode": "together" (الافتراضي) عندما يجب أن تمر الملفات في تشغيل واحد، مثل عدة ملفات PDF لـ merge-pdf. واستخدم "mode": "each" لبدء تشغيل لكل ملف، حتى 100 ملف في استدعاء واحد. يكلف كل تشغيل 3 أرصدة في الخطط المدفوعة وطلبًا واحدًا في خطة Free؛ وإذا بُلغ حد الخطة في المنتصف، يذكر الرد عدد الملفات التي لم تبدأ.
const res = await fetch(`https://maxscanner.app/api/v1/automations/${automationId}/runs/`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAXSCANNER_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'contracts-2026-11-11',
},
body: JSON.stringify({
mode: 'each', // one run per document
inputs: documentIds.map((documentId) => ({ kind: 'document', documentId })),
}),
});
const { runs, replayedCount, notStarted } = await res.json();تابع التشغيلات ونزّل النتائج
يعيد GET /api/v1/automation-runs/{runId}/ الحالة (reserved أو executing أو suspended أو completed أو failed أو cancelled)، وبعد الاكتمال قائمة outputs تتضمن documentId واسم الملف ونوعه وحجمه لكل ملف محفوظ. ويعرض GET /api/v1/automations/{automationId}/runs/ آخر 100 تشغيل مع العدد لكل حالة، وهي أسرع طريقة لمتابعة استدعاء جماعي. قراءة الحالة مجانية.
curl 'https://maxscanner.app/api/v1/automation-runs/$RUN_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"
# then, for each output:
curl "https://maxscanner.app/api/v1/documents/$DOCUMENT_ID/download/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"إدارة مسارات العمل
يمكن أيضًا تشغيل مسارات العمل المنشأة في المحرر المرئي من API: افتح لوحة التحكم ← مسارات العمل ← الإصدارات ← التشغيل من API واختر المفتاح. يوفر المحرر أيضًا خطوات تحتاج إلى شخص، مثل التوقيع والانتظار والموافقات؛ وهذه تبقى خارج مسارات العمل المنشأة عبر API.
- يعرض GET /api/v1/workflows/ كل مسارات العمل التي يستطيع هذا المفتاح تشغيلها مع خطواتها
- يعيد GET /api/v1/workflows/{workflowId}/ مسار عمل واحدًا
- يفصل DELETE /api/v1/workflows/{workflowId}/ مسار العمل عن المفتاح؛ تُؤرشف مسارات العمل المنشأة عبر API وتكتمل التشغيلات التي بدأت
- لتغيير الخطوات، أنشئ مسار عمل جديدًا واستخدم automationId الخاص به في الكود
الأسئلة الشائعة
هل يجب أن أستخدم المحرر المرئي؟
لا. ينشئ POST /api/v1/workflows/ مسار العمل من JSON. المحرر اختياري: لمراجعته أو للخطوات غير المتاحة عبر API.
ما الفرق بين "together" و"each"؟
يبدأ "together" تشغيلًا واحدًا يتلقى كل المدخلات، وهو ما يحتاجه merge-pdf. ويبدأ "each" تشغيلًا منفصلًا لكل مدخل، فلا يؤثر ملف معيب في الملفات الأخرى وتصل النتائج فور انتهاء كل ملف.
ما الصلاحية التي يحتاجها المفتاح؟
"تشغيل مسارات العمل المحفوظة" (workflows:run وworkflows:read) لإنشاء مسارات العمل وتشغيلها، و"حفظ المستندات" لاستيراد ملفات الإدخال، و"قراءة المستندات" لتنزيل النتائج.
هل يرسل تشغيل مسار العمل webhook عند انتهائه؟
ليس بعد. استعلم عن التشغيل أو قائمة التشغيلات؛ تُرسل webhooks لمهام المعالجة التي تبدأ مباشرة عبر /jobs و/pipeline و/pdf-job و/media/process.