Quét bằng API

Quét bằng API biến một tệp PDF thành bản quét chân thực qua một lệnh gọi REST, phù hợp với quy trình tự động và tích hợp ứng dụng. Tạo công việc, tải PDF lên rồi hỏi trạng thái hoặc chờ webhook: ba bước, từ bất kỳ môi trường hay ngôn ngữ nào gửi được yêu cầu HTTP. Không gian màu, độ phân giải, xoay, làm mờ, nhiễu, độ sáng, độ tương phản và viền đều tùy chỉnh được.

Một lệnh gọi diễn ra thế nào

  1. Tạo công việc

    POST /v1/scan-jobs

    Gửi config của bạn kèm webhookUrl nếu muốn; bạn nhận lại jobID và uploadURL đã ký sẵn.

  2. Tải PDF lên

    PUT {uploadURL}

    PUT tệp thẳng tới địa chỉ S3 đã ký sẵn ở bước trước — không cần mã thông báo.

  3. Nhận bản quét

    GET /v1/scan-jobs/{jobID}

    Hỏi trạng thái hoặc chờ webhook; khi công việc ở trạng thái completed thì tải về từ downloadURL.

Hợp với những việc này

Xuất hàng loạt ở phía máy chủ

Hợp đồng, hóa đơn và báo cáo sinh ra trên máy chủ đi thẳng qua hiệu ứng quét, không ai phải làm lại thủ công trên trang web.

Gắn vào hệ thống sẵn có

Thêm thao tác «xuất bản quét» vào CRM, ERP hay hệ thống phiếu yêu cầu và để nó gọi API.

Dây chuyền tự động

CI hay n8n, Zapier và những nền tảng tương tự khởi động công việc theo sự kiện, xong việc thì webhook chuyển tiếp sang bước sau.

Hàng đợi tệp lớn

Công việc chạy bất đồng bộ: tạo xong thì mỗi công việc được xử lý riêng, tiến độ tra được qua status và createdAfter.

Ngôn ngữ và môi trường

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLDòng lệnh / CI
ThêmMọi trình khách HTTP

API dùng HTTP và JSON tiêu chuẩn nên ngôn ngữ hay nền tảng tự động hóa nào gửi được yêu cầu đều gọi được.

Ví dụ mã

API Bearer Token

Mã thông báo gắn với tài khoản của bạn và có thể tạo lại bất cứ lúc nào. Quét bằng API cần tài khoản Pro: không có mã thông báo hợp lệ thì API trả về 401, không có vai trò Pro thì trả về 403.

Dùng thử

Chỉnh tham số, xem phần thân yêu cầu đổi theo, rồi lần lượt gọi ba lệnh tới API.

Tham số quét

Lần chạy thử gọi API bằng mã thông báo của bạn và cần tài khoản Pro; tham số và phần thân yêu cầu thì xem thoải mái.

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"
  }
}

Thông tin công việc quét

ví dụ
{
  "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-…"
}

Tham chiếu API

Phương thứcĐường dẫnMô tả
POST/v1/scan-jobsTạo một công việc quét. Gửi config và webhookUrl nếu cần; bạn nhận lại đối tượng công việc có trạng thái created cùng uploadURL đã ký sẵn.
PUT{uploadURL}Địa chỉ S3 đã ký sẵn từ bước trước, không nằm trên api.lookscanned.ioTải tệp PDF nguồn lên kèm Content-Type: application/pdf và Content-Length. Địa chỉ đã mang sẵn chữ ký nên đừng thêm tiêu đề Authorization.
GET/v1/scan-jobs/{jobID}Đọc một công việc, dùng để hỏi trạng thái. Ở created có uploadURL, ở completed có downloadURL.
GET/v1/scan-jobsLiệt kê các công việc của bạn, lọc theo jobID, status hoặc createdAfter.
Trạng tháicreatedprocessingcompletedfailed
  • 401 không có mã thông báo hợp lệ
  • 403 tài khoản không phải Pro
  • 404 không có công việc này

