API-szkennelés
Az API-szkenneléssel REST-híváson keresztül készíthetsz élethű, szkennelt másolatot egy PDF-ből, automatizált folyamatokhoz és alkalmazásintegrációkhoz. Hozz létre feladatot, töltsd fel a PDF-et, majd kérdezd le az állapotát, vagy várd meg a webhook értesítését. Ez a három lépés bármilyen HTTP-kérést küldeni képes környezetből vagy nyelvből elvégezhető. A színteret, a felbontást, az elforgatást, az elmosást, a zajt, a fényerőt, a kontrasztot és a szegélyt is beállíthatod.
A hívás menete
Hozd létre a feladatot
POST /v1/scan-jobs
Küldd el a config mezőt és szükség esetén a webhookUrl értékét. A válaszban egy jobID azonosítót és egy előre aláírt uploadURL címet kapsz.
Töltsd fel a PDF-et
PUT {uploadURL}
Küldd a fájlt PUT-kéréssel közvetlenül az előző lépésben kapott, előre aláírt S3-címre. Ehhez nem kell token.
Töltsd le a szkennelt másolatot
GET /v1/scan-jobs/{jobID}
Kérdezd le rendszeresen az állapotot, vagy várd meg a webhook értesítését. Ha a feladat állapota completed, a downloadURL címről letöltheted az eredményt.
Mire használhatod?
Szerveroldali tömeges feldolgozás
A szerveren készülő szerződések, számlák és jelentések automatikusan megkapják a szkennelési hatást. Nem kell őket egyenként feldolgoznod a weboldalon.
Beépítés meglévő rendszerbe
Adj „Szkennelt másolat exportálása” műveletet egy CRM-, ERP- vagy hibajegykezelő rendszerhez, és hívd meg belőle az API-t.
Automatizált munkafolyamatok
A CI, az n8n, a Zapier és hasonló eszközök egy esemény hatására elindítják a feladatot. Amint elkészült, a webhook elindíthatja a következő lépést.
Sok fájl feldolgozása
A feladatok aszinkron módon, egymástól függetlenül készülnek el. A haladást a status és a createdAfter mező alapján követheted.
Nyelvek és környezetek
Az API HTTP-t és JSON-t használ, így bármilyen kérést küldeni képes programozási nyelvből vagy automatizálási platformról meghívhatod.
Kódpéldák
Add Look Scanned API Scan to this project, so I can turn a PDF into a
realistic scanned copy from code.
API docs: https://lookscanned.io/en/scan/api
Write one function that:
1. POST https://api.lookscanned.io/v1/scan-jobs
Header: Authorization: Bearer $LOOKSCANNED_API_TOKEN
Body: {"config": {"colorspace": "gray", "resolution": 150, "rotate": 1}}
It returns jobID and a presigned uploadURL.
2. PUT the PDF bytes to uploadURL with Content-Type: application/pdf.
Send no Authorization header — that URL is already signed.
3. Poll GET /v1/scan-jobs/{jobID} until status is "completed" (or "failed"),
then return downloadURL.
Read the token from the LOOKSCANNED_API_TOKEN environment variable. Use the
language and HTTP client this project already uses, and add one test.interface ScanConfig {
rotate?: number // degrees to rotate the document
rotate_var?: number // degrees to rotate the document randomly
colorspace?: 'gray' | 'sRGB' // the colorspace of the output image
blur?: number // the amount of blur to apply to the image
noise?: number // the amount of noise to apply to the image
border?: boolean // whether to add a border to the image
brightness?: number // the brightness of the image. 1 is no change
contrast?: number // the contrast of the image. 1 is no change
resolution?: number // the resolution of the image in DPI
output_format?: 'image/png' | 'image/jpeg' // the format of the output image
}
interface ScanOptions {
config: ScanConfig
webhookUrl?: string // webhook URL to notify when job is completed
}
interface ScanResponse {
jobID: string // UUID of the scan job
userID: string // UUID of the user who created the job
createdAt: number // timestamp of job creation
status: 'pending' | 'processing' | 'completed' | 'failed'
config: ScanConfig
inputUploadedAt?: number // timestamp when input file was uploaded
completedAt?: number // timestamp when job was completed
webhookUrl?: string // webhook URL for notifications
uploadURL?: string // S3 presigned URL for file upload
downloadURL?: string // S3 presigned URL for file download
}
async function apiScan(pdfBlob: Blob, scanOptions: ScanOptions, token: string): Promise<ScanResponse> {
const response = await fetch('https://api.lookscanned.io/v1/scan-jobs', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: JSON.stringify(scanOptions)
})
const result: ScanResponse = await response.json()
// PUT PDF Blob to upload URL
const uploadURL = result.uploadURL
await fetch(uploadURL, {
method: 'PUT',
headers: {
'Content-Type': 'application/pdf',
'Content-Length': pdfBlob.size.toString()
},
body: pdfBlob
})
// get scan job status
const jobStatusResponse = await fetch(`https://api.lookscanned.io/v1/scan-jobs/${result.jobID}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
return await jobStatusResponse.json()
}import requests
def api_scan(pdf_file, scan_options, token):
# Create scan job
response = requests.post(
'https://api.lookscanned.io/v1/scan-jobs',
headers={'Authorization': f'Bearer {token}'},
json=scan_options
)
result = response.json()
# Upload PDF to presigned URL
upload_url = result['uploadURL']
requests.put(
upload_url,
headers={
'Content-Type': 'application/pdf',
'Content-Length': str(len(pdf_file))
},
data=pdf_file
)
# Get scan job status
job_status = requests.get(
f'https://api.lookscanned.io/v1/scan-jobs/{result["jobID"]}',
headers={'Authorization': f'Bearer {token}'}
)
return job_status.json()
# Example usage
if __name__ == "__main__":
with open('document.pdf', 'rb') as f:
pdf_content = f.read()
options = {
'config': {
# Optional parameters:
# 'rotate': 0, # degrees to rotate the document
# 'colorspace': 'gray', # gray or sRGB
# 'resolution': 300, # DPI
# 'rotate_var': 0, # random rotation variance in degrees
# 'blur': 0, # amount of blur
# 'noise': 0, # amount of noise
# 'border': False, # whether to add border
# 'brightness': 1, # 1 is no change
# 'contrast': 1, # 1 is no change
# 'output_format': 'image/png' # image/png or image/jpeg
},
'webhookUrl': 'https://example.com/webhook'
}
result = api_scan(pdf_content, options, 'your-api-token')
print(f"Scan job created with ID: {result['jobID']}")# Set your API token and PDF file as environment variables
export LOOKSCANNED_API_TOKEN='your_api_token_here'
# Create a new scan job
curl -X POST 'https://api.lookscanned.io/v1/scan-jobs' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"config": {
"rotate": 0,
"rotate_var": 1,
"colorspace": "gray",
"blur": 0.2,
"noise": 0.1,
"border": true,
"brightness": 1.0,
"contrast": 1.0,
"resolution": 300,
"output_format": "image/jpeg"
},
"webhookUrl": "https://your-domain.com/webhook"
}'
# Response will include uploadURL and jobID
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "userID": "446655440000-e29b-41d4-a716-550e8400",
# "createdAt": 1616161616,
# "status": "created",
# "uploadURL": "...",
# "config": { ... }
# }
# Upload PDF file to the presigned URL
curl -X PUT 'PRESIGNED_UPLOAD_URL' \
-H 'Content-Type: application/pdf' \
-H "Content-Length: PDF_FILE_SIZE" \
--data-binary "@path/to/your/file.pdf"
# Check job status
curl 'https://api.lookscanned.io/v1/scan-jobs/JOB_ID' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}"
# Response will include status and downloadURL when completed
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "status": "completed",
# "downloadURL": "...",
# ...
# }
# Download the PDF
curl -o scanned.pdf 'DOWNLOAD_URL'API Bearer Token
A token a fiókodhoz tartozik, és bármikor újat hozhatsz létre. Az API-szkenneléshez Pro-fiók kell: érvényes token nélkül az API 401-es, Pro-jogosultság nélkül 403-as választ ad.
Az API-szkennelés Pro funkció
Ez a fiók még nem Pro. Válts Pro csomagra, és itt megjelenik a tokened. Token nélkül az API 401-es, Pro-jogosultság nélkül 403-as választ ad.
Kipróbálás
Állítsd be a paramétereket, és figyeld, hogyan változik a kérés törzse. Ezután futtasd le a három API-hívást.
Szkennelési paraméterek
A próbafuttatás a saját tokeneddel hívja meg az API-t, ezért Pro-fiók szükséges hozzá. A paramétereket és a kérés törzsét ingyen is megnézheted.
{
"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"
}
}Szkennelési feladat adatai
példa{
"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-dokumentáció
| Metódus | Útvonal | Leírás |
|---|---|---|
| POST | /v1/scan-jobs | Szkennelési feladat létrehozása. Küldd el a config mezőt és szükség esetén a webhookUrl értékét. A válaszban a feladat objektumát kapod created állapottal és egy előre aláírt uploadURL címmel. |
| PUT | {uploadURL}Az előző lépésben kapott, előre aláírt S3-cím, nem az api.lookscanned.io | Töltsd fel a forrás-PDF-et Content-Type: application/pdf és Content-Length fejléccel. A cím már tartalmazza az aláírást, ezért ne adj hozzá Authorization fejlécet. |
| GET | /v1/scan-jobs/{jobID} | Egy feladat lekérdezése az állapot rendszeres ellenőrzéséhez. created állapotban uploadURL, completed állapotban downloadURL szerepel benne. |
| GET | /v1/scan-jobs | Saját feladatok listázása jobID, status vagy createdAfter szerinti szűréssel. |
401nincs érvényes token403a fiók nem Pro404nincs ilyen feladat
Kérés törzse
| Mező | Típus | Alapérték | Leírás |
|---|---|---|---|
| webhookUrl | string · — | — | A feladat befejezésekor egyszer hívja meg a szolgáltatás, így nem kell rendszeresen lekérdezned az állapotot. |
| config.colorspace | 'gray' | 'sRGB' · gray | gray | A kimeneti kép színtere; a gray szürkeárnyalatos eredményt ad. |
| config.resolution | number · 72 | 72 | A kimeneti kép felbontása DPI-ben. |
| config.rotate | number · — | — | A teljes dokumentum elforgatása fokban. |
| config.rotate_var | number · — | — | Az oldalankénti véletlenszerű elforgatás tartománya fokban. A ferdén behelyezett papír hatását utánozza. |
| config.blur | number · 0 | 0 | Az elmosás mértéke. |
| config.noise | number · 0 | 0 | A zaj mértéke. |
| config.brightness | number · 1 | 1 | Fényerő; az 1 változatlanul hagyja. |
| config.contrast | number · 1 | 1 | Kontraszt; az 1 változatlanul hagyja. |
| config.border | boolean · false | false | Kerüljön-e szkennelési szegély az oldalra. |
| config.output_format | 'image/png' | 'image/jpeg' · image/jpeg | image/jpeg | Az oldalak kimeneti képformátuma. |
Minden mező elhagyható. A „Kipróbálás” kezdőértékei (150-es felbontás, 1-es elforgatás, 1.3-as fényerő és kontraszt) a webalkalmazás ajánlott beállításai, nem az API alapértékei.
A feladat objektumának fontosabb mezői
- status
- created / processing / completed / failed – ettől függ, hogy az alábbi két cím közül melyik érhető el.
- uploadURL
- Csak created állapotban. Előre aláírt feltöltési cím, amelynek lejár az érvényessége.
- downloadURL
- Csak completed állapotban. Előre aláírt letöltési cím, amelynek lejár az érvényessége.
- inputUploadedAt / completedAt
- A forrásfájl feltöltésének és a feladat befejezésének időpontja. A kettő különbsége a feldolgozási idő.
Gyakori kérdések
Kell Pro az API-szkenneléshez?
Igen. Érvényes token nélkül az API 401-es választ ad, Pro-jogosultság nélküli fiókkal pedig 403-ast. Válts Pro csomagra, és jelentkezz be: a tokened ezen az oldalon jelenik meg.
Honnan tudom, hogy elkészült egy feladat?
Két lehetőséged van: rendszeresen hívd meg a GET /v1/scan-jobs/{jobID} végpontot, vagy adj meg webhookUrl értéket a feladat létrehozásakor. Utóbbi esetben a szolgáltatás egyszer értesít a befejezésről.
Ugyanazt az eredményt kapom, mint a weboldalon?
Igen. Mindkettő ugyanazt a szkennelési eljárást használja. A config színtér-, felbontás-, elforgatás-, elmosás-, zaj-, fényerő-, kontraszt- és szegélybeállításai a weboldal lehetőségeinek felelnek meg, más néven. Azonos paraméterekkel azonos eredményt kapsz. A feldolgozás helye tér el: a weboldalon helyben, az API-val távolról történik.
Elmenthetem a feltöltési és letöltési címeket későbbi használatra?
Nem érdemes. Az uploadURL és a downloadURL előre aláírt, korlátozott ideig érvényes cím. Ha lejárnak, kérdezd le újra a feladatot, hogy friss címeket kapj.
Mennyi ideig tart egy feladat?
Az oldalszámtól és a felbontástól függ. Néhány oldal általában másodpercek alatt elkészül; nagyobb felbontás vagy hosszabb dokumentum esetén több idő kell. Az inputUploadedAt és a completedAt különbsége mutatja a tényleges feldolgozási időt.
Mi történik, ha sikertelen egy feladat?
Az állapota failed lesz. Ennek gyakori oka az érvénytelen PDF, a titkosítási korlátozás vagy a megszakadt feltöltés. Ellenőrizd, hogy megnyitható-e a fájl, majd hozz létre új feladatot.
Visszakereshetem a korábbi feladatokat?
Igen. A GET /v1/scan-jobs a saját feladataidat listázza, jobID, status és createdAfter szerinti szűréssel. Így ellenőrizheted az előzményeket vagy újra letöltheted az eredményt.