البدء السريع مع API: حوّل ملفك الأول
أنشئ مفتاح API، وأرسل ملفًا، وانتظر انتهاء المهمة، ثم نزّل النتيجة، مع طلبات جاهزة للنسخ واللصق.
إجابة مختصرة
أنشئ مفتاحًا من لوحة التحكم → API والمفاتيح، ثم أرسل POST https://maxscanner.app/api/v1/jobs/ مع رابط URL عام للملف واسم الملف والصيغة المطلوبة. تُرجع API قيمة jobId فورًا؛ استعلم عبر GET /api/v1/jobs/{jobId}/ كل بضع ثوانٍ حتى تصبح قيمة status هي "completed"، ثم نزّل output.downloadUrl خلال خمس دقائق.
البدء السريع
- 1افتح لوحة التحكم → API والمفاتيح، واختر إنشاء مفتاح API، وحدّد "معالجة الملفات"، ثم انسخ المفتاح (يُعرض مرة واحدة فقط).
- 2احفظ المفتاح في متغير بيئة مثل MAXSCANNER_API_KEY، ولا تضعه أبدًا في شيفرة تعمل على جهة العميل.
- 3أرسل POST /api/v1/jobs/ مع url وfilename وformat. واحتفظ بقيمة jobId من الاستجابة 202.
- 4أرسل GET /api/v1/jobs/{jobId}/ كل 2–10 ثوانٍ حتى تصبح قيمة status هي completed أو failed.
- 5نزّل output.downloadUrl فورًا: تنتهي صلاحية الرابط الموقّع بعد خمس دقائق.
قبل أن تبدأ
تُرسَل كل الطلبات إلى https://maxscanner.app/api/v1/ مع المفتاح كرمز Bearer. تنتهي عناوين URL للطلبات بشرطة مائلة: العنوان الذي لا ينتهي بها يتلقى إعادة توجيه 308 يتبعها معظم عملاء HTTP، لكن إضافة الشرطة المائلة توفّر رحلة ذهاب وإياب إضافية.
تسمح الخطة المجانية (Free) بـ 10 طلبات يوميًا و100 طلب شهريًا، وهذا يكفي لبناء تكامل واختباره. أما الخطط المدفوعة فتستخدم بدلًا من ذلك أرصدة شهرية، وتتراوح تكلفة كل نقطة نهاية بين 0 و3 أرصدة.
- عنوان URL الأساسي: https://maxscanner.app/api/v1/
- الترويسة: Authorization: Bearer <your key> (مفتاحك)
- جسم الطلب: JSON مع Content-Type: application/json
- الملفات: حتى 50 MB عبر الاستيراد من URL أو الرفع المباشر
تحويل ملف Word إلى PDF
تختار نقطة نهاية المهام المعالج المناسب بناءً على صيغتي الإدخال والإخراج. مرّر رابط URL عامًا وسيتولى الخادم تنزيل الملف بنفسه عند إنشاء المهمة (حتى 50 MB خلال 30 ثانية؛ ولا تُتبَع عمليات إعادة التوجيه، لذا استخدم الرابط النهائي للملف)؛ أما الملفات الخاصة فاستخدم لها الرفع المباشر ومرّر sourceKey بدلًا من ذلك (راجع دليل الملفات والرفع). أضف الترويسة Idempotency-Key حتى لا يُنشئ الطلب المُعاد أبدًا مهمة ثانية.
curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-0001' \
-d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'انتظار النتيجة
المهام غير متزامنة حتى لا تُبقي الملفات الكبيرة اتصال HTTP لديك مفتوحًا. استعلم عن عنوان URL الخاص بالحالة بفاصل يبدأ من نحو 2 ثانية ويزداد تدريجيًا حتى 10 ثوانٍ. ينتهي ملف Office الصغير عادةً في أقل من 20 ثانية، أما فيديو بدقة 1080p فقد يستغرق دقائق. عندما تكون قيمة status هي completed، يتضمن output نوع المحتوى والحجم بالبايت ورابط downloadUrl موقّعًا.
curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY"الخطوات التالية
استبدل الاستعلام الدوري بخطاف ويب (webhook) عندما تعالج أكثر من عدد قليل من الملفات، واقرأ دليل المهام لمعرفة قواعد إعادة المحاولة، ثم اختر دليل الميزة التي تناسب عملك: OCR أو أدوات PDF أو الصور أو الوسائط أو تشغيل مسار عمل محفوظ.
الأسئلة الشائعة
هل أحتاج إلى تثبيت SDK؟
لا. تعتمد API على HTTPS وJSON فقط، لذا تعمل مع أي لغة برمجة أو أداة بدون كود قادرة على إرسال طلب HTTP. ويتضمن دليل أمثلة الشيفرة نسخًا كاملة بلغات Node.js وPython وPHP وcURL.
ما مدة صلاحية رابط التنزيل؟
خمس دقائق. إذا انتهت صلاحيته، فاطلب حالة المهمة مرة أخرى للحصول على رابط جديد.
هل يوجد وضع للاختبار؟
استخدم الخطة المجانية (Free) للاختبار: فهي توفر نقاط النهاية نفسها، وتحدّ كل حساب بـ 10 طلبات يوميًا و100 طلب شهريًا.