Thân yêu cầu

TrườngKiểuMặc địnhMô tả
webhookUrlstring · —Được gọi một lần khi công việc xong, nhờ vậy bạn không phải hỏi trạng thái liên tục.
config.colorspace'gray' | 'sRGB' · graygrayKhông gian màu của ảnh đầu ra; gray là bản quét đen trắng.
config.resolutionnumber · 7272Độ phân giải của ảnh đầu ra, tính bằng DPI.
config.rotatenumber · —Góc xoay của cả tài liệu, tính bằng độ.
config.rotate_varnumber · —Biên độ xoay ngẫu nhiên của từng trang, tính bằng độ — cho cảm giác tờ giấy đặt lệch.
config.blurnumber · 00Mức độ làm mờ.
config.noisenumber · 00Mức độ nhiễu.
config.brightnessnumber · 11Độ sáng; 1 là giữ nguyên.
config.contrastnumber · 11Độ tương phản; 1 là giữ nguyên.
config.borderboolean · falsefalseCó thêm viền quét cho trang hay không.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegĐịnh dạng ảnh dùng khi kết xuất các trang.

Mọi trường đều có thể bỏ qua. Các giá trị khởi đầu ở phần «Dùng thử» — độ phân giải 150, xoay 1, độ sáng và độ tương phản 1,3 — là tổ hợp mà ứng dụng web khuyến nghị, không phải mặc định của API.

Những trường đáng chú ý trong đối tượng công việc

status
created / processing / completed / failed — quyết định hai địa chỉ bên dưới có xuất hiện hay không.
uploadURL
Chỉ có khi ở created. Địa chỉ tải lên đã ký sẵn, có hạn dùng.
downloadURL
Chỉ có khi đã completed. Địa chỉ tải xuống đã ký sẵn, có hạn dùng.
inputUploadedAt / completedAt
Thời điểm tải xong tệp nguồn và thời điểm công việc xong; hiệu số là thời gian xử lý.

Câu hỏi thường gặp

Quét bằng API có cần Pro không?

Có. Không có mã thông báo hợp lệ thì API trả về 401, còn tài khoản không có vai trò Pro nhận 403. Nâng cấp rồi đăng nhập là lấy được mã thông báo ngay trên trang này.

Làm sao biết công việc đã xong?

Có hai cách: hỏi định kỳ GET /v1/scan-jobs/{jobID}, hoặc truyền webhookUrl khi tạo công việc để dịch vụ gọi lại một lần lúc xong.

Kết quả có giống khi quét trên trang web không?

Giống. Cả hai dùng chung một bản cài đặt hiệu ứng quét, và không gian màu, độ phân giải, xoay, làm mờ, nhiễu, độ sáng, độ tương phản, viền trong config tương ứng với các tùy chọn cùng tên trên trang web: cùng tham số thì cùng kết quả. Chỉ khác chỗ xử lý — trang web xử lý cục bộ, API xử lý ở dịch vụ từ xa.

Có thể lưu địa chỉ tải lên và tải xuống để dùng lại không?

Không nên. uploadURL và downloadURL đều là địa chỉ đã ký sẵn và có hạn dùng; hết hạn thì phải đọc lại công việc để lấy địa chỉ mới.

Xử lý một công việc mất bao lâu?

Tùy số trang và độ phân giải. Tài liệu vài trang thường xong trong vài giây; độ phân giải càng cao, số trang càng nhiều thì càng lâu. Hiệu của inputUploadedAt và completedAt cho biết thời gian thực tế.

Công việc thất bại thì làm gì?

Trạng thái chuyển thành failed. Nguyên nhân thường gặp là tệp không phải PDF hợp lệ, bị hạn chế do mã hóa, hoặc quá trình tải lên bị gián đoạn. Kiểm tra tệp mở được rồi tạo công việc mới.

Có tra được công việc cũ không?

Có. GET /v1/scan-jobs liệt kê các công việc của bạn và lọc được theo jobID, status, createdAfter, đủ để đối chiếu hoặc tải lại.