المسح الضوئي عبر API

يحوّل المسح الضوئي عبر API ملف PDF إلى نسخة ممسوحة ضوئيًا مقنعة عبر استدعاء REST واحد، وهو ما يناسب العمليات الآلية وتكامل التطبيقات. أنشئ المهمة، وارفع ملف PDF، ثم استعلم عن الحالة أو انتظر webhook: ثلاث خطوات من أي بيئة أو لغة تستطيع إرسال طلب HTTP. أما فضاء الألوان والدقة والدوران والضبابية والضوضاء والسطوع والتباين والحدود فكلها قابلة للضبط.

كيف يجري الاستدعاء

  1. إنشاء المهمة

    POST /v1/scan-jobs

    أرسل config الخاص بك، وإن شئت webhookUrl؛ فيصلك jobID وعنوان uploadURL موقّع مسبقًا.

  2. رفع ملف PDF

    PUT {uploadURL}

    أرسل الملف بطريقة PUT مباشرة إلى عنوان S3 الموقّع مسبقًا من الخطوة السابقة — دون الحاجة إلى رمز.

  3. استلام النسخة الممسوحة ضوئيًا

    GET /v1/scan-jobs/{jobID}

    استعلم عن الحالة أو انتظر webhook؛ وحين تصبح المهمة completed نزّلها من downloadURL.

أين يفيد

إنتاج مجمّع من الخادم

تمر العقود والفواتير والتقارير المنشأة على الخادم مباشرة عبر تأثير المسح الضوئي، دون أن يعيد أحد العمل يدويًا على صفحة الويب.

داخل نظام قائم

أضف إلى نظام إدارة العملاء أو تخطيط الموارد أو التذاكر إجراءً باسم «تصدير نسخة ممسوحة ضوئيًا» يستدعي الواجهة.

سلاسل الأتمتة

تبدأ منصات مثل CI وn8n وZapier المهمة عند وقوع حدث، ويسلّم webhook العمل إلى الخطوة التالية عند الانتهاء.

طوابير ملفات كبيرة

المهام غير متزامنة: بعد إنشائها تُعالج كل واحدة على حدة، ويبقى التقدم متاحًا عبر status وcreatedAfter.

اللغات والبيئات

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLسطر الأوامر / CI
المزيدأي عميل HTTP

الواجهة قائمة على HTTP وJSON القياسيين، فأي لغة أو منصة أتمتة تستطيع إرسال طلب تستطيع استدعاءها.

أمثلة برمجية

API Bearer Token

الرمز مرتبط بحسابك ويمكن توليده من جديد في أي وقت. ويتطلب المسح الضوئي عبر API حساب Pro: فبدون رمز صالح تردّ الواجهة بـ 401، وبدون دور Pro تردّ بـ 403.

جرّبه

اضبط المعاملات وراقب جسم الطلب وهو يتغيّر معها، ثم نفّذ الاستدعاءات الثلاثة على الواجهة.

معاملات المسح الضوئي

تشغيل التجربة يستدعي الواجهة برمزك ويتطلب حساب Pro؛ أما المعاملات وجسم الطلب فيمكن تصفحهما بحرية.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

معلومات مهمة المسح

مثال
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

مرجع الواجهة

الطريقةالمسارالوصف
POST/v1/scan-jobsينشئ مهمة مسح ضوئي. أرسل config وعند اللزوم webhookUrl؛ فيصلك كائن المهمة بحالة created وعنوان uploadURL موقّع مسبقًا.
PUT{uploadURL}عنوان S3 الموقّع مسبقًا من الخطوة السابقة، وهو ليس على api.lookscanned.ioيرفع ملف PDF المصدر مع Content-Type: application/pdf وContent-Length. والعنوان يحمل توقيعه بنفسه، فلا تُضف ترويسة Authorization.
GET/v1/scan-jobs/{jobID}يقرأ مهمة واحدة، للاستعلام الدوري. ففي حالة created يتضمن uploadURL، وفي حالة completed يتضمن downloadURL.
GET/v1/scan-jobsيسرد مهامك أنت، مع ترشيح حسب jobID أو status أو createdAfter.
الحالةcreatedprocessingcompletedfailed
  • 401 لا يوجد رمز صالح
  • 403 الحساب ليس Pro
  • 404 المهمة غير موجودة

جسم الطلب

