Pemindaian API

Pemindaian API mengubah PDF menjadi hasil pindaian yang meyakinkan lewat satu panggilan REST, cocok untuk alur otomatis dan integrasi aplikasi. Buat tugas, unggah PDF, lalu jajaki statusnya atau tunggu webhook: tiga langkah, dari lingkungan atau bahasa apa pun yang bisa mengirim permintaan HTTP. Ruang warna, resolusi, rotasi, kekaburan, derau, kecerahan, kontras, dan batas semuanya bisa diatur.

Bagaimana satu panggilan berjalan

  1. Buat tugasnya

    POST /v1/scan-jobs

    Kirim config Anda dan, bila perlu, webhookUrl; Anda menerima jobID dan uploadURL yang sudah ditandatangani.

  2. Unggah PDF

    PUT {uploadURL}

    Lakukan PUT file langsung ke alamat S3 bertanda tangan dari langkah sebelumnya — tanpa token.

  3. Ambil hasil pindaian

    GET /v1/scan-jobs/{jobID}

    Jajaki statusnya atau tunggu webhook; begitu tugas berstatus completed, unduh lewat downloadURL.

Cocok untuk hal ini

Produksi massal di backend

Kontrak, faktur, dan laporan yang dibuat di server langsung melewati efek pemindaian, tanpa ada yang mengulangi prosesnya secara manual di halaman web.

Di dalam sistem yang sudah ada

Tambahkan tindakan «ekspor hasil pindaian» pada CRM, ERP, atau sistem tiket, lalu biarkan ia memanggil API.

Rantai otomatisasi

CI, n8n, Zapier, dan sejenisnya memulai tugas berdasarkan peristiwa, dan webhook menyerahkannya ke langkah berikutnya setelah selesai.

Antrean file yang besar

Tugas bersifat asinkron: setelah dibuat, masing-masing diproses sendiri, dan kemajuannya bisa dilihat lewat status dan createdAfter.

Bahasa dan lingkungan

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLBaris perintah / CI
LainnyaKlien HTTP apa pun

API ini hanya HTTP dan JSON biasa, jadi bahasa atau platform otomatisasi apa pun yang bisa mengirim permintaan dapat memanggilnya.

Contoh kode

API Bearer Token

Token melekat pada akun Anda dan bisa dibuat ulang kapan saja. Pemindaian API memerlukan akun Pro: tanpa token yang sah API menjawab 401, dan tanpa peran Pro menjawab 403.

Coba

Atur parameternya, lihat badan permintaan ikut berubah, lalu jalankan tiga panggilan ke API.

Parameter pemindaian

Uji coba memanggil API dengan token Anda dan memerlukan akun Pro; parameter dan badan permintaannya bebas dibaca.

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

Info Tugas Pemindaian

contoh
{
  "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-…"
}

Referensi API

MetodeJalurKeterangan
POST/v1/scan-jobsMembuat tugas pemindaian. Kirim config dan, bila perlu, webhookUrl; Anda menerima objek tugas berstatus created beserta uploadURL bertanda tangan.
PUT{uploadURL}Alamat S3 bertanda tangan dari langkah sebelumnya, yang tidak berada di api.lookscanned.ioMengunggah PDF sumber dengan Content-Type: application/pdf dan Content-Length. Alamatnya sudah membawa tanda tangan sendiri, jadi jangan menambahkan header Authorization.
GET/v1/scan-jobs/{jobID}Membaca satu tugas, untuk penjajakan. Saat created berisi uploadURL, saat completed berisi downloadURL.
GET/v1/scan-jobsMenampilkan daftar tugas Anda sendiri, tersaring menurut jobID, status, atau createdAfter.
Statuscreatedprocessingcompletedfailed
  • 401 tidak ada token yang sah
  • 403 akun bukan Pro
  • 404 tugas tidak ada

Badan permintaan

BidangTipeBawaanKeterangan
webhookUrlstring · —Dipanggil sekali begitu tugas selesai, jadi Anda tidak perlu menjajaki statusnya.
config.colorspace'gray' | 'sRGB' · graygrayRuang warna gambar keluaran; gray berarti hasil pindaian hitam putih.
config.resolutionnumber · 7272Resolusi gambar keluaran, dalam DPI.
config.rotatenumber · —Rotasi seluruh dokumen, dalam derajat.
config.rotate_varnumber · —Rentang rotasi acak tiap halaman, dalam derajat — kesan kertas yang diletakkan miring.
config.blurnumber · 00Tingkat kekaburan.
config.noisenumber · 00Tingkat derau.
config.brightnessnumber · 11Kecerahan; 1 berarti tidak berubah.
config.contrastnumber · 11Kontras; 1 berarti tidak berubah.
config.borderboolean · falsefalseApakah halaman diberi batas pemindaian.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormat gambar saat halaman dirender.

Semua bidang boleh dilewatkan. Nilai awal di bagian «Coba» — resolusi 150, rotasi 1, kecerahan dan kontras 1,3 — adalah kombinasi yang disarankan aplikasi web, bukan nilai bawaan API.

Bidang objek tugas yang perlu diperhatikan

status
created / processing / completed / failed — menentukan apakah dua alamat di bawah ini muncul.
uploadURL
Hanya selama berstatus created. Alamat unggah bertanda tangan yang punya masa berlaku.
downloadURL
Hanya setelah berstatus completed. Alamat unduh bertanda tangan yang punya masa berlaku.
inputUploadedAt / completedAt
Kapan unggahan sumber selesai dan kapan tugas selesai; selisihnya adalah waktu pemrosesan.

Pertanyaan yang sering diajukan

Apakah pemindaian API butuh Pro?

Butuh. Tanpa token yang sah API menjawab 401, dan akun tanpa peran Pro mendapat 403. Setelah meningkatkan ke Pro dan masuk, tokennya ada di halaman ini.

Bagaimana saya tahu sebuah tugas sudah selesai?

Ada dua cara: menjajaki GET /v1/scan-jobs/{jobID}, atau mengirim webhookUrl saat membuat tugas dan membiarkan layanan menghubungi Anda sekali.

Apakah hasilnya sama dengan memindai di halaman web?

Sama. Keduanya memakai implementasi efek pemindaian yang sama, dan ruang warna, resolusi, rotasi, kekaburan, derau, kecerahan, kontras, serta batas di config adalah opsi bernama sama di halaman web: parameter sama, keluaran sama. Yang berbeda hanya tempat pemrosesannya — lokal di halaman, jarak jauh lewat API.

Bolehkah saya menyimpan alamat unggah dan unduh untuk dipakai lagi?

Sebaiknya tidak. uploadURL dan downloadURL adalah alamat bertanda tangan yang punya masa berlaku; setelah kedaluwarsa Anda harus membaca ulang tugasnya untuk mendapatkan yang baru.

Berapa lama satu tugas diproses?

Tergantung jumlah halaman dan resolusinya. Dokumen beberapa halaman biasanya selesai dalam hitungan detik; resolusi lebih tinggi dan dokumen lebih panjang butuh waktu lebih lama. Selisih inputUploadedAt dan completedAt menunjukkan waktu sebenarnya.

Bagaimana kalau sebuah tugas gagal?

Statusnya menjadi failed. Penyebab yang lazim adalah file yang bukan PDF sah, pembatasan enkripsi, atau unggahan yang terputus. Pastikan file-nya bisa dibuka, lalu buat tugas baru.

Bisakah saya melihat tugas yang lalu?

Bisa. GET /v1/scan-jobs menampilkan tugas Anda sendiri dan dapat disaring menurut jobID, status, dan createdAfter — cukup untuk pencocokan atau mengunduh ulang.