סריקה דרך 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.

למה זה מתאים

הפקה מרובה בצד השרת

חוזים, חשבוניות ודוחות שנוצרים בשרת עוברים ישר דרך אפקט הסריקה, בלי שאיש יחזור על אותה פעולה ידנית בדף האינטרנט.

בתוך מערכת קיימת

מוסיפים ל‑CRM, ל‑ERP או למערכת פניות פעולה של «ייצוא עותק סרוק» ונותנים לה לקרוא ל‑API.

שרשראות אוטומציה

‏CI, ‏n8n, ‏Zapier ודומיהן מתחילות משימה לפי אירוע, וה‑webhook מעביר את הטיפול לשלב הבא בסיום.

תורים גדולים של קבצים

המשימות אסינכרוניות: אחרי היצירה כל אחת מעובדת בנפרד, וההתקדמות זמינה דרך status ו‑createdAfter.

שפות וסביבות

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLשורת פקודה / CI
עודכל לקוח HTTP

ה‑API הוא HTTP ו‑JSON רגילים, ולכן כל שפה או פלטפורמת אוטומציה שיודעת לשלוח בקשה יכולה לקרוא לו.

דוגמאות קוד

API Bearer Token

האסימון שייך לחשבון שלך וניתן להפיק אותו מחדש בכל עת. סריקה דרך API מחייבת חשבון Pro: בלי אסימון תקף ה‑API משיב 401, ובלי תפקיד Pro הוא משיב 403.

התנסות

קבעו את הפרמטרים, ראו את גוף הבקשה משתנה בהתאם, ואז הריצו את שלוש הקריאות מול ה‑API.

פרמטרים של הסריקה

הרצת ניסיון קוראת ל‑API עם האסימון שלך ומחייבת חשבון 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-…"
}

מדריך ה‑API

שיטהנתיבתיאור
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רזולוציית תמונת הפלט, ב‑DPI.
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 — הם השילוב שיישום האינטרנט ממליץ עליו, ולא ברירות המחדל של ה‑API.

שדות שכדאי לשים לב אליהם באובייקט המשימה

status
‏created / processing / completed / failed — קובע אם שתי הכתובות שלהלן מופיעות.
uploadURL
רק כל עוד המשימה במצב created. כתובת העלאה חתומה מראש שתוקפה פג.
downloadURL
רק לאחר שהמשימה במצב completed. כתובת הורדה חתומה מראש שתוקפה פג.
inputUploadedAt / completedAt
מתי הסתיימה העלאת המקור ומתי הסתיימה המשימה; ההפרש הוא זמן העיבוד.

שאלות נפוצות

האם סריקה דרך API מחייבת Pro?

כן. בלי אסימון תקף ה‑API משיב 401, וחשבון בלי תפקיד Pro מקבל 403. אחרי שדרוג והתחברות האסימון מופיע בדף הזה.

איך אדע שמשימה הסתיימה?

בשתי דרכים: לתשאל את GET /v1/scan-jobs/{jobID}, או להעביר webhookUrl בעת יצירת המשימה ולתת לשירות לפנות אליך פעם אחת.

האם התוצאה זהה לסריקה בדף האינטרנט?

זהה. שני הצדדים משתמשים באותו מימוש של אפקט הסריקה, ומרחב הצבע, הרזולוציה, הסיבוב, הטשטוש, הרעש, הבהירות, הניגודיות והגבול ב‑config הם אותן אפשרויות בדף האינטרנט תחת אותם שמות: אותם פרמטרים נותנים אותה תוצאה. ההבדל היחיד הוא מקום העיבוד — מקומית בדף, ומרחוק דרך ה‑API.

אפשר לשמור את כתובות ההעלאה וההורדה ולהשתמש בהן שוב?

עדיף שלא. ‏uploadURL ו‑downloadURL הן כתובות חתומות מראש בעלות תוקף מוגבל; משפג התוקף צריך לקרוא את המשימה שוב כדי לקבל חדשות.

כמה זמן לוקחת משימה?

תלוי במספר העמודים וברזולוציה. מסמך של כמה עמודים מסתיים בדרך כלל תוך שניות; רזולוציה גבוהה יותר ומסמכים ארוכים יותר לוקחים זמן רב יותר. ההפרש בין inputUploadedAt ל‑completedAt נותן את הזמן בפועל.

מה עושים כשמשימה נכשלת?

הסטטוס משתנה ל‑failed. הסיבות הרגילות הן קובץ שאינו PDF תקין, הגבלות הצפנה או העלאה שנקטעה. ודא שהקובץ נפתח וצור משימה חדשה.

אפשר לצפות במשימות קודמות?

כן. ‏GET /v1/scan-jobs מציג את המשימות שלך ותומך בסינון לפי jobID, ‏status ו‑createdAfter, וזה מספיק להתאמה או להורדה חוזרת.