สแกนผ่าน 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 ได้ เพียงพอสำหรับการกระทบยอดหรือดาวน์โหลดซ้ำ