الحقلالنوعالافتراضيالوصف
webhookUrlstring · —يُستدعى مرة واحدة عند انتهاء المهمة، فلا تحتاج إلى الاستعلام الدوري عنها.
config.colorspace'gray' | 'sRGB' · graygrayفضاء ألوان الصورة الناتجة؛ وgray يعني نسخة ممسوحة ضوئيًا بالأبيض والأسود.
config.resolutionnumber · 7272دقة الصورة الناتجة، بوحدة نقطة لكل بوصة.
config.rotatenumber · —دوران المستند كله، بالدرجات.
config.rotate_varnumber · —مدى الدوران العشوائي لكل صفحة، بالدرجات — لإيهام ورقة وُضعت مائلة.
config.blurnumber · 00مقدار الضبابية.
config.noisenumber · 00مقدار الضوضاء.
config.brightnessnumber · 11السطوع؛ والقيمة 1 تبقيه كما هو.
config.contrastnumber · 11التباين؛ والقيمة 1 تبقيه كما هو.
config.borderboolean · falsefalseما إذا كانت الصفحة ستحصل على حدود المسح الضوئي.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegصيغة الصورة التي تُرسم إليها الصفحات.

يمكن إغفال أي حقل. أما القيم التي يبدأ منها قسم «جرّبه» — الدقة 150، والدوران 1، والسطوع والتباين 1.3 — فهي التركيبة التي يوصي بها تطبيق الويب، لا القيم الافتراضية للواجهة.

حقول جديرة بالانتباه في كائن المهمة

status
‏created / processing / completed / failed — وهي التي تحدد ظهور العنوانين التاليين من عدمه.
uploadURL
يظهر فقط أثناء الحالة created. عنوان رفع موقّع مسبقًا وله مدة صلاحية.
downloadURL
يظهر فقط بعد الحالة completed. عنوان تنزيل موقّع مسبقًا وله مدة صلاحية.
inputUploadedAt / completedAt
وقت اكتمال رفع الملف المصدر ووقت اكتمال المهمة؛ والفرق بينهما هو زمن المعالجة.

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

هل يتطلب المسح الضوئي عبر API اشتراك Pro؟

نعم. فبدون رمز صالح تردّ الواجهة بـ 401، والحساب الذي لا يحمل دور Pro يتلقى 403. وبعد الترقية وتسجيل الدخول يظهر الرمز في هذه الصفحة.

كيف أعرف أن المهمة انتهت؟

بطريقتين: الاستعلام الدوري عن GET /v1/scan-jobs/{jobID}، أو تمرير webhookUrl عند إنشاء المهمة لتتصل بك الخدمة مرة واحدة عند الانتهاء.

هل النتيجة نفسها نتيجة المسح على صفحة الويب؟

هي نفسها. فالجانبان يستخدمان التنفيذ ذاته لتأثير المسح الضوئي، وفضاء الألوان والدقة والدوران والضبابية والضوضاء والسطوع والتباين والحدود في config تقابل خيارات صفحة الويب بالأسماء نفسها: المعاملات نفسها تعطي المخرجات نفسها. ولا يختلف سوى مكان المعالجة — محليًا في الصفحة، وعن بُعد عبر الواجهة.

هل أستطيع حفظ عنواني الرفع والتنزيل وإعادة استخدامهما؟

يُفضّل ألا تفعل. فـ uploadURL وdownloadURL عنوانان موقّعان مسبقًا ولهما مدة صلاحية؛ وبعد انتهائها عليك قراءة المهمة من جديد للحصول على عنوانين جديدين.

كم تستغرق المهمة؟

يتوقف ذلك على عدد الصفحات والدقة. فالمستند من بضع صفحات ينتهي عادة خلال ثوانٍ، وكلما ارتفعت الدقة وزادت الصفحات طال الوقت. والفرق بين inputUploadedAt وcompletedAt يعطي الزمن الفعلي.

ماذا أفعل إذا فشلت المهمة؟

تتحول الحالة إلى failed. والأسباب المعتادة أن الملف ليس PDF صالحًا، أو أن التشفير يقيّده، أو أن الرفع انقطع. تأكد من أن الملف يُفتح، ثم أنشئ مهمة جديدة.

هل يمكنني الاطلاع على المهام السابقة؟

نعم. يسرد GET /v1/scan-jobs مهامك أنت ويقبل الترشيح حسب jobID وstatus وcreatedAfter، وهو ما يكفي للمطابقة أو لإعادة التنزيل.